/ 
Net-LibSSH-0.002
/ Net::LibSSH

NAME

Net::LibSSH - Perl binding for libssh — SSH without SFTP dependency

VERSION

version 0.002

SYNOPSIS

use Net::LibSSH;

my $ssh = Net::LibSSH->new;
$ssh->option(host => 'server.example.com');
$ssh->option(user => 'root');
$ssh->option(port => 22);

$ssh->connect or die "connect failed: " . $ssh->error;
$ssh->auth_agent or die "auth failed: " . $ssh->error;

my $ch = $ssh->channel;
$ch->exec("uname -r");
my $out = $ch->read;
print "Kernel: $out";
print "Exit: ", $ch->exit_status, "\n";

# Optional SFTP (returns undef if SFTP subsystem not available)
if (my $sftp = $ssh->sftp) {
  my $attr = $sftp->stat('/etc/hostname');
  print "size: $attr->{size}\n" if $attr;
}

DESCRIPTION

Net::LibSSH is a Perl XS binding for libssh.

Unlike Net::SSH2 (which wraps libssh2) and Net::OpenSSH (which wraps the system ssh binary), this module links directly against libssh — a separate, actively maintained C library. The key difference for automation use cases: file operations via Net::LibSSH::Channel use SSH exec channels and require no SFTP subsystem on the remote host.

SFTP is supported as an optional feature via "sftp": it returns undef gracefully when the remote server has no SFTP subsystem, rather than crashing.

Note: This module is not thread-safe and does not support fork. Use one connection per process.

METHODS

new

my $ssh = Net::LibSSH->new;

Creates a new session object.

option($key, $value)

$ssh->option(host => 'server.example.com');
$ssh->option(port => 22);
$ssh->option(user => 'root');

Set a session option before connecting. Supported keys: host, port, user, knownhosts, timeout, compression, log_verbosity, strict_hostkeycheck (set to 0 to disable host key verification).

connect

$ssh->connect or die $ssh->error;

Connect to the host. Returns 1 on success, 0 on failure.

disconnect

$ssh->disconnect;

Disconnect and free the underlying connection.

error

my $msg = $ssh->error;

Return the last error message from libssh.

auth_password($password)

$ssh->auth_password('s3cr3t') or die $ssh->error;

auth_publickey($privkey_path)

$ssh->auth_publickey('/root/.ssh/id_ed25519') or die $ssh->error;

auth_agent

$ssh->auth_agent or die $ssh->error;

Authenticate via the SSH agent, falling back to default key files if the agent is not available.

channel

my $ch = $ssh->channel;

Open a new session channel. Returns a Net::LibSSH::Channel object or undef on failure.

sftp

my $sftp = $ssh->sftp;  # returns undef if SFTP not available

Open an SFTP session. Returns a Net::LibSSH::SFTP object, or undef if the remote server does not support SFTP. Never throws.

SEE ALSO

Net::LibSSH::Channel, Net::LibSSH::SFTP, Alien::libssh, Net::SSH2

SUPPORT

Issues

Please report bugs and feature requests on GitHub at https://github.com/Getty/p5-net-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) 2025 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.