0
# CLI Tools
1

2
Command-line utilities for running RPyC servers and registries. These tools provide ready-to-use server implementations and registry services that can be deployed without writing custom code.
3

4
## Capabilities
5

6
### RPyC Classic Server
7

8
Command-line classic RPyC server for remote Python execution and development.
9

10
```python { .api }
11
# Command: rpyc_classic or rpyc_classic.py
12
# Usage: rpyc_classic [OPTIONS]
13

14
# Options:
15
--host HOST                    # Host to bind to (default: 0.0.0.0)
16
--port PORT                    # Port to bind to (default: 18812)
17
--ssl-port PORT               # SSL port to bind to (default: 18821)
18
--ssl-keyfile FILE            # SSL private key file
19
--ssl-certfile FILE           # SSL certificate file
20
--ssl-cafile FILE             # SSL CA certificate file
21
--mode {stdio,threaded,forking,oneshot}  # Server mode (default: threaded)
22
--host-only                   # Bind to host only (not 0.0.0.0)
23
--ipv6                        # Enable IPv6
24
--logfile FILE                # Log file path
25
--quiet                       # Quiet mode (less logging)
26
--register                    # Register with registry server
27
--registry-host HOST          # Registry server host
28
--registry-port PORT          # Registry server port
29
--registry-type {UDP,TCP}     # Registry type (default: UDP)
30
--auto-register              # Auto-register service
31
```
32

33
### RPyC Registry Server
34

35
Command-line registry server for service discovery and management.
36

37
```python { .api }
38
# Command: rpyc_registry or rpyc_registry.py  
39
# Usage: rpyc_registry [OPTIONS]
40

41
# Options:
42
--host HOST                   # Host to bind to (default: 0.0.0.0)
43
--port PORT                   # Port to bind to (default: 18811)
44
--mode {UDP,TCP}             # Registry mode (default: UDP)
45
--logfile FILE               # Log file path
46
--quiet                      # Quiet mode (less logging)
47
--pruning-timeout SECONDS    # Service pruning timeout (default: 3)
48
--allow-listing              # Allow service listing requests (default: True)
49
```
50

51
### Server Modes
52

53
Different concurrency models available for the classic server.
54

55
```python { .api }
56
# Server mode options:
57

58
STDIO_MODE = 'stdio'          # Single connection via stdin/stdout
59
THREADED_MODE = 'threaded'    # Multi-threaded server (default)
60
FORKING_MODE = 'forking'      # Multi-process forking server (Unix only)
61
ONESHOT_MODE = 'oneshot'      # Single connection server
62
```
63

64
### Configuration Profiles
65

66
Pre-configured profiles for common deployment scenarios.
67

68
```python { .api }
69
# Built-in configuration profiles:
70

71
DEVELOPMENT_PROFILE = {
72
    'host': 'localhost',
73
    'port': 18812,
74
    'mode': 'threaded',
75
    'logfile': None,
76
    'quiet': False,
77
    'ssl': False
78
}
79

80
PRODUCTION_PROFILE = {
81
    'host': '0.0.0.0', 
82
    'port': 18812,
83
    'mode': 'forking',
84
    'logfile': '/var/log/rpyc.log',
85
    'quiet': True,
86
    'ssl': True
87
}
88

89
SECURE_PROFILE = {
90
    'ssl': True,
91
    'ssl_port': 18821,
92
    'ssl_keyfile': '/etc/ssl/private/rpyc.key',
93
    'ssl_certfile': '/etc/ssl/certs/rpyc.crt',
94
    'host_only': True
95
}
96
```
97

98
## Examples
99

100
### Basic Classic Server
101

102
```bash
103
# Start basic classic server on default port
104
rpyc_classic
105

106
# Start on specific host and port
107
rpyc_classic --host 192.168.1.100 --port 12345
108

109
# Start with forking mode for better performance
110
rpyc_classic --mode forking
111

112
# Start with logging
113
rpyc_classic --logfile /var/log/rpyc.log
114
```
115

116
### SSL Classic Server
117

118
```bash
119
# Start SSL server with certificates
120
rpyc_classic \
121
    --ssl-keyfile /path/to/server.key \
122
    --ssl-certfile /path/to/server.crt \
123
    --ssl-port 18821
124

125
# SSL server with client authentication
126
rpyc_classic \
127
    --ssl-keyfile server.key \
128
    --ssl-certfile server.crt \
129
    --ssl-cafile ca.crt \
130
    --ssl-port 18821
131
```
132

133
### Classic Server with Registry
134

135
```bash
136
# Start server and register with local registry
137
rpyc_classic --register
138

139
# Register with specific registry server
140
rpyc_classic \
141
    --register \
142
    --registry-host registry.example.com \
143
    --registry-port 18811 \
144
    --registry-type TCP
145

146
# Auto-register with service name
147
rpyc_classic --auto-register
148
```
149

