Native Single Host Client

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

class pssh.clients.native.single.KeepAlive(sock, session)

Class for handling SSHClient keepalive functionality.

Spawns a greenlet in its own pool for sending keepalives to a given session.

Parameters:
eagain(func, *args, **kwargs)
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.

session
sock
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 for each individual SSH operation. Also currently sets socket as well as per function timeout in some cases, see function descriptions.

  • 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)

Close given channel, handling EAGAIN.

configure_keepalive()

Configures keepalive on the server for self.keepalive_seconds.

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

eagain(func, *args, **kwargs)

Handle EAGAIN and call given function with any args, polling for as long as there is data to receive.

eagain_write(write_func, data)

Write data with given write_func for an ssh2-python session while handling EAGAIN and resuming writes from last written byte on each call to write_func.

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.

Return type:

ssh2.channel.Channel

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.

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.

sock