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
```