Qore SSH2 Module

Table of Contents

• Introduction to the ssh2 Module
• Examples
• Function and Method Tags
  • NOOP
  • RUNTIME_NOOP
  • RET_VALUE_ONLY
  • CONSTANT
  • DEPRECATED
• Release Notes
  • Version 1.4.1
  • Version 1.4
  • Version 1.3
  • Version 1.2
  • Version 1.1
  • Version 1.0
  • Version 0.9.9
  • Version 0.9.8
  • Version 0.9.7
  • Version 0.9.6
  • Version 0.9.5

Introduction to the ssh2 Module

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

Also included with the binary ssh2 module:

• Ssh2Connections user module
• SftpPollerUtil user module
• SftpPoller user module

When connecting the module will try to:

• connect to the server with the given port or with port 22 if no port is given
• login as the given user (user is set in the URL given to SSH2Client::constructor() or SFTPClient::constructor() or can be modified with SSH2Base::setUser()) using:
  • publickey authentification (public and private key files can be modified with SSH2Base::setKeys())
  • password authentification (password can be set in the URL given to SSH2Client::constructor() or SFTPClient::constructor() or can be set afterwards with SSH2Base::setPassword())

See some examples here: Examples

Examples

Example of a basic sftp connection:

# create object
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
string url = "sftp://user:pass@host.com:22";
# create object
SSH2Client ssh2(url);
# connect to remote sshd daemon
ssh2.connect();
# get a session channel
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 1.4.1

• fixed a bug where the sftp event type was registered twice (issue 4389)

Version 1.4

• added support for the data provider API
• fixed a core dump when a SFTPClient disconnection occurs with open SSH2Channel objects (issue 3943)
• implemented support for serializing connection objects (issue 3696)
• implemented support for auto-reconnecting lost connections in the SftpPoller module (issue 1846)

Version 1.3

• added support for complex types in public APIs (issue 3540)
• added the following base class APIs:
  • SSH2Base::getAuthenticatedWith()
  • SSH2Base::getHost()
  • SSH2Base::getKeyPriv()
  • SSH2Base::getKeyPub()
  • SSH2Base::getPassword()
  • SSH2Base::getPort()
  • SSH2Base::getUser() (issue 3445)
• updated the Ssh2Connections module to support the updated abstract connection API (issue 2628)

Version 1.2

• added the Ssh2Connections user module
• added the following SFTPClient methods supporting streams:
  • SFTPClient::get()
  • SFTPClient::put()
• fixed bugs retrieving zero-length text files with SFTPClient::getFile(), SFTPClient::getTextFile(), SFTPClient::get(), and SFTPClient::retrieveFile() (issue 2549)
• fixed bugs streaming data with SFTPClient::transferFile() and SFTPClient::put() (issue 2633)

Version 1.1

• argument error in SFTPClient disconnection with socket errors causes a crash (issue 765)
• infinite loop in SftpPoller polling when PO_NO_PROCESS_CONTROL is not set and no sleep option is given (issue 773)
• implement support for additional directories in SftpPoller (issue 753)
• SftpPoller::run() cannot be synchronized (issue 798)
• compile fixes for Solaris 10 g++ (issue 861)
• add constructor option to SftpPoller for checking if polled directories are writable (issue 888)
• fixed a bug that could cause a crash when an error occurs in the SFTPClient class (issue 1040)
• streaming from SFTP server impossible without user re-implementing SftpPoller methods (issue 1557)
• fixed a bug in libssh2 library initialization error reporting (issue 1696)

Version 1.0

• fixed crashing bugs handling errors and handle scope in the SFTPClient class
• added the SftpPoller user module
• force socket disconnect in case of a timeout error when trying to close a file descriptor
• socket performance instrumentation supported in the SFTPClient class
• user modules moved to top-level qore module directory from version-specific module directory since they are valid for multiple versions of qore
• fixed a bug where a crash would result when attempting a connection and libssh2 would not return any user authentication methods
• implemented an automatic disconnection when timeouts occur to avoid dead connections
• fixed crashing bugs in the SFTPClient class handling disconnect events when an sftp handle was open; the handle must be closed before the socket connection is closed or a crash will result
• implemented the SFTPClient::retrieveFile() and SFTPClient::transferFile() methods
• ported the SFTPClient class tests to QUnit and added tests for the new methods
• ported test/sftp-poller.q to QUnit
• fixed a bug in socket handling related to asyncronous socket event polling and select(2) and lack of socket descriptor bounds checking (issue 714)
• requires Qore 0.8.12+ to build (uses the new QoreValue API)

Version 0.9.9

• closed some gaps in the non-blocking I/O solution introduced in the last release
• implemented implicit connections for the SFTPClient class
• implemented the SFTPClient::listFull() method
• implemented the SSH2Base::connected() method
• when errors occur in the SFTPClient class, the connection is marked as closed if the connection has been terminated
• made the current working directory in the SFTPClient class 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
• SFTPClient::getTextFile() has a 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