Under the hood

This package is implemented around the multiplexing feature found in later versions of OpenSSH. That feature allows one to run several sessions over a single SSH connection (OpenSSH 4.1 was the first one to provide all the required functionality).

When a new Net::OpenSSH object is created, the OpenSSH "ssh" client is run in master mode, establishing a persistent (for the lifetime of the object) connection to the server.

Then, every time a new operation is requested a new "ssh" process is started in slave mode, effectively reusing the master SSH connection to send the request to the remote side.

Net::OpenSSH Vs. Net::SSH::.* modules

Why should you use Net::OpenSSH instead of any of the other Perl SSH clients available?

Well, this is my (biased) opinion:

Net::SSH::Perl is not well maintained nowadays (update: a new maintainer has stepped in so this situation could change!!!), requires a bunch of modules (some of them very difficult to install) to be acceptably efficient and has an API that is limited in some ways.

Net::SSH2 is much better than Net::SSH::Perl, but not completely stable yet. It can be very difficult to install on some specific operating systems and its API is also limited, in the same way as Net::SSH::Perl.

Using Net::SSH::Expect, in general, is a bad idea. Handling interaction with a shell via Expect in a generic way just can not be reliably done.

Net::SSH is just a wrapper around any SSH binary commands available on the machine. It can be very slow as they establish a new SSH connection for every operation performed.

In comparison, Net::OpenSSH is a pure perl module that does not have any mandatory dependencies (obviously, besides requiring OpenSSH binaries).

Net::OpenSSH has a very perlish interface. Most operations are performed in a fashion very similar to that of the Perl builtins and common modules (e.g. IPC::Open2).

It is also very fast. The overhead introduced by launching a new ssh process for every operation is not appreciable (at least on my Linux box). The bottleneck is the latency intrinsic to the protocol, so Net::OpenSSH is probably as fast as an SSH client can be.

Being based on OpenSSH is also an advantage: a proved, stable, secure (to paranoid levels), inseparably and well maintained implementation of the SSH protocol is used.

On the other hand, Net::OpenSSH does not work on Windows, not even under Cygwin.

Net::OpenSSH specifically requires the OpenSSH SSH client (AFAIK, the multiplexing feature is not available from any other SSH client). However, note that it will interact with any server software, not just servers running OpenSSH "sshd".

For password authentication, IO::Pty has to be installed. Other modules and binaries are also required to implement specific functionality (for instance Net::SFTP::Foreign, Expect or rsync(1)).

Net::OpenSSH and Net::SSH2 do not support version 1 of the SSH protocol.

Optional arguments

Almost all methods in this package accept as first argument an optional reference to a hash containing parameters ("\%opts"). For instance, these two method calls are equivalent:

my $out1 = $ssh->capture(@cmd);
my $out2 = $ssh->capture({}, @cmd);

Error handling

Most methods return undef (or an empty list) to indicate failure.

The "error" method can always be used to explicitly check for errors. For instance:

my ($output, $errput) = $ssh->capture2({timeout => 1}, "find /");
$ssh->error and die "ssh failed: " . $ssh->error;

Net::OpenSSH methods

These are the methods provided by the package:

Net::OpenSSH->new($host, %opts)

Creates a new SSH master connection

$host can be a hostname or an IP address. It may also contain the name of the user, her password and the TCP port number where the server is listening:

my $ssh1 = Net::OpenSSH->new('jack@foo.bar.com');
my $ssh2 = Net::OpenSSH->new('jack:secret@foo.bar.com:10022');
my $ssh3 = Net::OpenSSH->new('jsmith@2001:db8::1428:57ab'); # IPv6

IPv6 addresses may optionally be enclosed in brackets:

my $ssh4 = Net::OpenSSH->new('jsmith@[::1]:1022');

This method always succeeds in returning a new object. Error checking has to be performed explicitly afterwards:

my $ssh = Net::OpenSSH->new($host, %opts);
$ssh->error and die "Can't ssh to $host: " . $ssh->error;

If you have problems getting Net::OpenSSH to connect to the remote host read the troubleshooting chapter near the end of this document.

Accepted options:

$ssh->error

Returns the error condition for the last performed operation.

The returned value is a dualvar as $! (see "$!" in perlvar) that renders an informative message when used in string context or an error number in numeric context (error codes appear in Net::OpenSSH::Constants).

$ssh->get_master_pty_log

In order to handle password authentication or entering the passphrase for a private key, Net::OpenSSH may run the master SSH process attached to a pty.

