Net::OpenSSH(3)

📦

version 0.84 · 11 versions

0.84 · alpine 3.22 (latest)
0.82 · epel 9
0.84 · epel 10
0.84 · alpine 3.23
0.84 · alpine 3.24
0.84 · arch rolling
0.84 · fedora 43
0.80 · ubuntu jammy
0.84 · fedora 44
0.83 · debian bookworm
0.84 · debian trixie, ubuntu noble, ubuntu resolute, ubuntu stonking

🐚 Net::OpenSSH(3) 🐚

Okay bestie, welcome to the manual page for Net::OpenSSH — that's the Net::OpenSSH(3) manpage, filed under User Contributed Perl Documentation. Grab a snack, this one's a whole saga 💖

✨ NAME ✨

Net::OpenSSH — a Perl SSH client package implemented on top of OpenSSH 🫶

🌸 SYNOPSIS 🌸

  use Net::OpenSSH;

  my $ssh = Net::OpenSSH->new($host);
  $ssh->error and
    die "Couldn't establish SSH connection: ". $ssh->error;

  $ssh->system("ls /tmp") or
    die "remote command failed: " . $ssh->error;

  my @ls = $ssh->capture("ls");
  $ssh->error and
    die "remote ls command failed: " . $ssh->error;

  my ($out, $err) = $ssh->capture2("find /root");
  $ssh->error and
    die "remote find command failed: " . $ssh->error;

  my ($rin, $pid) = $ssh->pipe_in("cat >/tmp/foo") or
    die "pipe_in method failed: " . $ssh->error;

  print $rin "hello\n";
  close $rin;

  my ($rout, $pid) = $ssh->pipe_out("cat /tmp/foo") or
    die "pipe_out method failed: " . $ssh->error;

  while (<$rout>) { print }
  close $rout;

  my ($in, $out ,$pid) = $ssh->open2("foo");
  my ($pty, $pid) = $ssh->open2pty("foo");
  my ($in, $out, $err, $pid) = $ssh->open3("foo");
  my ($pty, $err, $pid) = $ssh->open3pty("login");

  my $sftp = $ssh->sftp();
  $sftp->error and die "SFTP failed: " . $sftp->error;

Look at all those little snippets, they're so cute, they're literally the entire vibe of the module in one block 💅

🦋 DESCRIPTION 🦋

So. Net::OpenSSH is a secure shell client package that's implemented on top of the OpenSSH binary client (ssh). Yes, the actual binary. It's giving "stand on the shoulders of giants" energy and honestly? Iconic 👑

🎀 Under the hood 🎀

This package is built around the multiplexing feature that showed up in later versions of OpenSSH — that feature is what lets you run several sessions over a single SSH connection. Quick history flex: OpenSSH 4.1 was the first one to provide all the required functionality, so that's the bar, bestie ⭐

The way it works: when a new Net::OpenSSH object gets created, the OpenSSH ssh client runs in master mode, and it establishes a persistent connection to the server — persistent for the entire lifetime of the object, no cap.

Then, every single time a new operation is requested, a new ssh process is started in slave mode, effectively reusing that master SSH connection to send the request on over to the remote side. Chef's kiss, so efficient, we love to see it 💖

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

Okay so the big question: why would you use Net::OpenSSH instead of literally any of the other Perl SSH clients out there?

Well. Here's the author's own (self-admittedly biased) opinion, and I'm relaying it faithfully because that's the gig 🫶

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

Net::SSH2 is much better than Net::SSH::Perl, but it's 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.

Net::SSH::Expect, in general, is a bad idea. Like, genuinely. Handling interaction with a shell via Expect in a generic way just can not be reliably done. That's the whole thing, no notes 💀

Net::SSH is just a wrapper around whatever SSH binary commands happen to be available on the machine. It can be very slow because they establish a new SSH connection for every operation performed. Every. Single. One. 😭

In comparison, Net::OpenSSH is a pure perl module with no mandatory dependencies — obviously besides requiring OpenSSH binaries, let's be reasonable 🌸

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's also very fast. The overhead introduced by launching a new ssh process for every operation is not appreciable (at least on the author's Linux box). The bottleneck is the latency intrinsic to the protocol, so Net::OpenSSH is probably as fast as an SSH client can be. Slay 🚀

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

On the other hand — and I need you to hear this — Net::OpenSSH does not work on Windows, not even under Cygwin. 💀 Sorry bestie.

Net::OpenSSH specifically requires the OpenSSH SSH client (AFAIK, the multiplexing feature is not available from any other SSH client). However — important nuance — 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).

Also, quick note: Net::OpenSSH and Net::SSH2 do not support version 1 of the SSH protocol. Version 1 who? Never heard of her 🙈

💅 API 💅

⭐ Optional arguments ⭐

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

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

Same energy, different spelling 🎀

💜 Error handling 💜

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

The error method can always be used to explicitly check for errors, and honestly you should be checking, bestie. 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 — main character energy, every one of them:

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 — which is lowkey unhinged but okay — so 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. It's there for you, bestie 🫶

Accepted options:

user => $user_name — Login name 💖
port => $port — TCP port number where the server is running
password => $password — User given password for authentication.

Note that using password authentication in automated scripts is a very bad idea. When possible, you should use public key authentication instead. Seriously. I'm not being cute about this one 💀

passphrase => $passphrase — Uses the given passphrase to open the private key.
key_path => $private_key_path — Uses the key stored on the given file path for authentication 🔑
gateway => $gateway — If the given argument is a gateway object as returned by "find_gateway" in Net::OpenSSH::Gateway method, use it to connect to the remote host.

If it is a hash reference, call the "find_gateway" method first.

For instance, the following code fragments are equivalent:

  my $gateway = Net::OpenSSH::Gateway->find_gateway(
          proxy => 'http://proxy.corporate.com');
  $ssh = Net::OpenSSH->new($host, gateway => $gateway);

and

  $ssh = Net::OpenSSH->new($host,
          gateway => { proxy => 'http://proxy.corporate.com'});

proxy_command => $proxy_command — Use the given command to establish the connection to the remote host (see "ProxyCommand" on ssh_config(5)) 🌸
batch_mode => 1 — Disables querying the user for password and passphrases. No prompts, no waiting, no vibes.
ctl_dir => $path — Directory where the SSH master control socket will be created.

