parallel-ssh documentation · 2019. 4. 2. · parallel-ssh documentation, release 1.9.1+1.gcf2b65e...

Parallel-SSH DocumentationRelease 0+unknown

P Kittenis

Jan 28, 2021

CONTENTS

1 In a nutshell 3

2 Single Host Client 52.1 Design And Goals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52.2 Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62.3 Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.4 Advanced Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.5 API Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 262.6 Clients Feature Comparison . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 502.7 Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.8 Comparison With Alternatives . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512.9 Change Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532.10 Upgrading to API 2.0 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662.11 Indices and tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67

Python Module Index 69

Index 71

i

Parallel-SSH Documentation, Release 0+unknown

parallel-ssh is a non-blocking parallel SSH client library.

It provides clients based on C libraries with an easy to use Python API providing native code levels of performanceand stability.

CONTENTS 1

https://pypi.python.org/pypi/parallel-ssh

https://circleci.com/gh/ParallelSSH/parallel-ssh

https://codecov.io/gh/ParallelSSH/parallel-ssh

https://pypi.python.org/pypi/parallel-ssh

http://parallel-ssh.readthedocs.org/en/latest/


2 CONTENTS

CHAPTER

ONE

IN A NUTSHELL

Client will attempt to use all available keys under ~/.ssh as well as any keys in an SSH agent, if one is available.

from pssh.clients import ParallelSSHClient

client = ParallelSSHClient(['localhost', 'localhost'])output = client.run_command('uname')for host_out in output:

for line in host_out.stdout:print(line)

exit_code = host_out.exit_code

Output

<Uname output><Uname output>

3


4 Chapter 1. In a nutshell

CHAPTER

TWO

SINGLE HOST CLIENT

Single host client is also available with similar API.

from pssh.clients import SSHClient

client = SSHClient('localhost')host_out = client.run_command('uname')for line in host_out.stdout:

print(line)exit_code = host_out.exit_code

Output

<Uname output>

2.1 Design And Goals

parallel-ssh’s design goals and motivation are to provide a library for running asynchronous SSH commands inparallel with little to no load induced on the system by doing so with the intended usage being completely program-matic and non-interactive.

To meet these goals, API driven solutions are preferred first and foremost. This frees up the developer to drive thelibrary via any method desired, be that environment variables, CI driven tasks, command line tools, existing OpenSSHor new configuration files, from within an application et al.

2.1.1 Design Principles

Taking a cue from PEP 20, heavy emphasis is in the following areas.

• Readability

• Explicit is better than implicit

• Simple is better than complex

• Beautiful is better than ugly

Contributions are asked to keep these in mind.

In addition, a heavy emphasis is also given to test driven development. The library is continuously integration testedwith a real SSH server (OpenSSH) and has very high code test coverage.

5

https://www.python.org/dev/peps/pep-0020/


2.2 Installation

Installation is handled by Python’s standard setuptools library and pip.

2.2.1 Pip Install

pip may need to be updated to be able to install binary wheel packages.

pip install -U pip

pip install parallel-ssh

If pip is not available on your Python platform, see this installation guide.

2.2.2 From Source Dependencies

When installing from source, dependencies must be satisfied by pip install -r requirements.txt or bysystem packages.

For binary packages, see Pip Install.

Dependency Minimum Versionssh2-python per requirements.txtssh-python per requirements.txtgevent per requirements.txt

2.2.3 Building from Source

parallel-ssh is hosted on GitHub and the repository can be cloned with the following

git clone [email protected]:ParallelSSH/parallel-ssh.gitcd parallel-ssh

To install from source run:

pip install .

Or for developing changes:

pip install -r requirements_dev.txt

2.2.4 Python 2

As of January 1st 2021, Python 2 is no longer supported by the Python Software Foundation nor parallel-ssh -see Sunset Python 2.

Versions of parallel-ssh<=2.4.0 will still work.

Future releases are not guaranteed to be compatible or work at all with Python 2.

Versions >=2.5.0 may still work, no code changes have yet been made to stop Python 2 from working, though nosupport is offered if they do not.

6 Chapter 2. Single Host Client

http://docs.python-guide.org/en/latest/starting/installation/

https://www.python.org/doc/sunset-python-2/


Vendors that distribute this package for Python 2 are advised to run integration tests themselves on versions >=2.5.0to confirm compatibility - no automated testing is performed on Python 2 by this project.

If your company requires Python 2 support contact the author directly at the email address on Github commits todiscuss rates.

2.3 Quickstart

First, make sure that parallel-ssh is installed.

2.3.1 Run a command on hosts in parallel

The most basic usage of parallel-ssh is, unsurprisingly, to run a command on multiple hosts in parallel.

A complete example is shown below.

Examples all assume a valid key is available on a running SSH agent. See Programmatic Private Key Authenticationfor authenticating without an SSH agent.

Complete Example

Host list can contain identical hosts. Commands are executed concurrently on every host given to the client regardless,up to pool size.


hosts = ['localhost', 'localhost', 'localhost', 'localhost']client = ParallelSSHClient(hosts)cmd = 'uname'

output = client.run_command(cmd)for host_out in output:


Output:

LinuxLinuxLinuxLinux

2.3.2 Single Host Client

parallel-ssh has a fully featured, asynchronous single host client that it uses for all its parallel commands.

Users that do not need the parallel capabilities can use the single host client for a simpler way to run asynchronousnon-blocking commands on a remote host.


host = 'localhost'cmd = 'uname'

(continues on next page)

2.3. Quickstart 7

installation.html

quickstart.html#pkey-auth


(continued from previous page)

client = SSHClient(host)

host_out = client.run_command(cmd)for line in host_out.stdout:

print(line)

Output::

Linux

2.3.3 Step by Step

Make a list or other iterable of the hosts to run on:


hosts = ['host1', 'host2', 'host3', 'host4']

Where host1 to host4 are valid host names. IP addresses may also be used.

Create a client for these hosts:

client = ParallelSSHClient(hosts)

The client object can, and should, be reused. Existing connections to hosts will remain alive as long as the client objectis kept alive. Subsequent commands to the same host(s) will reuse their existing connection and benefit from muchfaster response times.

Now one or more commands can be run via the client:

output = client.run_command('uname')

When the call to run_command returns, the remote commands are already executing in parallel.

2.3.4 Run Command Output

Standard Output

Standard output, aka stdout, for a given HostOutput object.


Output

<line by line output><line by line output><..>

Iterating over stdout will only end when the remote command has finished unless interrupted.

The read_timeout keyword argument to run_command may be used to cause reading to timeout if no output isreceived after the given number of seconds - see join and output timeouts.

stdout is a generator. To retrieve all of stdout can wrap it with list, per below.


advanced.html#join-and-output-timeouts


stdout = list(host_out.stdout)

All hosts iteration

Of course, iterating over all hosts can also be done the same way.

for host_output in output:for line in host_output.stdout:

print("Host [%s] - %s" % (host, line))

Complete Example


client = ParallelSSHClient(['localhost', 'localhost'])output = client.run_command('whoami')client.join()

for host_output in output:hostname = host_output.hoststdout = list(host_output.stdout)print("Host %s: exit code %s, output %s" % (

hostname, host_output.exit_code, stdout))

Output

localhost: exit code 0, stdout ['<username>']localhost: exit code 0, stdout ['<username>']

New in 1.10.0

2.3.5 Exit codes

Exit codes are available on the host output object as a dynamic property. Exit code will be None if not available, orthe exit code as reported by channel.

First, ensure that all commands have finished by either joining on the output object or gathering all output, then iterateover all host’s output to print their exit codes.

client.join(output)for host_output in output:

print("Host %s exit code: %s" % (host_output.host, host_output.exit_code))

As of 1.11.0, client.join is not required as long as output has been gathered.

for host_out in output:for line in host_out.stdout:

print(line)print(host_out.exit_code)

See also:

pssh.output.HostOutput Host output class documentation.

2.3. Quickstart 9


2.3.6 Authentication

By default parallel-ssh will use an available SSH agent’s credentials to login to hosts via public key authentica-tion.

User/Password authentication

User/password authentication can be used by providing user name and password credentials:

client = ParallelSSHClient(hosts, user='my_user', password='my_pass')

Note: On Posix platforms, user name defaults to the current user if not provided.

On Windows, user name is required.

Programmatic Private Key authentication

It is also possible to programmatically provide a private key for authentication.


client = ParallelSSHClient(hosts, pkey='my_pkey')

Where my_pkey is a private key file in the current directory.

To use files under a user’s .ssh directory:

client = ParallelSSHClient(hosts, pkey='~/.ssh/my_pkey')

2.3.7 Output for Last Executed Commands

Output for last executed commands can be retrieved by get_last_output:

client.run_command('uname')output = client.get_last_output()for host_output in output:

for line in host_output.stdout:print(line)

This function can also be used to retrieve output for previously executed commands in the case where output objectwas not stored or is no longer available.

New in 1.2.0



2.3.8 Host Logger

There is a built in host logger that can be enabled to automatically log standard output from remote hosts. This requiresthe consume_output=True flag on join.

The helper function pssh.utils.enable_host_logger() will enable host logging to standard output, forexample:

from pssh.utils import enable_host_loggerenable_host_logger()

client.run_command('uname')client.join(consume_output=True)

Output

[localhost] Linux

2.3.9 Using standard input

Along with standard output and error, input is also available on the host output object. It can be used to send input tothe remote host where required, for example password prompts or any other prompt requiring user input.

The stdin attribute on HostOutput is a file-like object giving access to the remote stdin channel that can be writtento:

output = client.run_command('read line; echo $line')host_output = output[0]stdin = host_output.stdinstdin.write("writing to stdin\n")stdin.flush()for line in host_output.stdout:

print(line)

Output

writing to stdin

2.3.10 Errors and Exceptions

By default, parallel-ssh will raise exception on any errors connecting to hosts, whether that be connection errorssuch as DNS resolution failure or unreachable host, SSH authentication failures or any other errors.

Alternatively, the stop_on_errors flag is provided to tell the client to go ahead and attempt the command(s)anyway and return output for all hosts, including the exception on any hosts that failed:

output = client.run_command('whoami', stop_on_errors=False)

With this flag, the exception output attribute will contain the exception on any failed hosts, or None:

client.join(output)for host_output in output:

host = host_output.hostprint("Host %s: exit code %s, exception %s" % (

host, host_output.exit_code, host_output.exception))

2.3. Quickstart 11


Output

Host host1: exit code 0, exception NoneHost host2: exit code None, exception AuthenticationError <..>

See also:

Exceptions raised by the library can be found in the pssh.exceptions module and in API documentation.

2.4 Advanced Usage

There are several more advanced usage features of parallel-ssh, such as tunnelling (aka proxying) via an inter-mediate SSH server and per-host configuration and command substitution among others.

2.4.1 Agents and Private Keys

Programmatic Private Keys

By default, parallel-ssh will attempt to use loaded keys in an available SSH agent as well as default identity filesunder the user’s home directory.

See IDENTITIES in SSHClient for the list of default identity files.

A private key can also be provided programmatically.


client = ParallelSSHClient(hosts, pkey="~/.ssh/my_key")

Where my_key is a private key file under .ssh in the user’s home directory.

2.4.2 Native Clients

ssh2-python (libssh2)

The default client in parallel-ssh is based on ssh2-python (libssh2). It is a native client, offering C level perfor-mance with an easy to use Python API.

See this post for a performance comparison of the available clients in the 1.x.x series.

from pssh.clients import ParallelSSHClient, SSHClient

hosts = ['my_host', 'my_other_host']client = ParallelSSHClient(hosts)

output = client.run_command('uname')for host_out in output:


See also:

Feature comparison for how the 2.x.x client types compare.

API documentation for parallel and single native clients.


https://parallel-ssh.org/post/parallel-ssh-libssh2

clients.html

native_parallel.html

native_single.html


New in 1.2.0

ssh-python (libssh) Client

A set of alternative clients based on libssh via ssh-python are also provided.

The API is similar to the default client, while ssh-python offers more supported authentication methods comparedto the default client, such as certificate and GSS API authentication.

On the other hand, these clients lack SCP, SFTP and proxy functionality.