In that case and after a constructor call returns a connection failure error, this method can be called to retrieve the output captured at the pty (the log is discarded when the connection is established successfully).

Any data consumed from the pty by custom login handlers will be missing from the the returned log.

$ssh->get_user

$ssh->get_host

$ssh->get_port

Return the corresponding SSH login parameters.

$ssh->get_ctl_path

Returns the path to the socket where the OpenSSH master process listens for new multiplexed connections.

($in, $out, $err, $pid) = $ssh->open_ex(\%opts, @cmd)

Note: this is a low level method which, probably, you do not need to use!

That method starts the command @cmd on the remote machine creating new pipes for the IO channels as specified on the %opts hash.

If @cmd is omitted, the remote user shell is run.

Returns four values, the first three ($in, $out and $err) correspond to the local side of the pipes created (they can be undef) and the fourth ($pid) to the PID of the new SSH slave process. An empty list is returned on failure.

Note that "waitpid" has to be used afterwards to reap the slave SSH process.

Accepted options:

# similar to IPC::Open2 open2 function:
my ($in_pipe, $out_pipe, undef, $pid) =
    $ssh->open_ex( { stdin_pipe => 1,
                     stdout_pipe => 1 },
                   @cmd )
    or die "open_ex failed: " . $ssh->error;
# do some IO through $in/$out
# ...
waitpid($pid);

setpgrp => 1

Calls "setpgrp" after forking the child process. As a result it will not die when the user presses Ctrl+C at the console. See also "setpgrp" in perlfunc.

Using this option without also setting "master_setpgrp" on the constructor call is mostly useless as the signal will be delivered to the master process and all the remote commands aborted.

This feature is experimental.

$ssh->system(\%opts, @cmd)

Runs the command @cmd on the remote machine.

Returns true on success, undef otherwise.

The error status is set to "OSSH_SLAVE_CMD_FAILED" when the remote command exits with a non zero code (the code is available from $?, see "$?" in perlvar).

Example:

$ssh->system('ls -R /')
  or die "ls failed: " . $ssh->error";

As for "system" builtin, "SIGINT" and "SIGQUIT" signals are blocked. (see "system" in perlfunc). Also, setting $SIG{CHLD} to "IGNORE" or to a custom signal handler will interfere with this method.

Accepted options:

$ok = $ssh->test(\%opts, @cmd);

Runs the given command and returns its success/failure exit status as 1 or 0 respectively. Returns undef when something goes wrong in the SSH layer.

Error status is not set to OSSH_SLAVE_CMD_FAILED when the remote command exits with a non-zero code.

By default this method discards the remote command "stdout" and "sterr" streams.

Usage example:

if ($ssh->test(ps => -C => $executable)) {
  say "$executable is running on remote machine"
}
else {
  die "something got wrong: ". $ssh->error if $ssh->error;
  say "$executable is not running on remote machine"
}

This method support the same set of options as "system", except "async" and "tunnel".

$output = $ssh->capture(\%opts, @cmd);

@output = $ssh->capture(\%opts, @cmd);

This method is conceptually equivalent to the perl backquote operator (e.g. `ls`): it runs the command on the remote machine and captures its output.

In scalar context returns the output as a scalar. In list context returns the output broken into lines (it honors $/, see "$/" in perlvar).

The exit status of the remote command is returned in $?.

When an error happens while capturing (for instance, the operation times out), the partial captured output will be returned. Error conditions have to be explicitly checked using the "error" method. For instance:

my $output = $ssh->capture({ timeout => 10 },
                           "echo hello; sleep 20; echo bye");
$ssh->error and
    warn "operation didn't complete successfully: ". $ssh->error;
print $output;

Setting $SIG{CHLD} to a custom signal handler or to "IGNORE" will interfere with this method.

Accepted options:

($output, $errput) = $ssh->capture2(\%opts, @cmd)

captures the output sent to both stdout and stderr by @cmd on the remote machine.

Setting $SIG{CHLD} to a custom signal handler or to "IGNORE" will also interfere with this method.

The accepted options are:

($in, $pid) = $ssh->pipe_in(\%opts, @cmd)

This method is similar to the following Perl "open" call

$pid = open $in, '|-', @cmd

but running @cmd on the remote machine (see "open" in perlfunc).

No options are currently accepted.

There is no need to perform a waitpid on the returned PID as it will be done automatically by perl when $in is closed.

Example:

my ($in, $pid) = $ssh->pipe_in('cat >/tmp/fpp')
    or die "pipe_in failed: " . $ssh->error;
