| Net::SSH::Perl - Perl client Interface to SSH |
debug($msg)packet_start($packet_type)
Net::SSH::Perl - Perl client Interface to SSH
use Net::SSH::Perl;
my $ssh = Net::SSH::Perl->new($host);
$ssh->login($user, $pass);
my($stdout, $stderr, $exit) = $ssh->cmd($cmd);
Net::SSH::Perl is an all-Perl module implementing an SSH (Secure Shell) client. It is compatible with both the SSH-1 and SSH-2 protocols.
Net::SSH::Perl enables you to simply and securely execute commands on remote machines, and receive the STDOUT, STDERR, and exit status of that remote command. It contains built-in support for various methods of authenticating with the server (password authentication, RSA challenge-response authentication, etc.). It completely implements the I/O buffering, packet transport, and user authentication layers of the SSH protocol, and makes use of external Perl libraries (in the Crypt:: family of modules) to handle encryption of all data sent across the insecure network. It can also read your existing SSH configuration files (/etc/ssh_config, etc.), RSA identity files, DSA identity files, known hosts files, etc.
One advantage to using Net::SSH::Perl over wrapper-style implementations of ssh clients is that it saves on process overhead: you no longer need to fork and execute a separate process in order to connect to an sshd. Depending on the amount of time and memory needed to fork a process, this win can be quite substantial; particularly if you're running in a persistent Perl environment (mod_perl, for example), where forking a new process is a drain on process and memory resources.
It also simplifies the process of using password-based authentications; when writing a wrapper around ssh you probably need to use Expect to control the ssh client and give it your password. Net::SSH::Perl has built-in support for the authentication protocols, so there's no longer any hassle of communicating with any external processes.
The SSH2 protocol support (present in Net::SSH::Perl as of version
1.00) is compatible with the SSH2 implementation in OpenSSH, and should
also be fully compatible with the ``official'' SSH implementation. If
you find an SSH2 implementation that is not compatible with
Net::SSH::Perl, please let me know (email address down in
AUTHOR & COPYRIGHTS); it turns out that some SSH2 implementations
have subtle differences from others. 3DES (3des-cbc), Blowfish
(blowfish-cbc), and RC4 (arcfour) ciphers are currently
supported for SSH2 encryption, and integrity checking is performed
by either the hmac-sha1 or hmac-md5 algorithms. Compression, if
requested, is limited to Zlib. Supported server host key algorithms
are ssh-dss (the default) and ssh-rsa (requires Crypt::RSA);
supported SSH2 public key authentication algorithms are the same.
If you're looking for SFTP support, take a look at Net::SFTP, which provides a full-featured Perl implementation of SFTP, and sits on top of Net::SSH::Perl. SFTP requires the usage of the SSH2 protocol.
Usage of Net::SSH::Perl is very simple.
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:
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.
In SSH-1, the supported cipher names are IDEA, DES, DES3, and Blowfish; in SSH-2, the supported ciphers are arcfour, blowfish-cbc, and 3des-cbc.
The default SSH-1 cipher is IDEA; the default SSH-2 cipher is 3des-cbc.
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 3des-cbc,blowfish-cbc,arcfour.
Defaults to false.
Defaults to false.
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.
If you don't provide this, RSA authentication defaults to using $ENV{HOME}/.ssh/identity, and DSA authentication defaults to $ENV{HOME}/.ssh/id_dsa.
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.
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.
The default is 1 if you're starting up a shell, and 0 otherwise.
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.
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" ]);
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 username of the user executing the program is used.
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).
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-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.
Opens up an interactive shell on the remote machine and connects it to your STDIN. This is most effective when used with a pseudo tty; otherwise you won't get a command line prompt, and it won't look much like a shell. For this reason--unless you've specifically declined one--a pty will be requested from the remote machine, even if you haven't set the use_pty argument to new (described above).
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.
Registers an anonymous subroutine handler $subref to handle packets of type $packet_type during the client loop. The subroutine will be called when packets of type $packet_type are received, and in addition to the standard arguments (see below), will receive any additional arguments in @args, if specified.
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).
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.
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.
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.
Returns the Net::SSH::Perl::Config object managing the configuration data for this SSH object. This is constructed from data passed in to the constructor new (see above), merged with data read from the user and system configuration files. See the Net::SSH::Perl::Config docs for details on methods you can call on this object (you'll probably be more interested in the get and set methods).
Returns the socket connection to sshd. If your client is not connected, dies.
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.
Incoming data buffer, an object of type Net::SSH::Perl::Buffer. Returns the buffer object.
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.
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_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.
For samples/tutorials, take a look at the scripts in eg/ in the distribution directory.
There is a mailing list for development discussion and usage questions. Posting is limited to subscribers only. You can sign up at http://lists.sourceforge.net/lists/listinfo/ssh-sftp-perl-users
Please report all bugs via rt.cpan.org at https://rt.cpan.org/NoAuth/ReportBug.html?Queue=net%3A%3Assh%3A%3Aperl
Current maintainer is David Robins, dbrobins@cpan.org.
Previous maintainer was Dave Rolsky, autarch@urth.org.
Originally written by Benjamin Trott.
Copyright (c) 2001-2003 Benjamin Trott, Copyright (c) 2003-2008 David Rolsky. Copyright (c) David Robins. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
| Net::SSH::Perl - Perl client Interface to SSH |