Skip to content

Commit 722d4b6

Browse files
author
Dan
committed
Updated readme
1 parent 4067220 commit 722d4b6

File tree

1 file changed

+73
-84
lines changed

1 file changed

+73
-84
lines changed

‎README.rst‎

Lines changed: 73 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -22,102 +22,126 @@ Run SSH commands over many - hundreds/hundreds of thousands - number of servers
2222

2323
.. _`read the docs`: http://parallel-ssh.readthedocs.org/en/latest/
2424

25-
.. contents:: Table of Contents
25+
.. contents::
2626

2727
************
2828
Installation
2929
************
3030

31-
::
31+
.. code-block:: shell
3232
3333
pip install parallel-ssh
3434
35-
As of version ``0.93.0`` ``pip`` version >= ``6.0.0`` is required for Python 2.6 compatibility with latest versions of gevent which have dropped 2.6 support. This limitation will be removed post ``1.0.0`` releases which will deprecate ``2.6`` support.
36-
37-
To upgrade ``pip`` run the following - use of ``virtualenv`` is recommended so as not to override system provided packages::
38-
39-
pip install -U pip
40-
pip install parallel-ssh
41-
4235
*************
4336
Usage Example
4437
*************
4538

4639
See documentation on `read the docs`_ for more complete examples.
4740

41+
4842
Run ``ls`` on two remote hosts in parallel with ``sudo``.
4943

50-
::
44+
.. code-block:: python
5145
5246
from pprint import pprint
5347
from pssh.pssh_client import ParallelSSHClient
5448
5549
hosts = ['myhost1', 'myhost2']
5650
client = ParallelSSHClient(hosts)
51+
5752
output = client.run_command('ls -ltrh /tmp/', sudo=True)
5853
pprint(output)
59-
{'myhost1':
60-
host=myhost1
61-
cmd=<Greenlet>
62-
channel=<channel>
63-
stdout=<generator>
64-
stderr=<generator>
65-
stdin=<channel>
66-
exception=None
67-
'myhost2':
68-
<..>
69-
}
54+
55+
:Output:
56+
57+
.. code-block:: python
58+
59+
{'myhost1':
60+
host=myhost1
61+
cmd=<Greenlet>
62+
channel=<channel>
63+
stdout=<generator>
64+
stderr=<generator>
65+
stdin=<channel>
66+
exception=None
67+
'myhost2':
68+
<..>
69+
}
7070
7171
Standard output buffers are available in output object. Iterating on them can be used to get output as it becomes available. Iteration ends *only when command has finished*, though it may be interrupted and resumed at any point.
7272

73-
`Host output <http://parallel-ssh.readthedocs.io/en/latest/output.html>`_ attributes are available in per-host output dictionary, for example ``output['myhost1'].stdout``.
73+
`Host output <http://parallel-ssh.readthedocs.io/en/latest/output.html>`_ attributes are available in host output object, for example ``output['myhost1'].stdout``.
7474

75-
::
75+
.. code-block:: python
7676
7777
for host in output:
7878
for line in output[host].stdout:
7979
pprint("Host %s - output: %s" % (host, line))
80-
Host myhost1 - output: drwxr-xr-x 6 xxx xxx 4.0K Jan 1 00:00 xxx
81-
Host myhost1 - output: <..>
82-
Host myhost2 - output: drwxr-xr-x 6 xxx xxx 4.0K Jan 1 00:00 xxx
83-
Host myhost2 - output: <..>
80+
81+
:Output:
82+
83+
.. code-block:: shell
84+
85+
Host myhost1 - output: drwxr-xr-x 6 xxx xxx 4.0K Jan 1 00:00 xxx
86+
Host myhost1 - output: <..>
87+
Host myhost2 - output: drwxr-xr-x 6 xxx xxx 4.0K Jan 1 00:00 xxx
88+
Host myhost2 - output: <..>
8489
8590
Exit codes become available once output is iterated on to completion *or* ``client.join(output)`` is called.
8691

