/ 
Net-SSH2-0.03
River stage one • 6 direct dependents • 6 total dependents
/ Net::SSH2

NAME

Net::SSH2 - Support for the SSH 2 protocol via libSSH2.

SYNOPSIS

use Net::SSH2;

my $ssh2 = Net::SSH2->new();

if ($ssh2->auth_keyboard('fizban')) {
    my $chan = $ssh2->channel();
    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.

new

Create new SSH2 object.

Set the SSH2 banner text sent to the remote host (prepends required "SSH-2.0-").

error

Returns the last error code; returns false if no error. In list context, returns (code, error name, error string).

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]] )

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

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

poll ( timeout, arrayref of hashes )

Pass in a timeout in milliseconds (0 to block) 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.

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