ssh-python Parallel Client

API documentation for the ssh-python (libssh) based parallel client.

class pssh.clients.ssh.parallel.ParallelSSHClient(hosts, user=None, password=None, port=22, pkey=None, cert_file=None, num_retries=3, timeout=None, pool_size=100, allow_agent=True, host_config=None, retry_delay=5, forward_ssh_agent=False, gssapi_auth=False, gssapi_server_identity=None, gssapi_client_identity=None, gssapi_delegate_credentials=False, identity_auth=True, ipv6_only=False, compress=False)

ssh-python based parallel client.

Parameters:

  • hosts (list(str)) – Hosts to connect to

  • user (str) – (Optional) User to login as. Defaults to logged in user

  • password (str) – (Optional) Password to use for login. Defaults to no password

  • port (int) – (Optional) Port number to use for SSH connection. Defaults to 22.

  • pkey (str or bytes) – Private key file path to use. 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='id_rsa-cert.pub' 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) Individual SSH client timeout setting in seconds passed on to each SSH client spawned by ParallelSSHClient.

    This controls timeout setting of socket operations used for SSH sessions on a per session basis meaning for each individual SSH session.

    Defaults to OS default - usually 60 seconds.

    Parallel functions like run_command and join have a cummulative timeout setting that is separate to and not affected by self.timeout.

  • pool_size (int) – (Optional) Greenlet pool size. Controls concurrency, on how many hosts to execute tasks in parallel. Defaults to 100. Overhead in event loop will determine how high this can be set to, see scaling guide lines in project’s readme.

  • host_config (list(pssh.config.HostConfig)) – (Optional) Per-host configuration for cases where not all hosts use the same configuration.

  • allow_agent (bool) – (Optional) set to False to disable connecting to the system’s SSH agent. Currently unused - always off.

  • identity_auth (bool) – (Optional) set to False to disable attempting to authenticate with default identity files from pssh.clients.base_ssh_client.BaseSSHClient.IDENTITIES

  • forward_ssh_agent (bool) – (Optional) Turn on SSH agent forwarding - equivalent to ssh -A from the ssh command line utility. Defaults to False if not set. Currently unused meaning always off.

  • gssapi_server_identity (str) – Set GSSAPI server identity.

  • gssapi_server_identity – 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.

  • compress (bool) – Enable/Disable compression on the client. Defaults to off.

Raises:

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

run_command(command, sudo=False, user=None, stop_on_errors=True, use_pty=False, host_args=None, shell=None, encoding='utf-8', read_timeout=None)

Run command on all hosts in parallel, honoring self.pool_size, and return output.

This function will block until all commands have been received by remote servers and then return immediately.

More explicitly, function will return after connection and authentication establishment in the case of on new connections and after execute commands have been accepted by successfully established SSH channels.

Any connection and/or authentication exceptions will be raised here and need catching unless run_command is called with stop_on_errors=False in which case exceptions are added to individual host output instead.

Parameters:

  • command (str) – Command to run

  • sudo (bool) – (Optional) Run with sudo. Defaults to False

  • user (str) – (Optional) User to run command as. Requires sudo access for that user from the logged in user account.

  • stop_on_errors (bool) – (Optional) Raise exception on errors running command. Defaults to True. With stop_on_errors set to False, exceptions are instead added to output of run_command. See example usage below.

  • shell (str) – (Optional) Override shell to use to run command with. Defaults to login user’s defined shell. Use the shell’s command syntax, eg shell=’bash -c’ or shell=’zsh -c’.

  • use_pty (bool) – (Optional) Enable/Disable use of pseudo terminal emulation. Defaults to False

  • host_args (tuple or list) – (Optional) Format command string with per-host arguments in host_args. host_args length must equal length of host list - pssh.exceptions.HostArgumentError is raised otherwise

  • encoding (str) – Encoding to use for command string and output. Must be valid Python codec

  • read_timeout (float) – (Optional) Timeout in seconds for reading from stdout or stderr. Defaults to self.timeout. Reading from stdout/stderr will raise pssh.exceptions.Timeout after timeout number seconds if remote output is not ready.

Return type:

list(pssh.output.HostOutput)

Raises:

pssh.exceptions.AuthenticationError on authentication error

Raises:

pssh.exceptions.UnknownHostError on DNS resolution error

Raises:

pssh.exceptions.ConnectionError on error connecting

Raises:

pssh.exceptions.HostArgumentError on number of host arguments not equal to number of hosts

Raises:

TypeError on not enough host arguments for cmd string format

Raises:

KeyError on no host argument key in arguments dict for cmd string format

Raises:

pssh.exceptions.ProxyError on errors connecting to proxy if a proxy host has been set.

Raises:

pssh.exceptions.Timeout on timeout starting command.

Raises:

Exceptions from ssh.exceptions for all other specific errors.