++ed by:
HUBAN MPERRY KEEDI FVOX VTFRVL

7 PAUSE users
6 non-PAUSE users.

Benjamin Trott

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

INSTALLATION

Net::SSH::Perl installation is relatively straightforward. The only slightly complicated bit is that you'll need to install Crypt:: modules depending on which ciphers you wish to use. This has been made quite easy if you use the CPAN shell to install Net::SSH::Perl; the installation process will ask you which ciphers you wish to have installed, and will then add the Crypt:: modules as prerequisites. The CPAN shell should then install them automatically.

Even if you're not using the CPAN shell, the installation script tries to make things easy by detecting which modules you'll need to install, then loading the CPAN shell and installing them, if you want.

If you don't like either of those options you'll need to do the installations manually. In which case you'll need to install Math::GMP (version 1.04 or greater), String::CRC32 (version 1.2 or greater), and Digest::MD5, plus any additional Crypt:: modules you wish to use.

Net::SSH::Perl itself installs like a Perl module should:

    % perl Makefile.PL
    % make && make test && make install

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.

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, and DES3); 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.

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

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

ENCRYPTION CIPHERS

Net::SSH::Perl currently supports 4 encryption ciphers: IDEA, DES, 3DES, and Blowfish.

In order to use the ciphers you'll need to install the corresponding Crypt:: module. I've not listed any of these modules as prerequisites above, but during the installation process you'll be prompted to add some of these modules so that you can use the encryption. If you're using the CPAN shell, the modules should be automatically installed; otherwise you'll need to do so yourself.

AUTHOR

Benjamin Trott, ben@rhumba.pair.com

SUPPORT

Take a look at the scripts in eg/ for help and examples of using Net::SSH::Perl. eg/cmd.pl is just a simple example of some of the functionality, eg/pssh is an ssh-like client for running commands on other servers, and eg/pscp is a very simple scp-like script. Both pssh and pscp support a subset of the command line options that the actual tools support; obviously, only those options supported by Net::SSH::Perl are supported by pssh and pscp.

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

    ben@rhumba.pair.com

COPYRIGHT

(C) 2001 Benjamin Trott. All rights reserved.