4 use vars qw($VERSION @ISA @EXPORT_OK $ssh $equalspace $DEBUG @ssh_options);
6 use POSIX ":sys_wait_h";
13 @EXPORT_OK = qw( ssh issh ssh_cmd sshopen2 sshopen3 );
22 Net::SSH - Perl extension for secure shell
26 use Net::SSH qw(ssh issh sshopen2 sshopen3);
28 ssh('user@hostname', $command);
30 issh('user@hostname', $command);
32 ssh_cmd('user@hostname', $command);
37 args => [ '-arg1', '-arg2' ],
38 stdin_string => "string\n",
41 sshopen2('user@hostname', $reader, $writer, $command);
43 sshopen3('user@hostname', $writer, $reader, $error, $command);
47 Simple wrappers around ssh commands.
49 For an all-perl implementation that does not require the system B<ssh> command,
50 see L<Net::SSH::Perl> instead.
56 =item ssh [USER@]HOST, COMMAND [, ARGS ... ]
58 Calls ssh in batch mode.
63 my($host, @command) = @_;
64 @ssh_options = &_ssh_options unless @ssh_options;
65 my @cmd = ($ssh, @ssh_options, $host, @command);
66 warn "[Net::SSH::ssh] executing ". join(' ', @cmd). "\n"
71 =item issh [USER@]HOST, COMMAND [, ARGS ... ]
73 Prints the ssh command to be executed, waits for the user to confirm, and
74 (optionally) executes the command.
79 my($host, @command) = @_;
80 my @cmd = ($ssh, $host, @command);
81 print join(' ', @cmd), "\n";
87 =item ssh_cmd [USER@]HOST, COMMAND [, ARGS ... ]
89 =item ssh_cmd OPTIONS_HASHREF
91 Calls ssh in batch mode. Throws a fatal error if data occurs on the command's
92 STDERR. Returns any data from the command's STDOUT.
94 If using the hashref-style of passing arguments, possible keys are:
99 args (optional, arrayref)
100 stdin_string (optional) - written to the command's STDIN
105 my($host, $stdin_string, @command);
108 $host = $opt->{host};
109 $host = $opt->{user}. '@'. $host if exists $opt->{user};
110 @command = ( $opt->{command} );
111 push @command, @{ $opt->{args} } if exists $opt->{args};
112 $stdin_string = $opt->{stdin_string};
114 ($host, @command) = @_;
118 my $reader = IO::File->new();
119 my $writer = IO::File->new();
120 my $error = IO::File->new();
122 my $pid = sshopen3( $host, $writer, $reader, $error, @command ) or die $!;
124 print $writer $stdin_string if defined $stdin_string;
127 my $select = new IO::Select;
128 foreach ( $reader, $error ) { $select->add($_); }
130 my($output_stream, $error_stream) = ('', '');
131 while ( $select->count ) {
132 my @handles = $select->can_read;
133 foreach my $handle ( @handles ) {
135 my $bytes = sysread($handle, $buffer, 4096);
136 if ( !defined($bytes) ) {
137 waitpid($pid, WNOHANG);
138 die "[Net::SSH::ssh_cmd] $!"
140 $select->remove($handle) if !$bytes;
141 if ( $handle eq $reader ) {
142 $output_stream .= $buffer;
143 } elsif ( $handle eq $error ) {
144 $error_stream .= $buffer;
150 waitpid($pid, WNOHANG);
152 die "$error_stream" if length($error_stream);
154 return $output_stream;
158 =item sshopen2 [USER@]HOST, READER, WRITER, COMMAND [, ARGS ... ]
160 Connects the supplied filehandles to the ssh process (in batch mode).
165 my($host, $reader, $writer, @command) = @_;
166 @ssh_options = &_ssh_options unless @ssh_options;
167 open2($reader, $writer, $ssh, @ssh_options, $host, @command);
170 =item sshopen3 HOST, WRITER, READER, ERROR, COMMAND [, ARGS ... ]
172 Connects the supplied filehandles to the ssh process (in batch mode).
177 my($host, $writer, $reader, $error, @command) = @_;
178 @ssh_options = &_ssh_options unless @ssh_options;
179 open3($writer, $reader, $error, $ssh, @ssh_options, $host, @command);
183 print "Proceed [y/N]:";
184 my $x = scalar(<STDIN>);
189 my $reader = IO::File->new();
190 my $writer = IO::File->new();
191 my $error = IO::File->new();
192 open3($writer, $reader, $error, $ssh, '-V');
193 my $ssh_version = <$error>;
195 if ( $ssh_version =~ /.*OpenSSH[-|_](\w+)\./ && $1 == 1 ) {
200 my @options = ( '-o', 'BatchMode'.$equalspace.'yes' );
201 if ( $ssh_version =~ /.*OpenSSH[-|_](\w+)\./ && $1 > 1 ) {
202 unshift @options, '-T';
211 use Net::SSH qw(sshopen2);
214 my $user = "username";
215 my $host = "hostname";
218 sshopen2("$user\@$host", *READER, *WRITER, "$cmd") || die "ssh: $!";
228 =head1 FREQUENTLY ASKED QUESTIONS
230 Q: How do you supply a password to connect with ssh within a perl script
231 using the Net::SSH module?
233 A: You don't (at least not with this module). Use RSA or DSA keys. See the
234 quick help in the next section and the ssh-keygen(1) manpage.
236 A #2: See L<Net::SSH::Expect> instead.
238 Q: My script is "leaking" ssh processes.
240 A: See L<perlfaq8/"How do I avoid zombies on a Unix system">, L<IPC::Open2>,
241 L<IPC::Open3> and L<perlfunc/waitpid>.
243 =head1 GENERATING AND USING SSH KEYS
247 =item 1 Generate keys
253 And do not enter a passphrase unless you wanted to be prompted for
254 one during file copying.
256 Here is what you will see:
259 Generating public/private rsa key pair.
260 Enter file in which to save the key (/home/User/.ssh/id_rsa):
261 Enter passphrase (empty for no passphrase):
263 Enter same passphrase again:
265 Your identification has been saved in /home/User/.ssh/id_rsa.
266 Your public key has been saved in /home/User/.ssh/id_rsa.pub.
267 The key fingerprint is:
268 5a:cd:2b:0a:cd:d9:15:85:26:79:40:0c:55:2a:f4:23 User@JEFF-CPU
271 =item 2 Copy public to machines you want to upload to
273 C<id_rsa.pub> is your public key. Copy it to C<~/.ssh> on target machine.
275 Put a copy of the public key file on each machine you want to log into.
276 Name the copy C<authorized_keys> (some implementations name this file
281 chmod 600 authorized_keys
283 Then make sure your home dir on the remote machine is not group or
290 Ivan Kohler <ivan-netssh_pod@420.am>
292 Assistance wanted - this module could really use a maintainer with enough time
293 to at least review and apply more patches. Or the module should just be
294 deprecated in favor of Net::SSH::Expect or made into an ::Any style
295 compatibility wrapper that uses whatver implementation is avaialble
296 (Net::SSH2, Net::SSH::Perl or shelling out like the modules does now). Please
297 email Ivan if you are interested in helping.
299 John Harrison <japh@in-ta.net> contributed an example for the documentation.
301 Martin Langhoff <martin@cwa.co.nz> contributed the ssh_cmd command, and
302 Jeff Finucane <jeff@cmh.net> updated it and took care of the 0.04 release.
304 Anthony Awtrey <tony@awtrey.com> contributed a fix for those still using
307 Thanks to terrence brannon <tbone@directsynergy.com> for the documentation in
308 the GENERATING AND USING SSH KEYS section.
312 Copyright (c) 2004 Ivan Kohler.
313 Copyright (c) 2007 Freeside Internet Services, Inc.
315 This program is free software; you can redistribute it and/or modify it under
316 the same terms as Perl itself.
322 Look at IPC::Session (also fsh, well now the native SSH "master mode" stuff)
326 For a perl implementation that does not require the system B<ssh> command, see
327 L<Net::SSH::Perl> instead.
329 For a wrapper version that allows you to use passwords, see L<Net::SSH::Expect>
332 For another non-forking version that uses the libssh2 library, see
335 For a way to execute remote Perl code over an ssh connection see
338 ssh-keygen(1), ssh(1), L<IO::File>, L<IPC::Open2>, L<IPC::Open3>