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.
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
<
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.