from pssh.clients.ssh import ParallelSSHClient, SSHClient

hosts = ['localhost', 'localhost']client = ParallelSSHClient(hosts)

output = client.run_command('uname')client.join(output)for host_out in output:


See also:

API documentation for parallel and single ssh-python clients.

New in 1.12.0

GSS-API Authentication - aka Kerberos

GSS authentication allows logins using Windows LDAP configured user accounts via Kerberos on Linux.

from pssh.clients.ssh import ParallelSSHClient

client = ParallelSSHClient(hosts, gssapi_auth=True, gssapi_server_identity='gss_→˓server_id')

output = client.run_command('id')client.join(output)for host_out in output:

for line in output.stdout:print(line)

ssh-python ParallelSSHClient only.

Certificate authentication

In the pssh.clients.ssh clients, certificate authentication is supported.


client = ParallelSSHClient(hosts, pkey='id_rsa', cert_file='id_rsa-cert.pub')

2.4. Advanced Usage 13

https://libssh.org

https://github.com/ParallelSSH/ssh-python


Where id_rsa-cert.pub is an RSA signed certificate file for the id_rsa private key.

Both private key and corresponding signed public certificate file must be provided.

ssh-python ParallelSSHClient only.

2.4.3 Proxy Hosts and Tunneling

This is used in cases where the client does not have direct access to the target host(s) and has to authenticate via anintermediary proxy, also called a bastion host.

Commonly used for additional security as only the proxy host needs to have access to the target host.

Client ——–> Proxy host ——–> Target host

Proxy host can be configured as follows in the simplest case:

hosts = [<..>]client = ParallelSSHClient(hosts, proxy_host='bastion')

For single host clients:

host = '<..>'client = SSHClient(host, proxy_host='proxy')

Configuration for the proxy host’s user name, port, password and private key can also be provided, separate from targethost configuration.

hosts = [<..>]client = ParallelSSHClient(

hosts, user='target_host_user',proxy_host='bastion',proxy_user='my_proxy_user',proxy_port=2222,proxy_pkey='proxy.key')

Where proxy.key is a filename containing private key to use for proxy host authentication.

In the above example, connections to the target hosts are made via SSH through my_proxy_user@bastion:2222-> target_host_user@<host>.

Per Host Proxy Configuration

Proxy host can be configured in Per-Host Configuration:

hosts = [<..>]host_config = [

HostConfig(proxy_host='127.0.0.1'),HostConfig(proxy_host='127.0.0.2'),HostConfig(proxy_host='127.0.0.3'),HostConfig(proxy_host='127.0.0.4'),]

client = ParallelSSHClient(hosts, host_config=host_config)output = client.run_command('echo me')

See HostConfig for all possible configuration.



Note: New tunneling implementation from 2.2.0 for best performance.

Connecting to dozens or more hosts via a single proxy host will impact performance considerably.

See above for using host specific proxy configuration.

2.4.4 Join and Output Timeouts

Clients have timeout functionality on reading output and client.join.

Join timeout is applied to all parallel commands in total and is separate from ParallelSSHClient(timeout=<..>) which is applied to SSH session operations individually.

Timeout exceptions from join contain attributes for which commands have finished and which have not so clientcode can get output from any finished commands when handling timeouts.

from pssh.exceptions import Timeout

output = client.run_command(..)try:

client.join(output, timeout=5)except Timeout:

pass

The client will raise a Timeout exception if all remote commands have not finished within five seconds in the aboveexamples.

output = client.run_command(.., read_timeout=5)for host_out in output:

try:for line in host_out.stdout:

print(line)for line in host_out.stderr:

print(line)except Timeout:

pass

In the case of reading from output such as in the example above, timeout value is per output stream - meaning separatetimeouts for stdout and stderr as well as separate timeout per host output.

New in 1.5.0

Reading Output from Partially Finished Commands

Timeout exception when calling join has finished and unfinished commands as arguments.

This can be used to handle sets of commands that have finished and those that have not separately, for example to onlygather output on finished commands to avoid blocking.

output = client.run_command(..)try:

client.join(output, timeout=5)except Timeout as ex:

# Some commands timed outfinished_output = ex.args[2]





unfinished_output = ex.args[3]else:

# No timeout, all commands finished within five secondsfinished_output = outputunfinished_output = None

for host_out in finished_output:for line in host_out.stdout:

print(line)if unfinished_output is not None:

<handle unfinished output>

In the above example, output is printed only for those commands which have completed within the five second timeout.

Client code may choose to then join again only on the unfinished output if some commands have failed in order togather remaining output.

Reading Partial Output of Commands That Do Not Terminate

In some cases, such as when the remote command never terminates unless interrupted, it is necessary to use PTY andto close the channel to force the process to be terminated before a join sans timeout can complete. For example:

output = client.run_command('while true; do echo a line; sleep .1; done',use_pty=True, read_timeout=1)

# Read as many lines of output as hosts have sent before the timeoutstdout = []for host_out in output:

try:for line in host_out.stdout:

stdout.append(line)except Timeout:

pass

# Closing channel which has PTY has the effect of terminating# any running processes started on that channel.for host_out in output:

host_out.client.close_channel(host_out.channel)# Join is not strictly needed here as channel has already been closed and# command has finished, but is safe to use regardless.client.join(output)# Can now read output up to when the channel was closed without blocking.rest_of_stdout = list(output[0].stdout)

Without a PTY, a join call with a timeout will complete with timeout exception raised but the remote process will beleft running as per SSH protocol specifications.

Note: Read timeout may be changed after run_command has been called by changing HostOutput.read_timeout for that particular host output.

Note: When output from commands is not needed, it is best to use client.join(consume_output=True)so that output buffers are consumed automatically.



If output is not read or automatically consumed by join output buffers will continually grow, resulting in increasingmemory consumption while the client is running, though memory use rises very slowly.

2.4.5 Per-Host Configuration

Sometimes, different hosts require different configuration like user names and passwords, ports and private keys.Capability is provided to supply per host configuration for such cases.

from pssh.config import HostConfig

hosts = ['localhost', 'localhost']host_config = [

HostConfig(port=2222, user='user1',password='pass', private_key='my_pkey.pem'),

HostConfig(port=2223, user='user2',password='pass', private_key='my_other_key.pem'),

]

client = ParallelSSHClient(hosts, host_config=host_config)client.run_command('uname')<..>

In the above example, the client is configured to connect to hostname localhost, port 2222with username user1,password pass and private key file my_pkey.pem and hostname localhost, port 2222 with username user1,password pass and private key file my_other_pkey.pem.

When using host_config, the number of HostConfig entries must match the number of hosts in client.hosts. An exception is raised on client initialisation if not.

As of 2.2.0, proxy configuration can also be provided in HostConfig.

2.4.6 Per-Host Command substitution

For cases where different commands should be run on each host, or the same command with different arguments,functionality exists to provide per-host command arguments for substitution.

The host_args keyword parameter to run_command can be used to provide arguments to use to format thecommand string.

Number of host_args items should be at least as many as number of hosts.

Any Python string format specification characters may be used in command string.

In the following example, first host in hosts list will use cmd host1_cmd second host host2_cmd and so on:

output = client.run_command('%s', host_args=('host1_cmd','host2_cmd','host3_cmd',))

Command can also have multiple arguments to be substituted.

output = client.run_command('%s %s',host_args=(('host1_cmd1', 'host1_cmd2'),

('host2_cmd1', 'host2_cmd2'),('host3_cmd1', 'host3_cmd2'),))



This expands to the following per host commands:

host1: 'host1_cmd1 host1_cmd2'host2: 'host2_cmd1 host2_cmd2'host3: 'host3_cmd1 host3_cmd2'

A list of dictionaries can also be used as host_args for named argument substitution.

In the following example, first host in host list will use cmd echo command-1, second host echo command-2and so on.

host_args = [{'cmd': 'echo command-%s' % (i,)}for i in range(len(client.hosts))]

output = client.run_command('%(cmd)s', host_args=host_args)

This expands to the following per host commands:

host1: 'echo command-0'host2: 'echo command-1'host3: 'echo command-2'

2.4.7 Run command features and options

See run_command API documentation for a complete list of features and options.

Run with sudo

parallel-ssh can be instructed to run its commands under sudo:

client = <..>

output = client.run_command(<..>, sudo=True)client.join(output)

While not best practice and password-less sudo is best configured for a limited set of commands, a sudo passwordmay be provided via the stdin channel:

client = <..>

output = client.run_command(<..>, sudo=True)for host_out in output:

host_out.stdin.write('my_password\n')host_out.stdin.flush()

client.join(output)

Note: Note the inclusion of the new line \n when using sudo with a password.



Run with configurable shell

By default the client will use the login user’s shell to execute commands per the SSH protocol.

Shell to use is configurable:

client = <..>

output = client.run_command(<..>, shell='zsh -c')for host_out in output;


Commands will be run under the zsh shell in the above example. The command string syntax of the shell must beused, typically <shell> -c.

Output And Command Encoding

By default, command string and output are encoded as UTF-8. This can be configured with the encoding keywordargument to run_command and open_shell.

client = ParallelSSHClient(<..>)

cmd = b"echo \xbc".decode('latin-1')output = client.run_command(cmd, encoding='latin-1')stdout = list(output[0].stdout)

Contents of stdout are latin-1 decoded.

cmd string is also latin-1 encoded when running command or writing to interactive shell.

Output encoding can also be changed by adjusting HostOutput.encoding.


output = client.run_command('echo me')output[0].encoding = 'utf-16'stdout = list(output[0].stdout)

Contents of stdout are utf-16 decoded.

Note: Encoding must be valid Python codec

Enabling use of pseudo terminal emulation

Pseudo Terminal Emulation (PTY) can be enabled when running commands, defaults to off.

Enabling it has some side effects on the output and behaviour of commands such as combining stdout and stderr output- see bash man page for more information.

All output, including stderr, is sent to the stdout channel with PTY enabled.

client = <..>

output = client.run_command("echo 'asdf' >&2", use_pty=True)(continues on next page)


https://docs.python.org/3/library/codecs.html



for line in output[0].stdout:print(line)

Note output is from the stdout channel while it was written to stderr.

Output

asdf

Stderr is empty:

for line in output[0].stderr:print(line)

No output from stderr.

2.4.8 SFTP and SCP

SFTP and SCP are both supported by parallel-ssh and functions are provided by the client for copying files toand from remote servers - default native clients only.

Neither SFTP nor SCP have a shell interface and no output is sent for any SFTP/SCP commands.

As such, SFTP functions in ParallelSSHClient return greenlets that will need to be joined to raise any exceptionsfrom them. gevent.joinall() may be used for that.

Copying files to remote hosts in parallel

To copy the local file with relative path ../test to the remote relative path test_dir/test - remote directorywill be created if it does not exist, permissions allowing. raise_error=True instructs joinall to raise anyexceptions thrown by the greenlets.

from pssh.clients import ParallelSSHClientfrom gevent import joinall


cmds = client.copy_file('../test', 'test_dir/test')joinall(cmds, raise_error=True)

To recursively copy directory structures, enable the recurse flag:

cmds = client.copy_file('my_dir', 'my_dir', recurse=True)joinall(cmds, raise_error=True)

See also:

copy_file API documentation and exceptions raised.

gevent.joinall() Gevent’s joinall API documentation.


https://www.gevent.org/api/gevent.html#gevent.joinall



Copying files from remote hosts in parallel

Copying remote files in parallel requires that file names are de-duplicated otherwise they will overwrite each other.copy_remote_file names local files as <local_file><suffix_separator><host>, suffixing each filewith the host name it came from, separated by a configurable character or string.

from pssh.pssh_client import ParallelSSHClientfrom gevent import joinall


cmds = client.copy_remote_file('remote.file', 'local.file')joinall(cmds, raise_error=True)

The above will create files local.file_host1 where host1 is the host name the file was copied from.

Configurable per host Filenames

File name arguments, for both local and remote files and for copying to and from remote hosts, can be configured ona per-host basis similarly to host arguments in run_command.

Example shown applies to all file copy functionality, all of scp_send, scp_recv, copy_file andcopy_remote_file.

