tordarus/sshd-alpine repository overview

⁠sshd-alpine

A lightweight Alpine Linux container running an OpenSSH server. Configure the SSH listening port and multiple user accounts through environment variables.

⁠Usage

⁠Start the container

docker run -d \
  --name sshd \
  -p 222:22 \
  -e SSH_USER1=testuser \
  -e SSH_PASSWORD1='your-strong-password' \
  sshd-docker

Connect to the SSH server:

ssh -p 222 testuser@localhost

Replace sshd-docker with the image name you use.

⁠Configure multiple users

Define each user with a numbered pair of environment variables:

docker run -d \
  --name sshd \
  -p 222:22 \
  -e SSH_USER1=alice \
  -e SSH_PASSWORD1='alice-password' \
  -e SSH_USER2=bob \
  -e SSH_PASSWORD2='bob-password' \
  -e SSH_USER3=charlie \
  -e SSH_PASSWORD3='charlie-password' \
  sshd-docker

Connect using any configured account:

ssh -p 222 alice@localhost
ssh -p 222 bob@localhost
ssh -p 222 charlie@localhost

User configuration is processed sequentially, starting at 1. Processing stops at the first undefined or empty SSH_USER<n>. Any subsequent user variables are ignored.

Every configured username must have a corresponding non-empty password. Otherwise, the container exits with an error.

⁠Configure the SSH port

Use SSH_PORT to change the port on which the SSH server listens inside the container.

docker run -d \
  --name sshd \
  -p 2222:2222 \
  -e SSH_PORT=2222 \
  -e SSH_USER1=testuser \
  -e SSH_PASSWORD1='your-strong-password' \
  sshd-docker

Connect using:

ssh -p 2222 testuser@localhost

Docker port mapping follows the format HOST_PORT:CONTAINER_PORT. The published container port must match SSH_PORT.

⁠Environment variables

⁠User configuration rules

• Number users sequentially, starting at 1.
• An undefined or empty SSH_USER<n> terminates the user list.
• Every configured user requires a non-empty matching password.
• Usernames may contain letters, digits, underscores, and hyphens.
• At least one user must be configured.

⁠Container management

View SSH server logs:

docker logs sshd

Stop the container:

docker stop sshd

Remove the container:

docker rm sshd

⁠Persist SSH host keys

To keep the SSH server host keys across container recreation, persist /etc/ssh/ using a Docker volume. Without persistent storage, host keys generated inside the container may change when the container is restarted, causing SSH clients to report a host key mismatch.

Create a named volume:

docker volume create sshd-host-keys

Start the container with the volume mounted:

docker run -d \
  --name sshd \
  -p 222:22 \
  -v sshd-host-keys:/etc/ssh \
  -e SSH_USER1=testuser \
  -e SSH_PASSWORD1='your-strong-password' \
  sshd-docker

The first startup generates the host keys if they are missing. The named volume retains the files in /etc/ssh/ when the container is removed and recreated.