Net::SSH::Perl->new($host, %params)

new accepts the following named parameters in %params:

• protocol

  The protocol you wish to use for the connection: should be either 2, 1, '1,2' or '2,1'. The first two say, quite simply, "only use this version of the protocol" (SSH-2 or SSH-1, respectively). The latter two specify that either protocol can be used, but that one protocol (the first in the comma-separated list) is preferred over the other.

  For this reason, it's "safer" to use the latter two protocol specifications, because they ensure that either way, you'll be able to connect; if your server doesn't support the first protocol listed, the second will be used. (Presumably your server will support at least one of the two protocols. :)

  The default value is '1,2', for compatibility with OpenSSH; this means that the client will use SSH-1 if the server supports SSH-1. Of course, you can always override this using a user/global configuration file, or through using this constructor argument.

• cipher

  Specifies the name of the encryption cipher that you wish to use for this connection. This must be one of the supported ciphers; specifying an unsupported cipher will give you an error when you enter algorithm negotiation (in either SSH-1 or SSH-2).

  In SSH-1, the supported cipher names are IDEA, DES, DES3, and Blowfish; in SSH-2, the supported ciphers are aes256-ctr, aes192-ctr, aes128-ctr, chacha20-poly1305@openssh.com. arcfour, blowfish-cbc, and 3des-cbc are deprecated and are not enabled by default. aes256-cbc, aes192-cbc, and aes128-cbc are also supported but not enabled by default as CBC is no longer considered secure.

  The default SSH-1 cipher is IDEA; the default SSH-2 ciphers are aes256-ctr, aes192-ctr, aes128-ctr, chacha20-poly1305@openssh.com.

• ciphers

  Like cipher, this is a method of setting the cipher you wish to use for a particular SSH connection; but this corresponds to the Ciphers configuration option, where cipher corresponds to Cipher. This also applies only in SSH-2.

  This should be a comma-separated list of SSH-2 cipher names; the list of cipher names is listed above in cipher.

  This defaults to: chacha20-poly1305@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr.

• port

  The port of the sshd daemon to which you wish to connect; if not specified, this is assumed to be the default ssh port.

• debug

  Set to a true value if you want debugging messages printed out while the connection is being opened. These can be helpful in trying to determine connection problems, etc. The messages are similar (and in some cases exact) to those written out by the ssh client when you use the -v option.

  Defaults to false.

• interactive

  Set to a true value if you're using Net::SSH::Perl interactively. This is used in determining whether or not to display password prompts, for example. It's basically the inverse of the BatchMode parameter in ssh configuration.

  Defaults to false.

• privileged

  Set to a true value if you want to bind to a privileged port locally. You'll need this if you plan to use Rhosts or Rhosts-RSA authentication, because the remote server requires the client to connect on a privileged port. Of course, to bind to a privileged port you'll need to be root.

  If you don't provide this parameter, and Net::SSH::Perl detects that you're running as root, this will automatically be set to true. Otherwise it defaults to false.

• identity_files

  A list of identity files to be used in pubkey authentication. The value of this argument should be a reference to an array of strings, each string identifying the location of an identity file. Each identity file will be tested against the server until the client finds one that authenticates successfully.

  If you don't provide this, SSH1 authentication defaults to using $ENV{HOME}/.ssh/identity, and SSH2 authentication defaults to the three files $ENV{HOME}/.ssh/id_ed25519, $ENV{HOME}/.ssh/id_ecdsa, and $ENV{HOME}/.ssh/id_rsa.

• strict_host_key_checking

  This corresponds to the StrictHostKeyChecking ssh configuration option. Allowed values are no, yes, or ask. no disables host key checking, e.g., if you connect to a virtual host that answers to multiple IP addresses. yes or ask enable it, and when it fails in interactive mode, you are asked whether to continue. The host is then added to the list of known hosts.

• compression

  If set to a true value, compression is turned on for the session (assuming that the server supports it).

  Compression is off by default.

  Note that compression requires that you have the Compress::Zlib module installed on your system. If the module can't be loaded successfully, compression is disabled; you'll receive a warning stating as much if you having debugging on (debug set to 1), and you try to turn on compression.

• compression_level

  Specifies the compression level to use if compression is enabled (note that you must provide both the compression and compression_level arguments to set the level; providing only this argument will not turn on encryption).

  This setting is only applicable to SSH-1; the compression level for SSH-2 Zlib compression is always set to 6.

  The default value is 6.

