Native Single Host Client¶

Native single host non-blocking client. Suitable for running asynchronous commands on a single host.

class pssh.clients.native.single.SSHClient(host, user=None, password=None, port=None, pkey=None, alias=None, num_retries=3, retry_delay=5, allow_agent=True, timeout=None, forward_ssh_agent=False, proxy_host=None, proxy_port=None, proxy_pkey=None, proxy_user=None, proxy_password=None, _auth_thread_pool=True, keepalive_seconds=60, identity_auth=True, ipv6_only=False)¶

ssh2-python (libssh2) based non-blocking SSH client.

Parameters:

host (str) – Host name or IP to connect to.
user (str) – User to connect as. Defaults to logged in user.
password (str) – Password to use for password authentication.
alias (str) – Use an alias for this host.
port (int) – SSH port to connect to. Defaults to SSH default (22)
pkey (str or bytes) – Private key file path to use for authentication. Path must be either absolute path or relative to user home directory like ~/<path>. Bytes type input is used as private key data for authentication.
num_retries (int) – (Optional) Number of connection and authentication attempts before the client gives up. Defaults to 3.
retry_delay (int or float) – Number of seconds to wait between retries. Defaults to pssh.constants.RETRY_DELAY
timeout (int or float) – SSH session timeout setting in seconds. This controls timeout setting of authenticated SSH sessions.
allow_agent (bool) – (Optional) set to False to disable connecting to the system’s SSH agent
identity_auth (bool) – (Optional) set to False to disable attempting to authenticate with default identity files from pssh.clients.base.single.BaseSSHClient.IDENTITIES
forward_ssh_agent (bool) – Unused - agent forwarding not implemented.
proxy_host (str) – Connect to target host via given proxy host.
proxy_port (int) – Port to use for proxy connection. Defaults to self.port
keepalive_seconds (int) – Interval of keep alive messages being sent to server. Set to 0 or False to disable.
ipv6_only (bool) – Choose IPv6 addresses only if multiple are available for the host or raise NoIPv6AddressFoundError otherwise. Note this will disable connecting to an IPv4 address if an IP address is provided instead.

Raises:

pssh.exceptions.PKeyFileError on errors finding provided private key.

close_channel(channel)¶

configure_keepalive()¶

copy_file(local_file, remote_file, recurse=False, sftp=None)¶

Copy local file to host via SFTP.

Parameters:	local_file (str) – Local filepath to copy to remote host remote_file (str) – Remote filepath on remote host to copy file to recurse (bool) – Whether or not to descend into directories recursively. sftp (`ssh2.sftp.SFTP`) – SFTP channel to use instead of creating a new one.
Raises:	`ValueError` when a directory is supplied to `local_file` and `recurse` is not set
Raises:	`pssh.exceptions.SFTPError` on SFTP initialisation errors
Raises:	`pssh.exceptions.SFTPIOError` on I/O errors writing via SFTP
Raises:	`IOError` on local file IO errors
Raises:	`OSError` on local OS errors like permission denied

copy_remote_file(remote_file, local_file, recurse=False, sftp=None, encoding='utf-8')¶

Copy remote file to local host via SFTP.

Parameters:	remote_file (str) – Remote filepath to copy from local_file (str) – Local filepath where file(s) will be copied to recurse (bool) – Whether or not to recursively copy directories encoding (str) – Encoding to use for file paths. sftp (`ssh2.sftp.SFTP`) – SFTP channel to use instead of creating a new one.
Raises:	`ValueError` when a directory is supplied to `local_file` and `recurse` is not set
Raises:	`pssh.exceptions.SFTPError` on SFTP initialisation errors
Raises:	`pssh.exceptions.SFTPIOError` on I/O errors reading from SFTP
Raises:	`IOError` on local file IO errors
Raises:	`OSError` on local OS errors like permission denied

disconnect()¶

Attempt to disconnect session.

Any errors on calling disconnect are suppressed by this function.

