NAME

Net::SSH::Any - Use any SSH module

SYNOPSIS

  use Net::SSH::Any;

  my $ssh = Net::SSH::Any->new($host, user => $user, password => $passwd);

  my @out = $ssh->capture(cat => "/etc/passwd");
  my ($out, $err) = $ssh->capture2("ls -l /");
  $ssh->system("foo");

  my $sftp = $ssh->sftp; # returns Net::SFTP::Foreign object
  $sftp->put($local_path, $remote_path);

DESCRIPTION

  **************************************************************
  ***                                                        ***
  *** NOTE: This is an early release that may contain bugs.  ***
  *** The API is not stable and may change between releases. ***
  ***                                                        ***
  **************************************************************

Currently, there are several SSH client modules available from CPAN, but no one can be used on all the situations.

Net::SSH::Any is an adapter module offering an unified API with a plugin architecture that allows to use the other modules as backends.

It will work in the same way across most operating systems and installations as far as any of the supported backend modules is also installed.

The currently supported backend modules are Net::OpenSSH and Net::SSH2 and I plan to write a backend module on top of the ssh binary and maybe another one for Net::SSH::Perl.

The API is mostly a subset of the one from Net::OpenSSH, though there are some minor deviations in some methods.

API

Optional parameters

Almost all methods in this package accept as first argument a reference to a hash containing optional parameters. In example:

  $ssh->scp_get({recursive => 1}, $remote_src, $local_target);

The hash reference can be omitted when optional parameters are not required. In example:

  @out = $ssh->capture("ls ~/");

Error handling

Most methods return undef or an empty list to indicate failure. Exceptions to this rule are the constructor, which always returns and object, and those methods able to generate partial results as for instance <c>capture</c> or <c>scp_get_content</c>.

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

  my $out = $ssh->capture($cmd);
  $ssh->error and die "capture method failed: " . $ssh->error;

Shell quoting

By default when calling remote commands, this module tries to mimic perl system builtin in regard to argument processing.

When calling some method as, for instance, <c>capture</c>:

   $out = $ssh->capture($cmd)

The command line in $cmd is first processed by the remote shell honoring shell metacharacters, redirections, etc.

If more than one argument is passed, as in the following example:

   $out = $ssh->capture($cmd, $arg1, $arg2)

The module will escape any shell metacharacter so that effectively the remote call is equivalent to executing the remote command without going through a shell (the SSH protocol does not allow to do that directly).

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

For instance, spaces in the command path will be correctly handled in the following case:

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

Deactivating quoting when passing multiple arguments can also be useful, for instance:

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

When the glob option is set in SCP file transfer methods, it is used an alternative quoting mechanism which leaves file wildcards unquoted.

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

The current shell quoting implementation expects a shell compatible with Unix sh in the remote side. It will not work as expected if for instance, the remote machine runs Windows, VMS or if it is a router exposing an ad-hoc shell.

As a workaround, do any required quoting yourself and pass the quoted command as a string so that no further quoting is performed. For instance:

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

Net::SSH::Any methods

These are the methods available from the module:

$ssh = Net::SSH::Any->new($target, %opts)

This method creates a new Net::SSH::Any object representing a SSH connection to the remote machine as described by $target.

$target has to follow the pattern <c>user:password@hostname:port</c> where all parts but hostname are optional. For instance, the following constructor calls are all equivalent:

   Net::SSH::Any->new('hberlioz:f#nta$71k6@harpe.cnsmdp.fr:22');
   Net::SSH::Any->new('hberlioz@harpe.cnsmdp.fr',
                      password => 'f#nta$71k6', port => 22);
   Net::SSH::Any->new('harpe.cnsmdp.fr',
                      user => 'hberlioz', password => 'f#nta$71k6');

user => $user_name

port => $port

TCP port number where the remote server is listening.

password => $password

Password for user authentication.

key_path => $key_path

Path to file containing the private key to be used for user authentication.

Some backends (i.e. Net::SSH2), require the pulic key to be stored in a file of the same name with .pub appended.

passphrase => $passphrase

