Represents an SSH session object. Each SSH session object must first be connected, then authenticated
with the remote system. Note that there are multiple methods of authentication, this class supports
password and publickey. Once connected and authenticated, the SSH object can be used to perform
SCP (Secure Copy) operations of single files to and from the remote system, it can also be used
to execute remote commands, tunnel TCP traffic and forms the base connection for SFTP operations (see
%Net.SSH.SFTP).
The Test() method of this class illustrates some basic usage scenarios for this class.
NOTE: CacheSSH is currently not supported on OpenVMS platforms.
property LocalCharset as %String [ InitialExpression = $CASE($system.Version.GetOS(),"Windows":"",:"UTF8") ];
Character set used by the local system. Defaults to UTF-8 for UNIX
but likely should NOT BE SET for Windows (which means we'll use UCS-2
Unicode characters for local filenames).
Inherited description: This callback method is invoked by the %New() method to
provide notification that a new instance of an object is being created.
If this method returns an error then the object will not be created.
It is passed the arguments provided in the %New call.
When customizing this method, override the arguments with whatever variables and types you expect to receive from %New().
For example, if you're going to call %New, passing 2 arguments, %OnNew's signature could be:
Method %OnNew(dob as %Date = "", name as %Name = "") as %Status
If instead of returning a %Status code this returns an oref and this oref is a subclass of the current
class then this oref will be the one returned to the caller of %New method.
Authenticate with the remote server using a public/private key pair and passphrase (for the private key).
The private keys are PEM encoded and the public keys are in OpenSSH format.
If multiple forms of authentication are required by the server, for example /etc/ssh/sshd_config
contains:
AuthenticationMethods publickey,password
Then in this case read the "," (comma) as AND; the server will require both forms of authentication.
Calling AuthenticateWithKeyPair fails with LIBSSH2_ERROR_PUBLICKEY_UNVERIFIED which is a bit
misleading ... it's really "authenticated with partial success" so we can then try then authenticating with
a password which should then succeed (or keyboard-interactive).
method AuthenticateWithKeyboardInteractive(username As %String, lambda As %String, ByRef context) as %Status
Authenticate with the remote server using the "keyboard-interactive" authentication scheme. This requires
a callback lambda/function that will be called with a list of one or challenges to which the lambda will return
the responses to the challenge(s). The lambda is invoked with the following arguments:
username As %String Username being authenticated
instructions As %String Instructions from the server (optional)
prompts As %List A $LIST of challenge prompt(s)
promptflags As %List A $LIST of flags for each of the challenge prompt(s)
ByRef context A pass-by-ref context value
The lambda must return a $LIST of responses, with each Nth element in the $LIST corresponding to the Nth
challenge prompt. If there is no response for a prompt, then that Nth $LIST element should be empty.
The allowed values for promptflags are as follows:
E Echo on. If E is missing DO NOT ECHO! (e.g. password entry)
NOTE: The context can be anything of your choosing (an array, object or whatever) and it is passed
by reference.
See notes in AuthenticateWithKeyPair() when using multiple forms of authentication.
method AuthenticateWithUsername(username As %String, password As %String) as %Status
Authenticate with the remote server using a username/password via the "password" authentication
scheme. Note that this is NOT the same as keyboard-interactive which is typically what login
sessions use.
See notes in AuthenticateWithKeyPair() when using multiple forms of authentication.
Connect to a remote host, specifying the hostname, and optionally the port and remote hostkey to match.
The hostkey helps prevent impersonation attacks, it is a hash of the remote hosts' public key.
method Execute(pCommand As %String, ByRef pDevice As %String, ByRef pEnv) as %Status
Execute a remote command on the remote system. In order to do I/O with the remote
command, an XDEV device instance is passed back via the pDevice parameter. This is
a normal Cache' device and can be used with the USE/READ/WRITE/CLOSE commands.
Note that environment variables for the remote command can be passed as an array
of name/value pairs.
Forwards traffic via the SSH connection to a remote host/port. The traffic is sent via an XDEV device
that is opened by ForwardPort() and passed back by reference via the pDevice parameter.
method GetAlgorithms(ByRef preferences As %String) as %Status
Called to retrieve the current set of negotiated algorithms/methods for various categories.
Format of the result string is as follows:
<category>=<option>[:<category1>=<option1>[:...]]
Where <category> is one of:
KEX Key Exchange Methods
HOSTKEY Hostkey public key algorithms
CRYPT Encryption algorithms
MAC MAC algorithms
COMPCompression Algorithms
NOTE: The allowed values can be found here:
http://libssh2.sourceforge.net/doc/#libssh2sessionmethodpref
And <option> is a comma delimited list of one or more values.
method GetSupportedAlgorithms(ByRef algs As %String) as %Status
Called to retrieve the set of supported algorithms for various categories.
Format of the string is as follows:
<category>=<option>[:<category1>=<option1>[:...]]
Where <category> is one of:
KEX Key Exchange Methods
HOSTKEY Hostkey public key algorithms
CRYPT Encryption algorithms
MAC MAC algorithms
COMP Compression Algorithms
NOTE: The allowed values can be found here:
http://libssh2.sourceforge.net/doc/#libssh2sessionmethodpref
method GetTimeout(ByRef pTimeoutMS As %Integer = -1) as %Status
Gets the timeout for SSH operations in milliseconds. An infinite timeout is represented by the value of -1;
the default timeout is set to 30 seconds.
method SetPreferredAlgorithms(preferences As %String) as %Status
Called before connecting to a remote host to specify various preferred algorithms and methods that
should be used. Format of the preferences string is as follows:
<category>=<option>[:<category1>=<option1>[:...]]
Where <category> is one of:
KEX Key Exchange Methods
HOSTKEY Hostkey public key algorithms
CRYPT Encryption algorithms
MAC MAC algorithms
COMPCompression Algorithms
NOTE: The allowed values can be found here:
http://libssh2.sourceforge.net/doc/#libssh2sessionmethodpref
And <option> is a comma delimited list of one or more values.
Sets the timeout for SSH operations in milliseconds. An infinite timeout can be set by passing -1 to this
methods; the default timeout is set to 30 seconds.
Demonstrates the execution of a remote command (by default, uname -a).
classmethod TestForwardPort(host As %String, username As %String, password As %String, remotehost As %String = "whatismyipaddress.com", remoteport As %Integer = 80) as %Status
Demonstrates the use of port forwarding to whatismyipaddress.com via the remote SSH server.
method VersionInfo(ByRef pClientVersion As %String, ByRef pServerVersion As %String) as %Status
Retrieves the client and server SSH versions. If the server version is not available,
or if the session is not connected, then pServerVersion will be undefined. Note that the
client version refers to the release of libssh2 being used.