ssh-python Single Host Client

Single host non-blocking client based on ssh-python (libssh). Suitable for running asynchronous commands on a single host.

class pssh.clients.ssh.single.SSHClient(host, user=None, password=None, port=None, pkey=None, alias=None, cert_file=None, num_retries=3, retry_delay=5, allow_agent=True, timeout=None, identity_auth=True, gssapi_auth=False, gssapi_server_identity=None, gssapi_client_identity=None, gssapi_delegate_credentials=False, ipv6_only=False, _auth_thread_pool=True)

ssh-python based non-blocking client.

  • 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)
  • alias (str) – Use an alias for this host.
  • 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.
  • cert_file (str) – Public key signed certificate file to use for authentication. The corresponding private key must also be provided via pkey parameter. For example pkey='id_rsa',cert_file='' for RSA signed certificate. Path must be absolute or relative to user home directory.
  • 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) – (Optional) If provided, all commands will timeout after <timeout> number of seconds.
  • allow_agent (bool) – (Optional) set to False to disable connecting to the system’s SSH agent. Currently unused.
  • identity_auth (bool) – (Optional) set to False to disable attempting to authenticate with default identity files from pssh.clients.base_ssh_client.BaseSSHClient.IDENTITIES
  • gssapi_server_identity (str) – Enable GSS-API authentication. Uses GSS-MIC key exchange. Enabled if either gssapi_server_identity or gssapi_client_identity are provided.
  • gssapi_server_identity – Set GSSAPI server identity.
  • gssapi_client_identity (str) – Set GSSAPI client identity.
  • gssapi_delegate_credentials (bool) – Enable/disable server credentials delegation.
  • 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.

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


Close channel.

Parameters:channel ( – The channel to close.

Close socket if needed.

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

Execute command on remote host.

  • cmd (str) – The command string to execute.
  • use_pty (bool) – Whether or not to request a PTY on the channel executing command.
  • channel ( – Channel to use. New channel is created if not provided.

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

Return type:bool

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

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

Open new channel from session.


ssh-python based co-operative gevent poll on session socket. :param timeout: Deprecated and unused - to be removed.

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.

  • host_output (pssh.output.HostOutput) – Host output of command to wait for.
  • timeout (float) – Timeout value in seconds - defaults to no timeout.

pssh.exceptions.Timeout after <timeout> seconds if timeout set.