For example, to copy the local files ['local_file_1', 'local_file_2'] as remote files['remote_file_1', 'remote_file_2'] on the two hosts ['host1', 'host2']

hosts = ['host1', 'host2']


copy_args = [{'local_file': 'local_file_1','remote_file': 'remote_file_1',},{'local_file': 'local_file_2','remote_file': 'remote_file_2',}]

cmds = client.copy_file('%(local_file)s', '%(remote_file)s',copy_args=copy_args)

joinall(cmds)

The client will copy local_file_1 to host1 as remote_file_1 and local_file_2 to host2 asremote_file_2.

Each item in copy_args list should be a dictionary as shown above. Number of items in copy_args must matchlength of client.hosts if provided or exception will be raised.

copy_remote_file, scp_send and scp_recv may all be used in the same manner to configure remote andlocal file names per host.

See also:

copy_remote_file API documentation and exceptions raised.



Single host copy

If wanting to copy a file from a single remote host and retain the original filename, can use the single host SSHClientand its copy_remote_file directly.


client = SSHClient('localhost')client.copy_remote_file('remote_filename', 'local_filename')client.scp_recv('remote_filename', 'local_filename')

See also:

SSHClient.copy_remote_file API documentation and exceptions raised.

2.4.9 Interactive Shells

Interactive shells can be used to run commands, as an alternative to run_command.

This is best used in cases where wanting to run multiple commands per host on the same channel with combinedoutput.


cmd = """echo meecho me too"""

shells = client.open_shell()client.run_shell_commands(shells, cmd)client.join_shells(shells)

for shell in shells:for line in shell.stdout:

print(line)print(shell.exit_code)

Running Commands On Shells

Command to run can be multi-line, a single command or a list of commands.

Shells provided are used for all commands, reusing the channel opened by open_shell.

Multi-line Commands

Multi-line commands or command string is executed as-is.


cmd = """echo meecho me too"""





shells = client.open_shell()client.run_shell_commands(shells, cmd)

Single And List Of Commands

A single command can be used, as well as a list of commands to run on each shell.

cmd = 'echo me three'client.run_shell_commands(shells, cmd)

cmd = ['echo me also', 'echo and as well me', 'exit 1']client.run_shell_commands(shells, cmd)

Waiting For Completion

Joining shells waits for running commands to complete and closes shells.

This allows output to be read up to the last command executed without blocking.

client.join_shells(shells)

Joined on shells are closed and may not run any further commands.

Trying to use the same shells after join_shells will raise pssh.exceptions.ShellError.

Reading Shell Output

Output for each shell includes all commands executed.

for shell in shells:stdout = list(shell.stdout)exit_code = shell.exit_code

Exit code is for the last executed command only and can be retrieved when run_shell_commands has been usedat least once.

Each shell also has a shell.output which is a HostOutput object. shell.stdout et al are the same asshell.output.stdout.

Reading Partial Shell Output

Reading output will block indefinitely prior to join being called. Use read_timeout in order to read partial output.

shells = client.open_shell(read_timeout=1)client.run_shell_commands(shells, ['echo me'])

# Times out after one secondfor line in shells[0].stdout:

print(line)



Join Timeouts

Timeouts on join_shells can be done similarly to join.

cmds = ["echo me", "sleep 1.2"]

shells = client.open_shell()client.run_shell_commands(shells, cmds)client.join_shells(shells, timeout=1)

Single Clients

On single clients shells can be used as a context manager to join and close the shell on exit.

client = SSHClient(<..>)

cmd = 'echo me'with client.open_shell() as shell:

shell.run(cmd)print(list(shell.stdout))print(shell.exit_code)

Or explicitly:

cmd = 'echo me'shell = client.open_shell()shell.run(cmd)shell.close()

Closing a shell also waits for commands to complete.

See also:

pssh.clients.base.single.InteractiveShell for more documentation.

• open_shell()

• run_shell_commands()

• join_shells()

2.4.10 Hosts filtering and overriding

Iterators and filtering

Any type of iterator may be used as hosts list, including generator and list comprehension expressions.

List comprehension

hosts = ['dc1.myhost1', 'dc2.myhost2']client = ParallelSSHClient([h for h in hosts if h.find('dc1')])

Generator

hosts = ['dc1.myhost1', 'dc2.myhost2']client = ParallelSSHClient((h for h in hosts if h.find('dc1')))



Filter

hosts = ['dc1.myhost1', 'dc2.myhost2']client = ParallelSSHClient(filter(lambda h: h.find('dc1'), hosts))client.run_command(<..>)

Note: Assigning a generator to host list is possible as shown above, and the generator is consumed into a list onassignment.

Multiple calls to run_command will use the same hosts read from the provided generator.

Overriding hosts list

Hosts list can be modified in place.

A call to run_command will create new connections as necessary and output will only be returned for the hostsrun_command executed on.

Clients for hosts that are no longer on the host list are removed on host list assignment. Reading output from hostsremoved from host list is feasible, as long as their output objects or interactive shells are in scope.

client = <..>

client.hosts = ['otherhost']print(client.run_command('exit 0'))

<..>host='otherhost'exit_code=None<..>

When reassigning host list frequently, it is best to sort or otherwise ensure order is maintained to avoid reconnectionson hosts that are still in the host list but in a different position.

For example, the following will cause reconnections on both hosts, though both are still in the list.

client.hosts = ['host1', 'host2']client.hosts = ['host2', 'host1']

In such cases it would be best to maintain order to avoid reconnections. This is also true when adding or removinghosts in host list.

No change in clients occurs in the following case.

client.hosts = sorted(['host1', 'host2'])client.hosts = sorted(['host2', 'host1'])

Clients for hosts that would be removed by a reassignment can be calculated with:

set(enumerate(client.hosts)).difference(set(enumerate(new_hosts)))



2.5 API Documentation

2.5.1 Native Parallel Client

API documentation for the ssh2-python (libssh2) based parallel client.

class pssh.clients.native.parallel.ParallelSSHClient(hosts, user=None, pass-word=None, port=22,pkey=None, num_retries=3,timeout=None, pool_size=100,allow_agent=True,host_config=None,retry_delay=5,proxy_host=None,proxy_port=None,proxy_user=None,proxy_password=None,proxy_pkey=None, for-ward_ssh_agent=False,tunnel_timeout=None,keepalive_seconds=60, iden-tity_auth=True)

ssh2-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) – Private key file path to use. Path must be either absolute path or relative touser home directory like ~/<path>.

• num_retries (int) – (Optional) Number of connection and authentication attempts be-fore the client gives up. Defaults to 3.

• retry_delay (int) – Number of seconds to wait between retries. Defaults to pssh.constants.RETRY_DELAY

• timeout (float) – (Optional) Global timeout setting in seconds for all remote operationsincluding all SSH client operations DNS, opening connections, reading output from remoteservers, et al.

For concurrent functions this is a cumulative timeout setting for all concurrent operations.These functions, eg run_command and join, also allow timeout to be set just for thosefunctions if not set globally via this option.

For per host operations like list(host_out.stdout) for reading output it is appliedper host if set. Host output read timeout can also be set separately via run_command(<..>, read_timeout=<seconds>) Defaults to OS default - usually 60 seconds.

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


https://docs.python.org/2/library/functions.html#str



https://docs.python.org/2/library/functions.html#int




https://docs.python.org/2/library/functions.html#float



• host_config (dict) – (Optional) Per-host configuration for cases where not all hostsuse the same configuration.

• allow_agent (bool) – (Optional) set to False to disable connecting to the system’s SSHagent.

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

• proxy_host (str) – (Optional) SSH host to tunnel connection through so that SSHclients connect to host via client -> proxy_host -> host

• proxy_port (int) – (Optional) SSH port to use to login to proxy host if set. Defaults to22.

• proxy_user (str) – (Optional) User to login to proxy_host as. Defaults to logged inuser.

• proxy_password (str) – (Optional) Password to login to proxy_hostwith. Defaultsto no password.

• proxy_pkey (str) – (Optional) Private key file to be used for authentication withproxy_host. Defaults to available keys from SSHAgent and user’s SSH identities.

• forward_ssh_agent (bool) – (Optional) Turn on SSH agent forwarding - equivalentto ssh -A from the ssh command line utility. Defaults to False if not set. Requires agentforwarding implementation in libssh2 version used.

• tunnel_timeout – No-op - to be removed.

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

copy_file(local_file, remote_file, recurse=False, copy_args=None)Copy local file to remote file in parallel via SFTP.

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 fromthem 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) or .get() on each greenlet are called, 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 stringswith per-host arguments in copy_args. copy_args length must equal length of hostlist - 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 argumentsnot equal to number of hosts

Raises pss.exceptions.SFTPError on SFTP initialisation errors

2.5. API Documentation 27

https://docs.python.org/2/library/stdtypes.html#dict

https://docs.python.org/2/library/functions.html#bool












https://www.gevent.org/api/gevent.greenlet.html#gevent.Greenlet


Raises pssh.exceptions.SFTPIOError on I/O errors writing via SFTP

Raises OSError on local OS errors like permission denied

Note: Remote directories in remote_file that do not exist will be created as long as permissionsallow.

copy_remote_file(remote_file, local_file, recurse=False, suffix_separator='_', copy_args=None,encoding='utf-8')

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

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

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

gevent.joinall() function may be used to join on all greenlets and will also raise exceptions ifcalled 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 sepa-rator 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 stringswith per-host arguments in copy_args. copy_args length must equal length of hostlist - pssh.exceptions.HostArgumentError is raised otherwise

• encoding (str) – Encoding to use for file paths.





Raises pssh.exceptions.SFTPIOError on I/O errors reading from SFTP


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 bysuffix_separator.

