0
# Parallel SSH Operations
1

2
Execute commands across multiple hosts simultaneously with comprehensive configuration options, authentication methods, and result handling. Built for high performance and scalability with minimal system load on the client host.
3

4
## Capabilities
5

6
### ParallelSSHClient Initialization
7

8
Create a parallel SSH client for connecting to multiple hosts with shared or per-host configuration.
9

10
```python { .api }
11
class ParallelSSHClient:
12
    def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
13
                 num_retries=DEFAULT_RETRIES, timeout=None, pool_size=100,
14
                 allow_agent=True, host_config=None, retry_delay=RETRY_DELAY,
15
                 proxy_host=None, proxy_port=None, proxy_user=None, proxy_password=None,
16
                 proxy_pkey=None, forward_ssh_agent=False, keepalive_seconds=60,
17
                 identity_auth=True, ipv6_only=False):
18
        """
19
        Create parallel SSH client for multiple hosts.
20

21
        Parameters:
22
        - hosts (list[str]): List of hostnames or IP addresses
23
        - user (str, optional): Username for authentication 
24
        - password (str, optional): Password for authentication
25
        - port (int, optional): SSH port number (default: 22)
26
        - pkey (str or bytes, optional): Private key file path or key data
27
        - num_retries (int, optional): Connection retry attempts (default: 3)
28
        - timeout (float, optional): Global timeout in seconds for all operations
29
        - pool_size (int, optional): Greenlet pool size for concurrency (default: 100)
30
        - allow_agent (bool, optional): Use SSH agent authentication (default: True)
31
        - host_config (list[HostConfig], optional): Per-host configuration list
32
        - retry_delay (float, optional): Seconds between retries (default: 5)
33
        - proxy_host (str, optional): SSH proxy hostname
34
        - proxy_port (int, optional): SSH proxy port
35
        - proxy_user (str, optional): SSH proxy username  
36
        - proxy_password (str, optional): SSH proxy password
37
        - proxy_pkey (str or bytes, optional): SSH proxy private key
38
        - forward_ssh_agent (bool, optional): SSH agent forwarding (default: False)
39
        - keepalive_seconds (int, optional): Keepalive interval (default: 60)
40
        - identity_auth (bool, optional): Use default identity files (default: True)
41
        - ipv6_only (bool, optional): IPv6 addresses only (default: False)
42
        """
43
```
44

45
Usage example:
46

47
```python
48
from pssh.clients import ParallelSSHClient
49
from pssh.config import HostConfig
50

51
# Simple parallel client
52
hosts = ['web1.example.com', 'web2.example.com', 'db.example.com']
53
client = ParallelSSHClient(hosts, user='admin', port=22)
54

55
# With per-host configuration
56
host_config = [
57
    HostConfig(user='web_user', port=22),    # web1
58
    HostConfig(user='web_user', port=22),    # web2  
59
    HostConfig(user='db_user', port=2222)    # db (different port)
60
]
61
client = ParallelSSHClient(hosts, host_config=host_config)
62
```
63

64
### Parallel Command Execution
65

66
Execute commands on all hosts in parallel with comprehensive options for sudo, user switching, and output handling.
67

68
```python { .api }
69
def run_command(self, command, sudo=False, user=None, stop_on_errors=True,
70
               use_pty=False, host_args=None, shell=None, encoding='utf-8',
71
               read_timeout=None):
72
    """
73
    Execute command on all hosts in parallel.
74

75
    Parameters:
76
    - command (str): Command to execute
77
    - sudo (bool, optional): Run command with sudo (default: False)
78
    - user (str, optional): Run command as different user
79
    - stop_on_errors (bool, optional): Stop execution on first error (default: True)
80
    - use_pty (bool, optional): Use pseudo-terminal (default: False)
81
    - host_args (list, optional): Per-host command arguments
82
    - shell (str, optional): Shell to use for command execution
83
    - encoding (str, optional): Output encoding (default: 'utf-8')
84
    - read_timeout (float, optional): Per-host output read timeout
85

86
    Returns:
87
    list[HostOutput]: List of HostOutput objects containing results
88
    """
89
```
90

91
Usage examples:
92

93
```python
94
# Basic command execution
95
output = client.run_command('uptime')
96

97
# With sudo
98
output = client.run_command('systemctl status nginx', sudo=True)
99

100
# Run as different user
101
output = client.run_command('whoami', user='nginx')
102

103
# Per-host arguments
104
host_args = [
105
    {'command': 'ls /var/log/httpd'},    # web1
106
    {'command': 'ls /var/log/apache2'},  # web2  
107
    {'command': 'ls /var/log/mysql'}     # db
108
]
109
output = client.run_command(host_args=host_args)
110
```
111

112
### Connection Management
113

