NAME

Libssh::Session - Support for the SSH protocol via libssh.

SYNOPSIS

  !/usr/bin/perl

  use strict;
  use warnings;
  use Libssh::Session qw(:all);

  my $session = Libssh::Session->new();
  if (!$session->options(host => "127.0.0.1", port => 22)) {
    print $session->error() . "\n";
    exit(1);
  }

  if ($session->connect() != SSH_OK) {
    print $session->error() . "\n";
    exit(1);
  }
  
  if ($session->auth_password(password => "password") != SSH_AUTH_SUCCESS) {
    printf("auth issue: %s\n", $session->error(GetErrorSession => 1));
    exit(1);
  }

  print "== authentification succeeded\n";
  
  sub my_callback {
    my (%options) = @_;
    
    print "================================================\n";
    print "=== exit = " . $options{exit} . "\n";
    if ($options{exit} == SSH_OK || $options{exit} == SSH_AGAIN) { # AGAIN means timeout
        print "=== exit_code = " . $options{exit_code} . "\n";
        print "=== userdata = " . $options{userdata} . "\n";
        print "=== stdout = " . $options{stdout} . "\n";
        print "=== stderr = " . $options{stderr} . "\n";
    } else {
        printf("error: %s\n", $session->error(GetErrorSession => 1));
    }
    print "================================================\n";
    
    #$options{session}->add_command(command => { cmd => 'ls -l', callback => \&my_callback, userdata => 'cmd 3'});
  }

  $session->execute(commands => [ 
                    { cmd => 'ls -l', callback => \&my_callback, userdata => 'cmd 1'},
                    { cmd => 'ls wanterrormsg', callback => \&my_callback, userdata => 'cmd 2 error'},
                  ],
                  timeout => 60, timeout_nodata => 30, parallel => 4);
  exit(0);

DESCRIPTION

Libssh::Session is a perl interface to the libssh (http://www.libssh.org) library. It doesn't support all the library. It's working in progress.

Right now, you can authenticate and execute commands on a SSH server.

METHODS

new

Create new Session object:

    my $session = Libssh::Session->new();

auth_publickey_auto ([ OPTIONS ])

Tries to automatically authenticate with public key and "none". returns SSH_AUTH_SUCCESS if it succeeds.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

passphrase - passphrase for the private key (if it's needed. Otherwise don't set the option).

auth_password ([ OPTIONS ])

Try to authenticate by password. returns SSH_AUTH_SUCCESS if it succeeds.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

password - passphrase for the private key (if it's needed. Otherwise don't set the option).

auth_none ([ OPTIONS ])

Try to authenticate through the "none" method. returns SSH_AUTH_SUCCESS if it succeeds.

connect ([ OPTIONS ])

Connect to the ssh server. returns SSH_OK if no error. By default, the connect does the server check verification.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

connect_only - Set the value to '1' if you want to do the server check verification yourself.

SkipKeyProblem - Returns SSH_OK even if there is a problem (server known changed or server found other) with the ssh server (set by default. Set '0' to disable).

disconnect ()

Disconnect from a session. The session can then be reused to open a new session.

The method take care of the current open channels.

Warning: in many case, you should let the destructor do it!

execute_simple ([ OPTIONS ])

Execute a single command. Returns a reference to a hash table.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

cmd - The command to execute.

timeout - Set the timeout in seconds for the global command execution (By default: 300).

timeout_nodata - Set the timeout in seconds for no data received (By default: 120).

The hash table returned has the following attributes:

exit - SSH_ERROR in case of failure. SSH_AGAIN in case of timeout. SSH_OK otherwise.

exit_code - The exit code of the command executed. undef when timeout.

stdout - The stdout of the executed command.

stderr - The stderr of the executed command.

execute ([ OPTIONS ])

Execute multiple commands. If an error occured, please look how to handle it with the callback functions.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

commands - Reference to an array of hashes.

timeout - Set the timeout in seconds for the global command execution (By default: 300). Each command has its own timeout.

timeout_nodata - Set the timeout in seconds for no data received (By default: 120). Each command has its own timeout.

parallel - Set the number of parallel commands launched (By default: 4).

Warning: Execution times of callbacks count in timeout! Maybe you should save the datas and manages after the execute function.

Look the example above to see how to set the array for commands.

error ( )

Returns the last error message. returns undef if no error.

get_publickey_hash ([ OPTIONS ])

Get a hash of the public key. If an error occured, undef is returned.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

Type - Hash type to used. Default: SSH_PUBLICKEY_HASH_SHA1. Can be: SSH_PUBLICKEY_HASH_MD5.

get_server_publickey ( )

Returns the server public key. If an error occured, undef is returned.

Warning: should be used if you know what are you doing!

options ([ OPTIONS ])

Set options for the ssh session. If an error occured, != SSH_OK is returned.

OPTIONS are passed in a hash like fashion, using key and value pairs. Possible options are:

Host - The hostname or ip address to connect to.

User - The username for authentication.

Port - The port to connect to.

Timeout - Set a timeout for the connection in seconds.

LogVerbosity - Set the session logging verbosity (can be: SSH_LOG_NOLOG, SSH_LOG_RARE,...)

SshDir - Set the ssh directory. The ssh directory is used for files like known_hosts and identity (private and public key). It may include "%s" which will be replaced by the user home directory.

KnownHosts - Set the known hosts file name.

Identity - Set the identity file name (By default identity, id_dsa and id_rsa are checked).

RaiseError - Die if there is an error (By default: 0).

PrintError - print in stdout if there is an error (By default: 0).

LICENSE

This library is licensed under the Apache License 2.0. Details of this license can be found within the 'LICENSE' text file

AUTHOR

Quentin Garnier <qgarnier@centreon.com>