ssh-python based Parallel Client¶
API documentation for the
libssh) based parallel client.
ParallelSSHClient(hosts, user=None, password=None, port=22, pkey=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)¶
ssh-python based parallel client.
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) – Private key file path to use. Path must be either absolute path or relative to user home directory like
num_retries (int) – (Optional) Number of connection and authentication attempts before the client gives up. Defaults to 3.
retry_delay (int) – Number of seconds to wait between retries. Defaults to
timeout (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 (dict) – (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
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_hostas. Defaults to logged in user.
proxy_password (str) – (Optional) Password to login to
proxy_hostwith. Defaults to no password.
proxy_pkey (Private key file path to use.) – (Optional) Private key file to be used for authentication with
proxy_host. Defaults to available keys from SSHAgent and user’s SSH 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.
pssh.exceptions.PKeyFileErroron 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', timeout=None, greenlet_timeout=None, return_list=False)¶
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_commandis called with
stop_on_errors=Falsein which case exceptions are added to individual host output instead.
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
host_args (tuple or list) – (Optional) Format command string with per-host arguments in
host_argslength must equal length of host list -
pssh.exceptions.HostArgumentExceptionis raised otherwise
timeout (int) – (Optional) Timeout in seconds for reading from stdout or stderr. Defaults to no timeout. Reading from stdout/stderr will raise
timeoutnumber seconds if remote output is not ready.
greenlet_timeout (float) –
(Optional) Greenlet timeout setting. Defaults to no timeout. If set, this function will raise
greenlet_timeoutseconds if no result is available from greenlets.
In some cases, such as when using proxy hosts, connection timeout is controlled by proxy server and getting result from greenlets may hang indefinitely if remote server is unavailable.
Use this setting to avoid blocking in such circumstances. Note that
gevent.Timeoutis a special class that inherits from
BaseExceptionand thus can not be caught by
- Return type
Dictionary with host as key and
pssh.output.HostOutputas value as per
pssh.exceptions.AuthenticationExceptionon authentication error
pssh.exceptions.UnknownHostExceptionon DNS resolution error
pssh.exceptions.ConnectionErrorExceptionon error connecting
pssh.exceptions.HostArgumentExceptionon number of host arguments not equal to number of hosts
TypeErroron not enough host arguments for cmd string format
KeyErroron no host argument key in arguments dict for cmd string format
pssh.exceptions.ProxyErroron errors connecting to proxy if a proxy host has been set.
gevent.Timeouton greenlet timeout. Gevent timeout can not be caught by
ssh2.exceptionsfor all other specific errors such as