0
# Parallel SSH
1
2
Asynchronous parallel SSH client library that enables developers to execute SSH commands across many servers simultaneously with minimal system load on the client host. Built on mature C libraries (libssh2 and libssh) providing thread safety, native asynchronous execution, and significantly reduced CPU and memory overhead compared to other Python SSH libraries.
3
4
## Package Information
5
6
- **Package Name**: parallel-ssh
7
- **Language**: Python
8
- **Installation**: `pip install parallel-ssh`
9
10
## Core Imports
11
12
```python
13
from pssh.clients import ParallelSSHClient, SSHClient
14
```
15
16
Alternative SSH implementation (libssh-based):
17
18
```python
19
from pssh.clients.ssh import ParallelSSHClient, SSHClient
20
```
21
22
Configuration and utilities:
23
24
```python
25
from pssh.config import HostConfig
26
from pssh.utils import enable_host_logger, enable_debug_logger
27
```
28
29
## Basic Usage
30
31
```python
32
from pssh.clients import ParallelSSHClient
33
34
# Execute commands on multiple hosts in parallel
35
hosts = ['host1.example.com', 'host2.example.com', 'host3.example.com']
36
client = ParallelSSHClient(hosts)
37
38
# Run a command on all hosts
39
output = client.run_command('uname -a')
40
41
# Wait for completion and get results
42
client.join()
43
for host_output in output:
44
print(f"Host: {host_output.host}")
45
for line in host_output.stdout:
46
print(line)
47
print(f"Exit code: {host_output.exit_code}")
48
49
# Single host usage
50
from pssh.clients import SSHClient
51
52
client = SSHClient('host.example.com')
53
host_output = client.run_command('ls -la')
54
for line in host_output.stdout:
55
print(line)
56
```
57
58
## Architecture
59
60
The library provides two main client implementations:
61
62
- **Native Client** (default): Based on `ssh2-python` (libssh2 C library) offering highest performance and stability
63
- **SSH Client**: Alternative implementation using `ssh-python` (libssh C library) with identical API
64
65
Both implementations support:
66
- **Parallel execution** across hundreds or thousands of hosts
67
- **Thread-safe operations** with native threading for CPU-bound tasks like authentication
68
- **Asynchronous I/O** using gevent for non-blocking operations
69
- **Comprehensive file transfer** via both SFTP and SCP protocols
70
- **Flexible authentication** including SSH keys, passwords, and SSH agent integration
71
- **Advanced networking** with proxy support and IPv6 capabilities
72
73
## Capabilities
74
75
### Parallel SSH Operations
76
77
Execute commands across multiple hosts simultaneously with comprehensive configuration options, authentication methods, and result handling.
78
79
```python { .api }
80
class ParallelSSHClient:
81
def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
82
num_retries=3, timeout=None, pool_size=100, allow_agent=True,
83
host_config=None, retry_delay=5, proxy_host=None, proxy_port=None,
84
proxy_user=None, proxy_password=None, proxy_pkey=None,
85
forward_ssh_agent=False, keepalive_seconds=60, identity_auth=True,
86
ipv6_only=False): ...
87
88
def run_command(self, command, sudo=False, user=None, stop_on_errors=True,
89
use_pty=False, host_args=None, shell=None, encoding='utf-8',
90
read_timeout=None): ...
91
92
def join(self, output=None, consume_output=False, timeout=None): ...
93
```
94
95
[Parallel Operations](./parallel-operations.md)
96
97
### Single Host SSH Operations
98
99
Connect to and execute commands on individual hosts with the same rich feature set as parallel operations, ideal for single-host workflows.
100
101
```python { .api }
102
class SSHClient:
103
def __init__(self, host, user=None, password=None, port=None, pkey=None,
104
alias=None, num_retries=3, retry_delay=5, allow_agent=True,
105
timeout=None, forward_ssh_agent=False, proxy_host=None,
106
proxy_port=None, proxy_pkey=None, proxy_user=None,
107
proxy_password=None, keepalive_seconds=60, identity_auth=True,
108
ipv6_only=False): ...
109
110
def run_command(self, command, sudo=False, user=None, use_pty=False,
111
shell=None, encoding='utf-8', timeout=None, read_timeout=None): ...
112
```
113
114
[Single Host Operations](./single-host-operations.md)
115
116
### File Transfer Operations
117
118
High-performance file copying between local and remote hosts using both SFTP and SCP protocols, with support for recursive directory operations and per-host file naming.
119
120
```python { .api }
121
# SFTP operations
122
def copy_file(self, local_file, remote_file, recurse=False, copy_args=None): ...
123
def copy_remote_file(self, remote_file, local_file, recurse=False,
124
suffix_separator='_', copy_args=None, encoding='utf-8'): ...
125
126
# SCP operations
127
def scp_send(self, local_file, remote_file, recurse=False, copy_args=None): ...
128
def scp_recv(self, remote_file, local_file, recurse=False, copy_args=None,
129
suffix_separator='_'): ...
130
```
131
132
[File Transfer](./file-transfer.md)
133
134
### Configuration and Host Management
135
136
Flexible per-host configuration system allowing different authentication methods, connection parameters, and proxy settings for individual hosts within parallel operations.
137
138
```python { .api }
139
class HostConfig:
140
def __init__(self, user=None, port=None, password=None, private_key=None,
141
allow_agent=None, alias=None, num_retries=None, retry_delay=None,
142
timeout=None, identity_auth=None, proxy_host=None, proxy_port=None,
143
proxy_user=None, proxy_password=None, proxy_pkey=None,
144
keepalive_seconds=None, ipv6_only=None, cert_file=None,
145
auth_thread_pool=True, gssapi_auth=False,
146
gssapi_server_identity=None, gssapi_client_identity=None,
147
gssapi_delegate_credentials=False, forward_ssh_agent=False): ...
148
```
149
150
[Configuration](./configuration.md)
151
152
### Interactive Shell Sessions
153
154
Open and manage interactive shell sessions on remote hosts for complex multi-command workflows and real-time interaction.
155
156
```python { .api }
157
def open_shell(self, encoding='utf-8', read_timeout=None): ...
158
159
class InteractiveShell:
160
def run(self, cmd): ...
161
def close(self): ...
162
def __enter__(self): ... # Context manager support
163
def __exit__(self, exc_type, exc_val, exc_tb): ...
164
# Properties: stdout, stderr, stdin, exit_code, output
165
166
class Stdin:
167
def write(self, data): ...
168
def flush(self): ...
169
```
170
171
[Interactive Shells](./interactive-shells.md)
172
173
### Output Processing and Result Handling
174
175
Comprehensive result objects providing access to command output, exit codes, and execution metadata for both parallel and single-host operations.
176
177
```python { .api }
178
class HostOutput:
179
# Properties
180
host: str
181
alias: str
182
channel: object
183
stdin: object
184
stdout: generator # Yields output lines
185
stderr: generator # Yields error lines
186
exit_code: int # Command exit code (None until ready)
187
client: object # Reference to SSH client
188
exception: Exception # Exception if any occurred
189
```
190
191
[Output Handling](./output-handling.md)
192
193
## Types
194
195
```python { .api }
196
# Core exceptions
197
class UnknownHostError(Exception): ...
198
class ConnectionError(Exception): ...
199
class AuthenticationError(Exception): ...
200
class Timeout(Exception): ...
201
class SessionError(Exception): ...
202
class SFTPError(Exception): ...
203
class SFTPIOError(SFTPError): ...
204
class SCPError(Exception): ...
205
class ProxyError(Exception): ...
206
class HostArgumentError(Exception): ...
207
class ShellError(Exception): ...
208
class PKeyFileError(Exception): ...
209
class NoIPv6AddressFoundError(Exception): ...
210
class HostConfigError(Exception): ...
211
212
# Constants
213
DEFAULT_RETRIES = 3
214
RETRY_DELAY = 5
215
```