run_command(command, sudo=False, user=None, stop_on_errors=True, use_pty=False,host_args=None, shell=None, encoding='utf-8', timeout=None, read_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 imme-diately.

More explicitly, function will return after connection and authentication establishment in the case of onnew connections and after execute commands have been accepted by successfully established SSH chan-nels.

Any connection and/or authentication exceptions will be raised here and need catching unlessrun_command is called with stop_on_errors=False in which case exceptions are added to in-dividual 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 userfrom 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 outputof run_command. See example usage below.

• shell (str) – (Optional) Override shell to use to run command with. Defaults to loginuser’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. De-faults to False

• host_args (tuple or list) – (Optional) Format command string with per-hostarguments 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 validPython codec

• read_timeout (float) – (Optional) Timeout in seconds for reading from stdoutor stderr. Reading from stdout/stderr will raise pssh.exceptions.Timeout aftertimeout seconds when set if remote output is not ready.

• timeout (float) – Deprecated - use read_timeout. Same as read_timeout and kept forbackwards compatibility - to be removed in future release.

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

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









https://docs.python.org/library/codecs.html





Raises pssh.exceptions.HostArgumentError on number of host arguments not equalto 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 hasbeen set.

Raises pssh.exceptions.Timeout on timeout starting command.

Raises Exceptions from ssh2.exceptions for all other specific errors such as ssh2.exceptions.SocketDisconnectError et al.

scp_recv(remote_file, local_file, recurse=False, copy_args=None, suffix_separator='_')Copy remote file(s) in parallel via SCP as <local_file><suffix_separator><host> or as per copy_argsargument.


De-duplication behaviour is configurable by providing copy_args argument, see below.

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




Parameters





• copy_args (tuple or list) – (Optional) format remote_file and local_file stringswith per-host arguments in copy_args. copy_args length must equal length of hostlist - 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 argumentsnot equal to number of hosts.

Raises pss.exceptions.SCPError on errors copying file.

Raises OSError on local OS errors like permission denied.



https://ssh2-python.readthedocs.io/en/latest/exceptions.html#module-ssh2.exceptions

https://ssh2-python.readthedocs.io/en/latest/exceptions.html#ssh2.exceptions.SocketDisconnectError

https://ssh2-python.readthedocs.io/en/latest/exceptions.html#ssh2.exceptions.SocketDisconnectError








Note: File names will be de-duplicated by appending the hostname to the filepath separated bysuffix_separator or as per copy_args argument if provided.

scp_send(local_file, remote_file, recurse=False, copy_args=None)Copy local file to remote file in parallel via SCP.



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

Note: Creating remote directories when either remote_file contains directory paths or recurseis enabled requires SFTP support on the server as libssh2 SCP implementation lacks directory creationsupport.

Parameters




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

Raises pss.exceptions.SCPError on errors copying file.


2.5.2 Native Single Host Client

Native single host non-blocking client. Suitable for running asynchronous commands on a single host.

class pssh.clients.native.single.SSHClient(host, user=None, pass-word=None, port=None, pkey=None,num_retries=3, retry_delay=5, al-low_agent=True, timeout=None, for-ward_ssh_agent=False, proxy_host=None,proxy_port=None, proxy_pkey=None,proxy_user=None, proxy_password=None,_auth_thread_pool=True,keepalive_seconds=60, identity_auth=True)

ssh2-python (libssh2) based non-blocking SSH client.

Parameters

• host (str) – Host name or IP to connect to.

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

• password (str) – Password to use for password authentication.

• port (int) – SSH port to connect to. Defaults to SSH default (22)

• pkey (str) – Private key file path to use for authentication. Path must be either absolutepath or relative to user home directory like ~/<path>.















• timeout (int) – SSH session timeout setting in seconds. This controls timeout setting ofauthenticated SSH sessions.

• allow_agent (bool) – (Optional) set to False to disable connecting to the system’s SSHagent

• identity_auth (bool) – (Optional) set to False to disable attempting to authenticatewith default identity files from pssh.clients.base.single.BaseSSHClient.IDENTITIES

• forward_ssh_agent (bool) – Unused - agent forwarding not implemented.

• proxy_host (str) – Connect to target host via given proxy host.

• proxy_port (int) – Port to use for proxy connection. Defaults to self.port

• keepalive_seconds – Interval of keep alive messages being sent to server. Set to 0 orFalse to disable.


close_channel(channel)

configure_keepalive()

copy_file(local_file, remote_file, recurse=False, sftp=None)Copy local file to host via SFTP.

Parameters




• sftp (ssh2.sftp.SFTP) – SFTP channel to use instead of creating a new one.




Raises IOError on local file IO errors


copy_remote_file(remote_file, local_file, recurse=False, sftp=None, encoding='utf-8')Copy remote file to local host via SFTP.

Parameters

• remote_file (str) – Remote filepath to copy from

• local_file (str) – Local filepath where file(s) will be copied to

• recurse (bool) – Whether or not to recursively copy directories

• encoding (str) – Encoding to use for file paths.

• sftp (ssh2.sftp.SFTP) – SFTP channel to use instead of creating a new one.














https://ssh2-python.readthedocs.io/en/latest/sftp.html#ssh2.sftp.SFTP








Raises pssh.exceptions.SFTPIOError on I/O errors reading from SFTP



disconnect()Attempt to disconnect session.

Any errors on calling disconnect are suppressed by this function.

eagain_write(write_func, data, timeout=None)

execute(cmd, use_pty=False, channel=None)Execute command on remote server.

Parameters

• cmd (str) – Command to execute.

• use_pty (bool) – Whether or not to obtain a PTY on the channel.

• channel (ssh2.channel.Channel) – Use provided channel for execute rather thancreating a new one.

finished(channel)Checks if remote command has finished - has server sent client EOF.

Return type bool

get_exit_status(channel)Get exit status code for channel or None if not ready.

Parameters channel (ssh2.channel.Channel) – The channel to get status from.

Return type int or None

mkdir(sftp, directory)Make directory via SFTP channel.

Parent paths in the directory are created if they do not exist.

Parameters

• sftp (ssh2.sftp.SFTP) – SFTP client object

• directory (str) – Remote directory to create

Catches and logs at error level remote IOErrors on creating directory.

open_session()Open new channel from session

poll(timeout=None)Perform co-operative gevent poll on ssh2 session socket.

Blocks current greenlet only if socket has pending read or write operations in the appropriate direction.

scp_recv(remote_file, local_file, recurse=False, sftp=None, encoding='utf-8')Copy remote file to local host via SCP.

Note - Remote directory listings are gathered via SFTP when recurse is enabled - SCP lacks directorylist support. Enabling recursion therefore involves creating an extra SFTP channel and requires SFTPsupport on the server.

Parameters




https://ssh2-python.readthedocs.io/en/latest/channel.html#ssh2.channel.Channel





• remote_file (str) – Remote filepath to copy from

• local_file (str) – Local filepath where file(s) will be copied to

• recurse (bool) – Whether or not to recursively copy directories

• encoding (str) – Encoding to use for file paths when recursion is enabled.

Raises pssh.exceptions.SCPError on errors copying file.

Raises IOError on local file IO errors.


scp_send(local_file, remote_file, recurse=False, sftp=None)Copy local file to host via SCP.

Note - Directories are created via SFTP when recurse is enabled - SCP lacks directory create support.Enabling recursion therefore involves creating an extra SFTP channel and requires SFTP support on theserver.

Parameters









sftp_get(sftp, remote_file, local_file)

sftp_put(sftp, local_file, remote_file)

spawn_send_keepalive()Spawns a new greenlet that sends keep alive messages every self.keepalive_seconds

wait_finished(host_output, timeout=None)Wait for EOF from channel and close channel.

Used to wait for remote command completion and be able to gather exit code.

Parameters

• host_output (pssh.output.HostOutput) – Host output of command to wait for.

• timeout (float) – Timeout value in seconds - defaults to no timeout.

Raises pssh.exceptions.Timeout after <timeout> seconds if timeout given.











2.5.3 ssh-python Parallel Client

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

class pssh.clients.ssh.parallel.ParallelSSHClient(hosts, user=None, pass-word=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, gss-api_server_identity=None, gss-api_client_identity=None, gss-api_delegate_credentials=False,identity_auth=True)

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) – Private key file path to use. Path must be either absolute path or relative touser home directory like ~/<path>.

• cert_file (str) – Public key signed certificate file to use for authentication. Thecorresponding private key must also be provided via pkey parameter. For examplepkey='id_rsa', cert_file='id_rsa-cert.pub' for RSA signed certificate.Path must be absolute or relative to user home directory.



• timeout (float) – (Optional) Individual SSH client timeout setting in seconds passedon to each SSH client spawned by ParallelSSHClient.

This controls timeout setting of socket operations used for SSH sessions on a per sessionbasis 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 isseparate to and not affected by self.timeout.

• pool_size (int) – (Optional) Greenlet pool size. Controls concurrency, on how manyhosts to execute tasks in parallel. Defaults to 100. Overhead in event loop will determinehow 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 hostsuse the same configuration.

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
















• proxy_host (str) – (Optional) SSH host to tunnel connection through so that SSHclients connect to host via client -> proxy_host -> host

• proxy_port (int) – (Optional) SSH port to use to login to proxy host if set. Defaults to22.

• proxy_user (str) – (Optional) User to login to proxy_host as. Defaults to logged inuser.

• proxy_password (str) – (Optional) Password to login to proxy_hostwith. Defaultsto no password.

• proxy_pkey (Private key file path to use.) – (Optional) Private key file tobe used for authentication with proxy_host. Defaults to available keys from SSHAgentand user’s SSH identities.

• forward_ssh_agent (bool) – (Optional) Turn on SSH agent forwarding - equivalentto ssh -A from the ssh command line utility. Defaults to False if not set. Currently unusedmeaning 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 dele-gation.


run_command(command, sudo=False, user=None, stop_on_errors=True, use_pty=False,host_args=None, shell=None, encoding='utf-8', timeout=None, read_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 imme-diately.

More explicitly, function will return after connection and authentication establishment in the case of onnew connections and after execute commands have been accepted by successfully established SSH chan-nels.

Any connection and/or authentication exceptions will be raised here and need catching unlessrun_command is called with stop_on_errors=False in which case exceptions are added to in-dividual 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 userfrom 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 outputof run_command. See example usage below.

















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

• host_args (tuple or list) – (Optional) Format command string with per-hostarguments 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 validPython codec

• read_timeout (float) – (Optional) Timeout in seconds for reading from std-out 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.

• timeout (float) – Deprecated - use read_timeout. Same as read_timeout and kept forbackwards compatibility - to be removed in future release.


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 equalto 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 hasbeen set.

Raises pssh.exceptions.Timeout on timeout starting command.

Raises Exceptions from ssh.exceptions for all other specific errors.

2.5.4 ssh-python Single Host Client

Single host non-blocking client based on ssh-python (libssh). Suitable for running asynchronous commands ona single host.

class pssh.clients.ssh.single.SSHClient(host, user=None, password=None, port=None,pkey=None, cert_file=None, num_retries=3,retry_delay=5, allow_agent=True, time-out=None, identity_auth=True, gss-api_auth=False, gssapi_server_identity=None,gssapi_client_identity=None, gss-api_delegate_credentials=False,_auth_thread_pool=True)

ssh-python based non-blocking client.

Parameters

• host (str) – Host name or IP to connect to.

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








https://ssh-python.readthedocs.io/en/latest/exceptions.html#module-ssh.exceptions




• password (str) – Password to use for password authentication.

• port (int) – SSH port to connect to. Defaults to SSH default (22)

• pkey (str) – Private key file path to use for authentication. Path must be either absolutepath or relative to user home directory like ~/<path>.

• cert_file (str) – Public key signed certificate file to use for authentication. Thecorresponding private key must also be provided via pkey parameter. For examplepkey='id_rsa',cert_file='id_rsa-cert.pub' for RSA signed certificate.Path must be absolute or relative to user home directory.



• timeout (int) – (Optional) If provided, all commands will timeout after <timeout> num-ber of seconds.

• allow_agent (bool) – (Optional) set to False to disable connecting to the system’s SSHagent. Currently unused.


• gssapi_server_identity (str) – Enable GSS-API authentication. Uses GSS-MICkey exchange. Enabled if either gssapi_server_identity or gssapi_client_identity are pro-vided.

• gssapi_server_identity – Set GSSAPI server identity.

• gssapi_client_identity (str) – Set GSSAPI client identity.

• gssapi_delegate_credentials (bool) – Enable/disable server credentials dele-gation.


auth()

close_channel(channel)Close channel.

Parameters channel (ssh.channel.Channel) – The channel to close.

disconnect()Close socket if needed.

execute(cmd, use_pty=False, channel=None)Execute command on remote host.

Parameters

• cmd (str) – The command string to execute.

• use_pty (bool) – Whether or not to request a PTY on the channel executing command.

• channel (ssh.channel.Channel) – Channel to use. New channel is created if notprovided.

finished(channel)Checks if remote command has finished - has server sent client EOF.

Return type bool














https://ssh-python.readthedocs.io/en/latest/channel.html#ssh.channel.Channel



https://ssh-python.readthedocs.io/en/latest/channel.html#ssh.channel.Channel



get_exit_status(channel)Get exit status code for channel or None if not ready.

Parameters channel (ssh.channel.Channel) – The channel to get status from.

Return type int or None

open_session()Open new channel from session.

poll(timeout=None)ssh-python based co-operative gevent poll on session socket.

wait_finished(host_output, timeout=None)Wait for EOF from channel and close channel.

Used to wait for remote command completion and be able to gather exit code.

Parameters

• host_output (pssh.output.HostOutput) – Host output of command to wait for.

• timeout (float) – Timeout value in seconds - defaults to no timeout.

Raises pssh.exceptions.Timeout after <timeout> seconds if timeout set.

2.5.5 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, time-out=120, pool_size=10,host_config=None,retry_delay=5, iden-tity_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 likerun_command or copy_file so the two operations, login and running a remote command, can beseparated.

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








Parameters




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

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



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>


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




Parameters

















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




Raises IOError on I/O errors writing files

Raises OSError on OS errors like permission denied


Note: File names will be de-duplicated by appending the hostname to the filepath separated bysuffix_separator.

finished(output=None)Check if commands have finished without blocking.

Parameters output (list(HostOutput)) – (Optional) Output to check if finished. Defaultsto get_last_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

• timeout – No-op - to be removed.


Return type dict or list

join(output=None, consume_output=False, timeout=None, encoding='utf-8')Wait until all remote commands in output have finished. Does not block other commands from running inparallel.

Parameters

• output (HostOutput objects) – Output of commands to join on

• consume_output (bool) – Whether or not join should consume output buffers. Out-put buffers will be empty after join if set to True. Must be set to True to allow hostlogger 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. Thisfunction’s timeout is for all commands in total and will therefor be affected by pool sizeand total number of concurrent commands in self.pool. Since self.timeout is passed ontoeach individual SSH session it is not used for any parallel functions like run_command orjoin.










• encoding (str) – Unused - encoding from each HostOutput is used instead. To beremoved in future releases.

Raises pssh.exceptions.Timeout on timeout requested and reached with commandsstill 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 tojoin 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 commandsstill running.

open_shell(encoding='utf-8', read_timeout=None)Open interactive shells on all hosts.

Parameters

• encoding (str) – Encoding to use for command string and shell output.

• read_timeout (float) – Seconds before reading from output times out.

Returns Opened shells for each of self.hosts, in order.

Return type list(pssh.clients.native.base.single.InteractiveShell)

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

No-op - to be removed.

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)