150
### Registry Server
151

152
```bash
153
# Start UDP registry server (default)
154
rpyc_registry
155

156
# Start TCP registry server
157
rpyc_registry --mode TCP --port 18811
158

159
# Registry with custom settings
160
rpyc_registry \
161
    --host 0.0.0.0 \
162
    --port 18811 \
163
    --mode UDP \
164
    --pruning-timeout 5 \
165
    --logfile /var/log/rpyc-registry.log
166
```
167

168
### Development Setup
169

170
```bash
171
# Terminal 1: Start registry
172
rpyc_registry --logfile registry.log
173

174
# Terminal 2: Start classic server with registry
175
rpyc_classic --register --logfile server.log
176

177
# Terminal 3: Connect with Python client
178
python3 -c "
179
import rpyc
180
conn = rpyc.classic.connect('localhost')
181
print('Connected to:', conn.modules.socket.gethostname())
182
conn.close()
183
"
184
```
185

186
### Production Deployment
187

188
```bash
189
# Production registry server with TCP and logging
190
rpyc_registry \
191
    --mode TCP \
192
    --host 0.0.0.0 \
193
    --port 18811 \
194
    --logfile /var/log/rpyc-registry.log \
195
    --pruning-timeout 10
196

197
# Production classic server with SSL and forking
198
rpyc_classic \
199
    --mode forking \
200
    --host 0.0.0.0 \
201
    --port 18812 \
202
    --ssl-port 18821 \
203
    --ssl-keyfile /etc/ssl/private/rpyc.key \
204
    --ssl-certfile /etc/ssl/certs/rpyc.crt \
205
    --register \
206
    --registry-host localhost \
207
    --registry-type TCP \
208
    --logfile /var/log/rpyc-classic.log
209
```
210

211
### Docker Deployment
212

213
```bash
214
# Docker run with classic server
215
docker run -d \
216
    --name rpyc-server \
217
    -p 18812:18812 \
218
    -v /path/to/certs:/certs:ro \
219
    python:3.9 \
220
    rpyc_classic \
221
        --host 0.0.0.0 \
222
        --port 18812 \
223
        --ssl-port 18821 \
224
        --ssl-keyfile /certs/server.key \
225
        --ssl-certfile /certs/server.crt
226

227
# Docker run with registry
228
docker run -d \
229
    --name rpyc-registry \
230
    -p 18811:18811/udp \
231
    python:3.9 \
232
    rpyc_registry \
233
        --host 0.0.0.0 \
234
        --port 18811 \
235
        --mode UDP
236
```
237

238
### Systemd Service Configuration
239

240
```bash
241
# /etc/systemd/system/rpyc-classic.service
242
[Unit]
243
Description=RPyC Classic Server
244
After=network.target
245

246
[Service]
247
Type=simple
248
User=rpyc
249
Group=rpyc
250
ExecStart=/usr/local/bin/rpyc_classic \
251
    --mode forking \
252
    --host 0.0.0.0 \
253
    --port 18812 \
254
    --logfile /var/log/rpyc-classic.log \
255
    --register
256
Restart=always
257
RestartSec=10
258

259
[Install]
260
WantedBy=multi-user.target
261

262
# /etc/systemd/system/rpyc-registry.service  
263
[Unit]
264
Description=RPyC Registry Server
265
After=network.target
266

267
[Service]
268
Type=simple
269
User=rpyc
270
Group=rpyc
271
ExecStart=/usr/local/bin/rpyc_registry \
272
    --mode TCP \
273
    --host 0.0.0.0 \
274
    --port 18811 \
275
    --logfile /var/log/rpyc-registry.log
276
Restart=always
277
RestartSec=10
278

279
[Install]
280
WantedBy=multi-user.target
281

282
# Enable and start services
283
sudo systemctl enable rpyc-registry
284
sudo systemctl enable rpyc-classic
285
sudo systemctl start rpyc-registry
286
sudo systemctl start rpyc-classic
287
```
288

289
### High Availability Setup
290

