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, Ed25519 identity
28 files, 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. AES-CTR ("aes256-ctr", "aes192-ctr", and "aes128-ctr") and
52 Chacha20-Poly1305 ciphers are currently supported for SSH2 encryption.
53 Deprecated ciphers AES-CBC ("aes256-cbc", "aes192-cbc", and
54 "aes128-cbc") 3DES ("3des-cbc"), Blowfish ("blowfish-cbc"), and RC4
55 ("arcfour") are available but not enabled by default. One can enable
56 them by using the Ciphers options parameter. For example:
57 options => [ "Ciphers +aes256-cbc" ]
59 Using the + notation will append a cipher to the default ciphers list.
61 Integrity checking is performed by the "hmac-sha2-256",
63 "hmac-sha2-512", "hmac-sha2-256-etm@openssh.com", or
64 "hmac-sha2-512-etm@openssh.com" algorithms. The deprecated "hmac-sha1"
65 or "hmac-md5" algorithms are available but not enabled by default.
66 Many older SSH server installations still use hmac-sha1 as the main
67 accepted MAC algorithm. To enable this, use the following options
68 parameter:
69 options => [ "MACs +hmac-sha1" ]
71 Compression, if requested, is limited to Zlib.
73 Supported server host key algorithms are "ssh-ed25519", "rsa-sha2-512",
75 "rsa-sha2-256", "ecdsa-sha2-nistp521", "ecdsa-sha2-nistp384",
76 "ecdsa-sha2-nistp256", and "ssh-rsa". Deprecated "ssh-dss" is
77 supported but not enabled by default. It can be enabled with the
78 options parameter:
79 options => [ "HostKeyAlgorithms +ssh-dss" ]
81 Supported SSH2 public key authentication algorithms are the same.
83 Supported Key Exchange (KEX) algorithms are
85 "diffie-hellman-group1-sha1", "diffie-hellman-group14-sha1",
86 c<diffie-hellman-group14-sha256>, "diffie-hellman-group16-sha512",
87 "diffie-hellman-group18-sha512",
88 "diffie-hellman-group-exchange-sha256",
89 "diffie-hellman-group-exchange-sha1", and
90 "curve25519-sha256@libssh.org"/"curve25519-sha256". The
91 "diffie-hellman-group1-sha1" algorithm is disabled by default, but can
92 be activated via the options parameter:
93 options => [ "KexAlgorithms +diffie-hellman-group1-sha1" ]
95 If you're looking for SFTP support, take a look at Net::SFTP, which
97 provides a full-featured Perl implementation of SFTP, and sits on top
98 of Net::SSH::Perl. SFTP requires the usage of the SSH2 protocol.
99
101 Usage of Net::SSH::Perl is very simple.
102 Net::SSH::Perl->new($host, %params)
104 To set up a new connection, call the new method, which connects to
105 $host and returns a Net::SSH::Perl object.
106 new accepts the following named parameters in %params:
108 • protocol
110 The protocol you wish to use for the connection: should be either
112 2, 1, '1,2' or '2,1'. The first two say, quite simply, "only use
113 this version of the protocol" (SSH-2 or SSH-1, respectively). The
114 latter two specify that either protocol can be used, but that one
115 protocol (the first in the comma-separated list) is preferred over
116 the other.
117 For this reason, it's "safer" to use the latter two protocol
119 specifications, because they ensure that either way, you'll be able
120 to connect; if your server doesn't support the first protocol
121 listed, the second will be used. (Presumably your server will
122 support at least one of the two protocols. :)
123 The default value is '1,2', for compatibility with OpenSSH; this
125 means that the client will use SSH-1 if the server supports SSH-1.
126 Of course, you can always override this using a user/global
127 configuration file, or through using this constructor argument.
128 • cipher
130 Specifies the name of the encryption cipher that you wish to use
132 for this connection. This must be one of the supported ciphers;
133 specifying an unsupported cipher will give you an error when you
134 enter algorithm negotiation (in either SSH-1 or SSH-2).
135 In SSH-1, the supported cipher names are IDEA, DES, DES3, and
137 Blowfish; in SSH-2, the supported ciphers are aes256-ctr,
138 aes192-ctr, aes128-ctr, chacha20-poly1305@openssh.com. arcfour,
139 blowfish-cbc, and 3des-cbc are deprecated and are not enabled by
140 default. aes256-cbc, aes192-cbc, and aes128-cbc are also supported
141 but not enabled by default as CBC is no longer considered secure.
142 The default SSH-1 cipher is IDEA; the default SSH-2 ciphers are
144 aes256-ctr, aes192-ctr, aes128-ctr, chacha20-poly1305@openssh.com.
145 • ciphers
147 Like cipher, this is a method of setting the cipher you wish to use
149 for a particular SSH connection; but this corresponds to the
150 Ciphers configuration option, where cipher corresponds to Cipher.
151 This also applies only in SSH-2.
152 This should be a comma-separated list of SSH-2 cipher names; the
154 list of cipher names is listed above in cipher.
155 This defaults to:
157 chacha20-poly1305@openssh.com,aes256-ctr,aes192-ctr,aes128-ctr.
158 • port
160 The port of the sshd daemon to which you wish to connect; if not
162 specified, this is assumed to be the default ssh port.
163 • debug
165 Set to a true value if you want debugging messages printed out
167 while the connection is being opened. These can be helpful in
168 trying to determine connection problems, etc. The messages are
169 similar (and in some cases exact) to those written out by the ssh
170 client when you use the -v option.
171 Defaults to false.
173 • interactive
175 Set to a true value if you're using Net::SSH::Perl interactively.
177 This is used in determining whether or not to display password
178 prompts, for example. It's basically the inverse of the BatchMode
179 parameter in ssh configuration.
180 Defaults to false.
182 • privileged
184 Set to a true value if you want to bind to a privileged port
186 locally. You'll need this if you plan to use Rhosts or Rhosts-RSA
187 authentication, because the remote server requires the client to
188 connect on a privileged port. Of course, to bind to a privileged
189 port you'll need to be root.
190 If you don't provide this parameter, and Net::SSH::Perl detects
192 that you're running as root, this will automatically be set to
193 true. Otherwise it defaults to false.
194 • identity_files
196 A list of identity files to be used in pubkey authentication. The
198 value of this argument should be a reference to an array of
199 strings, each string identifying the location of an identity file.
200 Each identity file will be tested against the server until the
201 client finds one that authenticates successfully.
202 If you don't provide this, SSH1 authentication defaults to using
204 $ENV{HOME}/.ssh/identity, and SSH2 authentication defaults to the
205 three files $ENV{HOME}/.ssh/id_ed25519, $ENV{HOME}/.ssh/id_ecdsa,
206 and $ENV{HOME}/.ssh/id_rsa.
207 • strict_host_key_checking
209 This corresponds to the StrictHostKeyChecking ssh configuration
211 option. Allowed values are no, yes, or ask. no disables host key
212 checking, e.g., if you connect to a virtual host that answers to
213 multiple IP addresses. yes or ask enable it, and when it fails in
214 interactive mode, you are asked whether to continue. The host is
215 then added to the list of known hosts.
216 • compression
218 If set to a true value, compression is turned on for the session
220 (assuming that the server supports it).
221 Compression is off by default.
223 Note that compression requires that you have the Compress::Zlib
225 module installed on your system. If the module can't be loaded
226 successfully, compression is disabled; you'll receive a warning
227 stating as much if you having debugging on (debug set to 1), and
228 you try to turn on compression.
229 • compression_level
231 Specifies the compression level to use if compression is enabled
233 (note that you must provide both the compression and
234 compression_level arguments to set the level; providing only this
235 argument will not turn on encryption).
236 This setting is only applicable to SSH-1; the compression level for
238 SSH-2 Zlib compression is always set to 6.
239 The default value is 6.
241 • use_pty
243 Set this to 1 if you want to request a pseudo tty on the remote
245 machine. This is really only useful if you're setting up a shell
246 connection (see the shell method, below); and in that case, unless
247 you've explicitly declined a pty (by setting use_pty to 0), this
248 will be set automatically to 1. In other words, you probably won't
249 need to use this, often.
250 The default is 1 if you're starting up a shell, and 0 otherwise.
252 • terminal_mode_string
254 Specify the POSIX terminal mode string to send when use_pty is set.
256 By default the only mode set is the VEOF character to 0x04 (opcode
257 5, value 0x00000004). See RFC 4254 section 8 for complete details
258 on this value.
259 • no_append_veof
261 (SSH-2 only) Set this to 1 if you specified use_pty and do not want
263 Ctrl-D (0x04) appended twice to the end of your input string. On
264 most systems, these bytes cause the terminal driver to return "EOF"
265 when standard input is read. Without them, many programs that read
266 from standard input will hang after consuming all the data on
267 STDIN.
268 No other modifications are made to input data. If your data
270 contains 0x04 bytes, you may need to escape them.
271 Set this to 0 if you have raw terminal data to specify on standard
273 input, and you have terminated it correctly.
274 • options
276 Used to specify additional options to the configuration settings;
278 useful for specifying options for which there is no separate
279 constructor argument. This is analogous to the -o command line flag
280 to the ssh program.
281 If used, the value should be a reference to a list of option
283 directives in the format used in the config file. For example:
284 my $ssh = Net::SSH::Perl->new("host", options => [
286 "BatchMode yes", "RhostsAuthentication no" ]);
287 Available options are:
289 BindAddress
291 Host
292 BatchMode
293 ChallengeResponseAuthentication
294 CheckHostIP
295 Cipher
296 Ciphers*
297 Compression
298 CompressionLevel
299 DSAAuthentication
300 FingerprintHash
301 GlobalKnownHostsFile
302 HashKnownHosts
303 HostKeyAlgorithms*
304 HostName
305 IdentityFile
306 KexAlgorithms*
307 MACs*
308 NumberOfPasswordPrompts
309 PasswordAuthentication
310 PasswordPromptHost
311 PasswordPromptLogin
312 Port
313 Protocol
314 RhostsAuthentication
315 RhostsRSAAuthentication
316 RSAAuthentication
317 StrictHostKeyChecking
318 UpdateHostKeys
319 UsePrivilegedPort
320 User
321 UserKnownHostsFile
322 * Indicates the +/- wildcard notation may be used.
324 For example:
326 MACs +hmac-sha1
328 will add hmac-sha1 to the default MACs list.
330 Or:
332 Ciphers +aes*-cbc
334 will add aes128-cbc, aes192-cbc, and aes256-cbc to the default
336 Ciphers
337 While:
339 KexAlgorithms -*-sha512
341 will remove all algorithms that end in -sha512 from the default
343 list.
344 $ssh->login([ $user [, $password [, $suppress_shell ] ] ])
346 Sets the username and password to be used when authenticating with the
347 sshd daemon. The username $user is required for all authentication
348 protocols (to identify yourself to the remote server), but if you don't
349 supply it the username of the user executing the program is used.
350 The password $password is needed only for password authentication (it's
352 not used for passphrases on encrypted RSA/DSA identity files, though
353 perhaps it should be). And if you're running in an interactive session
354 and you've not provided a password, you'll be prompted for one.
355 By default, Net::SSH::Perl will open a channel with a shell on it. This
357 is usually what you want. If you are tunneling another protocol over
358 SSH, however, you may want to prevent this behavior. Passing a true
359 value in $suppress_shell will prevent the shell channel from being
360 opened (SSH2 only).
361 ($out, $err, $exit) = $ssh->cmd($cmd, [ $stdin ])
363 Runs the command $cmd on the remote server and returns the stdout,
364 stderr, and exit status of that command.
365 If $stdin is provided, it's supplied to the remote command $cmd on
367 standard input.
368 NOTE: the SSH-1 protocol does not support running multiple commands per
370 connection, unless those commands are chained together so that the
371 remote shell can evaluate them. Because of this, a new socket
372 connection is created each time you call cmd, and disposed of
373 afterwards. In other words, this code:
374 my $ssh = Net::SSH::Perl->new("host1");
376 $ssh->login("user1", "pass1");
377 $ssh->cmd("foo");
379 $ssh->cmd("bar");
380 will actually connect to the sshd on the first invocation of cmd, then
382 disconnect; then connect again on the second invocation of cmd, then
383 disconnect again.
384 Note that this does not apply to the SSH-2 protocol. SSH-2 fully
386 supports running more than one command over the same connection.
387 $ssh->shell
389 Opens up an interactive shell on the remote machine and connects it to
390 your STDIN. This is most effective when used with a pseudo tty;
391 otherwise you won't get a command line prompt, and it won't look much
392 like a shell. For this reason--unless you've specifically declined
393 one--a pty will be requested from the remote machine, even if you
394 haven't set the use_pty argument to new (described above).
395 This is really only useful in an interactive program.
397 In addition, you'll probably want to set your terminal to raw input
399 before calling this method. This lets Net::SSH::Perl process each
400 character and send it off to the remote machine, as you type it.
401 To do so, use Term::ReadKey in your program:
403 use Term::ReadKey;
405 ReadMode('raw');
406 $ssh->shell;
407 ReadMode('restore');
408 In fact, you may want to place the "restore" line in an END block, in
410 case your program exits prior to reaching that line.
411 If you need an example, take a look at eg/pssh, which uses almost this
413 exact code to implement an ssh shell.
414 $ssh->register_handler($packet_type, $subref [, @args ])
416 Registers an anonymous subroutine handler $subref to handle packets of
417 type $packet_type during the client loop. The subroutine will be called
418 when packets of type $packet_type are received, and in addition to the
419 standard arguments (see below), will receive any additional arguments
420 in @args, if specified.
421 The client loop is entered after the client has sent a command to the
423 remote server, and after any STDIN data has been sent; it consists of
424 reading packets from the server (STDOUT packets, STDERR packets, etc.)
425 until the server sends the exit status of the command executed
426 remotely. At this point the client exits the client loop and
427 disconnects from the server.
428 When you call the cmd method, the client loop by default simply sticks
430 STDOUT packets into a scalar variable and returns that value to the
431 caller. It does the same for STDERR packets, and for the process exit
432 status. (See the docs for cmd).
433 You can, however, override that default behavior, and instead process
435 the data itself as it is sent to the client. You do this by calling the
436 register_handler method and setting up handlers to be called at
437 specific times.
438 The behavior of the register_handler method differs between the
440 Net::SSH::Perl SSH-1 and SSH-2 implementations. This is so because of
441 the differences between the protocols (all client-server communications
442 in SSH-2 go through the channel mechanism, which means that input
443 packets are processed differently).
444 • SSH-1 Protocol
446 In the SSH-1 protocol, you should call register_handler with two
448 arguments: a packet type $packet_type and a subroutine reference
449 $subref. Your subroutine will receive as arguments the
450 Net::SSH::Perl::SSH1 object (with an open connection to the ssh3),
451 and a Net::SSH::Perl::Packet object, which represents the packet
452 read from the server. It will also receive any additional arguments
453 @args that you pass to register_handler; this can be used to give
454 your callback functions access to some of your otherwise private
455 variables, if desired. $packet_type should be an integer constant;
456 you can import the list of constants into your namespace by
457 explicitly loading the Net::SSH::Perl::Constants module:
458 use Net::SSH::Perl::Constants qw( :msg );
460 This will load all of the MSG constants into your namespace so that
462 you can use them when registering the handler. To do that, use this
463 method. For example:
464 $ssh->register_handler(SSH_SMSG_STDOUT_DATA, sub {
466 my($ssh, $packet) = @_;
467 print "I received this: ", $packet->get_str;
468 });
469 To learn about the methods that you can call on the packet object,
471 take a look at the Net::SSH::Perl::Packet docs, as well as the
472 Net::SSH::Perl::Buffer docs (the get_* and put_* methods).
473 Obviously, writing these handlers requires some knowledge of the
475 contents of each packet. For that, read through the SSH RFC, which
476 explains each packet type in detail. There's a get_* method for
477 each datatype that you may need to read from a packet.
478 Take a look at eg/remoteinteract.pl for an example of interacting
480 with a remote command through the use of register_handler.
481 • SSH-2 Protocol
483 In the SSH-2 protocol, you call register_handler with two
485 arguments: a string identifying the type of handler you wish to
486 create, and a subroutine reference. The "string" should be, at this
487 point, either "stdout" or "stderr"; any other string will be
488 silently ignored. "stdout" denotes that you wish to handle STDOUT
489 data sent from the server, and "stderr" that you wish to handle
490 STDERR data.
491 Your subroutine reference will be passed two arguments: a
493 Net::SSH::Perl::Channel object that represents the open channel on
494 which the data was sent, and a Net::SSH::Perl::Buffer object
495 containing data read from the server. In addition to these two
496 arguments, the callback will be passed any additional arguments
497 @args that you passed to register_handler; this can be used to give
498 your callback functions to otherwise private variables, if desired.
499 This illustrates the two main differences between the SSH-1 and
501 SSH-2 implementations. The first difference is that, as mentioned
502 above, all communication between server and client is done through
503 channels, which are built on top of the main connection between
504 client and server. Multiple channels are multiplexed over the same
505 connection. The second difference is that, in SSH-1, you are
506 processing the actual packets as they come in; in SSH-2, the
507 packets have already been processed somewhat, and their contents
508 stored in buffers--you are processing those buffers.
509 The above example (the I received this example) of using
511 register_handler in SSH-1 would look like this in SSH-2:
512 $ssh->register_handler("stdout", sub {
514 my($channel, $buffer) = @_;
515 print "I received this: ", $buffer->bytes;
516 });
517 As you can see, it's quite similar to the form used in SSH-1, but
519 with a few important differences, due to the differences mentioned
520 above between SSH-1 and SSH-2.
521
523 Your basic SSH needs will hopefully be met by the methods listed above.
524 If they're not, however, you may want to use some of the additional
525 methods listed here. Some of these are aimed at end-users, while others
526 are probably more useful for actually writing an authentication module,
527 or a cipher, etc.
528 $ssh->config
530 Returns the Net::SSH::Perl::Config object managing the configuration
531 data for this SSH object. This is constructed from data passed in to
532 the constructor new (see above), merged with data read from the user
533 and system configuration files. See the Net::SSH::Perl::Config docs for
534 details on methods you can call on this object (you'll probably be more
535 interested in the get and set methods).
536 $ssh->sock
538 Returns the socket connection to sshd. If your client is not connected,
539 dies.
540 $ssh->debug($msg)
542 If debugging is turned on for this session (see the debug parameter to
543 the new method, above), writes $msg to "STDERR". Otherwise nothing is
544 done.
545 $ssh->incoming_data
547 Incoming data buffer, an object of type Net::SSH::Perl::Buffer.
548 Returns the buffer object.
549 The idea behind this is that we our socket is non-blocking, so we
551 buffer input and periodically check back to see if we've read a full
552 packet. If we have a full packet, we rip it out of the incoming data
553 buffer and process it, returning it to the caller who presumably asked
554 for it.
555 This data "belongs" to the underlying packet layer in
557 Net::SSH::Perl::Packet. Unless you really know what you're doing you
558 probably don't want to disturb that data.
559 $ssh->session_id
561 Returns the session ID, which is generated from the server's host and
562 server keys, and from the check bytes that it sends along with the
563 keys. The server may require the session ID to be passed along in other
564 packets, as well (for example, when responding to RSA challenges).
565 $packet = $ssh->packet_start($packet_type)
567 Starts building a new packet of type $packet_type. This is just a handy
568 method for lazy people. Internally it calls
569 Net::SSH::Perl::Packet::new, so take a look at those docs for more
570 details.
571
573 For samples/tutorials, take a look at the scripts in eg/ in the
574 distribution directory.
575 Please report bugs at: https://github.com/lkinley/Net-SSH-Perl/issues
577
579 Development on V2 by Lance Kinley lkinley@rythmos.com
580 Previous maintainers were: David Robins, dbrobins@cpan.org Dave Rolsky,
582 autarch@urth.org.
583 Originally written by Benjamin Trott.
585
587 Copyright (c) 2015-2017 Rythmos, Inc. Copyright (c) 2001-2003 Benjamin
588 Trott, Copyright (c) 2003-2008 David Rolsky. Copyright (c) David
589 Robins. All rights reserved. This program is free software; you can
590 redistribute it and/or modify it under the same terms as Perl itself.
591 The full text of the license can be found in the LICENSE file included
593 with this module.
594perl v5.34.0 2021-07-22 Net::SSH::Perl(3)