/ 
Rex-LibSSH-0.004
/ Rex::LibSSH

NAME

Rex::LibSSH - Rex connection backend using Net::LibSSH (no SFTP required)

VERSION

version 0.004

SYNOPSIS

# In your Rexfile
use Rex -feature => ['1.4'];
use Rex::LibSSH;

set connection => 'LibSSH';

task 'deploy', 'myserver', sub {
    my $kernel = run 'uname -r';
    say "kernel: $kernel";
};

DESCRIPTION

Rex::LibSSH provides Rex connection, exec, filesystem, and file interfaces backed by Net::LibSSH — the XS binding for libssh.

Unlike Rex's built-in SSH and OpenSSH connection types, this backend performs all file operations (is_file, stat, ls, upload, download, etc.) over plain SSH exec channels. No SFTP subsystem is required on the remote host.

This makes it suitable for minimal containers, embedded systems, and any host where Rex would otherwise crash with:

Can't call method "stat" on an undefined value

Activating

Set the connection type in your Rexfile before connecting:

set connection => 'LibSSH';

Rex's interface dispatch will automatically load Rex::Interface::Connection::LibSSH, Rex::Interface::Exec::LibSSH, Rex::Interface::Fs::LibSSH, and Rex::Interface::File::LibSSH.

Authentication

Supports public key authentication:

Rex::Config->set_private_key('/home/user/.ssh/id_ed25519');
Rex::Config->set_public_key('/home/user/.ssh/id_ed25519.pub');

Or pass keys directly to Rex::connect:

Rex::connect(
    server      => '10.0.0.1',
    user        => 'root',
    private_key => '/path/to/key',
    public_key  => '/path/to/key.pub',
    auth_type   => 'key',
);

Host key verification

The server's host key is verified against known_hosts by default, exactly like an interactive ssh client but without the prompt: an unknown or changed key makes the connection fail before any authentication is attempted. Requires Net::LibSSH 0.004 or later — earlier versions of Rex::LibSSH never verified the host key regardless of what was passed (CWE-322).

Precedence: a strict_hostkeycheck option passed to Rex::connect wins (0 or 1); otherwise Rex::Config->get_openssh_opt()'s StrictHostKeyChecking is consulted — no or off (case-insensitive) turns verification off, anything else or unset leaves it on. use Rex -feature => ['disable_strict_host_key_checking'] sets exactly that openssh_opt, so the Rexfile-wide flag the OpenSSH backend honours works here too.

The known_hosts file is, in order: the knownhosts connect option, then openssh_opt's UserKnownHostsFile, then libssh's own default (~/.ssh/known_hosts). A host reached on a non-standard port needs the [host]:port form in known_hosts. Nothing is ever written to known_hosts by this backend — add a host out of band first (ssh-keyscan), or turn verification off explicitly:

# Rexfile-wide, same flag the OpenSSH backend honours
use Rex -feature => ['1.4', 'disable_strict_host_key_checking'];

# or per connection
Rex::connect(
    server              => '10.0.0.1',
    strict_hostkeycheck => 0,
    knownhosts          => '/path/to/known_hosts',   # optional
);

An unknown or changed key makes Rex::connect die with "Connection error or refused."; inside a task Rex reports "Couldn't connect to $server.". The underlying reason from Net::LibSSH (e.g. "host key is not in known_hosts and strict_hostkeycheck is on", or "host key has changed from the known_hosts entry -- possible man-in-the-middle attack") is logged as a warn-level line that also names the opt-out.

SEE ALSO

Net::LibSSH, Rex::Interface::Connection::LibSSH, Rex::Interface::Fs::LibSSH, Rex::Interface::File::LibSSH, Rex::Interface::Exec::LibSSH

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/rex-libssh/issues.

CONTRIBUTING

Contributions are welcome! Please fork the repository and submit a pull request.

AUTHOR

Torsten Raudssus <getty@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Torsten Raudssus <torsten@raudssus.de> https://raudssus.de/.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.