Provided by: libnet-ssh2-perl_0.53-1_amd64 
NAME
Net::SSH2 - Support for the SSH 2 protocol via libssh2.
SYNOPSIS
use Net::SSH2;
my $ssh2 = Net::SSH2->new();
$ssh2->connect('example.com') or die $!;
if ($ssh2->auth_keyboard('fizban')) {
my $chan = $ssh2->channel();
$chan->exec('program');
my $sftp = $ssh2->sftp();
my $fh = $sftp->open('/etc/passwd') or die;
print $_ while <$fh>;
}
DESCRIPTION
"Net::SSH2" is a perl interface to the libssh2 (<http://www.libssh2.org>) library. It
supports the SSH2 protocol (there is no support for SSH1) with all of the key exchanges,
ciphers, and compression of libssh2.
Unless otherwise indicated, methods return a true value on success and false on failure;
use the error method to get extended error information.
The typical order is to create the SSH2 object, set up the connection methods you want to
use, call connect, authenticate with one of the "auth" methods, then create channels on
the connection to perform commands.
EXPORTS
Exports the following constant tags:
all All constants.
ssh constants:
callback
channel
error
socket
trace
Tracing constants for use with "->trace" and "->new(trace => ...)".
hash
Key hash constants.
method
disconnect
Disconnect type constants.
SFTP constants:
fx
fxf
sftp
METHODS
new
Create new SSH2 object.
To turn on tracing with a debug build of libssh2 use:
my $ssh2 = Net::SSH2->new(trace => -1);
banner ( text )
Set the SSH2 banner text sent to the remote host (prepends required "SSH-2.0-").
version
In scalar context, returns libssh2 version/patch e.g. 0.18 or "0.18.0-20071110". In list
context, returns that version plus the numeric version (major, minor, and patch, each
encoded as 8 bits, e.g. 0x001200 for version 0.18) and the default banner text (e.g.
"SSH-2.0-libssh2_0.18.0-20071110").
error
Returns the last error code; returns false if no error. In list context, returns (code,
error name, error string).
sock
Returns a reference to the underlying IO::Socket::INET object, or "undef" if not yet
connected.
trace
Calls libssh2_trace with supplied bitmask, to enable all tracing use:
$ssh2->trace(-1);
You need a debug build of libssh2 with tracing support.
timeout ( timeout_ms )
Enables a global timeout (in milliseconds) which will affect every action.
libssh2 version 1.2.9 or higher is required to use this method.
method ( type [, values... ] )
Sets or returns a method preference; for get, pass in the type only; to set, pass in
either a list of values or a comma-separated string. Values can only be queried after the
session is connected.
The following methods can be set or queried:
KEX Key exchange method names. Supported values:
diffie-hellman-group1-sha1
Diffie-Hellman key exchange with SHA-1 as hash, and Oakley Group 2 (see RFC 2409).
diffie-hellman-group14-sha1
Diffie-Hellman key exchange with SHA-1 as hash, and Oakley Group 14 (see RFC
3526).
diffie-hellman-group-exchange-sha1
Diffie-Hellman key exchange with SHA-1 as hash, using a safe-prime/generator pair
(chosen by server) of arbitrary strength (specified by client) (see IETF draft
secsh-dh-group-exchange).
HOSTKEY
Public key algorithms. Supported values:
ssh-dss
Based on the Digital Signature Standard (FIPS-186-2).
ssh-rsa
Based on PKCS#1 (RFC 3447).
CRYPT_CS
Encryption algorithm from client to server. Supported algorithms:
aes256-cbc
AES in CBC mode, with 256-bit key.
rijndael-cbc@lysator.liu.se
Alias for aes256-cbc.
aes192-cbc
AES in CBC mode, with 192-bit key.
aes128-cbc
AES in CBC mode, with 128-bit key.
blowfish-cbc
Blowfish in CBC mode.
arcfour
ARCFOUR stream cipher.
cast128-cbc
CAST-128 in CBC mode.
3des-cbc
Three-key 3DES in CBC mode.
none
No encryption.
CRYPT_SC
Encryption algorithm from server to client. See CRYPT_CS for supported algorithms.
MAC_CS
Message Authentication Code (MAC) algorithms from client to server. Supported values:
hmac-sha1
SHA-1 with 20-byte digest and key length.
hmac-sha1-96
SHA-1 with 20-byte key length and 12-byte digest length.
hmac-md5
MD5 with 16-byte digest and key length.
hmac-md5-96
MD5 with 16-byte key length and 12-byte digest length.
hmac-ripemd160
RIPEMD-160 algorithm with 20-byte digest length.
hmac-ripemd160@openssh.com
Alias for hmac-ripemd160.
none
No encryption.
MAC_SC
Message Authentication Code (MAC) algorithms from server to client. See MAC_SC for
supported algorithms.
COMP_CS
Compression methods from client to server. Supported values:
zlib
The "zlib" compression method as described in RFC 1950 and RFC 1951.
none
No compression
COMP_SC
Compression methods from server to client. See COMP_CS for supported compression
methods.
connect ( handle | host [, port [, Timeout => secs ]] )
Accepts a handle over which to conduct the SSH 2 protocol. The handle may be:
an "IO::*" object
a glob reference
an integer file descriptor
a host name and port
disconnect ( [description [, reason [, language]]] )
Send a clean disconnect message to the remote server. Default values are empty strings
for description and language, and "SSH_DISCONNECT_BY_APPLICATION" for the reason.
hostkey ( hash type )
Returns a hash of the host key; note that the key is raw data and may contain nulls or
control characters. The type may be:
MD5 (16 bytes)
SHA1 (20 bytes)
auth_list ( [username] )
Get a list (or comma-separated string in scalar context) of authentication methods
supported by the server; or returns "undef". If "undef" is returned and auth_ok is true,
the server accepted an unauthenticated session for the given username.
auth_ok
Returns true iff the session is authenticated.
auth_password ( username [, password [, callback ]] )
Authenticate using a password (PasswordAuthentication must be enabled in sshd_config or
equivalent for this to work.)
If the password has expired, if a callback code reference was given, it's called as
"callback($self, $username)" and should return a password. If no callback is provided,
LIBSSH2_ERROR_PASSWORD_EXPIRED is returned.
auth_publickey ( username, public key, private key [, password ] )
Note that public key and private key are names of files containing the keys!
Authenticate using keys and an optional password.
auth_hostbased ( username, public key, private key, hostname, [, local username [, password ]]
)
Host-based authentication using an optional password. The local username defaults to be
the same as the remote username.
auth_keyboard ( username, password | callback )
Authenticate using "keyboard-interactive". Takes either a password, or a callback code
reference which is invoked as "callback->(self, username, name, instruction, prompt...)"
(where each prompt is a hash with "text" and "echo" keys, signifying the prompt text and
whether the user input should be echoed, respectively) which should return an array of
responses.
If only a username is provided, the default callback will handle standard interactive
responses; Term::ReadKey is required.
auth_agent ( username )
Try to authenticate using ssh-agent. This requires libssh2 version 1.2.3 or later.
auth ( ... )
This is a general, prioritizing authentication mechanism that can use any of the previous
methods. You provide it some parameters and (optionally) a ranked list of methods you
want considered (defaults to all). It will remove any unsupported methods or methods for
which it doesn't have parameters (e.g. if you don't give it a public key, it can't use
publickey or hostkey), and try the rest, returning whichever one succeeded or a false
value if they all failed. If a parameter is passed with an undef value, a default value
will be supplied if possible. The parameters are:
rank
An optional ranked list of methods to try. The names should be the names of the
Net::SSH2 "auth" methods, e.g. 'keyboard' or 'publickey', with the addition of
'keyboard-auto' for automated 'keyboard-interactive'.
username
password
publickey
privatekey
As in the methods, publickey and privatekey are filenames.
hostname
local_username
interact
If this is set to a true value, interactive methods will be considered.
cb_keyboard
auth_keyboard callback.
cb_password
auth_password callback.
channel ( [type, [window size, [packet size]]] )
Creates and returns a new channel object. The default type is "session". See
Net::SSH2::Channel.
tcpip ( host, port [, shost, sport ] )
Creates a TCP connection from the remote host to the given host:port, returning a new
channel. Binds to shost:sport (default 127.0.0.1:22).
listen ( port [, host [, bound port [, queue size ]]] )
Sets up a TCP listening port on the remote host. Host defaults to 0.0.0.0; if bound port
is provided, it should be a scalar reference in which the bound port is returned. Queue
size specifies the maximum number of queued connections allowed before the server refuses
new connections.
Returns a new Net::SSH2::Listener object.
scp_get ( remote [, local ] )
Retrieve a file with scp; local path defaults to basename of remote. "local" may be an IO
object (e.g. IO::File, IO::Scalar).
scp_put ( local [, remote ] )
Send a file with scp; remote path defaults to same as local. "local" may be an IO object
instead of a filename (but it must have a valid stat method).
sftp
Return SecureFTP interface object (see Net::SSH2::SFTP).
public_key
Return public key interface object (see Net::SSH2::PublicKey).
poll ( timeout, arrayref of hashes )
Pass in a timeout in milliseconds and an arrayref of hashes with the following keys:
handle
May be a Net::SSH2::Channel or Net::SSH2::Listener object, integer file descriptor, or
perl file handle.
events
Requested events. Combination of LIBSSH2_POLLFD_* constants (with the POLL prefix
stripped if present), or an arrayref of the names ('in', 'hup' etc.).
revents
Returned events. Returns a hash with the (lowercased) names of the received events
('in', 'hup', etc.) as keys with true values, and a "value" key with the integer
value.
Returns undef on error, or the number of active objects.
block_directions
Get the blocked direction when a function returns LIBSSH2_ERROR_EAGAIN, returns
LIBSSH2_SOCKET_BLOCK_INBOUND or LIBSSH2_SOCKET_BLOCK_OUTBOUND from the socket export
group.
debug ( state )
Class method (affects all Net::SSH2 objects). Pass 1 to enable, 0 to disable. Debug
output is sent to stderr via "warn".
blocking ( flag )
Enable or disable blocking. Note that if blocking is disabled, methods that create
channels may fail, e.g. "channel", "SFTP", "scp_*".
SEE ALSO
Net::SSH2::Channel, Net::SSH2::Listener, Net::SSH2::SFTP, Net::SSH2::File, Net::SSH2::Dir.
LibSSH2 documentation at <http://www.libssh2.org>.
IETF Secure Shell (secsh) working group at
<http://www.ietf.org/html.charters/secsh-charter.html>.
Net::SSH::Perl.
AUTHOR
David B. Robins, <dbrobins@cpan.org>
COPYRIGHT AND LICENSE
Copyright (C) 2005 - 2010 by David B. Robins; all rights reserved.
This library is free software; you can redistribute it and/or modify it under the same
terms as Perl itself, either Perl version 5.8.0 or, at your option, any later version of
Perl 5 you may have available.