Base Parallel Client¶
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=100, host_config=None, retry_delay=5, identity_auth=True, ipv6_only=False, proxy_host=None, proxy_port=None, proxy_user=None, proxy_password=None, proxy_pkey=None, keepalive_seconds=None, cert_file=None, gssapi_auth=False, gssapi_server_identity=None, gssapi_client_identity=None, gssapi_delegate_credentials=False, forward_ssh_agent=False, _auth_thread_pool=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
orcopy_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 withraise_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 commandsRaises: ValueError
when a directory is supplied to local_file and recurse is not setRaises: pssh.exceptions.HostArgumentError
on number of per-host copy arguments not equal to number of hostsRaises: IOError
on I/O errors writing filesRaises: OSError
on OS errors like permission deniedNote
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 ofmyfile
and default separator_
the resulting filename will bemyfile_myhost
for the file from hostmyhost
.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 withraise_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 alocal_file
value ofmyfile
and default separator the resulting filename will bemyfile_myhost
for the file from hostmyhost
.suffix_separator
has no meaning ifcopy_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 commandsRaises: ValueError
when a directory is supplied to local_file and recurse is not setRaises: pssh.exceptions.HostArgumentError
on number of per-host copy arguments not equal to number of hostsRaises: IOError
on I/O errors writing filesRaises: OSError
on OS errors like permission deniedNote
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
.
-
disconnect
()¶ Disconnect all clients.
-
finished
(output=None)¶ Check if commands have finished without blocking.
Parameters: output (list( HostOutput
)) – (Optional) Output to check if finished. Defaults toget_last_output
Return type: bool
-
get_last_output
(cmds=None)¶ Get output for last commands executed by
run_command
.Parameters: cmds (list( gevent.Greenlet
)) – Commands to get output for. Defaults toclient.cmds
Return type: list( pssh.output.HostOutput
)
-
join
(output=None, consume_output=False, timeout=None)¶ 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 toTrue
. Must be set toTrue
to allow host logger to log output on call tojoin
when host logger has been enabled. - timeout (float) – Timeout in seconds if all remote commands are not yet 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.
Raises: pssh.exceptions.Timeout
on timeout requested and reached with commands still running.Return type: None
-
join_shells
(shells, timeout=None)¶ Wait for running commands to complete and close shells.
Parameters: - shells (list(
pssh.clients.base.single.InteractiveShell
)) – Shells to join on. - timeout (float) – Seconds before waiting for shell commands to finish times out. Defaults to self.timeout if not provided.
Raises: pssh.exceptions.Timeout
on timeout requested and reached with commands still running.- shells (list(
-
open_shell
(encoding='utf-8', read_timeout=None)¶ Open interactive shells on all hosts.
Parameters: Returns: Opened shells for each of self.hosts, in order.
Return type: list(
pssh.clients.native.base.single.InteractiveShell
)
-
run_command
(command, user=None, stop_on_errors=True, host_args=None, use_pty=False, shell=None, encoding='utf-8', *args, **kwargs)¶
-
run_shell_commands
(shells, commands)¶ Run command(s) on shells.
Parameters: - shells (list(
pssh.clients.base.single.InteractiveShell
)) – Shells to run on. - commands (list or str) – Commands to run.
- shells (list(
-
hosts
¶
-