/ 
Libssh-Session-1.1
River stage zero No dependents
/ Libssh::Session

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_list ([ OPTIONS ])

Tries to retrieve a list of accepted authentication methods. Returns a bitfield of the following values: SSH_AUTH_METHOD_UNKNOWN SSH_AUTH_METHOD_NONE SSH_AUTH_METHOD_PASSWORD SSH_AUTH_METHOD_PUBLICKEY SSH_AUTH_METHOD_HOSTBASED SSH_AUTH_METHOD_INTERACTIVE SSH_AUTH_METHOD_GSSAPI_MIC

The function auth_none() must be called first before the methods are available.

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_kbdint ([ OPTIONS ])

Try to authenticate through the "keyboard-interactive" method. Returns one of the following: SSH_AUTH_ERROR: A serious error happened\n SSH_AUTH_DENIED: Authentication failed : use another method\n SSH_AUTH_PARTIAL: You've been partially authenticated, you still have to use another method\n SSH_AUTH_SUCCESS: Authentication success\n SSH_AUTH_INFO: The server asked some questions. Use auth_kbdint_getnprmopts() and such to retrieve and answer them.\n SSH_AUTH_AGAIN: In nonblocking mode, you've got to call this again later.

auth_kbdint_getname ([ OPTIONS ])

Get the "name" of the message block. Returns undef if there isn't one or it couldn't be retrieved.

auth_kbdint_getinstruction ([ OPTIONS ])

Get the "instruction" of the message block. Returns undef if there isn't one or it couldn't be retrieved.

auth_kbdint_getnprmopts ([ OPTIONS ])

Get the number of authentication questions given by the server. This function can be used once you've called auth_kbdint() and the server responded with SSH_AUTH_INFO.

auth_kbdint_getprompt ([ OPTIONS ])

Get a prompt from a message block. This function can be used once you've called auth_kbdint() and the server responded with SSH_AUTH_INFO to retrieve one of the authentication questions. The total number of quesitons can be retrieved with auth_kbdint_getnprmopts(). Returns a reference to a hash table.

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

index - The number of the prompt you want to retrieve.

The hash table returned has the following attributes:

text - The prompt text.

echo - '0' or '1' bool value whether or not the user's input should be echoed back.

auth_kbdint_setanswer ([ OPTIONS ])

Set the answer to a prompt from a message block.

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

index - The number of the prompt you want to give an answer to.

answer - The answer to the question. If reading ipnut from <STDIN> make sure to chomp() and append a "\0" character, otherwise it doesn't seem to work.

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>