0
# Configuration and Host Management
1

2
Flexible per-host configuration system allowing different authentication methods, connection parameters, and proxy settings for individual hosts within parallel operations. Enables fine-grained control over SSH connections and authentication.
3

4
## Capabilities
5

6
### HostConfig Class
7

8
Configure individual host settings within a ParallelSSHClient for hosts that require different authentication methods, ports, proxy settings, or other connection parameters.
9

10
```python { .api }
11
class HostConfig:
12
    def __init__(self, user=None, port=None, password=None, private_key=None,
13
                 allow_agent=None, alias=None, num_retries=None, retry_delay=None,
14
                 timeout=None, identity_auth=None, proxy_host=None, proxy_port=None,
15
                 proxy_user=None, proxy_password=None, proxy_pkey=None,
16
                 keepalive_seconds=None, ipv6_only=None, cert_file=None,
17
                 auth_thread_pool=True, gssapi_auth=False,
18
                 gssapi_server_identity=None, gssapi_client_identity=None,
19
                 gssapi_delegate_credentials=False, forward_ssh_agent=False):
20
        """
21
        Per-host configuration for ParallelSSHClient.
22

23
        Parameters:
24
        - user (str, optional): Username for this host
25
        - port (int, optional): SSH port for this host
26
        - password (str, optional): Password for this host
27
        - private_key (str or bytes, optional): Private key file path or key data
28
        - allow_agent (bool, optional): Enable SSH agent for this host
29
        - alias (str, optional): Alias name for this host
30
        - num_retries (int, optional): Retry attempts for this host
31
        - retry_delay (float, optional): Delay between retries for this host
32
        - timeout (float, optional): Connection timeout for this host
33
        - identity_auth (bool, optional): Enable identity file auth for this host
34
        - proxy_host (str, optional): SSH proxy hostname for this host
35
        - proxy_port (int, optional): SSH proxy port for this host
36
        - proxy_user (str, optional): SSH proxy username for this host
37
        - proxy_password (str, optional): SSH proxy password for this host
38
        - proxy_pkey (str or bytes, optional): SSH proxy private key for this host
39
        - keepalive_seconds (int, optional): Keepalive interval for this host
40
        - ipv6_only (bool, optional): IPv6 only mode for this host
41
        - cert_file (str or bytes, optional): Certificate file for authentication
42
        - auth_thread_pool (bool, optional): Use thread pool for auth (default: True)
43
        - gssapi_auth (bool, optional): Enable GSSAPI authentication (ssh client only)
44
        - gssapi_server_identity (str, optional): GSSAPI server identity (ssh client only)
45
        - gssapi_client_identity (str, optional): GSSAPI client identity (ssh client only)
46
        - gssapi_delegate_credentials (bool, optional): Delegate credentials (ssh client only)
47
        - forward_ssh_agent (bool, optional): SSH agent forwarding (default: False)
48
        """
49
```
50

51
### Per-Host Configuration Examples
52

53
Configure different authentication methods and connection settings for individual hosts within a parallel client.
54

55
```python
56
from pssh.clients import ParallelSSHClient
57
from pssh.config import HostConfig
58

59
# Different authentication per host
60
hosts = ['web1.example.com', 'web2.example.com', 'db.example.com']
61
host_config = [
62
    HostConfig(user='web_admin', password='web_pass', port=22),           # web1
63
    HostConfig(user='web_admin', private_key='~/.ssh/web_key', port=22),  # web2  
64
    HostConfig(user='db_admin', private_key='~/.ssh/db_key', port=3306)   # db (custom port)
65
]
66

67
client = ParallelSSHClient(hosts, host_config=host_config)
68

69
# Different proxy settings per host
70
host_config = [
71
    HostConfig(user='admin'),  # web1 - direct connection
72
    HostConfig(               # web2 - through proxy
73
        user='admin',
74
        proxy_host='bastion.example.com',
75
        proxy_user='proxy_user',
76
        proxy_pkey='~/.ssh/proxy_key'
77
    ),
78
    HostConfig(               # db - through different proxy
79
        user='db_admin', 
80
        proxy_host='db-bastion.example.com',
81
        proxy_user='db_proxy',
82
        proxy_password='proxy_pass'
83
    )
84
]
85

86
client = ParallelSSHClient(hosts, host_config=host_config)
87
```
88