This directory and its parents must be writable only by the current effective user or root — otherwise the connection will be aborted to avoid insecure operation. Yes, it will just straight up refuse you 🚫

By default ~/.libnet-openssh-perl is used.

ctl_path => $path — Path to the SSH master control socket.

Usually this option should be avoided, as the module is able to pick an unused socket path by itself. An exception to that rule is when the "external_master" feature is enabled.

Note that the length of the path is usually limited to between 92 and 108 bytes, depending of the underlying operating system. That's it, that's the whole budget 📏

ssh_cmd => $cmd — Name or full path to the OpenSSH ssh binary. For instance:

  my $ssh = Net::OpenSSH->new($host, ssh_cmd => '/opt/OpenSSH/bin/ssh');

scp_cmd => $cmd — Name or full path to the OpenSSH scp binary.

By default it is inferred from the ssh one.

rsync_cmd => $cmd — Name or full path to rsync binary. Defaults to rsync.
remote_shell => $name — Name of the remote shell. Used to select the argument quoter backend 🐚
timeout => $timeout — Maximum acceptable time that can elapse without network traffic or any other event happening on methods that are not immediate (for instance, when establishing the master SSH connection or inside methods capture, system, scp_get, etc.).

`$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 returned log. 🎀

`$ssh->get_user`

`$ssh->get_host`

`$ssh->get_port`

Each one returns the corresponding SSH login parameter. 🌸

`$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:

stdin_pipe => 1 — Creates a new pipe and connects the reading side to the stdin stream of the remote process. The writing side is returned as the first value ($in).
stdin_pty => 1 — Similar to stdin_pipe, but instead of a regular pipe it uses a pseudo-tty (pty). Note that on some operating systems (e.g. HP-UX, AIX), ttys are not reliable. They can overflow when large chunks are written or when data is written faster than it is read. 😬
stdin_fh => $fh — Duplicates $fh and uses it as the stdin stream of the remote process.
stdin_file => $filename, stdin_file => \@open_args — Opens the file of the given name for reading and uses it as the remote process stdin stream. If an array reference is passed its contents are used as the arguments for the underlying open call. For instance:

                 $ssh->system({stdin_file => ['-|', 'gzip -c -d file.gz']}, $rcmd);

stdin_discard => 1 — Uses /dev/null as the remote process stdin stream.
stdout_pipe => 1 — Creates a new pipe and connects the writing side to the stdout stream of the remote process. The reading side is returned as the second value ($out).
stdout_pty => 1 — Connects the stdout stream of the remote process to the pseudo-pty. This option requires stdin_pty to be also set.
stdout_fh => $fh — Duplicates $fh and uses it as the stdout stream of the remote process.
stdout_file => $filename, stdout_file => \@open_args — Opens the file of the given filename and redirect stdout there.
stdout_discard => 1 — Uses /dev/null as the remote process stdout stream.
stdinout_socket => 1 — Creates a new socketpair, attaches the stdin an stdout streams of the slave SSH process to one end and returns the other as the first value ($in) and undef for the second ($out). Example:

                 my ($socket, undef, undef, $pid) = $ssh->open_ex({stdinout_socket => 1},
                                                                  '/bin/netcat $dest');

🌸 `setpgrp => 1` 🌸

Calls setpgrp after forking the child process 🙌 which means it won't 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, because the signal will be delivered to the master process and all the remote commands aborted 😬 this feature is experimental, so like, be aware.

🌈 `$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 (that code is available from $?, see "$?" in perlvar).

Example:

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

Just like the system builtin, the 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 — so don't do that 🙈

Accepted options, bestie:

stdin_data => $input
stdin_data => \@input — sends the given data through the stdin stream to the remote process 📨 for example, this code creates a file on the remote side:

$ssh->system({stdin_data => \@data}, "cat >/tmp/foo")
  or die "unable to write file: " . $ssh->error;

timeout => $timeout — the operation gets aborted once $timeout seconds have elapsed with no network activity ⏱️ see also "Timeouts".
async => 1 — does not wait for the child process to exit, and returns the PID of the new process instead 🏃‍♀️ note that when this option is combined with stdin_data, the given data will be transferred to the remote side before control returns to the caller. See also the spawn method documentation below.
stdin_fh => $fh
stdin_discard => $bool
stdout_fh => $fh
stdout_discard => $bool
stderr_fh => $fh
stderr_discard => $bool
stderr_to_stdout => $bool
stdinout_dpipe => $cmd
tty => $bool — see the open_ex method documentation for an explanation of these options 👀
stdin_keep_open => $bool — when stdin_data is given, the module closes the stdin stream once all the data has been sent. Unfortunately 😭 some SSH buggy servers fail to handle this event correctly and close the channel prematurely. As a workaround, when this flag is set the stdin is left open until the remote process terminates 🫶

💖 `$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.

Important: the error status is not set to OSSH_SLAVE_CMD_FAILED when the remote command exits with a non-zero code, okay?

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 supports the same set of options as system, except async and tunnel ✌️

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

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

Conceptually this one is equivalent to the perl backquote operator (e.g. `ls`): it runs the command on the remote machine and captures its output 📸

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

The exit status of the remote command comes back 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:

stdin_data => $input
stdin_data => \@input
stdin_keep_open => $bool — see the system method documentation for an explanation of these options.
timeout => $timeout — see "Timeouts".
stdin_fh => $fh
stdin_discard => $bool
stderr_fh => $fh
stderr_discard => $bool
stderr_to_stdout => $bool
tty => $bool — see the open_ex method documentation for an explanation of these 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, same as above.

The accepted options are:

stdin_data => $input
stdin_data => \@input
stdin_keep_open => $bool — see the system method documentation for an explanation of these options.
timeout => $timeout — see "Timeouts".
stdin_fh => $fh
stdin_discard => $bool
tty => $bool — see the open_ex method documentation for an explanation of these options 💫

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

This method is similar to the following Perl open call:

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

…except it runs @cmd on the remote machine 🛰️ (see "open" in perlfunc).

No options are currently accepted.

There's no need to perform a waitpid on the returned PID, because 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 the previous method, it's equivalent to:

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

…running @cmd on the remote machine 🔄

No options are currently accepted.

💅 Shortcut city 💅

