Docker Deployment
Relevant source files
The following files were used as context for generating this wiki page:
Docker deployment for sshpiper involves running the core daemon (sshpiperd) alongside specialized plugins that interface with the Docker engine to route SSH traffic to containers. This ecosystem allows for dynamic SSH proxying where containers act as upstreams, identified and authenticated via Docker labels.
The system supports two primary modes of operation within Docker: standard routing to containers running an SSH daemon (sshd) and a "bridge" mode that allows SSH access into containers that do not have an internal sshd by using docker exec.
Sources: README.md:1-20, plugin/docker/README.md:1-10
Architecture and Components
The Docker-based deployment relies on the interaction between the sshpiperd daemon and the docker plugin. The plugin communicates with the Docker socket to discover active containers and their metadata.
The diagram shows the flow from an SSH client through the piper daemon and docker plugin to the final container target.
Discovery Mechanism
The docker plugin queries the Docker engine for containers. It filters and configures pipes based on specific labels attached to the containers. If a container lacks the required sshpiper.username, sshpiper.authorized_keys, or sshpiper.trusted_user_ca_keys labels, it is skipped by the discovery logic.
Sources: plugin/docker/docker.go:50-75, plugin/docker/README.md:25-35
Container Configuration via Labels
Deployment requires target containers to be tagged with specific labels that the sshpiper docker plugin uses to establish routing and authentication rules.
| Label | Description |
|---|---|
sshpiper.username | The username the downstream client uses to connect. |
sshpiper.container_username | The username to use when connecting to the upstream container. |
sshpiper.port | The SSH port of the container (defaults to 22). |
sshpiper.authorized_keys | Base64 encoded public keys for downstream authentication. |
sshpiper.private_key | Base64 encoded private key used by piper to auth with the container. |
sshpiper.docker_exec_cmd | Set to true to enable bridge mode (no sshd required in container). |
sshpiper.network | Specifies which network to use if the container is on multiple networks. |
Sources: plugin/docker/README.md:25-45, plugin/docker/docker.go:58-65
Docker-sshd Bridge (No-sshd Mode)
For containers without an internal SSH daemon, sshpiper provides a bridge mode. When sshpiper.docker_exec_cmd=true is set, the plugin initiates an internal SSH server bridge that translates SSH protocols into docker exec commands.
Sequence of events during a bridge-mode connection where no internal sshd exists in the target.
Technical Implementation
- Bridge Initialization: The plugin starts a local listener (
127.0.0.1:0) to act as the internal bridge. - Key Generation: For bridge mode,
sshpiperignores theprivate_keylabel and automatically generates an Ed25519 key pair for internal authentication. - Exec Command: The
sshpiper.docker_sshd_cmdlabel (defaulting to/bin/sh) defines the process executed inside the container once the SSH session is established.
Sources: plugin/docker/dockersshd_bridge.go:27-55, plugin/docker/docker.go:77-96, plugin/docker/README.md:38-42
Environment Configuration
The Docker plugin is configured primarily through standard Docker environment variables to establish its connection to the Docker daemon.
DOCKER_HOST: URL to the Docker server (defaults tounix:///var/run/docker.sock).DOCKER_API_VERSION: Specific API version to target.DOCKER_CERT_PATH: Path to TLS certificates for secure engine communication.DOCKER_TLS_VERIFY: Boolean to enable/disable TLS verification.
Sources: plugin/docker/README.md:15-22
Deployment Example (Docker Compose)
The project provides end-to-end (e2e) examples showing how to deploy sshpiperd with target containers.
services:
host-password:
image: linuxserver/openssh-server
environment:
- USER_PASSWORD=pass
- USER_NAME=user
labels:
- sshpiper.username=pass
- sshpiper.container_username=user
- sshpiper.port=2222
sshpiper:
image: farmer1992/sshpiperd
volumes:
- /var/run/docker.sock:/var/run/docker.sock
env:
- PLUGIN=docker
In this configuration, sshpiperd maps a downstream connection for user pass to the container's internal user on port 2222.
Sources: e2e/docker-compose.yml:2-15, plugin/docker/README.md:5-10
Conclusion
Docker deployment of sshpiper leverages the Docker API for dynamic service discovery. By utilizing container labels, administrators can manage SSH access without modifying static configuration files. The inclusion of a docker exec bridge further extends the utility of sshpiper by providing SSH-like access to minimal containers lacking a dedicated SSH daemon.
Sources: plugin/docker/README.md:1-5, plugin/docker/docker.go:50-55