print $in $_ for @data;
close $in or die "close failed";

($out, $pid) = $ssh->pipe_out(\%opts, @cmd)

Reciprocal to previous method, it is equivalent to

$pid = open $out, '-|', @cmd

running @cmd on the remote machine.

No options are currently accepted.

($in, $out, $pid) = $ssh->open2(\%opts, @cmd)

($pty, $pid) = $ssh->open2pty(\%opts, @cmd)

($socket, $pid) = $ssh->open2socket(\%opts, @cmd)

($in, $out, $err, $pid) = $ssh->open3(\%opts, @cmd)

($pty, $err, $pid) = $ssh->open3pty(\%opts, @cmd)

Shortcuts around "open_ex" method.

$pid = $ssh->spawn(\%opts, @_)

Another "open_ex" shortcut, it launches a new remote process in the background and returns the PID of the local slave SSH process.

At some later point in your script, "waitpid" should be called on the returned PID in order to reap the slave SSH process.

For instance, you can run some command on several hosts in parallel with the following code:

my %conn = map { $_ => Net::OpenSSH->new($_, async => 1) } @hosts;
my @pid;
for my $host (@hosts) {
    open my($fh), '>', "/tmp/out-$host.txt"
      or die "unable to create file: $!";
    push @pid, $conn{$host}->spawn({stdout_fh => $fh}, $cmd);
}
waitpid($_, 0) for @pid;

Note that "spawn" should not be used to start detached remote processes that may survive the local program (see also the "FAQ" about running remote processes detached).

($socket, $pid) = $ssh->open_tunnel(\%opts, $dest_host, $port)

($socket, $pid) = $ssh->open_tunnel(\%opts, $socket_path)

Similar to "open2socket", but instead of running a command, it opens a TCP tunnel to the given address. See also "Tunnels".

$out = $ssh->capture_tunnel(\%opts, $dest_host, $port)

@out = $ssh->capture_tunnel(\%opts, $dest_host, $port)

Similar to "capture", but instead of running a command, it opens a TCP tunnel.

Example:

$out = $ssh->capture_tunnel({stdin_data => join("\r\n",
                                                "GET / HTTP/1.0",
                                                "Host: www.perl.org",
                                                "", "") },
                            'www.perl.org', 80)

See also "Tunnels".

$ssh->scp_get(\%opts, $remote1, $remote2,..., $local_dir_or_file)

$ssh->scp_put(\%opts, $local, $local2,..., $remote_dir_or_file)

These two methods are wrappers around the "scp" command that allow transfers of files to/from the remote host using the existing SSH master connection.

When transferring several files, the target argument must point to an existing directory. If only one file is to be transferred, the target argument can be a directory or a file name or can be omitted. For instance:

$ssh->scp_get({glob => 1}, '/var/tmp/foo*', '/var/tmp/bar*', '/tmp');
$ssh->scp_put('/etc/passwd');

Both "scp_get" and "scp_put" methods return a true value when all the files are transferred correctly, otherwise they return undef.

Accepted options:

$ssh->rsync_get(\%opts, $remote1, $remote2,..., $local_dir_or_file)

$ssh->rsync_put(\%opts, $local1, $local2,..., $remote_dir_or_file)

These methods use "rsync" over SSH to transfer files from/to the remote machine.

They accept the same set of options as the "scp" ones.

Any unrecognized option will be passed as an argument to the "rsync" command (see rsync(1)). Underscores can be used instead of dashes in "rsync" option names.

For instance:

$ssh->rsync_get({exclude => '*~',
                 verbose => 1,
                 safe_links => 1},
                '/remote/dir', '/local/dir');

$sftp = $ssh->sftp(%sftp_opts)

Creates a new Net::SFTP::Foreign object for SFTP interaction that runs through the ssh master connection.

@call = $ssh->make_remote_command(\%opts, @cmd)

$call = $ssh->make_remote_command(\%opts, @cmd)

This method returns the arguments required to execute a command on the remote machine via SSH. For instance:

my @call = $ssh->make_remote_command(ls => "/var/log");
system @call;

In scalar context, returns the arguments quoted and joined into one string:

my $remote = $ssh->make_remote_comand("cd /tmp/ && tar xf -");
system "tar cf - . | $remote";

The options accepted are as follows:

$ssh->wait_for_master($async)

When the connection has been established by calling the constructor with the "async" option, this call allows one to advance the process.