89
### Advanced Authentication Configuration
90

91
Configure complex authentication scenarios including GSSAPI, certificate-based authentication, and SSH agent forwarding.
92

93
```python
94
# Mixed authentication methods
95
host_config = [
96
    HostConfig(                           # Host 1: SSH key authentication
97
        user='admin',
98
        private_key='/path/to/admin.key',
99
        allow_agent=False,
100
        identity_auth=False
101
    ),
102
    HostConfig(                           # Host 2: SSH agent authentication
103
        user='admin',
104
        allow_agent=True,
105
        identity_auth=True,
106
        forward_ssh_agent=True
107
    ),
108
    HostConfig(                           # Host 3: GSSAPI authentication (ssh client only)
109
        user='admin',
110
        gssapi_auth=True,
111
        gssapi_server_identity='host/server.example.com',
112
        gssapi_client_identity='admin@EXAMPLE.COM',
113
        gssapi_delegate_credentials=True
114
    ),
115
    HostConfig(                           # Host 4: Certificate authentication
116
        user='admin',
117
        cert_file='/path/to/admin.crt',
118
        private_key='/path/to/admin.key'
119
    )
120
]
121

122
# Note: GSSAPI features require pssh.clients.ssh implementation
123
from pssh.clients.ssh import ParallelSSHClient
124
client = ParallelSSHClient(hosts, host_config=host_config)
125
```
126

127
### Connection and Retry Configuration
128

129
Customize connection behavior, timeouts, and retry logic on a per-host basis.
130

131
```python
132
# Different timeout and retry settings per host type
133
host_config = [
134
    HostConfig(                           # Local network host - short timeouts
135
        user='admin',
136
        timeout=10,
137
        num_retries=2,
138
        retry_delay=2,
139
        keepalive_seconds=30
140
    ),
141
    HostConfig(                           # Remote host - longer timeouts  
142
        user='admin',
143
        timeout=30,
144
        num_retries=5,
145
        retry_delay=10,
146
        keepalive_seconds=120
147
    ),
148
    HostConfig(                           # Unreliable host - very patient settings
149
        user='admin',
150
        timeout=60,
151
        num_retries=10,
152
        retry_delay=30,
153
        keepalive_seconds=240
154
    )
155
]
156

157
client = ParallelSSHClient(hosts, host_config=host_config)
158
```
159

160
### IPv6 and Network Configuration
161

162
Configure network-specific settings including IPv6-only connections and custom port configurations.
163

164
```python
165
# Network-specific configurations
166
host_config = [
167
    HostConfig(                           # IPv4 host with standard port
168
        user='admin',
169
        port=22,
170
        ipv6_only=False
171
    ),
172
    HostConfig(                           # IPv6-only host
173
        user='admin', 
174
        port=22,
175
        ipv6_only=True
176
    ),
177
    HostConfig(                           # Custom SSH port
178
        user='admin',
179
        port=2222,
180
        ipv6_only=False
181
    ),
182
    HostConfig(                           # Host behind NAT with port forwarding
183
        user='admin',
184
        port=22022,  # Forwarded port
185
        timeout=45    # Longer timeout for NAT traversal
186
    )
187
]
188

189
# IPv6 addresses can be used directly
190
hosts = [
191
    'server1.example.com',               # IPv4/IPv6 hostname
192
    '2001:db8::1',                       # IPv6 address
193
    '192.168.1.100',                     # IPv4 address  
194
    '[2001:db8::2]:2222'                 # IPv6 address with port
195
]
196

197
client = ParallelSSHClient(hosts, host_config=host_config)
198
```
199

200
## Host Alias Management
201

202
Use aliases to identify hosts in output and logging, especially useful when working with IP addresses or complex hostnames.
203