114
Establish connections and authenticate to all hosts, with control over the connection process.
115

116
```python { .api }
117
def connect_auth(self):
118
    """
119
    Connect and authenticate to all hosts.
120

121
    Returns:
122
    list[gevent.Greenlet]: List of greenlets for connection operations
123
    """
124

125
def finished(self, output=None):
126
    """
127
    Check if all commands in output have finished without blocking.
128

129
    Parameters:
130
    - output (list[HostOutput], optional): Output to check (default: last run_command)
131

132
    Returns:
133
    bool: True if all commands finished, False otherwise
134
    """
135
```
136

137
### Result Synchronization
138

139
Wait for command completion and control output consumption across all hosts.
140

141
```python { .api }
142
def join(self, output=None, consume_output=False, timeout=None):
143
    """
144
    Wait for all commands in output to complete.
145

146
    Parameters:
147
    - output (list[HostOutput], optional): Output to wait for (default: last run_command)
148
    - consume_output (bool, optional): Consume and discard output (default: False)
149
    - timeout (float, optional): Timeout in seconds for join operation
150

151
    Raises:
152
    - Timeout: If timeout is reached before completion
153
    """
154
```
155

156
Usage examples:
157

158
```python
159
# Execute and wait for completion
160
output = client.run_command('long_running_command')
161
client.join(output)
162

163
# Process results after completion
164
for host_output in output:
165
    print(f"Host {host_output.host} exit code: {host_output.exit_code}")
166
    for line in host_output.stdout:
167
        print(f"  {line}")
168

169
# Join with timeout
170
try:
171
    client.join(output, timeout=30)
172
except Timeout:
173
    print("Commands did not complete within 30 seconds")
174

175
# Consume output without reading (useful with host logger)
176
from pssh.utils import enable_host_logger
177
enable_host_logger()
178
output = client.run_command('echo "Hello from $(hostname)"')
179
client.join(output, consume_output=True)  # Output logged automatically
180
```
181

182
### Interactive Shell Management
183

184
Manage interactive shell sessions across multiple hosts with parallel shell operations and coordination.
185

186
```python { .api }
187
def open_shell(self, encoding='utf-8', read_timeout=None):
188
    """
189
    Open interactive shell sessions on all hosts.
190

191
    Parameters:
192
    - encoding (str, optional): Shell output encoding (default: 'utf-8')
193
    - read_timeout (float, optional): Timeout for reading shell output
194

195
    Returns:
196
    list[InteractiveShell]: List of interactive shell objects for all hosts
197
    """
198

199
def run_shell_commands(self, shells, commands):
200
    """
201
    Execute commands on multiple shell sessions.
202

203
    Parameters:
204
    - shells (list[InteractiveShell]): List of shell objects
205
    - commands (list[str]): Commands to execute on all shells
206

207
    Returns:
208
    list[gevent.Greenlet]: List of greenlets for shell operations
209
    """
210

211
def join_shells(self, shells, timeout=None):
212
    """
213
    Wait for shell operations to complete.
214

215
    Parameters:
216
    - shells (list[InteractiveShell]): Shell objects to wait for
217
    - timeout (float, optional): Timeout in seconds
218

219
    Raises:
220
    - Timeout: If timeout is reached before completion
221
    """
222
```
223

224
### Output Management
225

226
Advanced output and command management for parallel operations.
227

228
```python { .api }
229
def get_last_output(self, cmds=None):
230
    """
231
    Get output from last executed commands.
232

233
    Parameters:
234
    - cmds (list, optional): Specific commands to get output for
235

236
    Returns:
237
    list[HostOutput]: Output objects from last command execution
238
    """
239
```
240

241
## Error Handling
242

243
The parallel client provides comprehensive error handling for various failure scenarios:
244

245
```python
246
from pssh.exceptions import (
247
    UnknownHostError, ConnectionError, AuthenticationError,
248
    Timeout, HostArgumentError
249
)
250

251
try:
252
    client = ParallelSSHClient(['invalid-host.example.com'])
253
    output = client.run_command('echo test')
254
    client.join()
255
except UnknownHostError as e:
256
    print(f"DNS resolution failed: {e}")
257
except ConnectionError as e:
258
    print(f"Connection failed: {e}")  
259
except AuthenticationError as e:
260
    print(f"Authentication failed: {e}")
261
except Timeout as e:
262
    print(f"Operation timed out: {e}")
263
```
264

265
## Performance Considerations
266

267
- **Pool Size**: Adjust `pool_size` parameter based on system resources and network capacity
268
- **Timeouts**: Set appropriate `timeout` and `read_timeout` values for your network conditions  
269
- **Connection Reuse**: Keep client instances alive for multiple operations to avoid reconnection overhead
270
- **Memory Usage**: For very large host lists, consider batching operations or using streaming output consumption