run_shell_commands(shells, commands)Run command(s) on shells.

Parameters

• shells (list(pssh.clients.base.single.InteractiveShell)) – Shells torun on.

• commands (list or str) – Commands to run.

property hosts








2.5.6 Base Single Client

API documentation for common single host client functionality.

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

class pssh.clients.base.single.BaseSSHClient(host, user=None, password=None,port=None, pkey=None,num_retries=3, retry_delay=5, al-low_agent=True, timeout=None,proxy_host=None, proxy_port=None,_auth_thread_pool=True, iden-tity_auth=True)

auth()

close_channel(channel)

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

copy_remote_file(remote_file, local_file, recurse=False, sftp=None, encoding='utf-8')

disconnect()

execute(cmd, use_pty=False, channel=None)

get_exit_status(channel)

mkdir(sftp, directory)

open_session()

open_shell(encoding='utf-8', read_timeout=None)Open interactive shell on new channel.

Can be used as context manager - with open_shell() as shell.

Parameters

• encoding (str) – Encoding to use for command string and shell output.

• read_timeout (float) – Timeout in seconds for reading from output.

poll(timeout=None)

read_output(stdout_buffer, timeout=None)Read standard output buffer. Returns a generator of line by line output.

Parameters stdout_buffer (pssh.clients.reader.ConcurrentRWBuffer) –Buffer to read from.

Return type generator

read_output_buffer(output_buffer, prefix=None, callback=None, callback_args=None,encoding='utf-8')

Read from output buffers and log to host_logger.

Parameters

• output_buffer (iterator) – Iterator containing buffer

• prefix (str) – String to prefix log output to host_logger with

• callback (function) – Function to call back once buffer is depleted:

• callback_args (tuple) – Arguments for call back function






read_stderr(stderr_buffer, timeout=None)Read standard error buffer. Returns a generator of line by line output.

Parameters stdout_buffer (pssh.clients.reader.ConcurrentRWBuffer) –Buffer to read from.

Return type generator

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

Run remote command.

Parameters

• command (str) – Command to run.

• sudo (bool) – Run command via sudo as super-user.

• user (str) – Run command as user via sudo

• use_pty (bool) – Whether or not to obtain a PTY on the channel.


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

• read_timeout (float) – (Optional) Timeout in seconds for reading output.

• timeout – Deprecated - use read_timeout.

Return type pssh.output.HostOutput

scp_recv(remote_file, local_file, recurse=False, sftp=None, encoding='utf-8')

scp_send(local_file, remote_file, recurse=False, sftp=None)

sftp_get(sftp, remote_file, local_file)

sftp_put(sftp, local_file, remote_file)

wait_finished(host_output, timeout=None)

IDENTITIES = ('/home/docs/.ssh/id_rsa', '/home/docs/.ssh/id_dsa', '/home/docs/.ssh/identity', '/home/docs/.ssh/id_ecdsa', '/home/docs/.ssh/id_ed25519')

class pssh.clients.base.single.InteractiveShell(channel, client, encoding='utf-8',read_timeout=None)

Run commands on an interactive shell.

Use as context manager to wait for commands to finish on exit.

Read from .stdout and stderr once context manager has exited.

InteractiveShell.output is a pssh.output.HostOutput object.

Parameters

• channel (ssh2.channel.Channel or similar.) – The channel to open shell on.

• client (BaseSSHClient) – The SSHClient that opened the channel.

• encoding (str) – Encoding to use for command string when calling run and shell out-put.

close()Wait for shell to finish executing and close channel.

run(cmd)Run command on interactive shell.












Parameters cmd (str) – The command string to run. Note that \n is appended to every string.

property exit_codeself.output.exit_code

output

property stderrself.output.stderr

property stdinself.output.stdin

property stdoutself.output.stdout

class pssh.clients.base.single.Stdin(channel, client)Stdin stream for a channel.

Handles EAGAIN.

Provides write and flush only.

Parameters

• channel (IO object) – The channel the stdin stream is from.

• client (BaseSSHClient) – The SSH client the channel is from.

flush()Flush pending data written to stdin.

write(data)Write to stdin.

Parameters data (str) – Data to write.

2.5.7 Host Output

Output module of ParallelSSH

class pssh.output.BufferData(reader, rw_buffer)

Parameters

• reader (gevent.Greenlet) – Greenlet reading data from channel and writing torw_buffer

• rw_bufffer – Read/write buffer

reader

rw_buffer

class pssh.output.HostOutput(host, channel, stdin, client, exception=None, encoding='utf-8',read_timeout=None, buffers=None)

Host output

Parameters

• host (str) – Host name output is for

• channel (socket.socket compatible object) – SSH channel used for command exe-cution

• stdin (file()-like object) – Standard input buffer






https://docs.python.org/2/library/functions.html#file


• client (pssh.clients.base.single.BaseSSHClient) – SSHClient output iscoming from.

• exception (Exception or None) – Exception from host if any

• read_timeout (float) – Timeout in seconds for reading from buffers.

• buffers (HostOutputBuffers) – Host buffer data.

buffers

channel

client

encoding

exception

property exit_code

host

read_timeout

property stderr

stdin

property stdout

class pssh.output.HostOutputBuffers(stdout, stderr)

Parameters

• stdout (BufferData) – Stdout data

• stderr (BufferData) – Stderr data

stderr

stdout

2.5.8 Host Config

Host specific configuration.

class pssh.config.HostConfig(user=None, port=None, password=None, private_key=None,allow_agent=None, num_retries=None, retry_delay=None,timeout=None, identity_auth=None, proxy_host=None,proxy_port=None, proxy_user=None, proxy_password=None,proxy_pkey=None, keepalive_seconds=None)

Host configuration for ParallelSSHClient.

Used to hold individual configuration for each host in ParallelSSHClient host list.

Parameters

• user (str) – Username to login as.

• port (int) – Port number.

• password (str) – Password to login with.

• private_key (str) – Private key file to use for authentication.

• allow_agent (bool) – Enable/disable SSH agent authentication.









• num_retries (int) – Number of retry attempts before giving up on connection and SSHoperations.

• retry_delay (int) – Delay in seconds between retry attempts.

• timeout (int) – Timeout value for connection and SSH sessions in seconds.

• identity_auth (bool) – Enable/disable identity file authentication under user’s homedirectory (~/.ssh).

• proxy_host (str) – Proxy SSH host to use for connecting to target SSH host. client ->proxy_host -> SSH host

• proxy_port (int) – Port for proxy host.

• proxy_user (str) – Username for proxy host.

• proxy_password (str) – Password for proxy host.

• proxy_pkey (str) – Private key for proxy host.

• keepalive_seconds (int) – Seconds between keepalive packets being sent. 0 to dis-able.

allow_agent

identity_auth

keepalive_seconds

num_retries

password

port

private_key

proxy_host

proxy_password

proxy_pkey

proxy_port

proxy_user

retry_delay

timeout

user

2.5.9 Native Tunnel

This module provides general purpose functionality for tunneling connections via an intermediary SSH proxy.

Clients connect to a provided local port and get traffic forwarded to/from the target host via an SSH proxy.

class pssh.clients.native.tunnel.LocalForwarderThread runner for a group of local port forwarding proxies.

Starts servers in their own gevent hub via thread run target.

Use enqueue to create new servers and get port to connect to via out_q once a target has been put into theinput queue.













SSHClient is the client for the SSH host that will be proxying.

enqueue(client, host, port)Add target host:port to tunnel via client to queue.

Parameters

• client (pssh.clients.native.single.SSHClient) – The client to connectvia.

• host (str) – Target host to open connection to.

• port (int) – Target port to connect on.

run()Thread runner ensures a non main hub has been created for all subsequent greenlets and waits for (client,host, port) tuples to be put into self.in_q.

A server is created once something is in the queue and the port to connect to is put into self.out_q.

shutdown()Stop all tunnel servers.

class pssh.clients.native.tunnel.TunnelServer(client, host, port,bind_address='127.0.0.1',num_retries=3)

Local port forwarding server for tunneling connections from remote SSH server.

Accepts connections on an available bind_address port once started and tunnels data to/from remote SSH hostfor each connection.

property listen_port

2.5.10 Output reader/writer

class pssh.clients.reader.ConcurrentRWBufferConcurrent reader/writer of bytes for use from multiple greenlets.

Supports both concurrent reading and writing.

Iterate on buffer object to read data, yielding greenlet if no data exists until self.eof has been set.

Writers should eof.set() when finished writing data via write.

Readers can use read() to get any available data or None.

read()Read available data, or return None

Return type bytes

write(data)Write data to buffer.

Parameters data (bytes) – Data to write

eof





2.5.11 Utility functions

Module containing static utility functions for parallel-ssh.

pssh.utils.enable_debug_logger()Enable debug logging for the library to sdout.

pssh.utils.enable_host_logger()Enable host logger for logging stdout from remote commands as it becomes available.

pssh.utils.enable_logger(_logger, level=20)Enables logging to stdout for given logger

2.5.12 Exceptions

Exceptions raised by parallel-ssh classes.

exception pssh.exceptions.AuthenticationErrorRaised on authentication error (user/password/ssh key error)

pssh.exceptions.AuthenticationExceptionalias of pssh.exceptions.AuthenticationError

exception pssh.exceptions.ConnectionErrorRaised on error connecting (connection refused/timed out)

pssh.exceptions.ConnectionErrorExceptionalias of pssh.exceptions.ConnectionError

exception pssh.exceptions.HostArgumentErrorRaised on errors with per-host arguments to parallel functions

pssh.exceptions.HostArgumentExceptionalias of pssh.exceptions.HostArgumentError

exception pssh.exceptions.PKeyFileErrorRaised on errors finding private key file

exception pssh.exceptions.ProxyErrorRaised on proxy errors

exception pssh.exceptions.SCPErrorRaised on errors copying file via SCP

exception pssh.exceptions.SFTPErrorRaised on SFTP errors

exception pssh.exceptions.SFTPIOErrorRaised on SFTP IO errors

exception pssh.exceptions.SSHErrorRaised on error authenticating with SSH server

pssh.exceptions.SSHExceptionalias of pssh.exceptions.SSHError

exception pssh.exceptions.SessionErrorRaised on errors establishing SSH session

exception pssh.exceptions.ShellErrorRaised on errors running command on interactive shell



exception pssh.exceptions.TimeoutRaised on timeout requested and reached

exception pssh.exceptions.UnknownHostErrorRaised when a host is unknown (dns failure)

pssh.exceptions.UnknownHostExceptionalias of pssh.exceptions.UnknownHostError

2.5.13 Constants

Constants definitions for pssh package

pssh.constants.DEFAULT_RETRIES = 3Default number of retry attempts for SSH client initialisation - authentication, establishing connections et al.

pssh.constants.RETRY_DELAY = 5Default delay in seconds between retry attempts for SSH client initialisation.

2.6 Clients Feature Comparison

The two available client types, default native clients based on ssh2-python (libssh2) and clients under pssh.clients.ssh based on ssh-python (libssh) support different authentication mechanisms and features.