• use_pty

  Set this to 1 if you want to request a pseudo tty on the remote machine. This is really only useful if you're setting up a shell connection (see the shell method, below); and in that case, unless you've explicitly declined a pty (by setting use_pty to 0), this will be set automatically to 1. In other words, you probably won't need to use this, often.

  The default is 1 if you're starting up a shell, and 0 otherwise.

• terminal_mode_string

  Specify the POSIX terminal mode string to send when use_pty is set. By default the only mode set is the VEOF character to 0x04 (opcode 5, value 0x00000004). See RFC 4254 section 8 for complete details on this value.

• no_append_veof

  (SSH-2 only) Set this to 1 if you specified use_pty and do not want Ctrl-D (0x04) appended twice to the end of your input string. On most systems, these bytes cause the terminal driver to return "EOF" when standard input is read. Without them, many programs that read from standard input will hang after consuming all the data on STDIN.

  No other modifications are made to input data. If your data contains 0x04 bytes, you may need to escape them.

  Set this to 0 if you have raw terminal data to specify on standard input, and you have terminated it correctly.

• options

  Used to specify additional options to the configuration settings; useful for specifying options for which there is no separate constructor argument. This is analogous to the -o command line flag to the ssh program.

  If used, the value should be a reference to a list of option directives in the format used in the config file. For example:

      my $ssh = Net::SSH::Perl->new("host", options => [
          "BatchMode yes", "RhostsAuthentication no" ]);
      

  Available options are:

      BindAddress
      Host
      BatchMode
      ChallengeResponseAuthentication
      CheckHostIP
      Cipher
      Ciphers*
      Compression
      CompressionLevel
      DSAAuthentication
      FingerprintHash
      GlobalKnownHostsFile
      HashKnownHosts
      HostKeyAlgorithms*
      HostName
      IdentityFile
      KexAlgorithms*
      MACs*
      NumberOfPasswordPrompts
      PasswordAuthentication
      PasswordPromptHost
      PasswordPromptLogin
      Port
      Protocol
      RhostsAuthentication
      RhostsRSAAuthentication
      RSAAuthentication
      StrictHostKeyChecking
      UpdateHostKeys
      UsePrivilegedPort
      User
      UserKnownHostsFile
      

  * Indicates the +/- wildcard notation may be used.

  For example:

      MACs +hmac-sha1
      

  will add hmac-sha1 to the default MACs list.

  Or:

      Ciphers +aes*-cbc
      

  will add aes128-cbc, aes192-cbc, and aes256-cbc to the default Ciphers

  While:

      KexAlgorithms -*-sha512
      

  will remove all algorithms that end in -sha512 from the default list.

$ssh->login([ $user [, $password [, $suppress_shell ] ] ])

