sshpiperd Daemon Configuration
Relevant source files
The following files were used as context for generating this wiki page:
sshpiperd is a reverse proxy for SSH connections that routes traffic from a downstream client to an upstream server. The daemon serves as the core management layer, wrapping the SSH library to handle connection lifecycle, logging, and screen recording while delegating routing and authentication decisions to modular plugins. Sources: README.md:1-25, CONTRIBUTING.md:65-69
The configuration of the daemon is primarily driven by command-line flags and environment variables. It supports various operation modes, including standalone execution with local plugins, remote gRPC plugin connections, and an optional administrative gRPC interface for session management. Sources: cmd/sshpiperd/main.go:120-410, README.md:50-70
Core Daemon Options
The daemon requires basic network configuration and server identity keys to function. It can listen on specific addresses and ports while managing SSH host keys in multiple formats.
Network and Identity Settings
| Flag | Env Var | Default | Description |
|---|---|---|---|
--address, -l | SSHPIPERD_ADDRESS | 0.0.0.0 | Listening address for incoming SSH connections. |
--port, -p | SSHPIPERD_PORT | 2222 | Listening port for incoming SSH connections. |
--server-key, -i | SSHPIPERD_SERVER_KEY | /etc/ssh/ssh_host_ed25519_key | Path to server key files (supports wildcards). |
--server-key-data | SSHPIPERD_SERVER_KEY_DATA | (empty) | Base64 encoded server key; overrides file-based keys. |
--server-key-generate-mode | SSHPIPERD_SERVER_KEY_GENERATE_MODE | disable | Mode for key generation: disable, notexist, always. |
--login-grace-time | SSHPIPERD_LOGIN_GRACE_TIME | 30s | Time to establish a pipe before forced closure. |
Sources: cmd/sshpiperd/main.go:124-165, cmd/sshpiperd/snap/README.md:16-25
Connection Flow
The daemon follows a structured lifecycle for every incoming connection, interacting with the configured plugin(s) to determine the target upstream.
The diagram shows how sshpiperd acts as a middleman, delegating authentication verification and routing logic to the plugin via gRPC calls. Sources: libplugin/plugin.proto:45-60, README.md:15-30
Plugin Configuration and Orchestration
Plugins are the primary logic providers for sshpiperd. They can be executed as child processes or connected to via remote gRPC.
Plugin Execution Modes
- Child Process (Standard): The daemon spawns the plugin executable and communicates via
stdin/stdoutwrapped in gRPC. Sources: cmd/sshpiperd/main.go:88-106, CONTRIBUTING.md:71-75 - Network gRPC: The daemon connects to a remote gRPC endpoint providing the
SshPiperPluginservice. Sources: cmd/sshpiperd/main.go:343-352, libplugin/plugin.proto:45-60
Multi-Plugin Piping
sshpiperd supports chaining multiple plugins using the -- separator. This allows for "additional challenges" (e.g., 2FA or math questions) before the final routing plugin is reached. Sources: cmd/sshpiperd/main.go:122-123, README.md:43-48
# Example of chaining a math challenge before fixed routing
sshpiperd [options] ./simplemath -- ./fixed --target 127.0.0.1:5522
Sources: README.md:46-48, cmd/sshpiperd/main.go:332-378
Session Recording and Logging
sshpiperd provides built-in capabilities to audit and record SSH sessions for later playback.
Recording Formats
- Asciicast: Saves output in Asciicast v2 format, compatible with
asciinema. Sources: README.md:82-94, cmd/sshpiperd/main.go:185-189 - Typescript: Compatible with the standard Linux
scriptreplaycommand. Sources: README.md:96-113, cmd/sshpiperd/main.go:185-189
Configuration Flags
| Flag | Description |
|---|---|
--screen-recording-dir | Directory where recording files are stored. |
--screen-recording-format | Format to use: asciicast or typescript. |
--username-as-recorddir | If true, creates subdirectories based on the SSH username. |
--log-level | Controls verbosity: trace, debug, info, warn, error, fatal, panic. |
--log-format | Log output style: text or json. |
Sources: cmd/sshpiperd/main.go:170-195, README.md:85-110
Admin gRPC Interface
The daemon includes an optional administrative API (disabled by default) that allows external tools like sshpiperd-webadmin to monitor and manage active pipes. Sources: README.md:50-55, libadmin/admin.proto:10-25
Admin Configuration Options
| Flag | Description |
|---|---|
--admin-grpc-port | Port to listen on. Setting this to > 0 enables the API. |
--admin-grpc-address | Local address for the admin listener (default: 127.0.0.1). |
--admin-grpc-insecure | Disables TLS (only recommended for trusted networks). |
--admin-grpc-tls-cert | Path to the server PEM certificate for TLS. |
--admin-grpc-tls-key | Path to the server PEM private key for TLS. |
--admin-grpc-tls-cacert | Path to CA cert for client certificate verification (mTLS). |
Sources: cmd/sshpiperd/main.go:235-275, README.md:57-65
Administrative Capabilities
Through the SshPiperAdmin service, administrators can:
- ServerInfo: Retrieve version and instance identification.
- ListSessions: View all current downstream and upstream connection pairs.
- StreamSession: Live-stream terminal output from a running session.
- KillSession: Terminate a specific pipe.
Sources: libadmin/admin.proto:12-25, cmd/sshpiperd-webadmin/main.go:13-20
Proxy Protocol and Security
For deployments behind load balancers, sshpiperd supports the PROXY protocol to preserve the original client IP address. Sources: cmd/sshpiperd/main.go:207-217
Security Constraints
- Allowed Proxy Addresses: You must specify which IP ranges are permitted to send PROXY headers using
--allowed-proxy-addresses. Sources: cmd/sshpiperd/main.go:207-211 - Algorithm Whitelisting: The daemon allows explicit configuration of SSH algorithms to meet compliance requirements:
--allowed-downstream-keyexchange-algos--allowed-downstream-ciphers-algos--allowed-downstream-macs-algos--allowed-downstream-pubkey-algos
Sources: cmd/sshpiperd/main.go:218-234
Summary
The sshpiperd daemon configuration is designed for high extensibility, allowing administrators to define the network footprint, security parameters, and auditing levels of the proxy. By separating core daemon logic from routing via the gRPC plugin system, it facilitates complex SSH workflows such as 2FA, dynamic routing, and centralized session management through its admin API. Sources: README.md:115-130, cmd/sshpiperd/main.go:370-410