ParallelSSHClient

class pssh.pssh_client.ParallelSSHClient(hosts, user=None, password=None, port=None, pkey=None, forward_ssh_agent=True, num_retries=3, timeout=120, pool_size=10, proxy_host=None, proxy_port=22, proxy_user=None, proxy_password=None, proxy_pkey=None, agent=None, allow_agent=True, host_config=None, channel_timeout=None, retry_delay=5)

Parallel SSH client using paramiko based SSH client

Parameters:
  • hosts (list(str)) – Hosts to connect to
  • user (str) – (Optional) User to login as. Defaults to logged in user or user from ~/.ssh/config or /etc/ssh/ssh_config if set
  • password (str) – (Optional) Password to use for login. Defaults to no password
  • port (int) – (Optional) Port number to use for SSH connection. Defaults to None which uses SSH default
  • pkey (paramiko.pkey.PKey) – (Optional) Client’s private key to be used to connect with
  • num_retries (int) – (Optional) Number of retries for connection attempts before the client gives up. Defaults to 3.
  • retry_delay (int) – Number of seconds to wait between retries. Defaults to pssh.constants.RETRY_DELAY
  • timeout (int) – (Optional) Number of seconds to wait before connection and authentication attempt times out. Note that total time before timeout will be timeout * num_retries + (5 * (num_retries-1)) number of seconds, where (5 * (num_retries-1)) refers to a five (5) second delay between retries.
  • forward_ssh_agent (bool) – (Optional) Turn on/off SSH agent forwarding - equivalent to ssh -A from the ssh command line utility. Defaults to True if not set.
  • pool_size (int) – (Optional) Greenlet pool size. Controls on how many hosts to execute tasks in parallel. Defaults to 10. Overhead in event loop will determine how high this can be set to, see scaling guide lines in project’s readme.
  • proxy_host (str) – (Optional) SSH host to tunnel connection through so that SSH clients connect to host via client -> proxy_host -> host
  • proxy_port (int) – (Optional) SSH port to use to login to proxy host if set. Defaults to 22.
  • proxy_user (str) – (Optional) User to login to proxy_host as. Defaults to logged in user.
  • proxy_password (str) – (Optional) Password to login to proxy_host with. Defaults to no password
  • proxy_pkey (paramiko.pkey.PKey) – (Optional) Private key to be used for authentication with proxy_host. Defaults to available keys from SSHAgent and user’s home directory keys
  • agent (pssh.agent.SSHAgent) – (Optional) SSH agent object to programmatically supply an agent to override system SSH agent with
  • host_config (dict) – (Optional) Per-host configuration for cases where not all hosts use the same configuration values.
  • channel_timeout (int) – (Optional) Time in seconds before reading from an SSH channel times out. For example with channel timeout set to one, trying to immediately gather output from a command producing no output for more than one second will timeout.
  • allow_agent (bool) – (Optional) set to False to disable connecting to the system’s SSH agent
finished(output)

Check if commands have finished without blocking

Parameters:output – As returned by pssh.pssh_client.ParallelSSHClient.get_output()
Return type:bool
get_output(cmd, output, encoding='utf-8')

Get output from command greenlet.

output parameter is modified in-place.

Parameters:
Return type:

None

join(output, consume_output=False)

Block until all remote commands in output have finished and retrieve exit codes

Parameters:
  • output (dict as returned by pssh.pssh_client.ParallelSSHClient.get_output()) – Output of commands to join on
  • consume_output (bool) – Whether or not join should consume output buffers. Output buffers will be empty after join if set to True. Must be set to True to allow host logger to log output on call to join.
run_command(command, sudo=False, user=None, stop_on_errors=True, shell=None, use_shell=True, use_pty=True, host_args=None, encoding='utf-8', **paramiko_kwargs)

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

This function will block until all commands have been sent to remote servers and then return immediately

More explicitly, function will return after connection and authentication establishment and after commands have been sent to 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 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_shell (bool) – (Optional) Run command with or without shell. Defaults to True - use shell defined in user login to run command string
  • use_pty (bool) – (Optional) Enable/Disable use of pseudo terminal emulation. Disabling it will prohibit capturing standard input/output. This is required in majority of cases, exceptions being where a shell is not used and/or input/output is not required. In particular when running a command which deliberately closes input/output pipes, such as a daemon process, you may want to disable use_pty. Defaults to True
  • 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.HostArgumentException is raised otherwise
  • encoding (str) – Encoding to use for output. Must be valid Python codec
  • paramiko_kwargs (dict) – (Optional) Extra keyword arguments to be passed on to paramiko.client.SSHClient.connect()
Return type:

Dictionary with host as key and pssh.output.HostOutput as value as per pssh.pssh_client.ParallelSSHClient.get_output()

Raises:

pssh.exceptions.AuthenticationException on authentication error

Raises:

pssh.exceptions.UnknownHostException on DNS resolution error

Raises:

pssh.exceptions.ConnectionErrorException on error connecting

Raises:

pssh.exceptions.SSHException on other undefined SSH errors

Raises:

pssh.exceptions.HostArgumentException 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