NAME

Test::SSH - Perl extension for testing SSH modules.

SYNOPSIS

  use Test::SSH;
  my $sshd = Test::SSH->new or skip_all;

  my %opts;
  $opts{host} = $sshd->host();
  $opts{port} = $sshd->port();
  $opts{user} = $sshd->user();
  given($sshd->auth_method) {
    when('password') {
      $opts{password} = $sshd->password;
    }
    when('publickey') {
      $opts{key_path} = $sshd->key_path;
    }
  }

  my $openssh = Net::OpenSSH->new(%opts);
  # or...
  my $anyssh  = Net::SSH::Any->new(%opts);
  # or...

DESCRIPTION

Important: This module is being replaced by Net::SSH::Any::Test. Development of Test::SSH is now mostly limited to bug fixing!

In order to test properly Perl modules that use the SSH protocol, a running server and a set of valid authentication credentials are required.

If you test your modules on a controlled environment, you may know the details of some local server or even have one configured just for that purpose, but if you plan to upload your modules to CPAN (or for that matter distribute them through any other medium) and want them to be tested by the CPAN testers and by programmers installing them, things become quite more difficult.

This module, uses several heuristics to find a local server or if none is found, start a new one and then provide your testing scripts with the credentials required to login.

Besides finding or starting a server the module also tests that it works running some simple commands there. It would try hard to not return the details of a server that is not working properly.

API

The module provides the following methods:

$sshd = Test::SSH->sshd(%opts)

Returns an object that can be queried to obtain the details of an accesible SSH server. If no server is found or can be launched, undef is returned.

In case a slave SSH server had been started, it will be killed once the returned object goes out of scope.

For modules distributed through CPAN or that are going to be tested on uncontrolled environments, commonly, no options should be given as the default should already be the right choice.

In any case, these are the accepted options:

requested_uri => $uri

The module looks for a SSH server at the location given.

backends => \@be

The module has several backend modules, every one implementing a different approach for finding a SSH server. This argument allows to select a specific subset of them.

path => \@path

By default the module looks for SSH program binaries on the path and on several common directories (i.e. /opt/*SSH*). This parameter allows to change that.

timeout => $timeout

Timeout used for running commands and stablishing remote connections. The default is 10s.

test_commands => \@cmds

When testing a SSH connection the module would try running the commands given here until any of them succeeds. The defaults is a set of very common Unix and shell commands (i.e. echo or true).

private_dir => $dir

Location used to save data bewteen runs (i.e. generated user and host key pairs).

The default is ~/.libtest-ssh-perl

private_keys => \@key_paths

List of private keys that will be used for login into the remote host.

The default is to look for keys in ~/.ssh.

logger => sub { ... }

Subroutine that will be called to report activity to the user.

The default is to use Test::More::diag.

run_server => $bool

Enables/disables the backends that start a new SSH server.

For instance:

  my $sshd = Test::SSH->new(run_server => ($ENV{AUTHOR_TESTING} || $ENV{AUTOMATED_TESTING}));

override_server_config => $hash_reference

Key/Value pairs in this hash reference will be used to override the defaults for the sshd_config file of the sshd server started. If a value in this hash is undef, the respective key of the server config will be deleted.

Also, the following environment variables can be used to change the module behaviour:

TEST_SSH_TARGET

Target URI. When set, the module will look for the SSH server at the location given. For instance:

  TEST_SSH_TARGET=ssh://root:12345@ssh.google.com/ perl testing_script.pl

Setting this variable will also dissable launching a custom SSH server for testing.

TEST_SSH_PASSWORD

When set, the value will be used as the login password. For instance:

  TEST_SSH_PASSWORD=12345 perl testing_script.pl

$sshd->host

Returns the name of the host.

$sshd->port

Returns the TCP port number where the server is listening.

$sshd->user

Returns the name of the remote user

$sshd->auth_method

Returns password or publickey indicating the method that can be used to connect to the remote server.

$sshd->key_path

When the authentication method is publickey, this method returns the path to the private key that can be used for loging into the remote host.

$sshd->password

When the authentication method is password, this method returns the password to be used for logging into the remote host.

$sshd->uri(%opts)

Returns an URI object descibing the SSH server.

The accepted options are as follows:

hidden_password => 1

When this option is set and in case of password authentication, the password will be replaced by five asterisks on the returned URI.

my %params = $sshd->connection_params

Returns the connection parameters as a list of key/value pairs.

$sshd->server_version

Connects to the server and retrieves its version signature.

BUGS AND SUPPORT

Well, this module is of complicated nature. It interacts in several ways with external uncontrolled entities in an unknown environment, so it may probably fail in lots of ways...

The good news is that if you use it and report me failures, bugs or any unexpected failure I will try to fix it and it will improve and mature over time!!!

In order to report bugs use the CPAN bugtracker (http://rt.cpan.org) or at your option the GitHub one (https://github.com/salva/p5-Test-SSH/issues).

The source code for the development version of the module is hosted at GitHub: https://github.com/salva/p5-Test-SSH). Patches or pull-request are very well welcome!

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.

COPYRIGHT AND LICENSE

Copyright (C) 2013-2017 by Salvador Fandiño (sfandino@yahoo.com), Andreas König (andk@cpan.org)

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