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 chal‐
22 lenge-response authentication, etc.). It completely implements the I/O
23 buffering, packet transport, and user authentication layers of the SSH
24 protocol, and makes use of external Perl libraries (in the Crypt:: fam‐
25 ily of modules) to handle encryption of all data sent across the inse‐
26 cure network. It can also read your existing SSH configuration files
27 (/etc/ssh_config, etc.), RSA identity files, DSA identity files, known
28 hosts files, etc.
29 One advantage to using Net::SSH::Perl over wrapper-style implementa‐
31 tions of ssh clients is that it saves on process overhead: you no
32 longer need to fork and execute a separate process in order to connect
33 to an sshd. Depending on the amount of time and memory needed to fork a
34 process, this win can be quite substantial; particularly if you're run‐
35 ning in a persistent Perl environment (mod_perl, for example), where
36 forking a new process is a drain on process and memory resources.
37 It also simplifies the process of using password-based authentications;
39 when writing a wrapper around ssh you probably need to use Expect to
40 control the ssh client and give it your password. Net::SSH::Perl has
41 built-in support for the authentication protocols, so there's no longer
42 any hassle of communicating with any external processes.
43 The SSH2 protocol support (present in Net::SSH::Perl as of version
45 1.00) is compatible with the SSH2 implementation in OpenSSH, and should
46 also be fully compatible with the "official" SSH implementation. If you
47 find an SSH2 implementation that is not compatible with Net::SSH::Perl,
48 please let me know (email address down in AUTHOR & COPYRIGHTS); it
49 turns out that some SSH2 implementations have subtle differences from
50 others. 3DES ("3des-cbc"), Blowfish ("blowfish-cbc"), and RC4 ("arc‐
51 four") ciphers are currently supported for SSH2 encryption, and
52 integrity checking is performed by either the "hmac-sha1" or "hmac-md5"
53 algorithms. Compression, if requested, is limited to Zlib. Supported
54 server host key algorithms are "ssh-dss" (the default) and "ssh-rsa"
55 (requires Crypt::RSA); supported SSH2 public key authentication algo‐
56 rithms are the same.
57 If you're looking for SFTP support, take a look at Net::SFTP, which
59 provides a full-featured Perl implementation of SFTP, and sits on top
60 of Net::SSH::Perl. SFTP requires the usage of the SSH2 protocol.
61
63 Usage of Net::SSH::Perl is very simple.
64 Net::SSH::Perl->new($host, %params)
66 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
74 2, 1, '1,2' or '2,1'. The first two say, quite simply, "only use
75 this version of the protocol" (SSH-2 or SSH-1, respectively). The
76 latter two specify that either protocol can be used, but that one
77 protocol (the first in the comma-separated list) is preferred over
78 the other.
79 For this reason, it's "safer" to use the latter two protocol speci‐
81 fications, because they ensure that either way, you'll be able to
82 connect; if your server doesn't support the first protocol listed,
83 the second will be used. (Presumably your server will support at
84 least one of the two protocols. :)
85 The default value is '1,2', for compatibility with OpenSSH; this
87 means that the client will use SSH-1 if the server supports SSH-1.
88 Of course, you can always override this using a user/global config‐
89 uration file, or through using this constructor argument.
90 * cipher
92 Specifies the name of the encryption cipher that you wish to use
93 for this connection. This must be one of the supported ciphers;
94 specifying an unsupported cipher will give you an error when you
95 enter algorithm negotiation (in either SSH-1 or SSH-2).
96 In SSH-1, the supported cipher names are IDEA, DES, DES3, and Blow‐
98 fish; in SSH-2, the supported ciphers are arcfour, blowfish-cbc,
99 and 3des-cbc.
100 The default SSH-1 cipher is IDEA; the default SSH-2 cipher is
102 3des-cbc.
103 * ciphers
105 Like cipher, this is a method of setting the cipher you wish to use
106 for a particular SSH connection; but this corresponds to the
107 Ciphers configuration option, where cipher corresponds to Cipher.
108 This also applies only in SSH-2.
109 This should be a comma-separated list of SSH-2 cipher names; the
111 list of cipher names is listed above in cipher.
112 This defaults to 3des-cbc,blowfish-cbc,arcfour.
114 * port
116 The port of the sshd daemon to which you wish to connect; if not
117 specified, this is assumed to be the default ssh port.
118 * debug
120 Set to a true value if you want debugging messages printed out
121 while the connection is being opened. These can be helpful in try‐
122 ing to determine connection problems, etc. The messages are similar
123 (and in some cases exact) to those written out by the ssh client
124 when you use the -v option.
125 Defaults to false.
127 * interactive
129 Set to a true value if you're using Net::SSH::Perl interactively.
130 This is used in determining whether or not to display password
131 prompts, for example. It's basically the inverse of the BatchMode
132 parameter in ssh configuration.
133 Defaults to false.
135 * privileged
137 Set to a true value if you want to bind to a privileged port
138 locally. You'll need this if you plan to use Rhosts or Rhosts-RSA
139 authentication, because the remote server requires the client to
140 connect on a privileged port. Of course, to bind to a privileged
141 port you'll need to be root.
142 If you don't provide this parameter, and Net::SSH::Perl detects
144 that you're running as root, this will automatically be set to
145 true. Otherwise it defaults to false.
146 * identity_files
148 A list of RSA/DSA identity files to be used in RSA/DSA authentica‐
149 tion. The value of this argument should be a reference to an array
150 of strings, each string identifying the location of an identity
151 file. Each identity file will be tested against the server until
152 the client finds one that authenticates successfully.
153 If you don't provide this, RSA authentication defaults to using
155 $ENV{HOME}/.ssh/identity, and DSA authentication defaults to
156 $ENV{HOME}/.ssh/id_dsa.
157 * compression
159 If set to a true value, compression is turned on for the session
160 (assuming that the server supports it).
161 Compression is off by default.
163 Note that compression requires that you have the Compress::Zlib
165 module installed on your system. If the module can't be loaded suc‐
166 cessfully, compression is disabled; you'll receive a warning stat‐
167 ing as much if you having debugging on (debug set to 1), and you
168 try to turn on compression.
169 * compression_level
171 Specifies the compression level to use if compression is enabled
172 (note that you must provide both the compression and compres‐
173 sion_level arguments to set the level; providing only this argument
174 will not turn on encryption).
175 This setting is only applicable to SSH-1; the compression level for
177 SSH-2 Zlib compression is always set to 6.
178 The default value is 6.
180 * use_pty
182 Set this to 1 if you want to request a pseudo tty on the remote
183 machine. This is really only useful if you're setting up a shell
184 connection (see the shell method, below); and in that case, unless
185 you've explicitly declined a pty (by setting use_pty to 0), this
186 will be set automatically to 1. In other words, you probably won't
187 need to use this, often.
188 The default is 1 if you're starting up a shell, and 0 otherwise.
190 * options
192 Used to specify additional options to the configuration settings;
193 useful for specifying options for which there is no separate con‐
194 structor argument. This is analogous to the -o command line flag to
195 the ssh program.
196 If used, the value should be a reference to a list of option direc‐
198 tives in the format used in the config file. For example:
199 my $ssh = Net::SSH::Perl->new("host", options => [
201 "BatchMode yes", "RhostsAuthentication no" ]);
202 $ssh->login([ $user [, $password [, $suppress_shell ] ] ])
204 Sets the username and password to be used when authenticating with the
206 sshd daemon. The username $user is required for all authentication pro‐
207 tocols (to identify yourself to the remote server), but if you don't
208 supply it the username of the user executing the program is used.
209 The password $password is needed only for password authentication (it's
211 not used for passphrases on encrypted RSA/DSA identity files, though
212 perhaps it should be). And if you're running in an interactive session
213 and you've not provided a password, you'll be prompted for one.
214 By default, Net::SSH::Perl will open a channel with a shell on it. This
216 is usually what you want. If you are tunneling another protocol over
217 SSH, however, you may want to prevent this behavior. Passing a true
218 value in $suppress_shell will prevent the shell channel from being
219 opened (SSH2 only).
220 ($out, $err, $exit) = $ssh->cmd($cmd, [ $stdin ])
222 Runs the command $cmd on the remote server and returns the stdout,
224 stderr, and exit status of that command.
225 If $stdin is provided, it's supplied to the remote command $cmd on
227 standard input.
228 NOTE: the SSH-1 protocol does not support running multiple commands per
230 connection, unless those commands are chained together so that the
231 remote shell can evaluate them. Because of this, a new socket connec‐
232 tion is created each time you call cmd, and disposed of afterwards. In
233 other words, this code:
234 my $ssh = Net::SSH::Perl->new("host1");
236 $ssh->login("user1", "pass1");
237 $ssh->cmd("foo");
239 $ssh->cmd("bar");
240 will actually connect to the sshd on the first invocation of cmd, then
242 disconnect; then connect again on the second invocation of cmd, then
243 disconnect again.
244 Note that this does not apply to the SSH-2 protocol. SSH-2 fully sup‐
246 ports running more than one command over the same connection.
247 $ssh->shell
249 Opens up an interactive shell on the remote machine and connects it to
251 your STDIN. This is most effective when used with a pseudo tty; other‐
252 wise you won't get a command line prompt, and it won't look much like a
253 shell. For this reason--unless you've specifically declined one--a pty
254 will be requested from the remote machine, even if you haven't set the
255 use_pty argument to new (described above).
256 This is really only useful in an interactive program.
258 In addition, you'll probably want to set your terminal to raw input
260 before calling this method. This lets Net::SSH::Perl process each char‐
261 acter and send it off to the remote machine, as you type it.
262 To do so, use Term::ReadKey in your program:
264 use Term::ReadKey;
266 ReadMode('raw');
267 $ssh->shell;
268 ReadMode('restore');
269 In fact, you may want to place the "restore" line in an END block, in
271 case your program exits prior to reaching that line.
272 If you need an example, take a look at eg/pssh, which uses almost this
274 exact code to implement an ssh shell.
275 $ssh->register_handler($packet_type, $subref [, @args ])
277 Registers an anonymous subroutine handler $subref to handle packets of
279 type $packet_type during the client loop. The subroutine will be called
280 when packets of type $packet_type are received, and in addition to the
281 standard arguments (see below), will receive any additional arguments
282 in @args, if specified.
283 The client loop is entered after the client has sent a command to the
285 remote server, and after any STDIN data has been sent; it consists of
286 reading packets from the server (STDOUT packets, STDERR packets, etc.)
287 until the server sends the exit status of the command executed
288 remotely. At this point the client exits the client loop and discon‐
289 nects from the server.
290 When you call the cmd method, the client loop by default simply sticks
292 STDOUT packets into a scalar variable and returns that value to the
293 caller. It does the same for STDERR packets, and for the process exit
294 status. (See the docs for cmd).
295 You can, however, override that default behavior, and instead process
297 the data itself as it is sent to the client. You do this by calling the
298 register_handler method and setting up handlers to be called at spe‐
299 cific times.
300 The behavior of the register_handler method differs between the
302 Net::SSH::Perl SSH-1 and SSH-2 implementations. This is so because of
303 the differences between the protocols (all client-server communications
304 in SSH-2 go through the channel mechanism, which means that input pack‐
305 ets are processed differently).
306 * SSH-1 Protocol
308 In the SSH-1 protocol, you should call register_handler with two
309 arguments: a packet type $packet_type and a subroutine reference
310 $subref. Your subroutine will receive as arguments the
311 Net::SSH::Perl::SSH1 object (with an open connection to the ssh3),
312 and a Net::SSH::Perl::Packet object, which represents the packet
313 read from the server. It will also receive any additional arguments
314 @args that you pass to register_handler; this can be used to give
315 your callback functions access to some of your otherwise private
316 variables, if desired. $packet_type should be an integer constant;
317 you can import the list of constants into your namespace by explic‐
318 itly loading the Net::SSH::Perl::Constants module:
319 use Net::SSH::Perl::Constants qw( :msg );
321 This will load all of the MSG constants into your namespace so that
323 you can use them when registering the handler. To do that, use this
324 method. For example:
325 $ssh->register_handler(SSH_SMSG_STDOUT_DATA, sub {
327 my($ssh, $packet) = @_;
328 print "I received this: ", $packet->get_str;
329 });
330 To learn about the methods that you can call on the packet object,
332 take a look at the Net::SSH::Perl::Packet docs, as well as the
333 Net::SSH::Perl::Buffer docs (the get_* and put_* methods).
334 Obviously, writing these handlers requires some knowledge of the
336 contents of each packet. For that, read through the SSH RFC, which
337 explains each packet type in detail. There's a get_* method for
338 each datatype that you may need to read from a packet.
339 Take a look at eg/remoteinteract.pl for an example of interacting
341 with a remote command through the use of register_handler.
342 * SSH-2 Protocol
344 In the SSH-2 protocol, you call register_handler with two argu‐
345 ments: a string identifying the type of handler you wish to create,
346 and a subroutine reference. The "string" should be, at this point,
347 either "stdout" or "stderr"; any other string will be silently
348 ignored. "stdout" denotes that you wish to handle STDOUT data sent
349 from the server, and "stderr" that you wish to handle STDERR data.
350 Your subroutine reference will be passed two arguments: a
352 Net::SSH::Perl::Channel object that represents the open channel on
353 which the data was sent, and a Net::SSH::Perl::Buffer object con‐
354 taining data read from the server. In addition to these two argu‐
355 ments, the callback will be passed any additional arguments @args
356 that you passed to register_handler; this can be used to give your
357 callback functions to otherwise private variables, if desired.
358 This illustrates the two main differences between the SSH-1 and
360 SSH-2 implementations. The first difference is that, as mentioned
361 above, all communication between server and client is done through
362 channels, which are built on top of the main connection between
363 client and server. Multiple channels are multiplexed over the same
364 connection. The second difference is that, in SSH-1, you are pro‐
365 cessing the actual packets as they come in; in SSH-2, the packets
366 have already been processed somewhat, and their contents stored in
367 buffers--you are processing those buffers.
368 The above example (the I received this example) of using regis‐
370 ter_handler in SSH-1 would look like this in SSH-2:
371 $ssh->register_handler("stdout", sub {
373 my($channel, $buffer) = @_;
374 print "I received this: ", $buffer->bytes;
375 });
376 As you can see, it's quite similar to the form used in SSH-1, but
378 with a few important differences, due to the differences mentioned
379 above between SSH-1 and SSH-2.
380
382 Your basic SSH needs will hopefully be met by the methods listed above.
383 If they're not, however, you may want to use some of the additional
384 methods listed here. Some of these are aimed at end-users, while others
385 are probably more useful for actually writing an authentication module,
386 or a cipher, etc.
387 $ssh->config
389 Returns the Net::SSH::Perl::Config object managing the configuration
391 data for this SSH object. This is constructed from data passed in to
392 the constructor new (see above), merged with data read from the user
393 and system configuration files. See the Net::SSH::Perl::Config docs for
394 details on methods you can call on this object (you'll probably be more
395 interested in the get and set methods).
396 $ssh->sock
398 Returns the socket connection to sshd. If your client is not connected,
400 dies.
401 $ssh->debug($msg)
403 If debugging is turned on for this session (see the debug parameter to
405 the new method, above), writes $msg to "STDERR". Otherwise nothing is
406 done.
407 $ssh->incoming_data
409 Incoming data buffer, an object of type Net::SSH::Perl::Buffer.
411 Returns the buffer object.
412 The idea behind this is that we our socket is non-blocking, so we buf‐
414 fer input and periodically check back to see if we've read a full
415 packet. If we have a full packet, we rip it out of the incoming data
416 buffer and process it, returning it to the caller who presumably asked
417 for it.
418 This data "belongs" to the underlying packet layer in
420 Net::SSH::Perl::Packet. Unless you really know what you're doing you
421 probably don't want to disturb that data.
422 $ssh->session_id
424 Returns the session ID, which is generated from the server's host and
426 server keys, and from the check bytes that it sends along with the
427 keys. The server may require the session ID to be passed along in other
428 packets, as well (for example, when responding to RSA challenges).
429 $packet = $ssh->packet_start($packet_type)
431 Starts building a new packet of type $packet_type. This is just a handy
433 method for lazy people. Internally it calls
434 Net::SSH::Perl::Packet::new, so take a look at those docs for more
435 details.
436
438 For samples/tutorials, take a look at the scripts in eg/ in the distri‐
439 bution directory.
440 There is a mailing list for development discussion and usage questions.
442 Posting is limited to subscribers only. You can sign up at
443 http://lists.sourceforge.net/lists/listinfo/ssh-sftp-perl-users
444 Please report all bugs via rt.cpan.org at
446 https://rt.cpan.org/NoAuth/ReportBug.html?Queue=net%3A%3Assh%3A%3Aperl
447
449 Current maintainer is David Robins, dbrobins@cpan.org.
450 Previous maintainer was Dave Rolsky, autarch@urth.org.
452 Originally written by Benjamin Trott.
454
456 Copyright (c) 2001-2003 Benjamin Trott, Copyright (c) 2003-2004 David
457 Rolsky. Copyright (c) David Robins. All rights reserved. This pro‐
458 gram is free software; you can redistribute it and/or modify it under
459 the same terms as Perl itself.
460 The full text of the license can be found in the LICENSE file included
462 with this module.
463perl v5.8.8 2003-12-03 Net::SSH::Perl(3)