class %Net.SSH.Session
extends %RegisteredObject
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.
• final parameter SSHPORT = 22;
Default SSH port
• final parameter SSHTRACEAUTH = 8;
Enables tracing of SSH authentication
• final parameter SSHTRACECONN = 16;
Enables tracing of SSH connections
• final parameter SSHTRACEERROR = 128;
Enables tracing of SSH error operations
• final parameter SSHTRACEKEX = 4;
Enables tracing of SSH key exchange
• final parameter SSHTRACEPUBLICKEY = 256;
Enables tracing of SSH public key operations
• final parameter SSHTRACESCP = 32;
Enables tracing of SSH/SCP operations
• final parameter SSHTRACESFTP = 64;
Enables tracing of SSH/SFTP operations
• final parameter SSHTRACESOCKET = 512;
Enables tracing of low level socket operations
• final parameter SSHTRACETRANS = 2;
Enables tracing of SSH transactions
• property HostKey
as %String;
Remote host key
• method %OnClose()
as %Status
Clean up any resources
• method AuthenticateWithKeyPair(username As %String, publickeyfile As %String, privatekeyfile As %String, passphrase As %String)
as %Status
Authenticate with the remote server using a public/private key pair and passphrase (for the private key)
• 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.
• method Connect(hostname As %String, port As %Integer = ..#SSHPORT, hostkey As %String = "")
as %Status
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 Disconnect()
as %Status
Disconnect from the remote host
• 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.
• method ForwardPort(pRemoteHost As %String, pRemotePort As %Integer, ByRef pDevice As %String)
as %Status
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 OpenSFTP(ByRef sftp As %Net.SSH.SFTP)
as %Status
Open up an SFTP session for SFTP activity.
• classmethod TestExecute(host As %String, username As %String, password As %String, command As %String = "uname -a")
as %Status
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.
