BaseParallelSSHClient

API documentation for common parallel client functionality.

This class is abstract and contains functions that need to be implemented for each underlying SSH library.

Abstract parallel SSH client package

class pssh.clients.base.parallel.BaseParallelSSHClient(hosts, user=None, password=None, port=None, pkey=None, allow_agent=True, num_retries=3, timeout=120, pool_size=10, host_config=None, retry_delay=5, identity_auth=True)

Parallel client base class.

connect_auth()

Connect to and authenticate with all hosts in parallel.

This function can be used to perform connection and authentication outside of command functions like run_command or copy_file so the two operations, login and running a remote command, can be separated.

It is not required to be called prior to any other functions.

Connections and authentication is performed in parallel by this and all other functions.

Returns

list of greenlets to joinall with.

Return type

list(gevent.greenlet.Greenlet)

copy_file(local_file, remote_file, recurse=False, copy_args=None)

Copy local file to remote file in parallel

This function returns a list of greenlets which can be join-ed on to wait for completion.

gevent.joinall() function may be used to join on all greenlets and will also raise exceptions from them if called with raise_error=True - default is False.

Alternatively call .get on each greenlet to raise any exceptions from it.

Exceptions listed here are raised when either gevent.joinall(<greenlets>, raise_error=True) is called or .get is called on each greenlet, not this function itself.

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.

  • copy_args (tuple or list) – (Optional) format local_file and remote_file strings with per-host arguments in copy_args. copy_args length must equal length of host list - pssh.exceptions.HostArgumentError is raised otherwise

Return type

List(gevent.Greenlet) of greenlets for remote copy commands

Raises

ValueError when a directory is supplied to local_file and recurse is not set

Raises

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

Raises

IOError on I/O errors writing files

Raises

OSError on OS errors like permission denied

Note

Remote directories in remote_file that do not exist will be created as long as permissions allow.

copy_remote_file(remote_file, local_file, recurse=False, suffix_separator='_', copy_args=None, **kwargs)

Copy remote file(s) in parallel as <local_file><suffix_separator><host>

With a local_file value of myfile and default separator _ the resulting filename will be myfile_myhost for the file from host myhost.

This function, like ParallelSSHClient.copy_file(), returns a list of greenlets which can be join-ed on to wait for completion.

gevent.joinall() function may be used to join on all greenlets and will also raise exceptions if called with raise_error=True - default is False.

Alternatively call .get on each greenlet to raise any exceptions from it.

Exceptions listed here are raised when either gevent.joinall(<greenlets>, raise_error=True) is called or .get is called on each greenlet, not this function itself.

Parameters
  • remote_file (str) – remote filepath to copy to local host

  • local_file (str) – local filepath on local host to copy file to

  • recurse (bool) – whether or not to recurse

  • suffix_separator (str) – (Optional) Separator string between filename and host, defaults to _. For example, for a local_file value of myfile and default separator the resulting filename will be myfile_myhost for the file from host myhost. suffix_separator has no meaning if copy_args is provided

  • copy_args (tuple or list) – (Optional) Format remote_file and local_file strings with per-host arguments in copy_args. copy_args length must equal length of host list - pssh.exceptions.HostArgumentError is raised otherwise

Return type

list(gevent.Greenlet) of greenlets for remote copy commands

Raises

ValueError when a directory is supplied to local_file and recurse is not set

Raises

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

Raises

IOError on I/O errors writing files

Raises

OSError on OS errors like permission denied

Note

Local directories in local_file that do not exist will be created as long as permissions allow.

Note

File names will be de-duplicated by appending the hostname to the filepath separated by suffix_separator.

finished(output)

Check if commands have finished without blocking

Parameters

output – As returned by pssh.pssh_client.ParallelSSHClient.get_output()

Return type

bool

get_last_output(cmds=None, timeout=None, return_list=True)

Get output for last commands executed by run_command

Parameters
  • cmds (list(gevent.Greenlet)) – Commands to get output for. Defaults to client.cmds

  • greenlet_timeout (float) – (Optional) Greenlet timeout setting. Defaults to no timeout. If set, this function will raise gevent.Timeout after greenlet_timeout seconds 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.Timeout is a special class that inherits from BaseException and thus can not be caught by stop_on_errors=False.

  • return_list (bool) – No-op - list of HostOutput always returned. Parameter kept for backwards compatibility - to be removed in future releases.

Return type

dict or list

join(output, consume_output=False, timeout=None, encoding='utf-8')

Wait until all remote commands in output have finished. Does not block other commands from running in parallel.

Parameters
  • output (HostOutput objects) – 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 when host logger has been enabled.

  • timeout (int) – Timeout in seconds if all remote commands are not yet finished. Note that use of timeout forces consume_output=True otherwise the channel output pending to be consumed always results in the channel not being finished. This function’s timeout is for all commands in total and will therefor be affected by pool size and total number of concurrent commands in self.pool. Since self.timeout is passed onto each individual SSH session it is not used for any parallel functions like run_command or join.

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

Raises

pssh.exceptions.Timeout on timeout requested and reached with commands still running.

Return type

None

reset_output_generators(host_out, timeout=None, client=None, channel=None, encoding='utf-8')

Reset output generators for host output.

Parameters
  • host_out (pssh.output.HostOutput) – Host output

  • client (pssh.ssh2_client.SSHClient) – (Optional) SSH client

  • channel (ssh2.channel.Channel) – (Optional) SSH channel

  • timeout (int) – (Optional) Timeout setting

  • encoding (str) –

    (Optional) Encoding to use for output. Must be valid Python codec

Return type

tuple(stdout, stderr)

run_command(command, user=None, stop_on_errors=True, host_args=None, use_pty=False, shell=None, encoding='utf-8', return_list=True, *args, **kwargs)