291
```bash
292
# Load balancer configuration (nginx)
293
# /etc/nginx/sites-available/rpyc
294
upstream rpyc_servers {
295
    server 192.168.1.10:18812;
296
    server 192.168.1.11:18812;
297
    server 192.168.1.12:18812;
298
}
299

300
server {
301
    listen 18812;
302
    proxy_pass rpyc_servers;
303
    proxy_timeout 30s;
304
    proxy_connect_timeout 5s;
305
}
306

307
# Multiple server instances
308
# Server 1:
309
rpyc_classic \
310
    --host 192.168.1.10 \
311
    --port 18812 \
312
    --mode forking \
313
    --register \
314
    --registry-host 192.168.1.100
315

316
# Server 2:
317
rpyc_classic \
318
    --host 192.168.1.11 \
319
    --port 18812 \
320
    --mode forking \
321
    --register \
322
    --registry-host 192.168.1.100
323

324
# Server 3:
325
rpyc_classic \
326
    --host 192.168.1.12 \
327
    --port 18812 \
328
    --mode forking \
329
    --register \
330
    --registry-host 192.168.1.100
331

332
# Registry cluster
333
rpyc_registry \
334
    --host 192.168.1.100 \
335
    --port 18811 \
336
    --mode TCP
337
```
338

339
### SSL Certificate Management
340

341
```bash
342
# Generate self-signed certificates for development
343
openssl genrsa -out server.key 2048
344
openssl req -new -key server.key -out server.csr
345
openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crt
346

347
# Start server with generated certificates
348
rpyc_classic \
349
    --ssl-keyfile server.key \
350
    --ssl-certfile server.crt \
351
    --ssl-port 18821
352

353
# Use Let's Encrypt certificates for production
354
certbot certonly --standalone -d rpyc.yourdomain.com
355

356
rpyc_classic \
357
    --ssl-keyfile /etc/letsencrypt/live/rpyc.yourdomain.com/privkey.pem \
358
    --ssl-certfile /etc/letsencrypt/live/rpyc.yourdomain.com/fullchain.pem \
359
    --ssl-port 18821
360
```
361

362
### Monitoring and Health Checks
363

364
```bash
365
# Health check script
366
#!/bin/bash
367
# rpyc-health-check.sh
368

369
HOST=${1:-localhost}
370
PORT=${2:-18812}
371

372
# Test connection
373
python3 -c "
374
import rpyc
375
import sys
376
try:
377
    conn = rpyc.connect('$HOST', $PORT, config={'sync_request_timeout': 5})
378
    conn.ping()
379
    conn.close()
380
    print('OK: RPyC server is responding')
381
    sys.exit(0)
382
except Exception as e:
383
    print(f'ERROR: {e}')
384
    sys.exit(1)
385
"
386

387
# Use with monitoring systems
388
# Nagios/Icinga check:
389
./rpyc-health-check.sh 192.168.1.10 18812
390

391
# Prometheus monitoring with custom exporter
392
rpyc_classic \
393
    --logfile /var/log/rpyc.log \
394
    --mode threaded &
395

396
# Parse logs for metrics
397
tail -f /var/log/rpyc.log | awk '
398
/connected/ { connections++ }
399
/disconnected/ { disconnections++ }
400
/error/ { errors++ }
401
{ print "rpyc_connections", connections }
402
{ print "rpyc_disconnections", disconnections }
403
{ print "rpyc_errors", errors }
404
'
405
```
406

407
### Client Connection Examples
408

409
```python
410
# Connect to CLI-started servers
411
import rpyc
412

413
# Connect to classic server
414
conn = rpyc.classic.connect('localhost', 18812)
415
print("Connected to:", conn.modules.socket.gethostname())
416

417
# Connect with SSL
418
ssl_conn = rpyc.classic.ssl_connect(
419
    'localhost', 18821,
420
    keyfile='client.key',
421
    certfile='client.crt'
422
)
423

424
# Discover via registry
425
services = rpyc.list_services()
426
print("Available services:", services)
427

428
# Connect by service name
429
service_conn = rpyc.connect_by_service('CLASSIC')
430
```
431

432
## Environment Variables
433

434
```python { .api }
435
# Environment variables supported by CLI tools:
436

437
RPYC_HOST = '0.0.0.0'                # Default host
438
RPYC_PORT = '18812'                  # Default port
439
RPYC_SSL_PORT = '18821'              # Default SSL port
440
RPYC_REGISTRY_HOST = 'localhost'     # Registry host
441
RPYC_REGISTRY_PORT = '18811'         # Registry port
442
RPYC_LOGFILE = '/var/log/rpyc.log'   # Log file path
443
RPYC_SSL_KEYFILE = 'server.key'      # SSL key file
444
RPYC_SSL_CERTFILE = 'server.crt'     # SSL certificate file
445
```
446

447
## Exit Codes
448

449
```python { .api }
450
# CLI tool exit codes:
451

452
SUCCESS = 0                          # Successful execution
453
INVALID_ARGS = 1                     # Invalid command line arguments
454
BIND_ERROR = 2                       # Failed to bind to port
455
SSL_ERROR = 3                        # SSL configuration error
456
REGISTRY_ERROR = 4                   # Registry connection error
457
PERMISSION_ERROR = 5                 # Insufficient permissions
458
```