1Net::SSH::Perl(3) User Contributed Perl Documentation Net::SSH::Perl(3)
2
6 Net::SSH::Perl - Perl client Interface to SSH
7
9 use Net::SSH::Perl;
10 my $ssh = Net::SSH::Perl->new($host);
11 $ssh->login($user, $pass);
12 my($stdout, $stderr, $exit) = $ssh->cmd($cmd);
13
15 Net::SSH::Perl is an all-Perl module implementing an SSH (Secure Shell)
16 client. It is compatible with both the SSH-1 and SSH-2 protocols.
17 Net::SSH::Perl enables you to simply and securely execute commands on
19 remote machines, and receive the STDOUT, STDERR, and exit status of
20 that remote command. It contains built-in support for various methods
21 of authenticating with the server (password authentication, RSA
22 challenge-response authentication, etc.). It completely implements the
23 I/O buffering, packet transport, and user authentication layers of the
24 SSH protocol, and makes use of external Perl libraries (in the Crypt::
25 family of modules) to handle encryption of all data sent across the
26 insecure network. It can also read your existing SSH configuration
27 files (/etc/ssh_config, etc.), RSA identity files, DSA identity files,
28 known hosts files, etc.
29 One advantage to using Net::SSH::Perl over wrapper-style
31 implementations of ssh clients is that it saves on process overhead:
32 you no longer need to fork and execute a separate process in order to
33 connect to an sshd. Depending on the amount of time and memory needed
34 to fork a process, this win can be quite substantial; particularly if
35 you're running in a persistent Perl environment (mod_perl, for
36 example), where forking a new process is a drain on process and memory
37 resources.
38 It also simplifies the process of using password-based authentications;
40 when writing a wrapper around ssh you probably need to use Expect to
41 control the ssh client and give it your password. Net::SSH::Perl has
42 built-in support for the authentication protocols, so there's no longer
43 any hassle of communicating with any external processes.
44 The SSH2 protocol support (present in Net::SSH::Perl as of version
46 1.00) is compatible with the SSH2 implementation in OpenSSH, and should
47 also be fully compatible with the "official" SSH implementation. If you
48 find an SSH2 implementation that is not compatible with Net::SSH::Perl,
49 please let me know (email address down in AUTHOR & COPYRIGHTS); it
50 turns out that some SSH2 implementations have subtle differences from
51 others. 3DES ("3des-cbc"), Blowfish ("blowfish-cbc"), and RC4
52 ("arcfour") ciphers are currently supported for SSH2 encryption, and
53 integrity checking is performed by either the "hmac-sha1" or "hmac-md5"
54 algorithms. Compression, if requested, is limited to Zlib. Supported
55 server host key algorithms are "ssh-dss" (the default) and "ssh-rsa"
56 (requires Crypt::RSA); supported SSH2 public key authentication
57 algorithms are the same.
58 If you're looking for SFTP support, take a look at Net::SFTP, which
60 provides a full-featured Perl implementation of SFTP, and sits on top
61 of Net::SSH::Perl. SFTP requires the usage of the SSH2 protocol.
62
64 Usage of Net::SSH::Perl is very simple.
65 Net::SSH::Perl->new($host, %params)
67 To set up a new connection, call the new method, which connects to
68 $host and returns a Net::SSH::Perl object.
69 new accepts the following named parameters in %params:
71 · protocol
73 The protocol you wish to use for the connection: should be either
75 2, 1, '1,2' or '2,1'. The first two say, quite simply, "only use
76 this version of the protocol" (SSH-2 or SSH-1, respectively). The
77 latter two specify that either protocol can be used, but that one
78 protocol (the first in the comma-separated list) is preferred over
79 the other.
80 For this reason, it's "safer" to use the latter two protocol
82 specifications, because they ensure that either way, you'll be able
83 to connect; if your server doesn't support the first protocol
84 listed, the second will be used. (Presumably your server will
85 support at least one of the two protocols. :)
86 The default value is '1,2', for compatibility with OpenSSH; this
88 means that the client will use SSH-1 if the server supports SSH-1.
89 Of course, you can always override this using a user/global
90 configuration file, or through using this constructor argument.
91 · cipher
93 Specifies the name of the encryption cipher that you wish to use
95 for this connection. This must be one of the supported ciphers;
96 specifying an unsupported cipher will give you an error when you
97 enter algorithm negotiation (in either SSH-1 or SSH-2).
98 In SSH-1, the supported cipher names are IDEA, DES, DES3, and
100 Blowfish; in SSH-2, the supported ciphers are arcfour, blowfish-
101 cbc, and 3des-cbc.
102 The default SSH-1 cipher is IDEA; the default SSH-2 cipher is
104 3des-cbc.
105 · ciphers
107 Like cipher, this is a method of setting the cipher you wish to use
109 for a particular SSH connection; but this corresponds to the
110 Ciphers configuration option, where cipher corresponds to Cipher.
111 This also applies only in SSH-2.
112 This should be a comma-separated list of SSH-2 cipher names; the
114 list of cipher names is listed above in cipher.
115 This defaults to 3des-cbc,blowfish-cbc,arcfour.
117 · port
119 The port of the sshd daemon to which you wish to connect; if not
121 specified, this is assumed to be the default ssh port.
122 · debug
124 Set to a true value if you want debugging messages printed out
126 while the connection is being opened. These can be helpful in
127 trying to determine connection problems, etc. The messages are
128 similar (and in some cases exact) to those written out by the ssh
129 client when you use the -v option.
130 Defaults to false.
132 · interactive
134 Set to a true value if you're using Net::SSH::Perl interactively.
136 This is used in determining whether or not to display password
137 prompts, for example. It's basically the inverse of the BatchMode
138 parameter in ssh configuration.
139 Defaults to false.
141 · privileged
143 Set to a true value if you want to bind to a privileged port
145 locally. You'll need this if you plan to use Rhosts or Rhosts-RSA
146 authentication, because the remote server requires the client to
147 connect on a privileged port. Of course, to bind to a privileged
148 port you'll need to be root.
149 If you don't provide this parameter, and Net::SSH::Perl detects
151 that you're running as root, this will automatically be set to
152 true. Otherwise it defaults to false.
153 · identity_files
155 A list of RSA/DSA identity files to be used in RSA/DSA
157 authentication. The value of this argument should be a reference
158 to an array of strings, each string identifying the location of an
159 identity file. Each identity file will be tested against the server
160 until the client finds one that authenticates successfully.
161 If you don't provide this, RSA authentication defaults to using
163 $ENV{HOME}/.ssh/identity, and DSA authentication defaults to
164 $ENV{HOME}/.ssh/id_dsa.
165 · compression
167 If set to a true value, compression is turned on for the session
169 (assuming that the server supports it).
170 Compression is off by default.
172 Note that compression requires that you have the Compress::Zlib
174 module installed on your system. If the module can't be loaded
175 successfully, compression is disabled; you'll receive a warning
176 stating as much if you having debugging on (debug set to 1), and
177 you try to turn on compression.
178 · compression_level
180 Specifies the compression level to use if compression is enabled
182 (note that you must provide both the compression and
183 compression_level arguments to set the level; providing only this
184 argument will not turn on encryption).
185 This setting is only applicable to SSH-1; the compression level for
187 SSH-2 Zlib compression is always set to 6.
188 The default value is 6.
190 · use_pty
192 Set this to 1 if you want to request a pseudo tty on the remote
194 machine. This is really only useful if you're setting up a shell
195 connection (see the shell method, below); and in that case, unless
196 you've explicitly declined a pty (by setting use_pty to 0), this
197 will be set automatically to 1. In other words, you probably won't
198 need to use this, often.
199 The default is 1 if you're starting up a shell, and 0 otherwise.
201 · options
203 Used to specify additional options to the configuration settings;
205 useful for specifying options for which there is no separate
206 constructor argument. This is analogous to the -o command line flag
207 to the ssh program.
208 If used, the value should be a reference to a list of option
210 directives in the format used in the config file. For example:
211 my $ssh = Net::SSH::Perl->new("host", options => [
213 "BatchMode yes", "RhostsAuthentication no" ]);
214 $ssh->login([ $user [, $password [, $suppress_shell ] ] ])
216 Sets the username and password to be used when authenticating with the
217 sshd daemon. The username $user is required for all authentication
218 protocols (to identify yourself to the remote server), but if you don't
219 supply it the username of the user executing the program is used.
220 The password $password is needed only for password authentication (it's
222 not used for passphrases on encrypted RSA/DSA identity files, though
223 perhaps it should be). And if you're running in an interactive session
224 and you've not provided a password, you'll be prompted for one.
225 By default, Net::SSH::Perl will open a channel with a shell on it. This
227 is usually what you want. If you are tunneling another protocol over
228 SSH, however, you may want to prevent this behavior. Passing a true
229 value in $suppress_shell will prevent the shell channel from being
230 opened (SSH2 only).
231 ($out, $err, $exit) = $ssh->cmd($cmd, [ $stdin ])
233 Runs the command $cmd on the remote server and returns the stdout,
234 stderr, and exit status of that command.
235 If $stdin is provided, it's supplied to the remote command $cmd on
237 standard input.
238 NOTE: the SSH-1 protocol does not support running multiple commands per
240 connection, unless those commands are chained together so that the
241 remote shell can evaluate them. Because of this, a new socket
242 connection is created each time you call cmd, and disposed of
243 afterwards. In other words, this code:
244 my $ssh = Net::SSH::Perl->new("host1");
246 $ssh->login("user1", "pass1");
247 $ssh->cmd("foo");
249 $ssh->cmd("bar");
250 will actually connect to the sshd on the first invocation of cmd, then
252 disconnect; then connect again on the second invocation of cmd, then
253 disconnect again.
254 Note that this does not apply to the SSH-2 protocol. SSH-2 fully
256 supports running more than one command over the same connection.
257 $ssh->shell
259 Opens up an interactive shell on the remote machine and connects it to
260 your STDIN. This is most effective when used with a pseudo tty;
261 otherwise you won't get a command line prompt, and it won't look much
262 like a shell. For this reason--unless you've specifically declined
263 one--a pty will be requested from the remote machine, even if you
264 haven't set the use_pty argument to new (described above).
265 This is really only useful in an interactive program.
267 In addition, you'll probably want to set your terminal to raw input
269 before calling this method. This lets Net::SSH::Perl process each
270 character and send it off to the remote machine, as you type it.
271 To do so, use Term::ReadKey in your program:
273 use Term::ReadKey;
275 ReadMode('raw');
276 $ssh->shell;
277 ReadMode('restore');
278 In fact, you may want to place the "restore" line in an END block, in
280 case your program exits prior to reaching that line.
281 If you need an example, take a look at eg/pssh, which uses almost this
283 exact code to implement an ssh shell.
284 $ssh->register_handler($packet_type, $subref [, @args ])
286 Registers an anonymous subroutine handler $subref to handle packets of
287 type $packet_type during the client loop. The subroutine will be called
288 when packets of type $packet_type are received, and in addition to the
289 standard arguments (see below), will receive any additional arguments
290 in @args, if specified.
291 The client loop is entered after the client has sent a command to the
293 remote server, and after any STDIN data has been sent; it consists of
294 reading packets from the server (STDOUT packets, STDERR packets, etc.)
295 until the server sends the exit status of the command executed
296 remotely. At this point the client exits the client loop and
297 disconnects from the server.
298 When you call the cmd method, the client loop by default simply sticks
300 STDOUT packets into a scalar variable and returns that value to the
301 caller. It does the same for STDERR packets, and for the process exit
302 status. (See the docs for cmd).
303 You can, however, override that default behavior, and instead process
305 the data itself as it is sent to the client. You do this by calling the
306 register_handler method and setting up handlers to be called at
307 specific times.
308 The behavior of the register_handler method differs between the
310 Net::SSH::Perl SSH-1 and SSH-2 implementations. This is so because of
311 the differences between the protocols (all client-server communications
312 in SSH-2 go through the channel mechanism, which means that input
313 packets are processed differently).
314 · SSH-1 Protocol
316 In the SSH-1 protocol, you should call register_handler with two
318 arguments: a packet type $packet_type and a subroutine reference
319 $subref. Your subroutine will receive as arguments the
320 Net::SSH::Perl::SSH1 object (with an open connection to the ssh3),
321 and a Net::SSH::Perl::Packet object, which represents the packet
322 read from the server. It will also receive any additional arguments
323 @args that you pass to register_handler; this can be used to give
324 your callback functions access to some of your otherwise private
325 variables, if desired. $packet_type should be an integer constant;
326 you can import the list of constants into your namespace by
327 explicitly loading the Net::SSH::Perl::Constants module:
328 use Net::SSH::Perl::Constants qw( :msg );
330 This will load all of the MSG constants into your namespace so that
332 you can use them when registering the handler. To do that, use this
333 method. For example:
334 $ssh->register_handler(SSH_SMSG_STDOUT_DATA, sub {
336 my($ssh, $packet) = @_;
337 print "I received this: ", $packet->get_str;
338 });
339 To learn about the methods that you can call on the packet object,
341 take a look at the Net::SSH::Perl::Packet docs, as well as the
342 Net::SSH::Perl::Buffer docs (the get_* and put_* methods).
343 Obviously, writing these handlers requires some knowledge of the
345 contents of each packet. For that, read through the SSH RFC, which
346 explains each packet type in detail. There's a get_* method for
347 each datatype that you may need to read from a packet.
348 Take a look at eg/remoteinteract.pl for an example of interacting
350 with a remote command through the use of register_handler.
351 · SSH-2 Protocol
353 In the SSH-2 protocol, you call register_handler with two
355 arguments: a string identifying the type of handler you wish to
356 create, and a subroutine reference. The "string" should be, at this
357 point, either "stdout" or "stderr"; any other string will be
358 silently ignored. "stdout" denotes that you wish to handle STDOUT
359 data sent from the server, and "stderr" that you wish to handle
360 STDERR data.
361 Your subroutine reference will be passed two arguments: a
363 Net::SSH::Perl::Channel object that represents the open channel on
364 which the data was sent, and a Net::SSH::Perl::Buffer object
365 containing data read from the server. In addition to these two
366 arguments, the callback will be passed any additional arguments
367 @args that you passed to register_handler; this can be used to give
368 your callback functions to otherwise private variables, if desired.
369 This illustrates the two main differences between the SSH-1 and
371 SSH-2 implementations. The first difference is that, as mentioned
372 above, all communication between server and client is done through
373 channels, which are built on top of the main connection between
374 client and server. Multiple channels are multiplexed over the same
375 connection. The second difference is that, in SSH-1, you are
376 processing the actual packets as they come in; in SSH-2, the
377 packets have already been processed somewhat, and their contents
378 stored in buffers--you are processing those buffers.
379 The above example (the I received this example) of using
381 register_handler in SSH-1 would look like this in SSH-2:
382 $ssh->register_handler("stdout", sub {
384 my($channel, $buffer) = @_;
385 print "I received this: ", $buffer->bytes;
386 });
387 As you can see, it's quite similar to the form used in SSH-1, but
389 with a few important differences, due to the differences mentioned
390 above between SSH-1 and SSH-2.
391
393 Your basic SSH needs will hopefully be met by the methods listed above.
394 If they're not, however, you may want to use some of the additional
395 methods listed here. Some of these are aimed at end-users, while others
396 are probably more useful for actually writing an authentication module,
397 or a cipher, etc.
398 $ssh->config
400 Returns the Net::SSH::Perl::Config object managing the configuration
401 data for this SSH object. This is constructed from data passed in to
402 the constructor new (see above), merged with data read from the user
403 and system configuration files. See the Net::SSH::Perl::Config docs for
404 details on methods you can call on this object (you'll probably be more
405 interested in the get and set methods).
406 $ssh->sock
408 Returns the socket connection to sshd. If your client is not connected,
409 dies.
410 $ssh->debug($msg)
412 If debugging is turned on for this session (see the debug parameter to
413 the new method, above), writes $msg to "STDERR". Otherwise nothing is
414 done.
415 $ssh->incoming_data
417 Incoming data buffer, an object of type Net::SSH::Perl::Buffer.
418 Returns the buffer object.
419 The idea behind this is that we our socket is non-blocking, so we
421 buffer input and periodically check back to see if we've read a full
422 packet. If we have a full packet, we rip it out of the incoming data
423 buffer and process it, returning it to the caller who presumably asked
424 for it.
425 This data "belongs" to the underlying packet layer in
427 Net::SSH::Perl::Packet. Unless you really know what you're doing you
428 probably don't want to disturb that data.
429 $ssh->session_id
431 Returns the session ID, which is generated from the server's host and
432 server keys, and from the check bytes that it sends along with the
433 keys. The server may require the session ID to be passed along in other
434 packets, as well (for example, when responding to RSA challenges).
435 $packet = $ssh->packet_start($packet_type)
437 Starts building a new packet of type $packet_type. This is just a handy
438 method for lazy people. Internally it calls
439 Net::SSH::Perl::Packet::new, so take a look at those docs for more
440 details.
441
443 For samples/tutorials, take a look at the scripts in eg/ in the
444 distribution directory.
445 There is a mailing list for development discussion and usage questions.
447 Posting is limited to subscribers only. You can sign up at
448 http://lists.sourceforge.net/lists/listinfo/ssh-sftp-perl-users
449 Please report all bugs via rt.cpan.org at
451 https://rt.cpan.org/NoAuth/ReportBug.html?Queue=net%3A%3Assh%3A%3Aperl
452
454 Current maintainer is David Robins, dbrobins@cpan.org.
455 Previous maintainer was Dave Rolsky, autarch@urth.org.
457 Originally written by Benjamin Trott.
459
461 Copyright (c) 2001-2003 Benjamin Trott, Copyright (c) 2003-2008 David
462 Rolsky. Copyright (c) David Robins. All rights reserved. This
463 program is free software; you can redistribute it and/or modify it
464 under the same terms as Perl itself.
465 The full text of the license can be found in the LICENSE file included
467 with this module.
468perl v5.12.2 2009-02-02 Net::SSH::Perl(3)