($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 the open_ex method, periodt ✨

👑 `$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, okay? Don't ghost it 🙈

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;

Okay quick vibe check though 💅 — do not use spawn to kick off detached remote processes, the kind that are supposed to outlive your local program. That's just not what it's for, bestie. (The FAQ has the whole tea on running remote processes detached, go peek 🫖.)

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

Basically open2socket's sibling, but instead of running a command it pops open a TCP tunnel to whatever address you hand it. Also see the "Tunnels" section 🚇.

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

Same energy as capture, except it opens a TCP tunnel instead of running a command. Obsessed tbh.

Example, because yes:

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

🌸 `$ssh->scp_get(\%opts, $remote1, $remote2,..., $local_dir_or_file)` and `$ssh->scp_put(\%opts, $local, $local2,..., $remote_dir_or_file)`

These two are lil wrappers around the scp command, so you can move files to/from the remote host using the SSH master connection you already have — recycling, iconic, mother earth is proud 🌈.

When you're transferring several files, the target argument has to point to an existing directory. If it's just one file, the target can be a directory, a file name, or you can straight up omit it. Like:

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

Both scp_get and scp_put return a true value when everything transferred correctly, otherwise you get undef 😭.

Options they accept:

quiet => 0 — by default scp gets called with the quiet flag -q on, to shut up the progress info. This option lets you turn the progress bar back on. It's giving "I want to watch it go" 💖
verbose => 1 — calls scp with the -v flag.
recursive => 1 — copies files and directories recursively, all the way down 🌀
glob => 1 — turns on shell metacharacter expansion in the sources list so you can use wildcards to pick files.
glob_flags => $flags — the second argument passed to the File::Glob::bsd_glob function. Heads up: only available for the scp_put method ⚠️
copy_attrs => 1 — copies modification times, access times and modes from the original files. preserving the metadata, we love to see it 🎀
bwlimit => $Kbits — limits the bandwidth used, in Kbit/s.
timeout => $secs — the transfer gets aborted if the connection doesn't finish before the given timeout elapses. See also "Timeouts" ⏰
async => 1 — doesn't wait for the scp command to finish. When you use this, the method returns the PID of the child scp process.

So yes, you can transfer files to several hosts in parallel, like this:

use Errno;
my (%pid, %ssh);
for my $host (@hosts) {
  $ssh{$host} = Net::OpenSSH->new($host, async => 1);
}
for my $host (@hosts) {
  $pid{$host} = $ssh{$host}->scp_put({async => 1}, $local_fn, $remote_fn)
    or warn "scp_put to $host failed: " . $ssh{$host}->error . "\n";
}
for my $host (@hosts) {
  if (my $pid = $pid{$host}) {
    if (waitpid($pid, 0) > 0) {
      my $exit = ($? >> 8);
      $exit and warn "transfer of file to $host failed ($exit)\n";
    }
    else {
      redo if ($! == EINTR);
      warn "waitpid($pid) failed: $!\n";
    }
  }
}

stdout_fh => $fh, stderr_fh => $fh, stderr_to_stdout => 1 — these get passed straight through, unchanged, to the open_ex method, so you can capture the output of the scp program. ✨

Fair warning: scp will not generate progress reports unless its stdout stream is attached to a tty. Just so you're not sitting there like 👁️👄👁️ waiting.

ssh_opts => \@opts — a list of extra options for the ssh command.

Use this one with care: the module does not check the options you give it in any way, and they could mess with it. You've been warned 💀

🦋 `$ssh->rsync_get(\%opts, $remote1, $remote2,..., $local_dir_or_file)` and `$ssh->rsync_put(\%opts, $local1, $local2,..., $remote_dir_or_file)`

These use rsync over SSH to move files from/to the remote machine — the fancy one, the upgraded one, main character energy 👑

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

Any option they don't recognize gets passed as an argument to the rsync command (go read rsync(1) bestie). And plot twist: you can use underscores 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)`

Makes you a brand new Net::SFTP::Foreign object for SFTP things, and it runs through the ssh master connection you already have. no extra setup, no drama 🎀

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

This one hands you back the arguments you need to run a command on the remote machine via SSH. Handy af:

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

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

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

Options it takes:

tty => $bool — enables/disables allocating a tty on the remote side.
forward_agent => $bool — enables/disables forwarding of the authentication agent.

Heads up: this option can only be used when agent forwarding was already requested on the constructor. no retroactive vibes 🙈

tunnel => 1 — returns a command that creates a connection to some TCP server reachable from the remote host. In that case the arguments are the destination address and port. Like:

$cmd = $ssh->make_remote_command({tunnel => 1}, $host, $port);

subsystem => 1 — returns a command for invoking an SSH subsystem (think SFTP or netconf). In that case the only argument is the subsystem name 🛰️

💜 `$ssh->wait_for_master($async)`

When the connection was established by calling the constructor with the async option, this call lets you advance the process. move it along, keep it going.

If $async is true, it'll do any work that can be done immediately without waiting — entering the password, checking whether the multiplexing socket exists, that kind of thing — and then it returns. If you give it a false value, it finalizes the whole connection process and waits until the multiplexing socket is actually available ⏳

It returns a true value once the connection has been successfully established. False comes back if the connection process fails, or if it hasn't completed yet — and then you can use the error method to tell those two cases apart 👀

From version 0.64 upwards: undef is returned when the master is still in an unstable state (login, killing, etc.) and 0 when it's in a stable state (running, stopped or gone). Numbers, bestie, they mean things 🔢

💜 `$ssh->check_master`

Runs a whole bunch of checks to make sure the master connection is still alive. like a wellness check but for processes 🫶

💜 `$ssh->shell_quote(@args)`

Returns the list of arguments, quoted so they'll come back to their original form when the remote shell parses them. nothing gets mangled, nothing gets eaten by the shell 🐚

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

Usually the module does this task automatically for you — 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)`

Like the previous shell_quote, but it leaves wildcard characters unquoted so they can actually do their wildcard thing ✨

It can be used as a class method too.

💜 `$ssh->set_expand_vars($bool)`

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

💜 `$ssh->get_expand_vars`

Returns the current state of the variable expansion feature. is it on or is it off, the people want to know 💅

💜 `$ssh->set_var($name, $value)` and `$ssh->get_var($name, $value)`

These two let you change and retrieve the value of the given name. 🎀

💜 `$ssh->get_master_pid`

Returns the PID of the master SSH process. the actual number, the whole identity 👑

💜 `$ssh->master_exited`

This method lets you tell the module that the master process has exited, for when you grab its PID from some external wait or waitpid call. Like so:

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;
  }
}

Genuinely important: if your program reaps the master process and this method doesn't get called, the OS could reassign that PID to some new unrelated process — and then the module would try to kill that at object destruction time. not the vibe. not the vibe at all 💀

💜 `$ssh->disconnect($async)`

Shuts the SSH connection down. bye bestie 👋

Usually you don't need to call this explicitly — just let the Net::OpenSSH object go out of scope and it handles itself.

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: closes any open connection and creates a new one. Any open channel also gets killed. fresh start, clean slate, rebrand 🌸

Note: calling this method may request the password or passphrase from the user again. so like, be ready 🔑

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)

Okay bestie, these two use sshfs(1) to import or export a file system through the SSH connection. File-system slay via SSH ✨

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). iykyk 💅

The options accepted are as follows:

ssh_opts => \@ssh_opts — options passed to the slave "ssh" process.
sshfs_opts => \@sshfs_opts — options passed to the "sshfs" command. For instance, to mount the file system in read-only mode:

my $pid = $ssh->sshfs_export({sshfs_opts => [-o => 'ro']},
                             "/", "/mnt/foo");

Note that this command requires a recent version of "sshfs" to work (at the time of writing, it requires the yet unreleased version available from the FUSE git repository!). not me warning you about unreleased software 😭

See also the sshfs(1) man page and the "sshfs" and FUSE web sites at https://github.com/libfuse/sshfs and https://github.com/libfuse/libfuse respectively. web links, but make it manual-page chic 🦋

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

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

Example:

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

🐚 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. shell? not today, bestie 💅

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. spaces in paths: handled, periodt ✨

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). glob girl summer 🌸

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. aliases said “no” and the full path said “bet” 💀

⏳ 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. SIGPIPE said “surprise” 😭

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. orphan process behavior: not iconic 🙈

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

🔮 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"). order matters, bestie 💜

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. variable expansion ate that path up ✨

🌈 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. tunnel vision, but make it network 🦋

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;

 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);

or, y'know, capturing the output of several requests in parallel — that's the one above, bestie, look at it, it's serving 💅

So like, under the hood, to create a tunnel, a brand new ssh process gets spawned with the option -W${address}:${port} (available from OpenSSH 5.4 and upwards), and it redirects its stdio streams to the remote given address. And here's the iconic part: unlike when ssh -L options are used to create tunnels, no TCP port is opened on the local machine at any time, so this is a perfectly secure operation. No cap. Actually secure. 🔥

The PID of the new process is what the named methods hand back to you. You must reap it once the pipe or socket handlers for the local side of the tunnel have been closed. That's not optional, that's your homework. ✨

⚠️ 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). So if it's not working, it might just be the vibes of your server admin, not you. 🫶

🦋 Tunnels targeting UNIX sockets

When you're connecting to hosts running a recent version of OpenSSH sshd, you can also open connections targeting Unix sockets. Slay.

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 lives at patches/openssh-fwd-stdio-to-streamlocal-1.patch. Yes, you have to patch. I know. 😭

🧚 Port forwarding

Real talk: Net::OpenSSH does not offer direct support for handling port forwardings between server and client. But bestie, it's literally fine, you can do it easily anyway by 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']});

Setup, cancel, setup, cancel. Main character behaviour honestly. 💅

🎀 Data encoding

Okay so Net::OpenSSH has some support for transparently converting the data sent or received from the remote server into Perl's internal unicode representation. Cute, right? ✨

The methods that support this feature are the ones 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. So don't come for me if your pipe data is still raw. 🙈

It's 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. Default vibes: latin1. Periodt.

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 sent 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. Two for one, iconic. 👑

The constructor also accepts default_encoding, default_stream_encoding and default_argument_encoding that set the defaults. Yes, you can set your defaults and never think about it again. 🌸

🌈 Diverting `new`

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

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! 😭 Not me saying that. Well. Lowkey saying that.

💜 3rd PARTY MODULE INTEGRATION

🍓 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. That's it. That's the whole thing. ✨

🦋 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);

Look at that. waitpid($pid, 0) at the end like a responsible queen. 🎀

💀 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. It's giving incompatible. 😭

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. 🚨 Like, that's the whole kingdom. Gone.

💅 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!

Please. For me. Protect the .ssh directory. 🙏

🧚 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 frameworks such as AnyEvent or IO::Async in the following way. Buckle up bestie, it's a four-step routine. 🌈

Create a disconnected Net::OpenSSH object:

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

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(...);
   }
 }

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's 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. Options on options, we love to see it. 💅

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. Nobody wants that. Not you, not your event loop, not anybody. 😭

🎀 Other modules

CPAN contains several modules that rely on SSH to perform their duties — as for example IPC::PerlSSH or GRID::Machine. The catalogue is real. 🛍️

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. Pipes. For transport. We stan a flexible plugin system. 🫶✨

🔧✨ TROUBLESHOOTING ✨🔧

Okay bestie, so usually Net::OpenSSH just works right out of the box 💖, but when it doesn't, some people have a genuinely hard time figuring out why. This lil mini troubleshooting guide is here to help you find the problem and solve it. No cap.

1 - check the error message 💅

First thing: right after your Net::OpenSSH constructor call, add an error check, okay?

$ssh = Net::OpenSSH->new(...);
$ssh->error and die "SSH connection failed: " . $ssh->error;

That error message will literally tell you what went wrong. Read it first, bestie. 😭

2 - Check the connection parameters 🫶

Believe it or not, passing bad parameters to Net::OpenSSH is one of the top causes of failures — so check that you're using the right ones, fr fr.

Specifically, if you're getting them from the outside, make sure they don't have extra spaces or newlines stuck to them. Do you need to chomp? 👀

Passwords and URIs may contain $ or @ characters. If you've hardcoded those in your script, check that they're quoted properly — and BTW, use strict. Periodt.

3 - OpenSSH version 🦋

Make sure you have a version of ssh that's recent enough:

$ ssh -V
OpenSSH_5.1p1 Debian-5, OpenSSL 0.9.8g 19 Oct 2007

OpenSSH version 4.1 was the first to support the multiplexing feature, and it's the minimal version the module needs to work. Honestly, I advise you to use the latest OpenSSH (currently 7.5). 💚

The ssh_cmd constructor option lets you pick which ssh binary to use. For example:

$ssh = Net::OpenSSH->new($host,
                         ssh_cmd => "/opt/OpenSSH/5.8/bin/ssh")

Some hardware vendors (e.g. Sun — err… Oracle 🙈) include custom versions of OpenSSH bundled with the operating system. In principle, Net::OpenSSH should work with these SSH clients as long as they're derived from some version of OpenSSH that's recent enough. Anyway, my advice is: use the real OpenSSH software if you can! 💯

4 - run ssh from the command line 🎀

Check that you can connect to the remote host using the same parameters you're passing to Net::OpenSSH. In particular, make sure you're running ssh as the same local user.

If you're running your script from a web server, that user is probably www, apache, or something like that.

Common problems are:

Remote host public key not present in known_hosts file.

The SSH protocol uses public keys to identify remote hosts, so they can't be supplanted by some malicious third parties.

For OpenSSH, usually the server public key is stored in /etc/ssh/ssh_host_dsa_key.pub or in /etc/ssh/ssh_host_rsa_key.pub, and that key should be copied into the ~/.ssh/known_hosts file on the local machine (other SSH implementations may use other file locations).

Maintaining server keys when several hosts and clients are involved can be somewhat inconvenient, so most SSH clients, by default, when a new connection is made to a host whose key is not in the known_hosts file, show the key and ask the user if they want the key copied there.

Wrong remote host public key in known_hosts file.

This is another common problem. It happens when a server is replaced or reinstalled from scratch and its public key changes, so it becomes different from the one installed in the known_hosts file.

The easiest way to solve it is to remove the old key from the known_hosts file by hand using any editor, then connect to the server replying yes when asked to save the new key.

Wrong permissions for the ~/.ssh directory or its contents.

The OpenSSH client performs several checks on the access permissions of the ~/.ssh directory and its contents, and refuses to use them when they're misconfigured. See the FILES section from the ssh(1) man page.

Incorrect settings for password or public key authentication.

Check that you're using the right password, or that the user public key is correctly installed on the server.

5 - security checks on the multiplexing socket 🔐

Net::OpenSSH performs some security checks on the directory where the multiplexing socket is going to be placed, to make sure other users can't access it.

The default location for the multiplexing socket is under ~/.libnet-openssh-perl. You can change it using the ctl_dir and ctl_path constructor arguments.

The requirements for that directory and all its parents are:

They have to be owned by the user executing the script or by root.
Their permission masks must be 0755 or more restrictive, so nobody else has permissions to perform write operations on them.

The constructor option strict_mode disables these security checks — but you should not use it unless you understand its implications, bestie. 🚨

6 - file system must support sockets 💀

Some file systems (like FAT or AFS) do not support placing sockets inside them.

Make sure the ctl_dir path does not lay into one of those file systems. Vibe check your filesystem, okay? ✨

🐛✨ DEBUGGING ✨🐛

Debugging of Net::OpenSSH internals is controlled through the variable $Net::OpenSSH::debug. Every bit of this variable activates debugging of some subsystem, like this:

bit 1 - errors — Dumps changes on the internal object attribute where errors are stored.
bit 2 - ctl_path — Dumps information about ctl_path calculation and the tests performed on that directory in order to decide if it's secure to place the multiplexing socket inside.
bit 4 - connecting — Dumps information about the establishment of new master connections.
bit 8 - commands and arguments — Dumps the command and arguments for every system/exec call.
bit 16 - command execution — Dumps information about the progress of command execution.
bit 32 - destruction — Dumps information about the destruction of Net::OpenSSH objects and the termination of the SSH master processes.
bit 64 - IO loop — Dumps information about the progress of the IO loop on capture operations.
bit 128 - IO hexdumps — Generates hexdumps of the information that travels through the SSH streams inside capture operations.
bit 512 - OS tracing of the master process — Use the module Net::OpenSSH::OSTracer to trace the SSH master process at the OS level.

For instance, in order to activate all the debugging flags, you can use:

$Net::OpenSSH::debug = ~0;

Note that the meaning of the flags and the information generated is only intended for debugging of the module, and may change without notice between releases. 👑 No promises, iykyk.

If you're using password authentication, enabling debugging for IO::Tty may also show interesting information:

$IO::Tty::DEBUG = 1;

Finally, by default debugging output is sent to STDERR. You can override it by pointing $Net::OpenSSH::debug_fh to a different file handle. For instance:

BEGIN {
  open my $out, '>', '/tmp/debug.txt' or warn $!;
  $Net::OpenSSH::debug_fh = $out;
  $Net::OpenSSH::debug = -1;
}

🔐 SECURITY 🔐

Q: Is this module secure? A: Well, it tries to be! 💖

Okay so from a security standpoint, the whole goal of this module is to be as secure as OpenSSH, your operating system, your shell and in general your environment allow it to be. No cap — it is not out here taking shortcuts just to make your life easier if that shortcut means lowering the security level (for instance, disabling StrictHostKeyChecking by default). That is not the vibe. 🙅‍♀️

In code supporting features that are not just proxied to OpenSSH, the module tries to keep the same standards of security as OpenSSH — for instance, checking directory and file permissions when placing the multiplexing socket. It is giving careful, responsible, checks-its-own-permissions energy. ✨

On the other hand, and keeping with OpenSSH philosophy, the module lets you disable most (all?) of those security measures. But just because it lets you do it does not mean it is a good idea to do so!!! Bestie, please. 😭💀

If you are a novice programmer or SSH user, and googling you have just found some flag that you don't understand but that seems to magically solve your connection problems... well, believe me, it is probably a bad idea to use it. Ask somebody who really knows first! 🙏

Just to make things clear: if your code contains any of the keywords from the (non-exclusive) list below and you don't know why, you are probably wrecking the security of the SSH protocol:

strict_mode
StrictHostKeyChecking
UserKnownHostsFile

That list is lowkey a warning label. Do not ignore it. 💅

Other considerations related to security you may like to know are as follows:

🧼 Taint mode 🧼

The module supports working in taint mode. Slay. ✨

If you are in an exposed environment, you should probably enable it for your script in order to catch any unchecked command for being executed in the remote side. It is literally there to help you catch sketchy stuff before it becomes a whole group-chat meltdown. 🫶

🌐 Web environments 🌐

It is a bad idea to establish SSH connections from your webserver because if it becomes compromised in any way, the attacker would be able to use the credentials from your script to connect to the remote host and do anything he wishes there. Highkey do not do this. 🚩😭

Webserver + SSH credentials = not the cute little combo you think it is. If that webserver gets compromised, your script's credentials are basically handing over the remote host. 💀

🧚 Command quoting 🧚

The module can quote commands and arguments for you in a flexible and powerful way. Obsessed. 💖

This is a feature you should use as it reduces the possibility of some attacker being able to inject and run arbitrary commands on the remote machine (and even for scripts that are not exposed it is always advisable to enable argument quoting). It is giving responsible, cautious, main-character security energy. 👑

Having said that, take into consideration that argument-quoting is just a hack to emulate the invoke-without-a-shell feature of Perl builtins such as system and alike. There may be bugs(*) on the quoting code, your particular shell may have different quoting rules with unhandled corner cases or whatever. So like… it is very good, but it is not a magic force field. ✨

If your script is exposed to the outside, you should check your inputs and restrict what you accept as valid. Validate your inputs, bestie. Fr fr. 🫶

[* even if this is one of the parts of the module more intensively tested!]

Yes, it is intensively tested. Yes, you still validate your inputs. Both things can be true. 💅

💀 Shellshock 💀

(see Shellshock at http://en.wikipedia.org/wiki/Shellshock_%28software_bug%29)

When executing local commands, the module always avoids calling the shell so in this way it is not affected by Shellshock. Good news, honestly. ✨

Unfortunately, some commands (scp, rsync and ssh when the ProxyCommand option is used) invoke other commands under the hood using the user shell. That opens the door to local Shellshock exploitation. Not iconic. Not slay. Very much a security red flag. 🚩😭

On the remote side invocation of the shell is unavoidable due to the protocol design. That is just how the protocol works, no cap.

By default, SSH does not forward environment variables, but some Linux distributions explicitly change the default OpenSSH configuration to enable forwarding and acceptance of some specific ones (for instance LANG and LC_* on Debian and derivatives, Fedora does alike) and this also opens the door to Shellshock exploitation. So yeah, distro defaults can absolutely matter here. 👀

Note that the shell used to invoke commands is not /bin/sh but the user shell as configured in /etc/passwd, PAM or whatever authentication subsystem is used by the local or remote operating system. Debian users, don't think you are not affected because your /bin/sh points to dash! That plot twist is not the flex you think it is. 💀✨

🌈 FAQ 🌈

Frequent questions about the module:

💻 Connecting to switches, routers, etc.

Q: I can not get the method system, capture, etc., to work when connecting to some router, switch, etc. What I am doing wrong?

A: Okay so bestie, roughly the SSH protocol has two modes of operation: command mode and interactive mode.

Command mode is literally for running single commands on the remote host. It opens a SSH channel between both hosts, asks the remote computer to run some given command and when it finishes, the channel is closed. It’s what you get, for instance, when you run something as…

$ ssh my.unix.box cat foo.txt

… and it is also the way Net::OpenSSH runs commands on the remote host. Slay.

Interactive mode launches a shell on the remote hosts with its stdio streams redirected to the local ones so that the user can transparently interact with it.

Some devices (as probably the one you are using) do not run an standard, general purpose shell (e.g. bash, csh or ksh) but some custom program specially targeted and limited to the task of configuring the device.

Usually, the SSH server running on these devices does not support command mode. It unconditionally attaches the restricted shell to any incoming SSH connection and waits for the user to enter commands through the redirected stdin stream.

The only way to work-around this limitation is to make your script talk to the restricted shell (1-open a new SSH session, 2-wait for the shell prompt, 3-send a command, 4-read the output until you get to the shell prompt again, repeat from 3). The best tool for this task is probably Expect, used alone or combined with Net::OpenSSH (see "Expect").

There are some devices that support command mode but that only accept one command per connection. In that cases, using Expect is also probably the best option.

Nowadays, there is a new player, Net::CLI::Interact that may be more suitable than Expect, and Net::Appliance::Session for working specifically with network devices.

🌐 Connection fails

Q: I am unable to make the module connect to the remote host…

A: Have you read the troubleshooting section? (see "TROUBLESHOOTING").

🔐 Disable StrictHostKeyChecking

Q: Why is ssh not run with StrictHostKeyChecking=no?

A: Using StrictHostKeyChecking=no relaxes the default security level of SSH and it will be relatively easy to end with a misconfigured SSH (for instance, when known_hosts is unwritable) that could be forged to connect to a bad host in order to perform man-in-the-middle attacks, etc.

I advice you to do not use that option unless you fully understand its implications from a security point of view.

If you want to use it anyway, past it to the constructor:

$ssh = Net::OpenSSH->new($host,
         master_opts => [-o => "StrictHostKeyChecking=no"],
         ...);

😭 child process STDIN/STDOUT/STDERR is not a real system file handle

Q: Calls to system, capture, etc. fail with the previous error, what’s happening?

A: The reported stdio stream is closed or is not attached to a real file handle (e.g. it is a tied handle). Redirect it to /dev/null or to a real file:

my $out = $ssh->capture({stdin_discard => 1, stderr_to_stdout => 1},
                        $cmd);

☀️ Solaris (and AIX and probably others)

Q: I was trying Net::OpenSSH on Solaris and seem to be running into an issue…

A: The SSH client bundled with Solaris is an early fork of OpenSSH that does not provide the multiplexing functionality required by Net::OpenSSH. You will have to install the OpenSSH client.

Precompiled packages are available from Sun Freeware (http://www.sunfreeware.com). There, select your OS version an CPU architecture, download the OpenSSH package and its dependencies and install them. Note that you do not need to configure Solaris to use the OpenSSH server sshd.

Ensure that OpenSSH client is in your path before the system ssh or alternatively, you can hardcode the full path into your scripts as follows:

$ssh = Net::OpenSSH->new($host,
                         ssh_cmd => '/usr/local/bin/ssh');

AIX and probably some other unixen, also bundle SSH clients lacking the multiplexing functionality and require installation of the real OpenSSH.

📂 Can not change working directory

Q: I want to run some command inside a given remote directory but I am unable to change the working directory. For instance:

$ssh->system('cd /home/foo/bin');
$ssh->systen('ls');

does not list the contents of /home/foo/bin.

What am I doing wrong?

A: Net::OpenSSH (and, for that matter, all the SSH modules available from CPAN but Net::SSH::Expect) run every command in a new session so most shell builtins that are run for its side effects become useless (e.g. cd, export, ulimit, umask, etc., usually, you can list them running help from the shell).

A work around is to combine several commands in one, for instance:

$ssh->system('cd /home/foo/bin && ls');

Note the use of the shell && operator instead of ; in order to abort the command as soon as any of the subcommands fail.

Also, several commands can be combined into one while still using the multi-argument quoting feature as follows:

$ssh->system(@cmd1, \\'&&', @cmd2, \\'&&', @cmd3, ...);

🚀 Running detached remote processes

Q: I need to be able to ssh into several machines from my script, launch a process to run in the background there, and then return immediately while the remote programs keep running…

A: If the remote systems run some Unix/Linux variant, the right approach is to use nohup(1) that will disconnect the remote process from the stdio streams and to ask the shell to run the command on the background. For instance:

$ssh->system("nohup $long_running_command &");

Also, it may be possible to demonize the remote program. If it is written in Perl you can use App::Daemon for that (actually, there are several CPAN modules that provided that kind of functionality).

In any case, note that you should not use spawn for that.

💀 MaxSessions server limit reached

Q: I created an $ssh object and then fork a lot children processes which use this object. When the children number is bigger than MaxSessions as defined in sshd configuration (defaults to 10), trying to fork new remote commands will prompt the user for the password.

A: When the slave SSH client gets a response from the remote servers saying that the maximum number of sessions for the current connection has been reached, it fall backs to open a new direct connection without going through the multiplexing socket.

To stop that for happening, the following hack can be used:

$ssh = Net::OpenSSH->new(host,
    default_ssh_opts => ['-oConnectionAttempts=0'],
    ...);

👑 Running remote commands with sudo

Q: How can I run remote commands using sudo to become root first?

A: The simplest way is to tell sudo to read the password from stdin with the -S flag and to do not use cached credentials with the -k flag. You may also like to use the -p flag to tell sudo to print an empty prompt. For instance:

my @out = $ssh->capture({ stdin_data => "$sudo_passwd\n" },
                        'sudo', '-Sk',
                        '-p', '',
                        '--',
                        @cmd);

If the version of sudo installed on the remote host does not support the -S flag (it tells sudo to read the password from its STDIN stream), you can do it as follows:

my @out = $ssh->capture({ tty => 1,
                          stdin_data => "$sudo_passwd\n" },
                        'sudo', '-k',
                        '-p', '',
                        '--',
                        @cmd);

This may generate an spurious and harmless warning from the SSH master connection (because we are requesting allocation of a tty on the remote side and locally we are attaching it to a regular pair of pipes).

If for whatever reason the methods described above fail, you can always revert to using Expect to talk to the remote sudo. See the examples/expect.pl script from this module distribution.

🎀 Interactive sessions

Q: How can I start an interactive remote session?

A: Just call the system method with an empty argument list:

my $ssh = Net::OpenSSH->new(...);
$ssh->system;

Q: How about running an interactive sftp session?

A: Programs that use an underlying ssh connection usually provide some way (for instance, command line option -o) to pass additional options for the ssh command used to run that connection. We just need to use such mechanism to pass the path to the control socket.

For instance, for the particular case of sftp:

$cp = $ssh->get_ctl_path;
system "sftp", "-oControlPath=$cp", $host;

🌈 SEE ALSO 🌈

okay so bestie, when you’re done obsessing over the main character of this page, here’s the whole ✨ extended universe ✨:

OpenSSH client documentation ssh(1), ssh_config(5), the project web <http://www.openssh.org> and its FAQ <http://www.openbsd.org/openssh/faq.html>. scp(1) and rsync(1). The OpenSSH Wikibook <http://en.wikibooks.org/wiki/OpenSSH>.
Net::OpenSSH::Gateway — for detailed instruction about how to get this module to connect to hosts through proxies and other SSH gateway servers.
Core perl documentation perlipc, "open" in perlfunc, "waitpid" in perlfunc.
IO::Pty — so you know how to use the pseudo tty objects returned by several methods on this package.
Net::SFTP::Foreign — provides a compatible SFTP implementation.
Expect — can be used to interact with commands run through this module on the remote machine (see also the expect.pl and <autosudo.pl> scripts in the examples directory).
SSH::OpenSSH::Parallel — an advanced scheduler that allows one to run commands in remote hosts in parallel. It is obviously based on Net::OpenSSH.
SSH::Batch — allows one to run remote commands in parallel in a cluster. It is build on top on Net::OpenSSH also.
Other Perl SSH clients: Net::SSH::Perl, Net::SSH2, Net::SSH, Net::SSH::Expect, Net::SCP, Net::SSH::Mechanize.
Net::OpenSSH::Compat — a package offering a set of compatibility layers for other SSH modules on top of Net::OpenSSH.
IPC::PerlSSH, GRID::Machine — allow execution of Perl code in remote machines through SSH.
SSH::RPC — implements an RPC mechanism on top of SSH using Net::OpenSSH to handle the connections.
Net::CLI::Interact — allows one to interact with remote shells and other services. It is specially suited for interaction with network equipment. The phrasebook approach it uses is very clever. You may also like to check the other modules <https://metacpan.org/author/OLIVER> from its author, Oliver Gorwits.

🐛 BUGS AND SUPPORT 🐛

bestie, this is the fine print that’s still giving important ✨. read it before you come for the module, okay?

🧪 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>.

🎯 TODO 🎯

Tests for scp_*, rsync_* and sftp methods
Make pipe_in and pipe_out methods open_ex based
auto_discard_streams feature for mod_perl2 and similar environments
Refactor open_ex support for multiple commands, maybe just keeping tunnel, ssh and raw

Send your feature requests, ideas or any feedback, please!

🛠️ CONTRIBUTING CODE 🛠️

The source code of this module is hosted at GitHub: <http://github.com/salva/p5-Net-OpenSSH>.

Code contributions to the module are welcome but you should obey the following rules:

Only Perl 5.8.4 required — yes, that's pretty old, but Net::OpenSSH is intended to be also used by system administrators that sometimes have to struggle with old systems. The reason to pick 5.8.4 is that it has been the default perl on Solaris for a long time.
Avoid the "All the world's a Linux PC" syndrome — the module should work on any (barely) sane Unix or Linux operating system. Specially, it should not be assumed that the over-featured GNU utilities and toolchain are available.
Dependencies are optional — in order to make the module very easy to install, no mandatory dependencies on other CPAN modules are allowed. Optional modules, that are loaded only on demand, are acceptable when they are used for adding new functionality (as it is done, for instance, with IO::Pty). Glue code for integration with 3rd party modules is also allowed (as it is done with Expect). Usage of language extension modules and alike is not acceptable.
Tests should be lax — we don't want false negatives when testing. In case of doubt tests should succeed. Also, in case of tests invoking some external program, it should be checked that the external program is available and that it works as expected or otherwise skip those tests.
Backward compatibility — nowadays Net::OpenSSH is quite stable and there are lots of scripts out there using it that we don't want to break, so, keeping the API backward compatible is a top priority. Probably only security issues could now justify a backward incompatible change.
Follow my coding style — look at the rest of the code. I let Emacs do the formatting for me using cperl-mode PerlStyle.
Talk to me — before making a large change or implementing a new feature get in touch with me. I may have my own ideas about how things should be done. It is better if you know them before hand, otherwise, you risk getting your patch rejected.

Well, actually you should know that I am quite good at rejecting patches but it is not my fault!

Most of the patches I get are broken in some way: they don't follow the main module principles, sometimes the author didn't get the full picture and solved the issue in a short-sighted way, etc.

In any case, you should not be discouraged to contribute. Even if your patch is not applied directly, seeing how it solves your requirements or, in the case of bugs, the underlying problem analysis may be very useful and help me to do it... my way.

I always welcome documentation corrections and improvements.

📜 COPYRIGHT AND LICENSE 📜

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.10.0 or, at your option, any later version of Perl 5 you may have available.

💖 and that’s the whole page, bestie! source/version is perl v5.40.2, dated 2025-01-03, and it’s Net::OpenSSH(3) — iconic, no cap 👑✨

📦 where this page comes from

alpine 3.22: perl-net-openssh-doc 0.84-r1 · GPL-1.0-or-later OR Artistic-1.0-Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-06: a language model's rewrite of the original, under its terms

Net::OpenSSH(3)

🐚 Net::OpenSSH(3) 🐚

✨ NAME ✨

🌸 SYNOPSIS 🌸

🦋 DESCRIPTION 🦋

🎀 Under the hood 🎀

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

💅 API 💅

⭐ Optional arguments ⭐

💜 Error handling 💜

👑 Net::OpenSSH methods 👑

$ssh->error

$ssh->get_master_pty_log

$ssh->get_user

$ssh->get_host

$ssh->get_port

$ssh->get_ctl_path

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

🌸 setpgrp => 1 🌸

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

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

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

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

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

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

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

💅 Shortcut city 💅

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

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

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

🌸 $ssh->scp_get(\%opts, $remote1, $remote2,..., $local_dir_or_file) and $ssh->scp_put(\%opts, $local, $local2,..., $remote_dir_or_file)

🦋 $ssh->rsync_get(\%opts, $remote1, $remote2,..., $local_dir_or_file) and $ssh->rsync_put(\%opts, $local1, $local2,..., $remote_dir_or_file)

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

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

💜 $ssh->wait_for_master($async)

💜 $ssh->check_master

💜 $ssh->shell_quote(@args)

💜 $ssh->shell_quote_glob(@args)

💜 $ssh->set_expand_vars($bool)

💜 $ssh->get_expand_vars

💜 $ssh->set_var($name, $value) and $ssh->get_var($name, $value)

💜 $ssh->get_master_pid

💜 $ssh->master_exited

💜 $ssh->disconnect($async)

💜 $ssh->restart($async)

🐚 Shell quoting

⏳ Timeouts

🔮 Variable expansion

🌈 Tunnels

🦋 Tunnels targeting UNIX sockets

🧚 Port forwarding

🎀 Data encoding

🌈 Diverting new

💜 3rd PARTY MODULE INTEGRATION

🍓 Expect

🦋 Net::Telnet

💀 mod_perl and mod_perl2

🧚 Net::SFTP::Foreign

🌸 Net::SSH::Any

⭐ Object::Remote

👑 AnyEvent (and similar frameworks)

🎀 Other modules

🔧✨ TROUBLESHOOTING ✨🔧

1 - check the error message 💅

2 - Check the connection parameters 🫶

3 - OpenSSH version 🦋

4 - run ssh from the command line 🎀

5 - security checks on the multiplexing socket 🔐

6 - file system must support sockets 💀

🐛✨ DEBUGGING ✨🐛

🔐 SECURITY 🔐

🧼 Taint mode 🧼

🌐 Web environments 🌐

🧚 Command quoting 🧚

💀 Shellshock 💀

🌈 FAQ 🌈

💻 Connecting to switches, routers, etc.

🌐 Connection fails

🔐 Disable StrictHostKeyChecking

😭 child process STDIN/STDOUT/STDERR is not a real system file handle

`$ssh->error`

`$ssh->get_master_pty_log`

`$ssh->get_user`

`$ssh->get_host`

`$ssh->get_port`

`$ssh->get_ctl_path`

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

🌸 `setpgrp => 1` 🌸

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

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

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

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

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

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

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

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

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

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

🌸 `$ssh->scp_get(\%opts, $remote1, $remote2,..., $local_dir_or_file)` and `$ssh->scp_put(\%opts, $local, $local2,..., $remote_dir_or_file)`

🦋 `$ssh->rsync_get(\%opts, $remote1, $remote2,..., $local_dir_or_file)` and `$ssh->rsync_put(\%opts, $local1, $local2,..., $remote_dir_or_file)`

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

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

💜 `$ssh->wait_for_master($async)`

💜 `$ssh->check_master`

💜 `$ssh->shell_quote(@args)`

💜 `$ssh->shell_quote_glob(@args)`

💜 `$ssh->set_expand_vars($bool)`

💜 `$ssh->get_expand_vars`

💜 `$ssh->set_var($name, $value)` and `$ssh->get_var($name, $value)`

💜 `$ssh->get_master_pid`

💜 `$ssh->master_exited`

💜 `$ssh->disconnect($async)`

💜 `$ssh->restart($async)`

🌈 Diverting `new`