204
```python
205
# Using aliases for better identification
206
hosts = ['192.168.1.10', '192.168.1.20', '10.0.0.5']
207
host_config = [
208
    HostConfig(user='admin', alias='web-server-1'),
209
    HostConfig(user='admin', alias='web-server-2'),  
210
    HostConfig(user='admin', alias='database-server')
211
]
212

213
client = ParallelSSHClient(hosts, host_config=host_config)
214
output = client.run_command('hostname')
215

216
# Output will show aliases instead of IP addresses
217
for host_output in output:
218
    print(f"Alias: {host_output.alias}, Host: {host_output.host}")
219
    # Output: Alias: web-server-1, Host: 192.168.1.10
220
```
221

222
## Configuration Validation
223

224
HostConfig performs automatic validation of configuration parameters to catch common errors early.
225

226
```python
227
from pssh.config import HostConfig
228

229
try:
230
    # Invalid configurations will raise ValueError
231
    config = HostConfig(port="invalid_port")  # Should be int
232
except ValueError as e:
233
    print(f"Configuration error: {e}")
234

235
try:
236
    config = HostConfig(num_retries=-1)  # Should be positive
237
except ValueError as e:
238
    print(f"Configuration error: {e}")
239

240
try:
241
    config = HostConfig(timeout="not_a_number")  # Should be int or float
242
except ValueError as e:
243
    print(f"Configuration error: {e}")
244
```
245

246
## Best Practices
247

248
### Security Considerations
249

250
```python
251
# Prefer key-based authentication over passwords
252
host_config = [
253
    HostConfig(
254
        user='admin',
255
        private_key='~/.ssh/id_rsa',    # Key file
256
        password=None,                   # No password storage
257
        allow_agent=True                 # Use SSH agent when available
258
    )
259
]
260

261
# For environments requiring password auth, consider using environment variables
262
import os
263
host_config = [
264
    HostConfig(
265
        user='admin',
266
        password=os.getenv('SSH_PASSWORD'),  # From environment
267
        allow_agent=False,
268
        identity_auth=False
269
    )
270
]
271
```
272

273
### Performance Optimization
274

275
```python
276
# Optimize authentication performance
277
host_config = [
278
    HostConfig(
279
        user='admin',
280
        private_key='~/.ssh/id_rsa',
281
        auth_thread_pool=True,           # Use thread pool for auth (default)
282
        allow_agent=False,               # Disable if not needed
283
        identity_auth=False,             # Disable if using specific key
284
        keepalive_seconds=60             # Reasonable keepalive interval
285
    )
286
]
287

288
# For high-latency connections
289
host_config = [
290
    HostConfig(
291
        user='admin',
292
        timeout=120,                     # Longer timeout
293
        keepalive_seconds=300,           # Longer keepalive
294
        num_retries=3,                   # Reasonable retry count
295
        retry_delay=15                   # Longer retry delay
296
    )
297
]
298
```
299

300
### Configuration Templates
301

302
```python
303
# Create reusable configuration templates
304
def create_web_server_config(user='web_admin', key_path='~/.ssh/web_key'):
305
    return HostConfig(
306
        user=user,
307
        private_key=key_path,
308
        port=22,
309
        timeout=30,
310
        num_retries=3,
311
        keepalive_seconds=60
312
    )
313

314
def create_database_config(user='db_admin', key_path='~/.ssh/db_key'):
315
    return HostConfig(
316
        user=user,
317
        private_key=key_path,
318
        port=3306,  # Custom port for database hosts
319
        timeout=60,
320
        num_retries=5,
321
        keepalive_seconds=120
322
    )
323

324
# Apply templates to host groups
325
web_hosts = ['web1.example.com', 'web2.example.com']
326
db_hosts = ['db1.example.com', 'db2.example.com']
327

328
hosts = web_hosts + db_hosts
329
host_config = (
330
    [create_web_server_config() for _ in web_hosts] +
331
    [create_database_config() for _ in db_hosts]
332
)
333

334
client = ParallelSSHClient(hosts, host_config=host_config)
335
```