eagain_write(write_func, data)¶

execute(cmd, use_pty=False, channel=None)¶

Execute command on remote server.

Parameters:	cmd (str) – Command to execute. use_pty (bool) – Whether or not to obtain a PTY on the channel. channel (`ssh2.channel.Channel`) – Use provided channel for execute rather than creating a new one.

finished(channel)¶

Checks if remote command has finished - has server sent client EOF.

Return type:	bool

get_exit_status(channel)¶

Get exit status code for channel or None if not ready.

Parameters:	channel (`ssh2.channel.Channel`) – The channel to get status from.
Return type:	int or `None`

mkdir(sftp, directory)¶

Make directory via SFTP channel.

Parent paths in the directory are created if they do not exist.

Parameters:	sftp (`ssh2.sftp.SFTP`) – SFTP client object directory (str) – Remote directory to create

Catches and logs at error level remote IOErrors on creating directory.

open_session()¶: Open new channel from session

poll(timeout=None)¶

Perform co-operative gevent poll on ssh2 session socket.

Blocks current greenlet only if socket has pending read or write operations in the appropriate direction. :param timeout: Deprecated and unused - to be removed.

scp_recv(remote_file, local_file, recurse=False, sftp=None, encoding='utf-8')¶

Copy remote file to local host via SCP.

Note - Remote directory listings are gathered via SFTP when recurse is enabled - SCP lacks directory list support. Enabling recursion therefore involves creating an extra SFTP channel and requires SFTP support on the server.

Parameters:	remote_file (str) – Remote filepath to copy from local_file (str) – Local filepath where file(s) will be copied to recurse (bool) – Whether or not to recursively copy directories sftp (`ssh2.sftp.SFTP`) – The SFTP channel to use instead of creating a new one. Only used when `recurse` is `True`. encoding (str) – Encoding to use for file paths when recursion is enabled.
Raises:	`pssh.exceptions.SCPError` on errors copying file.
Raises:	`IOError` on local file IO errors.
Raises:	`OSError` on local OS errors like permission denied.

scp_send(local_file, remote_file, recurse=False, sftp=None)¶

Copy local file to host via SCP.

Note - Directories are created via SFTP when recurse is enabled - SCP lacks directory create support. Enabling recursion therefore involves creating an extra SFTP channel and requires SFTP support on the server.

Parameters:	local_file (str) – Local filepath to copy to remote host remote_file (str) – Remote filepath on remote host to copy file to sftp (`ssh2.sftp.SFTP`) – The SFTP channel to use instead of creating a new one. Only used when `recurse` is `True`. recurse (bool) – Whether or not to descend into directories recursively.
Raises:	`ValueError` when a directory is supplied to `local_file` and `recurse` is not set
Raises:	`pssh.exceptions.SFTPError` on SFTP initialisation errors
Raises:	`pssh.exceptions.SFTPIOError` on I/O errors writing via SFTP
Raises:	`IOError` on local file IO errors
Raises:	`OSError` on local OS errors like permission denied

sftp_get(sftp, remote_file, local_file)¶

sftp_put(sftp, local_file, remote_file)¶

Perform an SFTP put - copy local file path to remote via SFTP.

Parameters:	sftp (`ssh2.sftp.SFTP`) – SFTP client object. local_file (str) – Local filepath to copy to remote host. remote_file (str) – Remote filepath on remote host to copy file to.
Raises:	`pssh.exceptions.SFTPIOError` on I/O errors writing via SFTP.

spawn_send_keepalive()¶: Spawns a new greenlet that sends keep alive messages every self.keepalive_seconds

wait_finished(host_output, timeout=None)¶

Wait for EOF from channel and close channel.

Used to wait for remote command completion and be able to gather exit code.

Parameters:	host_output (`pssh.output.HostOutput`) – Host output of command to wait for. timeout (float) – Timeout value in seconds - defaults to no timeout.
Raises:	`pssh.exceptions.Timeout` after <timeout> seconds if timeout given.