allows Qore programs to establish an ssh2 connection to a remote server More...

#include <QC_SSH2Client.dox.h>

Inheritance diagram for Qore::SSH2::SSH2Client:

Public Member Methods
	constructor (string url, softint port=0)
	creates the object with the given hostname and port number More...

	copy ()
	throws an exception; currently SSH2Client objects cannot be copied More...

hash< Ssh2ConnectionInfo >	info ()
	returns a hash with information about the current connection status More...

SSH2Channel	openDirectTcpipChannel (string host, softint port, string source_host="127.0.0.1", softint source_port=22, timeout timeout=60s)
	Opens a port forwarding channel and returns the corresponding SSH2Channel object for the new forwarded connection. More...

SSH2Channel	openSessionChannel (timeout timeout=60s)
	Opens a login session and returns a SSH2Channel object for the session. More...

SSH2Channel	scpGet (string path, timeout timeout=60s, *reference< hash< Ssh2StatInfo > > statinfo)
	opens a channel for retrieving a remote file with an optional timeout value and an optional reference for returning file status information More...

nothing	scpGet (string path, Qore::OutputStream os, timeout timeout=60s)
	Retrieves a remote file and writes its content to an OutputStream. More...

SSH2Channel	scpPut (string remote_path, softint size, softint mode=0644, date mtime, date atime, timeout timeout=60s)
	Opens a channel for sending a file to the remote server; an SSH2Channel object is returned to use to send the file's data. More...

nothing	scpPut (string remote_path, Qore::InputStream is, softint size, softint mode=0644, date mtime, date atime, timeout timeout=60s)
	Sends a file to the remote server; the content of the file is read from an InputStream. More...

Public Member Methods inherited from Qore::SSH2::SSH2Base
	clearStats ()
	Clears performance statistics. More...

nothing	clearWarningQueue ()
	Removes any warning Queue object from the Socket. More...

nothing	connect (timeout timeout=1m)
	connect to remote system More...

bool	connected ()
	returns True if the session is connected, False if not More...

	constructor ()
	Throws an exception; the constructor cannot be called manually. More...

nothing	disconnect (timeout timeout=1m)
	Disconnects from the remote system; throws an exception if the object is not currently connected. More...

*string	getAuthenticatedWith ()
	returns the authentication type if connected More...

*string	getHost ()
	returns the target hostname if any is set More...

*string	getKeyPriv ()
	returns the private key path if any is set More...

*string	getKeyPub ()
	returns the public key path if any is set More...

*string	getPassword ()
	returns the connection passsword if any is set More...

int	getPort ()
	returns the target port More...

hash< auto >	getUsageInfo ()
	Returns performance statistics for the socket. More...

*string	getUser ()
	returns the target user if any is set More...

nothing	setKeys (string priv_key, *string pub_key)
	Sets path to the private key and optionally the public key to use for the next connection; can only be called when a connection is not established, otherwise an exception is thrown. More...

nothing	setPassword (string pass)
	Sets the password for the next connection; can only be called when a connection is not established, otherwise an exception is thrown. More...

nothing	setUser (string user)
	Sets the user name for the next connection; can only be called when a connection is not established, otherwise an exception is thrown. More...

nothing	setWarningQueue (int warning_ms, int warning_bs, Queue queue, any arg, timeout min_ms=1s)
	Sets a Queue object to receive socket warnings. More...

Detailed Description

allows Qore programs to establish an ssh2 connection to a remote server

Restrictions:: Qore::PO_NO_NETWORK

Member Function Documentation

◆ constructor()

Qore::SSH2::SSH2Client::constructor	(	string	url,
		softint	port = `0`
	)

creates the object with the given hostname and port number

Example:: ssh2client SSH2Client("host", 4022);

Parameters

url	the remote host to connect to - can also be a url like `"ssh://user:pass@hostname:port"`
port	the port number on the remote host to connect to; if the port is 0, then the port given in the url argument is used; if none is given there, then the default port is used (22)

Exceptions

SSH2CLIENT-PARAMETER-ERROR	empty url passed
SSH2-ERROR	socket error sending data; timeout on socket; invalid SSH2 protocol response; server returned an error message

◆ copy()

Qore::SSH2::SSH2Client::copy ( )

throws an exception; currently SSH2Client objects cannot be copied

Exceptions

SSH2CLIENT-COPY-ERROR copying SSH2Client objects is not currently implemented

◆ info()

hash< Ssh2ConnectionInfo > Qore::SSH2::SSH2Client::info ( )

returns a hash with information about the current connection status

Code Flags:: CONSTANT

Example:: hash<Ssh2ConnectionInfo> h = ssh2client.info();

this method is safe to call when not connected

Returns

a hash with the following keys:

ssh2host: (string) the host name of the remote server
ssh2port: (int) the port number of the remote server
ssh2user: (string) the user name used for the connection
keyfile_priv: (string) the filename of the local private key file used
keyfile_pub: (string) the filename of the local public key file used
fingerprint: (*string) The fingerprint of the public host key of the remote server as a string of hex digit pairs separated by colons (:), ex: "AC:AA:DF:3F:49:82:5A:1A:DE:C9:ED:14:00:7D:65:9E" or NOTHING if not connected
authenticated: (*string) a string giving the authentication mechanism used: "publickey", "password", "keyboard-interactive" or NOTHING if not connected
connected: (bool) tells if the connection is currently active or not
methods: (hash) a hash of strings giving the crytographic methods used for the connection

◆ openDirectTcpipChannel()

SSH2Channel Qore::SSH2::SSH2Client::openDirectTcpipChannel	(	string	host,
		softint	port,
		string	source_host = `"127.0.0.1"`,
		softint	source_port = `22`,
		timeout	timeout = `60s`
	)

