Provided by: libnet-ssh2-perl_0.58-3_amd64 bug

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

       Note that the returned error value is only meaningful after some other method indicates an
       error by returning false.

   sock
       Returns a reference to the underlying IO::Socket object (usually a derived class as
       IO::Socket::IP or IO::Socket::INET), 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 ] [, Compress => 1]] )
       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
           In order to handle IPv6 addresses the optional module IO::Socket::IP needs to be
           installed (otherwise the module will use the IPv4 only core module IO::Socket::INET to
           establish the connection).

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

       Note: in previous versions of the module this method was called "hostkey".

   remote_hostkey
       Returns the public key of the remote host and its type which is one of
       "LIBSSH2_HOSTKEY_TYPE_RSA", "LIBSSH2_HOSTKEY_TYPE_DSS", or "LIBSSH2_HOSTKEY_TYPE_UNKNOWN".

   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_password_interact ( username [, callback])
       Prompts the user for the password interactively using Term::ReadKey.

   auth_publickey ( username, publickey_path, privatekey_path [, passphrase ] )
       Note that public key and private key are names of files containing the keys!

       Authenticate using keys and an optional passphrase.

       When libssh2 is compiled using OpenSSL as the crypto backend, passing this method "undef"
       as the public key argument is acceptable (OpenSSH is able to extract the public key from
       the private one).

   auth_publickey_frommemory ( username, publickey_blob, privatekey_blob [, passphrase ] )
       Authenticate using the given public/private key and an optional passphrase. The keys must
       be PEM encoded.

       This method requires libssh2 1.6.0 or later compiled with the OpenSSL backend.

   auth_hostbased ( username, publickey, privatekey, hostname, [, local username [, passphrase ]]
       )
       Host-based authentication using an optional passphrase.  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' and 'password-interact' that
           prompts the user for the password interactively.

       username
       password
       publickey
       privatekey
       passphrase
           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.

       fallback
           If a password is given but authentication using it fails, the module will fall back to
           ask the user for another password if this parameter is set to a true value.

       cb_keyboard
           auth_keyboard callback.

       cb_password
           auth_password callback.

       For historical reasons and in order to maintain backward compatibility with older versions
       of the module, when the "password" argument is given, it is also used as the passphrase
       (and a deprecation warning generated).

       In order to avoid that behaviour the "passphrase" argument must be also passed (it could
       be "undef"). For instance:

         $ssh2->auth(username => $user,
                     privatekey => $privatekey_path,
                     publickey => $publickey_path,
                     password => $password,
                     passphrase => undef);

       This work around will be removed in a not too distant future version of the module.

   flag (key, value)
       Sets the given session flag.

       The currently supported flag values are:

       COMPRESS
           If set before the connection negotiation is performed, compression will be negotiated
           for this connection.

           Compression can also be enabled passing the "Compress" option "connect".

       SIGPIPE
           if set, Net::SSH2/libssh2 will not attempt to block SIGPIPEs but will let them trigger
           from the underlying socket layer.

   keepalive_config(want_reply, interval)
       Set how often keepalive messages should be sent.

       "want_reply" indicates whether the keepalive messages should request a response from the
       server. "interval" is number of seconds that can pass without any I/O.

   keepalive_send
       Send a keepalive message if needed.

       On failure returns undef. On success returns how many seconds you can sleep after this
       call before you need to call it again.

       Note that the underlying libssh2 function "libssh2_keepalive_send" can not recover from
       EAGAIN errors. If this method fails with such error, the SSH connection may become
       corrupted.

   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.

       The "shost" and "sport" arguments are merely informative and passed to the remote SSH
       server as the origin of the connection. They default to 127.0.0.1:22.

       Note that this method does not open a new port on the local machine and forwards incoming
       connections to the remote side.

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

   known_hosts
       Returns known hosts interface object (see Net::SSH2::KnownHosts).

   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::Any and Net::SFTP::Foreign integrate nicely with Net::SSH2.

       Other Perl modules related to SSH you may find interesting: Net::OpenSSH, Net::SSH::Perl,
       Net::OpenSSH::Parallel, Net::OpenSSH::Compat.

COPYRIGHT AND LICENSE

       Copyright (C) 2005 - 2010 by David B. Robins (dbrobins@cpan.org).

       Copyright (C) 2010 - 2015 by Rafael Kitover (rkitover@cpan.org).

       Copyright (C) 2011 - 2015 by Salvador FandiƱo (salva@cpan.org).

       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.