Libssh::Session(3)

📦 version 1.100.0, in opensuse-leap 16.0

🦋 NAME 🦋

Okay so bestie, welcome to Libssh::Session(3) — section 3 of the User Contributed Perl Documentation, no cap ✨ — the page that gives you support for the SSH protocol via libssh. That's the whole vibe. SSH, but from Perl, through libssh. Slay.

🌸 SYNOPSIS 🌸

Here's the iconique little script they hand you, verbatim, copy it exactly:

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

See that # AGAIN means timeout comment in there? Keep it, it's doing important work 💅

💖 DESCRIPTION 💖

"Libssh::Session" is a perl interface to the libssh library (<http://www.libssh.org>) 🫶. Real talk though: it doesn't support all of the library — it's working in progress, bestie, we're all just doing our best out here 😭.

Right now, what it actually does is let you authenticate and execute commands on a SSH server. That's the whole flex. And honestly? It ate. 🔥

✨ METHODS ✨

🎀 new

Create a new Session object, duh:

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

Main character energy from the jump 👑

🔑 auth_publickey_auto ([ OPTIONS ])

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

"OPTIONS" get passed in a hash-like fashion, key and value pairs, iykyk. The possible option is:

  • 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 these values, all of them, in a row:

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

Heads up bestie: 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" get passed in a hash-like fashion, using key and value pairs. The possible option is:

  • password — the doc literally describes this one as "passphrase for the private key (if it's needed. Otherwise don't set the option)." Yes, that's word-for-word what it says 🙈 copying is a love language.

⌨️ 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.

(The \ns are part of the documentation's own formatting, so I kept them, don't come for me 💀)

🏷️ 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. You can use this 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" come in hash-like fashion, key and value pairs. The possible option:

  • index — The number of the prompt you want to retrieve.

And the hash table it hands back has these attributes bestie:

  • 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" in hash-like fashion, key and value pairs. Possible options:

  • 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.
That "\0" thing is not a suggestion, it's a whole lifestyle. Skip it and it just won't 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 hash-like, key and value pairs. Possible options:

  • 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).
Bestie, peep that SkipKeyProblem default — it's on out of the box. If you want to actually hear about a changed/other server, set it to '0' 👀

👋 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" hash-style, key and value pairs. Possible options:

  • 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 it returns has these 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" hash-like, key and value pairs. Possible options:

  • 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. Like, do not be doing your whole side quest inside the callback, bestie, the clock is ticking 😭

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

🩹 error ( )

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

(And yeah, the example up top calls it like $session->error(GetErrorSession => 1) — that's how it shows up in the synopsis, keep it as-is 💅)

🧬 get_publickey_hash ([ OPTIONS ])

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

"OPTIONS" hash-like, key and value pairs. Possible option:

  • 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! Respectfully, do not just vibe-check this one 🫣

⚙️ options ([ OPTIONS ])

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

"OPTIONS" hash-style, key and value pairs. Possible options, the full set:

  • 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> — thank you for your service 🫶✨

And that's the page, bestie!! Written by that author up there, shipped as perl v5.42.0, dated 2024-06-23, and it lives at Libssh::Session(3) in the User Contributed Perl Documentation. Go forth and SSH, mwah 💋💅

📦 where this page comes from