Opens a port forwarding channel and returns the corresponding SSH2Channel object for the new forwarded connection.

Example:: SS2Channel chan = ssh2client.("host", 4022, NOTHING, NOTHING, 30s);

Parameters

host	the remote host to connect to
port	the port number on the remote host to connect to
source_host	the host name to report as the source of the connection
source_port	the port number to report as the source of the connection
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)

Exceptions

SSH2CLIENT-OPENDIRECTTCPIPCHANNEL-ERROR	port number for forwarded channel as second argument cannot be zero; source port number as fourth argument cannot be zero
SSH2CLIENT-NOT-CONNECTED	client is not connected
SSH2CLIENT-TIMEOUT	timeout opening channel
SSH2-ERROR	error opening channel

◆ openSessionChannel()

SSH2Channel Qore::SSH2::SSH2Client::openSessionChannel ( timeout timeout = 60s )

Opens a login session and returns a SSH2Channel object for the session.

Example:: SSH2Channel chan = ssh2client.openSessionChannel(30s);

Parameters

timeout an integer giving a timeout in milliseconds or a relative date/time value (ex: 15s for 15 seconds)

Exceptions

SSH2CLIENT-NOT-CONNECTED	client is not connected
SSH2CLIENT-TIMEOUT	timeout opening channel
SSH2-ERROR	error opening channel

◆ scpGet() [1/2]

nothing Qore::SSH2::SSH2Client::scpGet	(	string	path,
		Qore::OutputStream	os,
		timeout	timeout = `60s`
	)

Retrieves a remote file and writes its content to an OutputStream.

Example:: ssh2client.scpGet("file.txt", outputStream);

Parameters

path	the path of the remote file to get
os	the output stream
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)

Exceptions

SSH2CLIENT-NOT-CONNECTED	client is not connected
SSH2CLIENT-TIMEOUT	timeout opening channel
SSH2-ERROR	error opening channel

Since: ssh2 1.1

◆ scpGet() [2/2]

SSH2Channel Qore::SSH2::SSH2Client::scpGet	(	string	path,
		timeout	timeout = `60s`,
		*reference< hash< Ssh2StatInfo > >	statinfo
	)

opens a channel for retrieving a remote file with an optional timeout value and an optional reference for returning file status information

Example:: hash<Ssh2StatInfo> info;

SS2Channel chan = ssh2client.scpGet("/tmp/file.txt", 30s, \info);

Parameters

path	the path of the remote file to get
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)
statinfo	an optional reference to an Ssh2StatInfo hash for file status info with the following keys: `"mode"`: the file's mode `"permissions"`: a string of the file's mode (ex: `"drwxr-xr-x"`) `"size"`: the size of the file in bytes `"atime"`: the last access time of the file `"mtime"`: the last modified time of the file

Returns: an SSH2Channel object is returned to use to retrieve the file's data

Exceptions

SSH2CLIENT-NOT-CONNECTED	client is not connected
SSH2CLIENT-TIMEOUT	timeout opening channel
SSH2-ERROR	error opening channel

◆ scpPut() [1/2]

nothing Qore::SSH2::SSH2Client::scpPut	(	string	remote_path,
		Qore::InputStream	is,
		softint	size,
		softint	mode = `0644`,
		*date	mtime,
		*date	atime,
		timeout	timeout = `60s`
	)

Sends a file to the remote server; the content of the file is read from an InputStream.

Example:: ssh2client.scpPut("/tmp/file.txt", inputStream, size, 0644, 2010-12-25, 2010-12-25, 30s);

Parameters

remote_path	the path of the file to save on the remote server
is	the input stream to read from
size	the size of the file to send; this parameter is required
mode	the file's mode on the remote machine
mtime	the file's last modified time to create on the remote machine
atime	the file's last access time to create on the remote machine
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)

Exceptions

SSH2CLIENT-NOT-CONNECTED	client is not connected
SSH2CLIENT-TIMEOUT	timeout opening channel
SSH2-ERROR	error opening channel

Since: ssh2 1.1

◆ scpPut() [2/2]

SSH2Channel Qore::SSH2::SSH2Client::scpPut	(	string	remote_path,
		softint	size,
		softint	mode = `0644`,
		*date	mtime,
		*date	atime,
		timeout	timeout = `60s`
	)

Opens a channel for sending a file to the remote server; an SSH2Channel object is returned to use to send the file's data.

Example:: SS2Channel chan = ssh2client.scpPut("/tmp/file.txt", size, 0644, 2010-12-25, 2010-12-25, 30s);

Parameters

remote_path	the path of the file to save on the remote server
size	the size of the file to send; this parameter is required
mode	the file's mode on the remote machine
mtime	the file's last modified time to create on the remote machine
atime	the file's last access time to create on the remote machine
timeout	an integer giving a timeout in milliseconds or a relative date/time value (ex: `15s` for 15 seconds)

Returns: an SSH2Channel object is returned to use to send the file's data

Exceptions

SSH2CLIENT-NOT-CONNECTED	client is not connected
SSH2CLIENT-TIMEOUT	timeout opening channel
SSH2-ERROR	error opening channel

The documentation for this class was generated from the following file:

QC_SSH2Client.dox.h

Public Member Methods

Detailed Description

Member Function Documentation

◆ constructor()

◆ copy()

◆ info()

◆ openDirectTcpipChannel()

◆ openSessionChannel()

◆ scpGet() [1/2]

◆ scpGet() [2/2]

◆ scpPut() [1/2]

◆ scpPut() [2/2]