The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Net-SSH-Perl-0.52
River stage one • 9 direct dependents • 9 total dependents
19 ++
/ Net::SSH::Perl

NAME

Net::SSH::Perl - Perl client Interface to SSH

SYNOPSIS

    use Net::SSH::Perl;
    my $ssh = Net::SSH::Perl->new($host);
    $ssh->login($user, $pass);
    my($stdout, $stderr, $exit) = $ssh->cmd($cmd);

DESCRIPTION

Net::SSH::Perl is an all-Perl module implementing an ssh client. In other words, it isn't a wrapper around the actual ssh client, which is both good and bad. The good is that you don't have to fork another process to connect to an sshd daemon, so you save on overhead, which is a big win. The bad is that currently Net::SSH::Perl doesn't support all of the authentication protocols and encryption ciphers that the actual ssh program does, so you can't take advantage of them. (For a list of what ciphers and auth methods are supported, keep reading.)

Of course, I think that the good outweighs the bad (particularly since the bad is something that can be improved and worked on), and that's why Net::SSH::Perl exists.

BASIC USAGE

Usage of Net::SSH::Perl is very simple.

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

To set up a new connection, call the new method, which connects to $host and returns a Net::SSH::Perl object.

new accepts the following named parameters in %params:

  • cipher

    Specifies the name of the encryption cipher that you wish to use for this connection. This must be one of the supported ciphers (currently, IDEA, DES, DES3, and Blowfish); specifying an unsupported cipher is a fatal error. The default cipher is IDEA.

  • 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 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 RSA identity files to be used in RSA authentication. The value of this argument should be a reference to an array of strings, each string identifying the location of an identity file.

    If you don't provide this, RSA authentication defaults to using "$ENV{HOME}/.ssh/identity".

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

Sets the username and password to be used when authenticating with the sshd daemon. The username $user is required for all authentication protocols (to identify yourself to the remote server), but if you don't supply it the currently logged-in user is used instead.

The password $password is needed only for password authentication (it's not used for RSA passphrase authentication, 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.

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

Runs the command $cmd on the remote server and returns the stdout, stderr, and exit status of that command.

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

NOTE: the ssh protocol does not support (so far as I know) 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.

This is less than ideal, obviously. Future version of Net::SSH::Perl may find ways around that.

ADVANCED METHODS

Your basic SSH needs will hopefully be met by the methods listed above. If they're not, however, you may want to use some of the additional methods listed here. Some of these are aimed at end-users, while others are probably more useful for actually writing an authentication module, or a cipher, etc.

$ssh->sock

Returns the socket connection to sshd. If your client is not connected, dies.

$ssh->debug($msg)

If debugging is turned on for this session (see the debug parameter to the new method, above), writes $msg to STDERR. Otherwise nothing is done.

$ssh->in_leftover([ $leftover ])

"Input leftover"; you can use this to store the data left over from the last socket read, the data that wasn't read into a packet on the client side. This is needed because we read as much data as we can (up to 8192) from the remote socket; not all of the data we read comprises one single packet, however. Your client code, though, will most likely have asked for one single packet; so we need some way to store the leftover data between reads.

If passed $leftover, sets the internal leftover buffer.

Returns the contents of the leftover buffer.

$ssh->set_cipher($cipher_name)

Sets the cipher for the SSH session $ssh to $cipher_name (which must be a valid cipher name), and turns on encryption for that session.

$ssh->send_cipher

Returns the "send" cipher object. This is the object that encrypts outgoing data.

If it's not defined, encryption is not turned on for the session.

$ssh->receive_cipher

Returns the "receive" cipher object. This is the object that decrypts incoming data.

If it's not defined, encryption is not turned on for the session.

NOTE: the send and receive ciphers and two different objects, each with its own internal state (initialization vector, in particular). Thus they cannot be interchanged.

$ssh->session_key

Returns the session key, which is simply 32 bytes of random data and is used as the encryption/decryption key.

$ssh->session_id

Returns the session ID, which is generated from the server's host and server keys, and from the check bytes that it sends along with the keys. The server may require the session ID to be passed along in other packets, as well (for example, when responding to RSA challenges).

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

Starts building a new packet of type $packet_type. This is just a handy method for lazy people. Internally it calls Net::SSH::Perl::Packet::new, so take a look at those docs for more details.

SUPPORT

For samples/tutorials, take a look at the scripts in eg/ in the distribution directory.

If you have any questions, code samples, bug reports, or feedback, please email them to:

    ben@rhumba.pair.com

AUTHOR & COPYRIGHT

Benjamin Trott, ben@rhumba.pair.com

Except where otherwise noted, Net::SSH::Perl is Copyright 2001 Benjamin Trott. All rights reserved. Net::SSH::Perl is free software; you may redistribute it and/or modify it under the same terms as Perl itself.