Below is a comparison of feature support for the two client types.

Feature ssh2-python (libssh2) ssh-python (libssh)Agent forwarding No Not yet implementedProxying/tunneling Yes NoKerberos (GSS) authentication Not supported YesPrivate key file authentication Yes YesAgent authentication Yes YesPassword authentication Yes YesOpenSSH config parsing Not yet implemented Not yet implementedECDSA keys support Yes YesED25519 keys support Yes YesCertificate authentication Not supported YesSFTP copy to/from hosts Yes NoSCP functionality Yes NoKeep-alive functionality Yes No

The default client offers the most features, but lacks certain authentication mechanisms like GSS-API and certificateauthentication. Both client types are based on C libraries and offer similar levels of performance.

Users that need the authentication mechanisms not supported by the default client can from pssh.clients.sshimport ParallelSSHClient, SSHClient instead of the default clients.



2.7 Scaling

Some guide lines on scaling parallel-ssh and pool size numbers.

In general, long lived commands with little or no output gathering will scale better. Pool sizes in the multiple thousandshave been used successfully with little CPU overhead in the single thread running them in these use cases.

Conversely, many short lived commands with output gathering will not scale as well. In this use case, smaller poolsizes in the hundreds are likely to perform better with regards to CPU overhead in the event loop.

Multiple Python native threads, each of which can get its own event loop, may be used to scale this use case furtheras number of CPU cores allows. Note that parallel-ssh imports must be done within the target function of thenewly started thread for it to receive its own event loop. gevent.get_hub() may be used to confirm that theworker thread event loop differs from the main thread.

Gathering is highlighted here as output generation does not affect scaling. Only when output is gathered either overmultiple still running commands, or while more commands are being triggered, is overhead increased.

2.7.1 Technical Details

To understand why this is, consider that in co-operative multi tasking, which is being used in this project via thegevent library, a co-routine (greenlet) needs to yield the event loop to allow others to execute - co-operation.When one co-routine is constantly grabbing the event loop in order to gather output, or when co-routines are constantlytrying to start new short-lived commands, it causes contention with other co-routines that also want to use the eventloop.

This manifests itself as increased CPU usage in the process running the event loop and reduced performance withregards to scaling improvements from increasing pool size.

On the other end of the spectrum, long lived remote commands that generate no output only need the event loop atthe start, when they are establishing connections, and at the end, when they are finished and need to gather exit codes,which results in practically zero CPU overhead at any time other than start or end of command execution.

Output generation is done remotely and has no effect on the event loop until output is gathered - output buffers areiterated on. Only at that point does the event loop need to be held.

2.8 Comparison With Alternatives

There are not many alternatives for SSH libraries in Python. Of the few that do exist, here is how they compare withparallel-ssh.

As always, it is best to use a tool that is suited to the task at hand. parallel-ssh is a library for programmatic andnon-interactive use. If requirements do not match what it provides then it best not be used. Same applies for the toolsdescribed below.

2.7. Scaling 51


2.8.1 Paramiko

The default SSH client library in parallel-ssh<=1.6.x series.

Pure Python code, while having native extensions as dependencies, with poor performance and numerous bugs com-pared to both OpenSSH binaries and the libssh2 based native clients in parallel-ssh 1.2.x and above.Recent versions have regressed in performance and have blocker issues.

It does not support non-blocking mode, so to make it non-blocking monkey patching must be used which affects allother uses of the Python standard library.

Based on its use in historical parallel-ssh releases as well as performance testing, paramiko is very far frombeing mature enough to be used.

This is why parallel-ssh has moved away from paramiko entirely since 2.0.0 where it was dropped as adependency.

2.8.2 asyncssh

Pure Python asyncio framework using client library. License (EPL) is not compatible with GPL, BSD or other opensource licenses and combined works cannot be distributed.

Therefore unsuitable for use in many projects, including parallel-ssh.

2.8.3 Fabric

Port of Capistrano from Ruby to Python. Intended for command line use and is heavily systems administration orientedrather than non-interactive library. Same maintainer as Paramiko.

Uses Paramiko and suffers from the same limitations. More over, uses threads for parallelisation, while not beingthread safe, and exhibits very poor performance and extremely high CPU usage even for limited number of hosts - 1to 10 - with scaling limited to one core.

Library API is non-standard, poorly documented and with numerous issues as API use is not intended.

2.8.4 Ansible

A configuration management and automation tool that makes use of SSH remote commands. Uses, in parts, bothParamiko and OpenSSH binaries.

Similarly to Fabric, uses threads for parallelisation and suffers from the poor scaling that this model offers.

See The State of Python SSH Libraries for what to expect from scaling SSH with threads, as compared to non-blockingI/O with parallel-ssh.

Again similar to Fabric, its intended and documented use is interactive via command line rather than library API based.It may, however, be an option if Ansible is already being used for automation purposes with existing playbooks, thenumber of hosts is small, and when the use case is interactive via command line.

parallel-ssh is, on the other hand, a suitable option for Ansible as an SSH client that would improve its parallelSSH performance significantly.


https://github.com/ParallelSSH/parallel-ssh/issues/83


https://www.eclipse.org/legal/eplfaq.php#USEINANOTHER

https://github.com/fabric/fabric/issues/1433

https://github.com/fabric/fabric/issues/1433

https://parallel-ssh.org/post/ssh2-python/

https://parallel-ssh.org/post/parallel-ssh-libssh2/

https://parallel-ssh.org/post/parallel-ssh-libssh2/


2.8.5 ssh2-python

Bindings for libssh2 C library. Used by parallel-ssh as of 1.2.0 and is by same author.

Does not do parallelisation out of the box but can be made parallel via Python’s threading library relatively easilyand as it is a wrapper to a native library that releases Python’s GIL, can scale to multiple cores.

parallel-ssh uses ssh2-python in its native non-blocking mode with event loop and co-operative socketsprovided by gevent for an extremely high performance library without the side-effects of monkey patching - seebenchmarks.

In addition, parallel-ssh uses native threads to offload CPU bound tasks like authentication in order to scale tomultiple cores while still remaining non-blocking for network I/O.

pssh.clients.native.SSHClient is a single host natively non-blocking client for users that do not needparallel capabilities but still want a fully featured client with native code performance.

Out of all the available Python SSH libraries, libssh2 and ssh2-python have been shown, see benchmarksabove, to perform the best with the least resource utilisation and ironically for a native code extension the least amountof dependencies. Only libssh2 C library and its dependencies which are included in binary wheels.

However, it lacks support for some SSH features present elsewhere like GSS-API and certificate authentication.

2.8.6 ssh-python

Bindings for libssh C library. A client option in parallel-ssh, same author. Similar performance to ssh2-python above.

For non-blocking use, only certain functions are supported. SCP/SFTP in particular cannot be used in non-blockingmode, nor can tunnels.

Supports more authentication options compared to ssh2-python like GSS-API (Kerberos) and certificate authenti-cation.

2.9 Change Log

2.9.1 2.5.4

Fixes

• Password authentication via pssh.clients.ssh would not work - #276

2.9.2 2.5.3

Fixes

• Sending files via scp_send or sftp_put with timeout set could timeout unexpectedly on opening remotefile - #271.

2.9. Change Log 53



2.9.3 2.5.2

Fixes

• Agent authentication would not work for the libssh clients under pssh.clients.ssh - #267.

• Password authentication would be attempted if all other methods failed even when no password was provided.

• Gevent minimum version was too low - #269.

2.9.4 2.5.1

Fixes

• Successful identity file authentication would raise error - #264.

2.9.5 2.5.0

Changes

• Python 2 no longer supported.

• Updated class arguments, refactor for pssh.clients.native.tunnel.

Fixes

• Closed clients with proxy host enabled would not shutdown their proxy servers.

• Clients with proxy host enabled would not disconnect the proxy client on .disconnect being called.

• Default identity files would not be used when private key was not specified - #222.

• ParallelSSHClient(<..>, identity_auth=False would not be honoured.

2.9.6 2.4.0

Changes

• Added interactive shell support to single and parallel clients - see documentation.

• Added pssh.utils.enable_debug_logger function.

• ParallelSSHClient timeout parameter is now also applied to starting remote commands viarun_command.

• HostOutput.stdin now handles EAGAIN automatically when writing - #165.

• Assigning to ParallelSSHClient.hosts cleans up clients of hosts no longer in host list - #220.


https://parallel-ssh.readthedocs.io/en/latest/advanced.html#interactive-shells


Fixes

• SSHClient with proxy enabled could not be used without setting port - #248

• Encoding would not be applied to command string on run_command and interactive shells, utf-8 used instead- #174.

2.9.7 2.3.2

Fixes

• Client output implementation Python 2 support.

2.9.8 2.3.1

Changes

• SSHClient.read_output and read_stderr now take buffer to read from as argument instead of chan-nel.

• SSHClient.wait_finished now takes HostOutput argument instead of channel.

Fixes

• Output for multiple commands on one host run at the same time would be lost.

2.9.9 2.3.0

Changes

• SSHClient now starts buffering output from remote host, both standard output and standard error, when acommand is run.

• SSHClient.read_output, SSHClient.read_stderr and iterating on stdout/stderr fromHostOutput now read from the internal buffer rather than the SSH channel directly.

• ParallelSSHClient.join no longer requires consume_output to be set in order to get exit codeswithout first reading output.

• ParallelSSHClient.join with timeout no longer consumes output by default. It is now possible to usejoin with a timeout and capture output after join completes.

• ParallelSSHClient.reset_output_generators is now a no-op and no longer required to be calledafter timeouts.

• HostOutput.stdout and stderr are now dynamic properties.

• Added HostOutput.read_timeout attribute. Can be used to see what read timeout was whenrun_command was called and to change timeout when next reading from HostOutput.stdout andstderr.

• Added HostOutput.encoding attribute for encoding used when run_command was called. Encodingcan now be changed for when next reading output.

2.9. Change Log 55


• ParallelSSHClient.join with timeout no longer affects stdout or stderr read timeout set whenrun_command was called.

• LibSSH clients under pssh.clients.ssh now allow output to be read as it becomes available withoutwaiting for remote command to finish first.

• Reading from output behaviour is now consistent across all client types - parallel and single clients under bothpssh.clients.native and pssh.clients.ssh.

• ParallelSSHClient.join can now be called without arguments and defaults to last ran commands.

• ParallelSSHClient.finished can now be called without arguments and defaults to last ran commands.

This is now possible:

output = client.run_command(<..>)client.join(output)assert output[0].exit_code is not None

As is this:

client.run_command(<..>, read_timeout=1)client.join(output, timeout=1)for line in output[0].stdout:

print(line)

Output can be read after and has separate timeout from join.

See documentation for more examples on use of timeouts.

2.9.10 2.2.0

Changes

• New single host tunneling, SSH proxy, implementation for increased performance.

• Native SSHClient now accepts proxy_host, proxy_port and associated parameters - see API docu-mentation.

• Proxy configuration can now be provided via HostConfig.

• Added ParallelSSHClient.connect_auth function for connecting and authenticating to hosts in par-allel.

2.9.11 2.1.0

Changes

• Added certificate authentication support for the pssh.clients.ssh clients.


https://parallel-ssh.readthedocs.io/en/latest/advanced.html#partial-output

https://parallel-ssh.readthedocs.io/en/latest/config.html

https://parallel-ssh.readthedocs.io/en/latest/config.html


2.9.12 2.0.0

Changes

See Upgrading to API 2.0 for examples of code that will need updating.

• Removed paramiko clients and dependency.

• ParallelSSHClient.run_command now always returns a list of HostOutput - return_list argu-ment is a no-op and may be removed.

• ParallelSSHClient.get_last_output now always returns a list of HostOutput.

• SSHClient.run_command now returns HostOutput.

• Removed deprecated since 1.0.0 HostOutput dictionary attributes.

• Removed deprecated since 1.0.0 imports and modules.

• Removed paramiko based load_private_key and read_openssh_config functions from pssh.utils.

• Removed paramiko based pssh.tunnel.

• Removed paramiko based pssh.agent.

• Removed deprecated ParallelSSHClient.get_output function.

• Removed deprecated ParallelSSHClient.get_exit_code and get_exit_codes functions.

• Removed deprecated ParallelSSHClient host_config dictionary implementation - now list ofHostConfig.

• Removed HostOutput.cmd attribute.

• Removed ParallelSSHClient.host_clients attribute.

• Made ParallelSSHClient(timeout=<seconds>) a global timeout setting for all operations.

• Removed run_command(greenlet_timeout=<..>) argument - now uses global timeout setting.

• Renamed run_command timeout to read_timeout=<seconds>) for setting output read timeout in-dividually - defaults to global timeout setting.

