Qore SSH2 Module  0.9.9
 All Classes Namespaces Functions
Qore SSH2 Module

Introduction

The ssh2 module provides Qore the possibility to communicate with sshd servers via the ssh2 protocol; the underlying functionality is provided by libssh2.

This module is released under a choice of two licenses:

  • LGPL 2.1
  • MIT (see COPYING.MIT in the source distribution for more information) The module is tagged as such in the module's header (meaning it can be loaded unconditionally regardless of how the Qore library was initialized). This version of the module requires Qore 0.8.1+ to compile and run.

To use the module in a Qore script, use the %requires directive as follows:

%requires ssh2

This module provides the following classes:

Class Description
Qore::SSH2::SSH2Base base class for SFTPClient and SSH2Client
Qore::SSH2::SSH2Client allows Qore programs to establish an ssh2 connection to a remote server
Qore::SSH2::SFTPClient allows Qore programs to use the sftp protocol
Qore::SSH2::SSH2Channel allows Qore programs to send and receive data through an ssh2 channel

When connecting the module will try to:

See some examples here: Examples

Examples

Example of a basic sftp connection:

# create object
my SFTPClient $sftp("sftp://user:pass@host.com:22");
# connect to sftp server
$sftp.connect();

Example of logging in via ssh2 and executing a command and retrieving the output:

# set URL
my string $url = "sftp://user:pass@host.com:22";
# create object
my SSH2Client $ssh2($url);
# connect to remote sshd daemon
$ssh2.connect();
# get a session channel
my SSH2Channel $chan = $sc.openSessionChannel();
# execute a command on the channel
$chan.exec("ls -l");
# retrieve the output and print it out
stdout.printf("%s", $chan.read());
# close channel
$chan.sendEof();
$chan.close();
# print out the exit status after the channel is closed
stdout.printf("exit status: %d\n", $chan.getExitStatus());

Function and Method Tags

NOOP

Code with this flag makes no calculations, but rather returns a constant value. This flag is given to function and method variants that return a default value depending on the type of argument(s). When variants with this flag are resolved at parse time, a "call-with-type-errors" warning is raised (assuming this warning is enabled), unless PO_REQUIRE_TYPES or PO_STRICT_ARGS is set. If PO_REQUIRE_TYPES or PO_STRICT_ARGS is set, then these variants are inaccessible at parse time; resolving to a variant with this flag set at parse time causes an exception to be thrown.

These variants are included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

This tag is equal to RUNTIME_NOOP, except no runtime effect is caused by resolving a function or method tagged with NOOP at runtime; this tag only affects parse time resolution.

RUNTIME_NOOP

Code with this flag makes no calculations, but rather returns a constant value. This flag is given to function and method variants that return a default value depending on the type of argument(s). When variants with this flag are resolved at parse time, a "call-with-type-errors" warning is raised (assuming this warning is enabled), unless PO_REQUIRE_TYPES or PO_STRICT_ARGS is set. If PO_REQUIRE_TYPES or PO_STRICT_ARGS is set, then these variants are inaccessible; resolving to a variant with this flag set at parse time or run time causes an exception to be thrown.

These variants are included for backwards-compatibility with qore prior to version 0.8.0 for functions that would ignore type errors in arguments.

This tag is equal to NOOP, except that RUNTIME_NOOP is also enforced at runtime.

RET_VALUE_ONLY

This flag indicates that the function or method has no side effects; it only returns a value, for example.

This tag is identical to CONSTANT except that functions or methods tagged with RET_VALUE_ONLY could throw exceptions.

CONSTANT

This flag indicates that the function or method has no side effects and does not throw any exceptions.

This tag is identical to RET_VALUE_ONLY except that functions or methods tagged with CONSTANT do not throw exceptions.

DEPRECATED

Code with this flag is deprecated and may be removed in a future version of this module; if a variant with this flag is resolved at parse time, a "deprecated" warning is raised (assuming this warning is enabled).

Release Notes

Version 0.9.9

  • closed some gaps in the non-blocking I/O solution introduced in the last release
  • implemented implicit connections for the Qore::SSH2::SFTPClient class
  • implemented the Qore::SSH2::SFTPClient::listFull() method
  • implemented the Qore::SSH2::SSH2Base::connected() method
  • when errors occur in the SFTPClient class, the connection is marked as closed if the connection has been terminated
  • made cwd persistent across connections to better deal with implicit disconnections and reconnections
  • use keepalive by default to try and maintain persistent connections
  • released also under the MIT licenses (in addition to LGPL 2.1)

Version 0.9.8

  • default timeout of 60 seconds added to connect methods to avoid hanging connections indefinitely
  • non-blocking I/O implemented for all SFTPClient methods, default timeout set to 60s
  • send the file mode when opening files read-only in case broken servers will erroneously set the remote file's mode to 0 and then the file will not be readable
  • Qore::SSH2::SFTPClient::getTextFile() has new optional parameter: encoding

Version 0.9.7

  • an exception will be thrown if a key file is set and either the public or private key is not available or readable; previously such errors would cause hard-to-debug connection problems (for instance, see: http://comments.gmane.org/gmane.network.ssh.libssh2.devel/5873; note that the patch mentioned in the linked thread was subsequently reverted)
  • fixed another deadlock in the SFTPClient::disconnect() method
  • minor doc updates
  • requires qore 0.8.5+ to build and run

Version 0.9.6

  • major documentation updates; now using doxygen
  • fixed a deadlock in the SFTPClient::disconnect() method
  • requires qore 0.8.1+ to build and run

Version 0.9.5

  • Initial release of the ssh2 module
  • Requires qore 0.8.0+ to build and run