If $async is true, it will perform any work that can be done immediately without waiting (for instance, entering the password or checking for the existence of the multiplexing socket) and then return. If a false value is given, it will finalize the connection process and wait until the multiplexing socket is available.

It returns a true value after the connection has been successfully established. False is returned if the connection process fails or if it has not yet completed (then, the "error" method can be used to distinguish between both cases).

From version 0.64 upwards, undef is returned when the master is still in an unstable state (login, killing, etc.) and 0 when it is in a stable state (running, stopped or gone).

$ssh->check_master

This method runs several checks to ensure that the master connection is still alive.

$ssh->shell_quote(@args)

Returns the list of arguments quoted so that they will be restored to their original form when parsed by the remote shell.

In scalar context returns the list of arguments quoted and joined.

Usually this task is done automatically by the module. See "Shell quoting" below.

This method can also be used as a class method.

Example:

my $quoted_args = Net::OpenSSH->shell_quote(@args);
system('ssh', '--', $host, $quoted_args);

$ssh->shell_quote_glob(@args)

This method is like the previous "shell_quote" but leaves wildcard characters unquoted.

It can be used as a class method also.

$ssh->set_expand_vars($bool)

Enables/disables variable expansion feature (see "Variable expansion").

$ssh->get_expand_vars

Returns current state of variable expansion feature.

$ssh->set_var($name, $value)

$ssh->get_var($name, $value)

These methods allow one to change and to retrieve the value of the given name.

$ssh->get_master_pid

Returns the PID of the master SSH process

$ssh->master_exited

This methods allows one to tell the module that the master process has exited when we get its PID from some external wait or waitpid call. For instance:

my $ssh = Net::OpenSSH->new('foo', async => 1);
# create new processes
# ...
# rip them...
my $master_pid = $ssh->master_pid;
while ((my $pid = wait) > 0) {
  if ($pid == $master_pid) {
    $ssh->master_exited;
  }
}

If your program rips the master process and this method is not called, the OS could reassign the PID to a new unrelated process and the module would try to kill it at object destruction time.

$ssh->disconnect($async)

Shuts down the SSH connection.

Usually, you don't need to call this method explicitly, but just let the Net::OpenSSH object go out of scope.

If "async" is true, it doesn't wait for the SSH connection to terminate. In that case, "wait_for_master" must be called repeatedly until the shutdown sequence terminates (See the "AnyEvent" integration section below).

$ssh->restart($async)

Restarts the SSH session closing any open connection and creating a new one. Any open channel would also be killed.

Note that calling this method may request again the password or passphrase from the user.

In asynchronous mode, this method requires the connection to be terminated before it gets called. Afterwards, "wait_for_master" should be called repeatedly until the new connection is established. For instance:

my $async = 1;
$ssh->disconnect($async);
while (1) {
  defined $ssh->wait_for_master($async) # returns 0 when the
                                        # disconnect process
                                        # finishes
    and last;
  do_something_else();
}
$ssh->restart($async);
while (1) {
  defined $ssh->wait_for_master($async)
    and last;
  do_something_else();
}

$pid = $ssh->sshfs_import(\%opts, $remote_fs, $local_mnt_point)

$pid = $ssh->sshfs_export(\%opts, $local_fs, $remote_mnt_point)

These methods use sshfs(1) to import or export a file system through the SSH connection.

They return the $pid of the "sshfs" process or of the slave "ssh" process used to proxy it. Killing that process unmounts the file system, though, it may be probably better to use fusermount(1).

The options accepted are as follows:

$or = $ssh->object_remote(@args)

Returns an Object::Remote::Connection instance running on top of the Net::OpenSSH connection.

Example:

my $or = $ssh->object_remote;
my $hostname = Sys::Hostname->can::on($or, 'hostname');
say $hostname->();

See also Object::Remote.

$any = $ssh->any(%opts)

Wraps the current object inside a Net::SSH::Any one.

Example:

my $any = $ssh->any;
my $content = $any->scp_get_content("my-file.txt");

$pid = $ssh->disown_master

Under normal operation Net::OpenSSH controls the life-time of the master "ssh" process and when the object is destroyed the master process and any connection running over it are terminated.

In some (rare) cases, it is desirable to let the master process and all the running connections survive. Calling this method does just that, it tells Net::OpenSSH object that the master process is not its own anymore.

The return value is the PID of the master process.

Note also that disowning the master process does not affect the operation of the module in any other regard.

For instance:

# See examples/sshfs_mount.pl for a working program
my $ssh = Net::OpenSSH->new($host);
my $sshfs_pid = $ssh->sshfs_import("/home/foo", "my-remote-home");
$ssh->disown_master;
$ssh->stop; # tells the master to stop accepting requests
exit(0);

$ssh->default_ssh_configuration

Allows one to retrieve the default SSH configuration for the target host from system files (i.e. "/etc/ssh/ssh_config") and user files ("~/.ssh/config").

Under the hood, this method just calls "ssh -G $host" and returns the output unprocessed.

Example:

my $ssh = Net::OpenSSH->new($host, connect => 0);
my $txt = $ssh->default_ssh_configuration;
my @lines = split /^/m, $txt;
chomp @lines;
my %def_cfg = map split(/\s+/, $_, 2), @lines;

Shell quoting

By default, when invoking remote commands, this module tries to mimic perl "system" builtin in regard to argument processing. Quoting "system" in perlfunc:

Argument processing varies depending on the number of arguments.  If
there is more than one argument in LIST, or if LIST is an array with
more than one value, starts the program given by the first element
of the list with arguments given by the rest of the list.  If there
is only one scalar argument, the argument is checked for shell
metacharacters, and if there are any, the entire argument is passed
to the system's command shell for parsing (this is "/bin/sh -c" on
Unix platforms, but varies on other platforms).

Take for example Net::OpenSSH "system" method:

$ssh->system("ls -l *");
$ssh->system('ls', '-l', '/');

The first call passes the argument unchanged to ssh and it is executed in the remote side through the shell which interprets metacharacters.

The second call escapes any shell metacharacters so that, effectively, it is equivalent to calling the command directly and not through the shell.

Under the hood, as the Secure Shell protocol does not provide for this mode of operation and always spawns a new shell where it runs the given command, Net::OpenSSH quotes any shell metacharacters in the command list.

All the methods that invoke a remote command (system, open_ex, etc.) accept the option "quote_args" that allows one to force/disable shell quoting.

For instance:

$ssh->system({quote_args => 1}, "/path with spaces/bin/foo");

will correctly handle the spaces in the program path.

The shell quoting mechanism implements some extensions (for instance, performing redirections to /dev/null on the remote side) that can be disabled with the option "quote_args_extended":

$ssh->system({ stderr_discard => 1,
               quote_args => 1, quote_args_extended => 0 },
             @cmd);

The option "quote_args" can also be used to disable quoting when more than one argument is passed. For instance, to get some pattern expanded by the remote shell:

$ssh->system({quote_args => 0}, 'ls', '-l', "/tmp/files_*.dat");

The method "shell_quote" can be used to selectively quote some arguments and leave others untouched:

$ssh->system({quote_args => 0},
             $ssh->shell_quote('ls', '-l'),
             "/tmp/files_*.dat");

When the glob option is set in "scp" and "rsync" file transfer methods, an alternative quoting method which knows about file wildcards and passes them unquoted is used. The set of wildcards recognized currently is the one supported by bash(1).

Another way to selectively use quote globing or fully disable quoting for some specific arguments is to pass them as scalar references or double scalar references respectively. In practice, that means prepending them with one or two backslashes. For instance:

# quote the last argument for globing:
$ssh->system('ls', '-l', \'/tmp/my files/filed_*dat');
# append a redirection to the remote command
$ssh->system('ls', '-lR', \\'>/tmp/ls-lR.txt');
# expand remote shell variables and glob in the same command:
$ssh->system('tar', 'czf', \\'$HOME/out.tgz', \'/var/log/server.*.log');

As shell quoting is a tricky matter, I expect bugs to appear in this area. You can see how "ssh" is called, and the quoting used setting the following debug flag:

$Net::OpenSSH::debug |= 16;

By default, the module assumes the remote shell is some variant of a POSIX or Bourne shell ("bash", "dash", "ksh", etc.). If this is not the case, the construction option "remote_shell" can be used to select an alternative quoting mechanism.

For instance:

$ssh = Net::OpenSSH->new($host, remote_shell => 'csh');
$ssh->system(echo => "hard\n to\n  quote\n   argument!");

Currently there are quoters available for POSIX (Bourne) compatible shells, "csh" and the two Windows variants "MSWin" (for servers using Win32::CreateProcess, see Net::OpenSSH::ShellQuoter::MSWin) and "MSCmd" (for servers using "cmd.exe", see Net::OpenSSH::ShellQuoter::MSCmd).

In any case, you can always do the quoting yourself and pass the quoted remote command as a single string:

# for VMS
$ssh->system('DIR/SIZE NFOO::USERS:[JSMITH.DOCS]*.TXT;0');

Note that the current quoting mechanism does not handle possible aliases defined by the remote shell. In that case, to force execution of the command instead of the alias, the full path to the command must be used.

Timeouts

In order to stop remote processes when they timeout, the ideal approach would be to send them signals through the SSH connection as specified by the protocol standard.

Unfortunately OpenSSH does not implement that feature so Net::OpenSSH has to use other imperfect approaches:

• close slave I/O streams

  Closing the STDIN and STDOUT streams of the unresponsive remote process will effectively deliver a SIGPIPE when it tries to access any of them.

  Remote processes may not access STDIN or STDOUT and even then, Net::OpenSSH can only close these channels when it is capturing them, so this approach does not always work.

• killing the local SSH slave process

  This action may leave the remote process running, creating a remote orphan so Net::OpenSSH does not use it unless the construction option "kill_ssh_on_timeout" is set.

Luckily, future versions of OpenSSH will support signaling remote processes via the mux channel.

Variable expansion

The variable expansion feature allows one to define variables that are expanded automatically inside command arguments and file paths.

This feature is disabled by default. It is intended to be used with Net::OpenSSH::Parallel and other similar modules.

Variables are delimited by a pair of percent signs ("%"), for instance "%HOST%". Also, two consecutive percent signs are replaced by a single one.

The special variables "HOST", "USER" and "PORT" are maintained internally by the module and take the obvious values.

Variable expansion is performed before shell quoting (see "Shell quoting").

Some usage example:

my $ssh = Net::OpenSSH->new('server.foo.com', expand_vars => 1);
$ssh->set_var(ID => 42);
$ssh->system("ls >/tmp/ls.out-%HOST%-%ID%");

will redirect the output of the "ls" command to "/tmp/ls.out-server.foo.com-42" on the remote host.

Tunnels

Besides running commands on the remote host, Net::OpenSSH also allows one to tunnel TCP connections to remote machines reachable from the SSH server.

That feature is made available through the "tunnel" option of the "open_ex" method, and also through wrapper methods "open_tunnel" and "capture_tunnel" and most others where it makes sense.

Example:

$ssh->system({tunnel => 1,
              stdin_data => "GET / HTTP/1.0\r\n\r\n",
              stdout_file => "/tmp/$server.res"},
             $server, 80)
    or die "unable to retrieve page: " . $ssh->error;

or capturing the output of several requests in parallel:

my @pids;
for (@servers) {
  my $pid = $ssh->spawn({tunnel => 1,
                         stdin_file => "/tmp/request.req",
                         stdout_file => "/tmp/$_.res"},
                        $_, 80);
  if ($pid) {
    push @pids, $pid;
  }
  else {
    warn "unable to spawn tunnel process to $_: " . $ssh->error;
  }
}
waitpid ($_, 0) for (@pids);

Under the hood, in order to create a tunnel, a new "ssh" process is spawned with the option "-W${address}:${port}" (available from OpenSSH 5.4 and upwards) making it redirect its stdio streams to the remote given address. Unlike when "ssh" "-L" options is used to create tunnels, no TCP port is opened on the local machine at any time so this is a perfectly secure operation.

The PID of the new process is returned by the named methods. It must be reaped once the pipe or socket handlers for the local side of the tunnel have been closed.

OpenSSH 5.4 or later is required for the tunnels functionality to work. Also, note that tunnel forwarding may be administratively forbidden at the server side (see sshd(8) and sshd_config(5) or the documentation provided by your SSH server vendor).

Tunnels targeting UNIX sockets

When connecting to hosts running a recent version of OpenSSH sshd, it is also possible to open connections targeting Unix sockets.

For instance:

my $response = $ssh->capture({tunnel => 1, stdin_data => $request },
                             "/tmp/socket-foo");

Currently, this feature requires a patched OpenSSH ssh client. The patch is available as "patches/openssh-fwd-stdio-to-streamlocal-1.patch".

Port forwarding

Net::OpenSSH does not offer direct support for handling port forwardings between server and client. But that can be done easily anyway passing custom SSH options to its methods.

For instance, tunnel creation options can be passed to the constructor:

my $ssh = Net::OpenSSH->new(...
                  master_opts => -Llocalhost:1234:localhost:3306');

The port forwardings can also be changed for a running SSH connection using a Control command:

# setting up a tunnel:
$ssh->system({ssh_opts => ['-O','forward',
                           '-L127.0.0.1:12345:127.0.0.1:3306']});
# canceling it:
$ssh->system({ssh_opts => ['-O', 'cancel',
                           '-L127.0.0.1:12345:127.0.0.1:3306']});

Data encoding

Net::OpenSSH has some support for transparently converting the data send or received from the remote server to Perl internal unicode representation.

The methods supporting that feature are those that move data from/to Perl data structures (e.g. "capture", "capture2", "capture_tunnel" and methods supporting the "stdin_data" option). Data accessed through pipes, sockets or redirections is not affected by the encoding options.

It is also possible to set the encoding of the command and arguments passed to the remote server on the command line.

By default, if no encoding option is given on the constructor or on the method calls, Net::OpenSSH will not perform any encoding transformation, effectively processing the data as "latin1".

When data can not be converted between the Perl internal representation and the selected encoding inside some Net::OpenSSH method, it will fail with an "OSSH_ENCODING_ERROR" error.

The supported encoding options are as follows:

stream_encoding => $encoding

sets the encoding of the data send and received on capture methods.

argument_encoding => $encoding

sets the encoding of the command line arguments

encoding => $encoding

sets both "argument_encoding" and "stream_encoding".

The constructor also accepts "default_encoding", "default_stream_encoding" and "default_argument_encoding" that set the defaults.

Diverting "new"

When a code ref is installed at $Net::OpenSSH::FACTORY, calls to new will be diverted through it.

That feature can be used to transparently implement connection caching, for instance:

my $old_factory = $Net::OpenSSH::FACTORY;
my %cache;
sub factory {
  my ($class, %opts) = @_;
  my $signature = join("\0", $class, map { $_ => $opts{$_} }, sort keys %opts);
  my $old = $cache{signature};
  return $old if ($old and $old->error != OSSH_MASTER_FAILED);
  local $Net::OpenSSH::FACTORY = $old_factory;
  $cache{$signature} = $class->new(%opts);
}
$Net::OpenSSH::FACTORY = \&factory;

... and I am sure it can be abused in several other ways!

Expect

Sometimes you would like to use Expect to control some program running in the remote host. You can do it as follows:

my ($pty, $pid) = $ssh->open2pty(@cmd)
    or die "unable to run remote command @cmd";
my $expect = Expect->init($pty);

Then, you will be able to use the new Expect object in $expect as usual.

Net::Telnet

This example is adapted from Net::Telnet documentation:

my ($pty, $pid) = $ssh->open2pty({stderr_to_stdout => 1})
  or die "unable to start remote shell: " . $ssh->error;
my $telnet = Net::Telnet->new(-fhopen => $pty,
                              -prompt => '/.*\$ $/',
                              -telnetmode => 0,
                              -cmd_remove_mode => 1,
                              -output_record_separator => "\r");
$telnet->waitfor(-match => $telnet->prompt,
                 -errmode => "return")
  or die "login failed: " . $telnet->lastline;
my @lines = $telnet->cmd("who");
...
$telnet->close;
waitpid($pid, 0);

mod_perl and mod_perl2

mod_perl and mod_perl2 tie STDIN and STDOUT to objects that are not backed up by real file descriptors at the operating system level. Net::OpenSSH will fail if any of these handles is used explicitly or implicitly when calling some remote command.

The work-around is to redirect them to "/dev/null" or to some file:

open my $def_in, '<', '/dev/null' or die "unable to open /dev/null";
my $ssh = Net::OpenSSH->new($host,
                            default_stdin_fh => $def_in);
my $out = $ssh->capture($cmd1);
$ssh->system({stdout_discard => 1}, $cmd2);
$ssh->system({stdout_to_file => '/tmp/output'}, $cmd3);

Also, note that from a security stand point, running "ssh" from inside the web server process is not a great idea. An attacker exploiting some Apache bug would be able to access the SSH keys and passwords and gain unlimited access to the remote systems.

If you can, use a queue (as TheSchwartz) or any other mechanism to execute the ssh commands from another process running under a different user account.

At a minimum, ensure that "~www-data/.ssh" (or similar) is not accessible through the web server!

Net::SFTP::Foreign

See method "sftp".

Net::SSH::Any

See method "any".

Object::Remote

See method "object_remote".

AnyEvent (and similar frameworks)

Net::OpenSSH provides all the functionality required to be integrated inside event oriented programming framework such as AnyEvent or IO::Async in the following way:

1. Create a disconnected Net::OpenSSH object:

my $ssh = Net::OpenSSH->new($host, async => 1, ...);

2. Let the object connect to the remote host:

Use a timer to call the "wait_for_master" method in async mode repeatedly until it returns a true value indicating success.

Also, the object error state needs to be checked after every call in order to detect failed connections. For instance:

my $ssh = Net::OpenSSH->new(..., async => 1);
my $w;
$w = AE::timer 0.1, 0.1, sub {
  if ($ssh->wait_for_master(1)) {
    # the connection has been established!
    # remote commands can be run now
    undef $w;
    on_ssh_success(...);
  }
  elsif ($ssh->error) {
    # connection can not be established
    undef $w;
    on_ssh_failure(...);
  }
}

3. Use the event framework to launch the remote processes:

Call Net::OpenSSH "make_remote_command" to construct commands which can be run using the framework regular facilities for launching external commands.

Error checking should also be performed at this point because the SSH connection could be broken.

For instance:

if (defined(my $cmd = $ssh->make_remote_command(echo => 'hello!')) {
  AnyEvent::Util::run_cmd($cmd, %run_cmd_opts);
}
else {
  # something went wrong!
}

Alternatively, any of the "open*" methods provided by Net::OpenSSH could also be used to launch remote commands.

4. When finished, disconnect asynchronously

After initiating an asynchronous disconnect with disconnect(1), repeatedly call "wait_for_master" until you get a defined but false value:

$ssh->disconnect(1);
my $w; $w = AE::timer 0.1, 0.1, sub {
  my $res = $ssh->wait_for_master(1);
  if (defined $res && !$res) {
    undef $w;
    undef $ssh;
  }
};

Be careful not to let the $ssh object go out of scope until the disconnection has finished, otherwise its destructor will wait and block your program until the disconnection has completed.

Other modules

CPAN contains several modules that rely on SSH to perform their duties as for example IPC::PerlSSH or GRID::Machine.

Often, it is possible to instruct them to go through a Net::OpenSSH multiplexed connection employing some available constructor option. For instance:

use Net::OpenSSH;
use IPC::PerlIPC;
my $ssh = Net::OpenSSH->new(...);
$ssh->error and die "unable to connect to remote host: " . $ssh->error;
my @cmd = $ssh->make_remote_command('/usr/bin/perl');
my $ipc = IPC::PerlSSH->new(Command => \@cmd);
my @r = $ipc->eval('...');

or...

use GRID::Machine;
...
my @cmd = $ssh->make_remote_command('/usr/bin/perl');
my $grid = GRID::Machine->new(command => \@cmd);
my $r = $grid->eval('print "hello world!\n"');

In other cases, some kind of plugin mechanism is provided by the 3rd party modules to allow for different transports. The method "open2" may be used to create a pair of pipes for transport in these cases.

Experimental features

Support for the "restart" feature is experimental.

Object::Remote integration is highly experimental.

Support for tunnels targeting Unix sockets is highly experimental.

Support for the "setpgrp" feature is highly experimental.

Support for the gateway feature is highly experimental and mostly stalled.

Support for taint mode is experimental.

Known issues

Net::OpenSSH does not work on Windows. OpenSSH multiplexing feature requires passing file handles through sockets, something that is not supported by any version of Windows.

It does not work on VMS either... well, probably, it does not work on anything not resembling a modern Linux/Unix OS.

Old versions of OpenSSH "ssh" may leave stdio streams in non-blocking mode. That can result on failures when writing to "STDOUT" or "STDERR" after using the module. In order to work-around this issue, Perl "fcntl" in perlfunc can be used to unset the non-blocking flag:

use Fcntl qw(F_GETFL F_SETFL O_NONBLOCK);
my $flags = fcntl(STDOUT, F_GETFL, 0);
fcntl(STDOUT, F_SETFL, $flags & ~O_NONBLOCK);

Reporting bugs and asking for help

To report bugs send an email to the address that appear below or use the CPAN bug tracking system at http://rt.cpan.org.

Post questions related to how to use the module in PerlMonks http://perlmonks.org/, you will probably get faster responses than if you address me directly and I visit PerlMonks quite often, so I will see your question anyway.

Commercial support

Commercial support, professional services and custom software development around this module are available through my current company. Drop me an email with a rough description of your requirements and we will get back to you ASAP.

My wishlist

If you like this module and you are feeling generous, take a look at my Amazon Wish List: http://amzn.com/w/1WU1P6IR5QZ42.

Also consider contributing to the OpenSSH project this module builds upon: http://www.openssh.org/donations.html.