• Removed pssh.native package and native code.

• ParallelSSHClient.scp_send now supports copy_args keyword argument for providing per-hostfile name arguments like rest of scp_* and copy_* functionality.

• Changed exception names to end in Error from Exception - backwards compatible.

• UnknownHostException, AuthenticationException, ConnectionErrorException,SSHException no longer available as imports from pssh - use from pssh.exceptions.

2.9. Change Log 57

https://parallel-ssh.readthedocs.io/en/latest/api_upgrade_2_0.html


Fixes

• Removed now unnecessary locking around SSHClient initialisation so it can be parallelised - #219.

• ParallelSSHClient.join with encoding would not pass on encoding when reading from output buffers- #214.

• Clients could raise Timeout early when timeout settings were used with many hosts.

Packaging

• Package architecture has changed to none-any.

2.9.13 1.13.0

Changes

• Added pssh.config.HostConfig for providing per-host configuration. Replaces dictionaryhost_config which is now deprecated. See per-host configuration documentation.

• ParallelSSHClient.scp_send and scp_recv with directory target path will now copy source file todirectory keeping existing name instead of failing when recurse is off - #183.

• pssh.clients.ssh.SSHClient wait_finished timeout is now separate fromSSHClient(timeout=<timeout>) session timeout.

• ParallelSSHClient.join with timeout now has finished and unfinished commands as Timeout excep-tion arguments for use by client code.

Fixes

• ParallelSSHClient.copy_file with recurse enabled and absolute destination path would create emptydirectory in home directory of user - #197.

• ParallelSSHClient.copy_file and scp_recv with recurse enabled would not create remote direc-tories when copying empty local directories.

• ParallelSSHClient.scp_send would require SFTP when recurse is off and remote destination pathcontains directory - #157.

• ParallelSSHClient.scp_recv could block infinitely on large - 200-300MB or more - files.

• SSHClient.wait_finished would not apply timeout value given.

2.9.14 1.12.1

Fixes

• Reading from output streams with timeout via run_command(<..>, timeout=<timeout>) would raise timeoutearly when trying to read from a stream with no data written to it while other streams have pending data - #180.


https://parallel-ssh.readthedocs.io/en/latest/advanced.html#per-host-configuration


2.9.15 1.12.0

Changes

• Added ssh-python (libssh) based native client with run_command implementation.

• ParallelSSHClient.join with timeout no longer consumes output by default to allow reading of outputafter timeout.

Fixes

• ParallelSSHClient.join with timeout would raise Timeout before value given when client was busywith other commands.

Note: ssh-python client at pssh.clients.ssh.ParallelSSHClient is available for testing. Please report any issues.

To use:


This release adds (yet another) client, this one based on ssh-python (libssh). Key features of this client are moresupported authentication methods compared to ssh2-python.

Future releases will also enable certificate authentication for the ssh-python client.

Please migrate to one of the two native clients if have not already as paramiko is very quickly accumulating yet morebugs and the 2.0.0 release which removes it is imminent.

Users that require paramiko for any reason can pin their parallel-ssh versions to parallel-ssh<2.0.0.

2.9.16 1.11.2

Fixes

• ParallelSSHClient going out of scope would cause new client sessions to fail if client.join was not called prior -#200

2.9.17 1.11.0

Changes

• Moved polling to gevent.select.poll to increase performance and better handle high number of sockets - #189

• HostOutput.exit_code is now a dynamic property returning either None when exit code not ready or theexit code as reported by channel. ParallelSSHClient.get_exit_codes is now a no-op and scheduledto be removed.

• Native client exit codes are now more explicit and return None if no exit code is ready. Would previously return0 by default.

2.9. Change Log 59

https://libssh.org

https://github.com/ParallelSSH/ssh-python

https://libssh.org


Packaging

• Removed OSX Python 3.6 and 3.7 wheels. OSX wheels for brew python, currently 3.8, on OSX 10.14 and10.15 are provided.

Fixes

• Native client would fail on opening sockets with large file descriptor values - #189

2.9.18 1.10.0

Changes

• Added return_list optional argument to run_command to return list of HostOutput objects as outputrather than dictionary - defaults to False. List output will become default starting from 2.0.0.

• Updated native clients for new version of ssh2-python.

• Manylinux 2010 wheels.

Fixes

• Sockets would not be closed on client going out of scope - #175

• Calling join() would reset encoding set on run_command - #159

2.9.19 1.9.1

Fixes

• Native client SCP and SFTP uploads would not handle partial writes from waiting on socket correctly.

• Native client copy_file SFTP upload would get stuck repeating same writes until killed when copying multi-MB files from Windows clients - #148

• Native client scp_send would not correctly preserve file mask of local file on the remote.

• Native client tunnel, used for proxy implementation, would not handle partial writes from waiting on socketcorrectly.

2.9.20 1.9.0

Changes

• Removed libssh2 native library dependency in favour of bundled ssh2-python libssh2 library.

• Changed native client forward agent default behaviour to off due to incompatibility with certain SSH serverimplementations.

• Added keep-alive functionality to native client - defaults to 60 seconds. ParallelSSHClient(<..>,keepalive_seconds=<interval>) to configure interval. Set to 0 to disable.

• Added ~/.ssh/id_ecdsa default identity location to native client.



2.9.21 1.8.2

Fixes

• Native parallel client forward_ssh_agent flag would not be applied correctly.

2.9.22 1.8.1

Fixes

• Native client socket timeout setting would be longer than expected - #133

Packaging

• Added Windows 3.7 wheels

2.9.23 1.8.0

Changes

• Native client no longer requires public key file for authentication.

• Native clients raise pssh.exceptions.PKeyFileError on object initialisation if provided private keyfile paths cannot be found.

• Native clients expand user directory (~/<path>) on provided private key paths.

• Parallel clients raise TypeError when provided hosts is a string instead of list or other iterable.

2.9.24 1.7.0

Changes

• Better tunneling implementation for native clients that supports multiple tunnels over single SSH connection forconnecting multiple hosts through single proxy.

• Added greenlet_timeout setting to native client run_command to pass on to getting greenlet result toallow for greenlets to timeout.

• Native client raises specific exceptions on non-authentication errors connecting to host instead of genericSessionError.

Fixes

• Native client tunneling would not work correctly - #123.

• timeout setting was not applied to native client sockets.

• Native client would have SessionError instead of Timeout exceptions on timeout errors connecting tohosts.

2.9. Change Log 61


2.9.25 1.6.3

Changes

• Re-generated C code with latest Cython release.

Fixes

• ssh2-python >= 0.14.0 support.

2.9.26 1.6.2

Fixes

• Native client proxy initialisation failures were not caught by stop_on_errors=False - #121.

2.9.27 1.6.1

Fixes

• Host would always be 127.0.0.1 when using proxy_host on native client - #120.

2.9.28 1.6.0

Changes

• Added scp_send and scp_recv functions to native clients for sending and receiving files via SCP respec-tively.

• Refactoring - clients moved to their own sub-package - pssh.clients - with backwards compatibility forimports from pssh.pssh_client and pssh.pssh2_client.

• Show underlying exception from native client library when raising parallel-ssh exceptions.

• host parameter added to all exceptions raised by parallel clients - #116

• Deprecation warning for client imports.

• Deprecation warning for default client changing from paramiko to native client as of 2.0.0.

• Upgrade embedded libssh2 in binary wheels to latest version plus enhancements.

• Adds support for ECDSA host keys for native client.

• Adds support for SHA-256 host key fingerprints for native client.

• Added SSH agent forwarding to native client, defaults to on as per paramiko client - forward_ssh_agentkeyword parameter.

• Windows wheels switched to OpenSSL back end for native client.

• Windows wheels include zlib and have compression enabled for native client.

• Added OSX 10.13 wheel build.



Fixes

• Windows native client could not connect to newer SSH servers - thanks Pavel.

Note - libssh2 changes apply to binary wheels only. For building from source, see documentation.

2.9.29 1.5.5

Fixes

• Use of sudo in native client incorrectly required escaping of command.

2.9.30 1.5.4

Changes

• Compatibility with ssh2-python >= 0.11.0.

2.9.31 1.5.2

Changes

• Output generators automatically restarted on call to join so output can resume on any timeouts.

2.9.32 1.5.1

Fixes

• Output pssh.exceptions.Timeout exception raising was not enabled.

2.9.33 1.5.0

Changes

• ParallelSSH2Client.join with timeout now consumes output to ensure command completion status isaccurate.

• Output reading now raises pssh.exceptions.Timeout exception when timeout is requested and reachedwith command still running.

2.9. Change Log 63

http://parallel-ssh.readthedocs.io/en/latest/installation.html#building-from-source


Fixes

• ParallelSSH2Client.join would always raise Timeout when output has not been consumed even ifcommand has finished - #104.

2.9.34 1.4.0

Changes

• ParallelSSH2Client.join now raises pssh.exceptions.Timeout exception when timeout is re-quested and reached with command still running.

Fixes

• ParallelSSH2Client.join timeout duration was incorrectly for per-host rather than total.

• SFTP read flags were not fully portable.

2.9.35 1.3.2

Fixes

• Binary wheels would have bad version info and require git for installation.

2.9.36 1.3.1

Changes

• Added timeout optional parameter to join and run_command, for reading output, on native clients.

Fixes

• From source builds when Cython is installed with recent versions of ssh2-python.

2.9.37 1.3.0

Changes

• Native clients proxy implementation

• Native clients connection and authentication retry mechanism

Proxy/tunnelling implementation is experimental - please report any issues.



2.9.38 1.2.1

Fixes

• PyPy builds

2.9.39 1.2.0

Changes

• New ssh2-python (libssh2) native library based clients

• Added retry_delay keyword parameter to parallel clients

• Added get_last_output function for retrieving output of last executed commands

• Added cmds attribute to parallel clients for last executed commands

Fixes

• Remote path for SFTP operations was created incorrectly on Windows - #88 - thanks @moscoquera

• Parallel client key error when openssh config with a host name override was used - #93

• Clean up after paramiko clients

2.9.40 1.1.1

Changes

• Accept Paramiko version 2 but < 2.2 (it’s buggy).

2.9.41 1.1.0

Changes

• Allow passing on of additional keyword arguments to underlying SSH library via run_command - #85

2.9.42 1.0.0

Changes from 0.9x series API

• ParallelSSHClient.join no longer consumes output buffers

• Command output is now a dictionary of host name -> host output object with stdout and et al attributes. Hostoutput supports dictionary-like item lookup for backwards compatibility. No code changes are needed to outputuse though documentation will from now on refer to the new attribute style output. Dictionary-like item accessis deprecated and will be removed in future major release, like 2.x.

• Made output encoding configurable via keyword argument on run_command and get_output

• pssh.output.HostOutput class added to hold host output

2.9. Change Log 65

http://parallel-ssh.readthedocs.io/en/latest/output.html


• Added copy_remote_file function for copying remote files to local ones in parallel

• Deprecated since 0.70.0 ParallelSSHClient API endpoints removed

• Removed setuptools >= 28.0.0 dependency for better compatibility with existing installations. Pip version de-pendency remains for Py 2.6 compatibility with gevent - documented on project’s readme

• Documented use_pty parameter of run_command

• SSHClient read_output_buffer is now public function and has gained callback capability

• If using the single SSHClient directly, read_output_buffer should now be used to read output buffers - this is notneeded for ParallelSSHClient

• run_command now uses named positional and keyword arguments

2.10 Upgrading to API 2.0

Here can be found code examples for the 1.x API and how they can be migrated to the new 2.x API.