87-
::
92+
.. code-block:: python
8893
8994
for host in output:
9095
print(output[host].exit_code)
91-
0
92-
0
9396
94-
The client's ``join`` function can be used to block and wait for all parallel commands to finish::
97+
:Output:
98+
.. code-block:: python
99+
100+
0
101+
0
102+
103+
The client's ``join`` function can be used to block and wait for all parallel commands to finish:
104+
105+
.. code-block:: python
95106
96107
client.join(output)
97108
98-
Similarly, output and exit codes are available after ``client.join`` is called::
109+
Similarly, output and exit codes are available after ``client.join`` is called:
110+
111+
.. code-block:: python
99112
100113
output = client.run_command('exit 0')
114+
101115
# Block and gather exit codes. Output is updated in-place
102116
client.join(output)
103117
pprint(output.values()[0].exit_code)
104-
0
118+
105119
# Output is available
106120
for line in output.values()[0].stdout:
107121
pprint(line)
108-
<..stdout..>
122+
123+
:Output:
124+
.. code-block:: python
125+
126+
0
127+
<..stdout..>
109128
110129
.. note::
111130

112131
In versions prior to ``1.0.0`` only, ``client.join`` would consume standard output.
113132

114-
There is also a built in host logger that can be enabled to log output from remote hosts. The helper function ``pssh.utils.enable_host_logger`` will enable host logging to stdout, for example ::
133+
There is also a built in host logger that can be enabled to log output from remote hosts. The helper function ``pssh.utils.enable_host_logger`` will enable host logging to stdout, for example:
134+
135+
.. code-block:: python
115136
116137
import pssh.utils
117138
pssh.utils.enable_host_logger()
118139
client.join(client.run_command('uname'))
119-
120-
[localhost] Linux
140+
141+
:Output:
142+
.. code-block:: shell
143+
144+
[localhost] Linux
121145
122146
*****************
123147
Design And Goals
@@ -154,9 +178,11 @@ Output *generation* is done remotely and has no effect on the event loop until o
154178
SFTP/SCP
155179
********
156180

157-
SFTP is supported (SCP version 2) natively, no ``scp`` command required.
181+
SFTP is supported (SCP version 2) natively, no ``scp`` binary required.
158182

159-
For example to copy a local file to remote hosts in parallel::
183+
For example to copy a local file to remote hosts in parallel:
184+
185+
.. code-block:: python
160186
161187
from pssh import ParallelSSHClient, utils
162188
from gevent import joinall
@@ -166,15 +192,18 @@ For example to copy a local file to remote hosts in parallel::
166192
client = ParallelSSHClient(hosts)
167193
greenlets = client.copy_file('../test', 'test_dir/test')
168194
joinall(greenlets, raise_error=True)
169-
170-
Copied local file ../test to remote destination myhost1:test_dir/test
171-
Copied local file ../test to remote destination myhost2:test_dir/test
195+
196+
:Output:
197+
.. code-block:: python
198+
199+
Copied local file ../test to remote destination myhost1:test_dir/test
200+
Copied local file ../test to remote destination myhost2:test_dir/test
172201
173202
There is similar capability to copy remote files to local ones suffixed with the host's name with the ``copy_remote_file`` function.
174203

175204
Directory recursion is supported in both cases via the ``recurse`` parameter - defaults to off.
176205

177-
See `copy_file <http://parallel-ssh.readthedocs.io/en/latest/pssh_client.html#pssh.pssh_client.ParallelSSHClient.copy_file>`_ and `copy_remote_file <http://parallel-ssh.readthedocs.io/en/latest/pssh_client.html#pssh.pssh_client.ParallelSSHClient.copy_remote_file>`_ documentation for more examples.
206+
See `SFTP documentation <http://parallel-ssh.readthedocs.io/en/latest/advanced.html#sftp>`_ for more examples.
178207

179208
**************************
180209
Frequently asked questions
@@ -186,7 +215,7 @@ Frequently asked questions
186215
:A:
187216
In short, the tools are intended for different use cases.
188217