The password $password is needed only for password authentication (it's not used for passphrases on encrypted RSA/DSA identity files, though perhaps it should be). And if you're running in an interactive session and you've not provided a password, you'll be prompted for one.

By default, Net::SSH::Perl will open a channel with a shell on it. This is usually what you want. If you are tunneling another protocol over SSH, however, you may want to prevent this behavior. Passing a true value in $suppress_shell will prevent the shell channel from being opened (SSH2 only).

($out, $err, $exit) = $ssh->cmd($cmd, [ $stdin ])

If $stdin is provided, it's supplied to the remote command $cmd on standard input.

NOTE: the SSH-1 protocol does not support running multiple commands per connection, unless those commands are chained together so that the remote shell can evaluate them. Because of this, a new socket connection is created each time you call cmd, and disposed of afterwards. In other words, this code:

    my $ssh = Net::SSH::Perl->new("host1");
    $ssh->login("user1", "pass1");

    $ssh->cmd("foo");
    $ssh->cmd("bar");

will actually connect to the sshd on the first invocation of cmd, then disconnect; then connect again on the second invocation of cmd, then disconnect again.

Note that this does not apply to the SSH-2 protocol. SSH-2 fully supports running more than one command over the same connection.

$ssh->shell

This is really only useful in an interactive program.

In addition, you'll probably want to set your terminal to raw input before calling this method. This lets Net::SSH::Perl process each character and send it off to the remote machine, as you type it.

To do so, use Term::ReadKey in your program:

    use Term::ReadKey;
    ReadMode('raw');
    $ssh->shell;
    ReadMode('restore');

In fact, you may want to place the "restore" line in an END block, in case your program exits prior to reaching that line.

If you need an example, take a look at eg/pssh, which uses almost this exact code to implement an ssh shell.

$ssh->register_handler($packet_type, $subref [, @args ])

The client loop is entered after the client has sent a command to the remote server, and after any STDIN data has been sent; it consists of reading packets from the server (STDOUT packets, STDERR packets, etc.) until the server sends the exit status of the command executed remotely. At this point the client exits the client loop and disconnects from the server.

When you call the cmd method, the client loop by default simply sticks STDOUT packets into a scalar variable and returns that value to the caller. It does the same for STDERR packets, and for the process exit status. (See the docs for cmd).

You can, however, override that default behavior, and instead process the data itself as it is sent to the client. You do this by calling the register_handler method and setting up handlers to be called at specific times.

The behavior of the register_handler method differs between the Net::SSH::Perl SSH-1 and SSH-2 implementations. This is so because of the differences between the protocols (all client-server communications in SSH-2 go through the channel mechanism, which means that input packets are processed differently).

• SSH-1 Protocol

  In the SSH-1 protocol, you should call register_handler with two arguments: a packet type $packet_type and a subroutine reference $subref. Your subroutine will receive as arguments the Net::SSH::Perl::SSH1 object (with an open connection to the ssh3), and a Net::SSH::Perl::Packet object, which represents the packet read from the server. It will also receive any additional arguments @args that you pass to register_handler; this can be used to give your callback functions access to some of your otherwise private variables, if desired. $packet_type should be an integer constant; you can import the list of constants into your namespace by explicitly loading the Net::SSH::Perl::Constants module:

      use Net::SSH::Perl::Constants qw( :msg );
      

  This will load all of the MSG constants into your namespace so that you can use them when registering the handler. To do that, use this method. For example:

      $ssh->register_handler(SSH_SMSG_STDOUT_DATA, sub {
          my($ssh, $packet) = @_;
          print "I received this: ", $packet->get_str;
      });
      

  To learn about the methods that you can call on the packet object, take a look at the Net::SSH::Perl::Packet docs, as well as the Net::SSH::Perl::Buffer docs (the get_* and put_* methods).

  Obviously, writing these handlers requires some knowledge of the contents of each packet. For that, read through the SSH RFC, which explains each packet type in detail. There's a get_* method for each datatype that you may need to read from a packet.

  Take a look at eg/remoteinteract.pl for an example of interacting with a remote command through the use of register_handler.

• SSH-2 Protocol

  In the SSH-2 protocol, you call register_handler with two arguments: a string identifying the type of handler you wish to create, and a subroutine reference. The "string" should be, at this point, either "stdout" or "stderr"; any other string will be silently ignored. "stdout" denotes that you wish to handle STDOUT data sent from the server, and "stderr" that you wish to handle STDERR data.

  Your subroutine reference will be passed two arguments: a Net::SSH::Perl::Channel object that represents the open channel on which the data was sent, and a Net::SSH::Perl::Buffer object containing data read from the server. In addition to these two arguments, the callback will be passed any additional arguments @args that you passed to register_handler; this can be used to give your callback functions to otherwise private variables, if desired.

  This illustrates the two main differences between the SSH-1 and SSH-2 implementations. The first difference is that, as mentioned above, all communication between server and client is done through channels, which are built on top of the main connection between client and server. Multiple channels are multiplexed over the same connection. The second difference is that, in SSH-1, you are processing the actual packets as they come in; in SSH-2, the packets have already been processed somewhat, and their contents stored in buffers--you are processing those buffers.

  The above example (the I received this example) of using register_handler in SSH-1 would look like this in SSH-2:

      $ssh->register_handler("stdout", sub {
          my($channel, $buffer) = @_;
          print "I received this: ", $buffer->bytes;
      });
      

  As you can see, it's quite similar to the form used in SSH-1, but with a few important differences, due to the differences mentioned above between SSH-1 and SSH-2.

$ssh->config

$ssh->sock

$ssh->debug($msg)

$ssh->incoming_data

The idea behind this is that we our socket is non-blocking, so we buffer input and periodically check back to see if we've read a full packet. If we have a full packet, we rip it out of the incoming data buffer and process it, returning it to the caller who presumably asked for it.

This data "belongs" to the underlying packet layer in Net::SSH::Perl::Packet. Unless you really know what you're doing you probably don't want to disturb that data.

$ssh->session_id

$packet = $ssh->packet_start($packet_type)