Code that was already making use of run_command(<..>, return_list=True is compatible with the 2.xAPI - return_list=True parameter may now be removed.

2.10.1 Parallel Client Run Command

1.x code

client = ParallelSSHClient(..)

output = client.run_command(<cmd>)for host, host_out in output.values():

<..>

2.x code


output = client.run_command(<cmd>)for host_out in output:

host = host_out.host<..>

2.10.2 Parallel Client Get last output

1.x code


output = client.get_last_output()for host, host_out in output.values():

<..>



2.x code


output = client.get_last_output()for host_out in output:

host = host_out.host<..>

2.10.3 Single Client Run Command

1.x code

client = SSHClient(..)

channel, host, stdout, stderr, stdin = client.run_command(<cmd>)for line in stdout:

<..>exit_code = client.get_exit_status(channel)

2.x code

client = SSHClient(..)

host_out = client.run_command(<cmd>)for line in host_out.stdout:

<..>exit_code = host_out.exit_code

2.11 Indices and tables

• genindex

2.11. Indices and tables 67

PYTHON MODULE INDEX

ppssh.clients.base.parallel, 39pssh.clients.base.single, 43pssh.clients.native.parallel, 26pssh.clients.native.single, 31pssh.clients.native.tunnel, 47pssh.clients.reader, 48pssh.clients.ssh.parallel, 35pssh.clients.ssh.single, 37pssh.config, 46pssh.constants, 50pssh.exceptions, 49pssh.output, 45pssh.utils, 49

69


70 Python Module Index

INDEX

Aallow_agent (pssh.config.HostConfig attribute), 47auth() (pssh.clients.base.single.BaseSSHClient

method), 43auth() (pssh.clients.ssh.single.SSHClient method), 38AuthenticationError, 49AuthenticationException (in module

pssh.exceptions), 49

BBaseParallelSSHClient (class in

pssh.clients.base.parallel), 39BaseSSHClient (class in pssh.clients.base.single), 43BufferData (class in pssh.output), 45buffers (pssh.output.HostOutput attribute), 46

Cchannel (pssh.output.HostOutput attribute), 46client (pssh.output.HostOutput attribute), 46close() (pssh.clients.base.single.InteractiveShell

method), 44close_channel() (pssh.clients.base.single.BaseSSHClient

method), 43close_channel() (pssh.clients.native.single.SSHClient

method), 32close_channel() (pssh.clients.ssh.single.SSHClient

method), 38ConcurrentRWBuffer (class in pssh.clients.reader),

48configure_keepalive()

(pssh.clients.native.single.SSHClient method),32

connect_auth() (pssh.clients.base.parallel.BaseParallelSSHClientmethod), 39

ConnectionError, 49ConnectionErrorException (in module

pssh.exceptions), 49copy_file() (pssh.clients.base.parallel.BaseParallelSSHClient

method), 39copy_file() (pssh.clients.base.single.BaseSSHClient

method), 43

copy_file() (pssh.clients.native.parallel.ParallelSSHClientmethod), 27

copy_file() (pssh.clients.native.single.SSHClientmethod), 32

copy_remote_file()(pssh.clients.base.parallel.BaseParallelSSHClientmethod), 40

copy_remote_file()(pssh.clients.base.single.BaseSSHClientmethod), 43

copy_remote_file()(pssh.clients.native.parallel.ParallelSSHClientmethod), 28

copy_remote_file()(pssh.clients.native.single.SSHClient method),32

DDEFAULT_RETRIES (in module pssh.constants), 50disconnect() (pssh.clients.base.single.BaseSSHClient

method), 43disconnect() (pssh.clients.native.single.SSHClient

method), 33disconnect() (pssh.clients.ssh.single.SSHClient

method), 38

Eeagain_write() (pssh.clients.native.single.SSHClient

method), 33enable_debug_logger() (in module pssh.utils), 49enable_host_logger() (in module pssh.utils), 49enable_logger() (in module pssh.utils), 49encoding (pssh.output.HostOutput attribute), 46enqueue() (pssh.clients.native.tunnel.LocalForwarder

method), 48eof (pssh.clients.reader.ConcurrentRWBuffer attribute),

48exception (pssh.output.HostOutput attribute), 46execute() (pssh.clients.base.single.BaseSSHClient

method), 43execute() (pssh.clients.native.single.SSHClient

method), 33

71


execute() (pssh.clients.ssh.single.SSHClient method),38

exit_code() (pssh.clients.base.single.InteractiveShellproperty), 45

exit_code() (pssh.output.HostOutput property), 46

Ffinished() (pssh.clients.base.parallel.BaseParallelSSHClient

method), 41finished() (pssh.clients.native.single.SSHClient

method), 33finished() (pssh.clients.ssh.single.SSHClient

method), 38flush() (pssh.clients.base.single.Stdin method), 45

Gget_exit_status()

(pssh.clients.base.single.BaseSSHClientmethod), 43

get_exit_status()(pssh.clients.native.single.SSHClient method),33

get_exit_status()(pssh.clients.ssh.single.SSHClient method),38

get_last_output()(pssh.clients.base.parallel.BaseParallelSSHClientmethod), 41

Hhost (pssh.output.HostOutput attribute), 46HostArgumentError, 49HostArgumentException (in module

pssh.exceptions), 49HostConfig (class in pssh.config), 46HostOutput (class in pssh.output), 45HostOutputBuffers (class in pssh.output), 46hosts() (pssh.clients.base.parallel.BaseParallelSSHClient

property), 42

IIDENTITIES (pssh.clients.base.single.BaseSSHClient

attribute), 44identity_auth (pssh.config.HostConfig attribute), 47InteractiveShell (class in

pssh.clients.base.single), 44

Jjoin() (pssh.clients.base.parallel.BaseParallelSSHClient

method), 41join_shells() (pssh.clients.base.parallel.BaseParallelSSHClient

method), 42

Kkeepalive_seconds (pssh.config.HostConfig at-

tribute), 47

Llisten_port() (pssh.clients.native.tunnel.TunnelServer

property), 48LocalForwarder (class in pssh.clients.native.tunnel),

47

Mmkdir() (pssh.clients.base.single.BaseSSHClient

method), 43mkdir() (pssh.clients.native.single.SSHClient method),

33module

pssh.clients.base.parallel, 39pssh.clients.base.single, 43pssh.clients.native.parallel, 26pssh.clients.native.single, 31pssh.clients.native.tunnel, 47pssh.clients.reader, 48pssh.clients.ssh.parallel, 35pssh.clients.ssh.single, 37pssh.config, 46pssh.constants, 50pssh.exceptions, 49pssh.output, 45pssh.utils, 49

Nnum_retries (pssh.config.HostConfig attribute), 47

Oopen_session() (pssh.clients.base.single.BaseSSHClient

method), 43open_session() (pssh.clients.native.single.SSHClient

method), 33open_session() (pssh.clients.ssh.single.SSHClient

method), 39open_shell() (pssh.clients.base.parallel.BaseParallelSSHClient

method), 42open_shell() (pssh.clients.base.single.BaseSSHClient

method), 43output (pssh.clients.base.single.InteractiveShell

attribute), 45

PParallelSSHClient (class in

pssh.clients.native.parallel), 26ParallelSSHClient (class in

pssh.clients.ssh.parallel), 35password (pssh.config.HostConfig attribute), 47

72 Index


PKeyFileError, 49poll() (pssh.clients.base.single.BaseSSHClient

method), 43poll() (pssh.clients.native.single.SSHClient method),

33poll() (pssh.clients.ssh.single.SSHClient method), 39port (pssh.config.HostConfig attribute), 47private_key (pssh.config.HostConfig attribute), 47proxy_host (pssh.config.HostConfig attribute), 47proxy_password (pssh.config.HostConfig attribute),

47proxy_pkey (pssh.config.HostConfig attribute), 47proxy_port (pssh.config.HostConfig attribute), 47proxy_user (pssh.config.HostConfig attribute), 47ProxyError, 49pssh.clients.base.parallel

module, 39pssh.clients.base.single

module, 43pssh.clients.native.parallel

module, 26pssh.clients.native.single

module, 31pssh.clients.native.tunnel

module, 47pssh.clients.reader

module, 48pssh.clients.ssh.parallel

module, 35pssh.clients.ssh.single

module, 37pssh.config

module, 46pssh.constants

module, 50pssh.exceptions

module, 49pssh.output

module, 45pssh.utils

module, 49

Rread() (pssh.clients.reader.ConcurrentRWBuffer

method), 48read_output() (pssh.clients.base.single.BaseSSHClient

method), 43read_output_buffer()

(pssh.clients.base.single.BaseSSHClientmethod), 43

read_stderr() (pssh.clients.base.single.BaseSSHClientmethod), 43

read_timeout (pssh.output.HostOutput attribute), 46reader (pssh.output.BufferData attribute), 45

reset_output_generators()(pssh.clients.base.parallel.BaseParallelSSHClientmethod), 42

RETRY_DELAY (in module pssh.constants), 50retry_delay (pssh.config.HostConfig attribute), 47run() (pssh.clients.base.single.InteractiveShell

method), 44run() (pssh.clients.native.tunnel.LocalForwarder

method), 48run_command() (pssh.clients.base.parallel.BaseParallelSSHClient

method), 42run_command() (pssh.clients.base.single.BaseSSHClient

method), 44run_command() (pssh.clients.native.parallel.ParallelSSHClient

method), 29run_command() (pssh.clients.ssh.parallel.ParallelSSHClient

method), 36run_shell_commands()

(pssh.clients.base.parallel.BaseParallelSSHClientmethod), 42

rw_buffer (pssh.output.BufferData attribute), 45

Sscp_recv() (pssh.clients.base.single.BaseSSHClient

method), 44scp_recv() (pssh.clients.native.parallel.ParallelSSHClient

method), 30scp_recv() (pssh.clients.native.single.SSHClient

method), 33scp_send() (pssh.clients.base.single.BaseSSHClient

method), 44scp_send() (pssh.clients.native.parallel.ParallelSSHClient

method), 31scp_send() (pssh.clients.native.single.SSHClient

method), 34SCPError, 49SessionError, 49sftp_get() (pssh.clients.base.single.BaseSSHClient

method), 44sftp_get() (pssh.clients.native.single.SSHClient

method), 34sftp_put() (pssh.clients.base.single.BaseSSHClient

method), 44sftp_put() (pssh.clients.native.single.SSHClient

method), 34SFTPError, 49SFTPIOError, 49ShellError, 49shutdown() (pssh.clients.native.tunnel.LocalForwarder

method), 48spawn_send_keepalive()

(pssh.clients.native.single.SSHClient method),34

SSHClient (class in pssh.clients.native.single), 31

Index 73


SSHClient (class in pssh.clients.ssh.single), 37SSHError, 49SSHException (in module pssh.exceptions), 49stderr (pssh.output.HostOutputBuffers attribute), 46stderr() (pssh.clients.base.single.InteractiveShell

property), 45stderr() (pssh.output.HostOutput property), 46Stdin (class in pssh.clients.base.single), 45stdin (pssh.output.HostOutput attribute), 46stdin() (pssh.clients.base.single.InteractiveShell

property), 45stdout (pssh.output.HostOutputBuffers attribute), 46stdout() (pssh.clients.base.single.InteractiveShell

property), 45stdout() (pssh.output.HostOutput property), 46

TTimeout, 49timeout (pssh.config.HostConfig attribute), 47TunnelServer (class in pssh.clients.native.tunnel), 48

UUnknownHostError, 50UnknownHostException (in module

pssh.exceptions), 50user (pssh.config.HostConfig attribute), 47

Wwait_finished() (pssh.clients.base.single.BaseSSHClient

method), 44wait_finished() (pssh.clients.native.single.SSHClient

method), 34wait_finished() (pssh.clients.ssh.single.SSHClient

method), 39write() (pssh.clients.base.single.Stdin method), 45write() (pssh.clients.reader.ConcurrentRWBuffer

method), 48

74 Index

parallel-ssh documentation · 2019. 4. 2. · parallel-ssh documentation, release 1.9.1+1.gcf2b65e...

Documents