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, 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.
  • 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, timeout=None)
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
  • 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
  • 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)
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.