189-
``ParallelSSH`` satisfies uses cases for a parallel SSH client library that scales well over hundreds to hundreds of thousands of hosts - per `Design And Goals`_ - a use case that is very common on cloud platforms and virtual machine automation. It would be best used where it is a good fit for the use case at hand.
218+
``ParallelSSH`` is a parallel SSH client library that scales well over hundreds to hundreds of thousands of hosts - per `Design And Goals`_ - a use case that is very common on cloud platforms and virtual machine automation. It would be best used where it is a good fit for the use case at hand.
190219

191220
Fabric and tools like it on the other hand are not well suited to such use cases, for many reasons, performance and differing design goals in particular. The similarity is only that these tools also make use of SSH to run commands.
192221

@@ -212,48 +241,8 @@ Frequently asked questions
212241

213242
Though ``ParallelSSH`` is pure python code and will run on any platform that has a working Python interpreter, its ``gevent`` dependency and certain dependencies of ``paramiko`` contain native code which either needs a binary package to be provided for the platform or to be built from source. Binary packages for ``gevent`` are provided for OSX, Linux and Windows platforms as of this time of writing.
214243

215-
:Q:
216-
Are SSH agents used?
217-
218-
:A:
219-
All available keys in a system configured SSH agent in addition to SSH keys in the user's home directory, `~/.ssh/id_dsa`, `~/.ssh/id_rsa` et al are automatically used by ParallelSSH.
220-
221-
Use of SSH agent can be disabled by creating a client as ``ParallelSSHClient(allow_agent=False)``. `See documentation <http://parallel-ssh.readthedocs.org/en/latest/>`_ for more information.
222-
223-
:Q:
224-
Can ParallelSSH forward my SSH agent?
225-
226-
:A:
227-
SSH agent forwarding, what ``ssh -A`` does on the command line, is supported and enabled by default. Creating an object as ``ParallelSSHClient(forward_ssh_agent=False)`` will disable this behaviour.
228-
229-
:Q:
230-
Is tunneling/proxying supported?
231-
232-
:A:
233-
Yes, `ParallelSSH` natively supports tunelling - also known as proxying - through an intermediate SSH server. Connecting to a remote host is accomplished via an SSH tunnel using the SSH's protocol direct TCP tunneling feature, using local port forwarding. This is done natively in python and tunnel connections are asynchronous like all other connections in the `ParallelSSH` library. For example, client -> proxy SSH server -> remote SSH destination.
234-
235-
Use the ``proxy_host`` and ``proxy_port`` parameters to configure your proxy::
236-
237-
client = ParallelSSHClient(hosts, proxy_host='my_ssh_proxy_host')
238-
239-
Note that while connections from the ParallelSSH `client` to the tunnel host are asynchronous, connections from the tunnel host to the remote destination(s) may not be, depending on the SSH server implementation. If the SSH server uses threading to implement its tunelling and that server is used to tunnel to a large number of remote destinations system load on the tunnel server will increase linearly with number of threads used.
240-
241-
:Q:
242-
Is there a way to programmatically provide an SSH key?
243-
244-
:A:
245-
Yes, use the ``pkey`` parameter of the `ParallelSSHClient class`_. There is also a ``load_private_key`` helper function in ``pssh.utils`` that can be used to load any supported key type. See `ParallelSSHClient class`_ documentation for examples.
246-
247-
:Q:
248-
Is there a way to programmatically provide an SSH agent?
249-
250-
:A:
251-
Yes, with the ``SSHAgent`` class that can be provided via the ``agent`` class parameter of `ParallelSSHClient class`_. Supplying an agent object in this way overrides use of the system's SSH agent, if any. See `SSHAgent documentation <http://parallel-ssh.readthedocs.io/en/latest/agent.html>`_ for an example.
252-
253244
:Q:
254245
Is there a user's group for feedback and discussion about ParallelSSH?
255246

256247
:A:
257248
There is a public `ParallelSSH Google group <https://groups.google.com/forum/#!forum/parallelssh>`_ setup for this purpose - both posting and viewing are open to the public.
258-
259-
.. _`ParallelSSHClient class`: http://parallel-ssh.readthedocs.io/en/latest/pssh_client.html#module-pssh.pssh_client

0 commit comments

Comments
 (0)