Passphrase to be used to unlock the private key.

timeout => $seconds

Default timeout.

argument_encoding => $encoding

The encoding used for the commands and arguments sent to the remote stream.

stream_encoding => $encoding

On operation interchanging data between perl and the remote commands (as oposed to operations redirecting the remote commands output to the file system) the encoding to be used.

encoding => $encoding

This option is equivalent to setting argument_encoding and stream_encoding.

remote_*_cmd => $remote_cmd_path

Some operations (i.e. SCP operations) execute a remote command implicitly. By default the corresponding standard command without any path is invoked (i.e scp).

If any other command is preferred, it can be requested through these set of options. For instance:

   $ssh = Net::SSH::Any->new($target,
                             remote_scp_cmd => '/usr/local/bin/scp',
                             remote_tar_cmd => '/usr/local/bin/gtar');

backends => \@preferred_backends

List of preferred backends to be tried.

backend_opts => \%backend_opts

Options specific for the backends.

$ssh->error

This method returns the error, if any, from the last method.

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

Runs a command on the remote machine redirecting the stdout and stderr streams to STDOUT and STDERR respectively.

Note than STDIN is not forwarded to the remote command.

The set of options accepted by this method is as follows:

timeout => $seconds: If there is not any network traffic over the given number of seconds, the command is aborted.
stdin_data => $data
stdin_data => \@data: The given data is sent as the remote command stdin stream.
stdout_fh => $fh: The remote stdout stream is redirected to the given file handle.
stdout_file => $filename: The remote stdout stream is saved to the given file.
stdout_discard => $bool: The remote stdout stream is discarded.
stderr_to_stdout => $bool: The remote stderr stream is mixed into the stdout stream.
stderr_fh => $fh: The remote stderr stream is redirected to the given file handle.
stderr_file => $filename: The remote stderr stream is saved on the given file.
stderr_discard => $bool: The remote stderr stream is discarded.

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

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

The given command is executed on the remote machine and the output captured and returned.

When called in list context this method returns the output split in lines.

In case of error the partial output is returned. The error method should be used to check that no error hapenned even when output has been returned.

The set of options accepted by this method is as follows:

timeout => $seconds: Remote command timeout.
stdin_data => $data
stdin_data => \@data: Data to be sent through the remote command stdin stream.
stderr_to_stdout => $bool: The remote stderr stream is redirected to the stdout stream (and then captured).
stderr_discard => $bool: Remote stderr is discarded.
stderr_fh => $fh: Redirect remote stderr stream to the given file handle.
stderr_file => $filename: Save the remote stderr stream to the given file.

($stdout, $stderr) = $ssh->capture2(\%opts, @cmd)

Captures both the stdout and stderr streams from the remote command and returns them.

timeout => $seconds
stdin_data => $data
stdin_data => \@data

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

stderr_to_stdout => $bool
stderr_discard => $bool

$ssh->scp_get(\%opts, @srcs, $target)

glob => $bool
recursive => $bool
copy_attr => $bool
copy_perm => $bool
copy_time => $bool
update => $bool
numbered => $bool
overwrite => $bool

$ssh->scp_put(\%opts, @srcs, $target)

glob => $bool
recursive => $bool
copy_attr => $bool
follow_links => 0

$data = $ssh->scp_get_content(\%opts, @srcs)

glob => $bool
recursive => $bool

$ssh->scp_mkdir(\%opts, $dir)

$sftp = $ssh->sftp(%opts);

fs_encoding => $encoding
timeout => $seconds

BUGS AND SUPPORT

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://perlmoks.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.

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

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're 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.

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.12.4 or, at your option, any later version of Perl 5 you may have available.

1 POD Error

The following errors were encountered while parsing the POD:

Around line 919:: Non-ASCII character seen before =encoding in 'Fandiño,'. Assuming UTF-8

To install Net::SSH::Any, copy and paste the appropriate command in to your terminal.

cpanm

cpanm Net::SSH::Any

CPAN shell

perl -MCPAN -e shell
install Net::SSH::Any

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)