mkntz/openssh-server

By mkntz

•Updated 26 days ago

Docker for running instances of OpenSSH server

Image

Networking

Security

1.4K

Overview Tags

mkntz/openssh-server repository overview

⁠OpenSSH Server Docker Image

⁠Quick reference

Maintained by: mkntz⁠
Where to get help: GitHub Issues⁠
Where to file issues: GitHub Issues⁠
Source of this description: GitHub Repository⁠
Supported architectures: amd64, arm64
Image updates: Automated builds on new Alpine releases and OpenSSH updates

⁠Supported tags and respective `Dockerfile` links

⁠Introduction

A lightweight, secure, and highly configurable OpenSSH server Docker image based on Alpine Linux. Perfect for development environments, SSH tunneling, SFTP access, and secure remote access scenarios.

⁠🚀 Quick Start

Run an OpenSSH server with randomly generated credentials:

docker run -d \
  --name openssh-server \
  -p 2222:22 \
  mkntz/openssh-server:10.3p1

Check the logs to retrieve the generated username and password:

docker logs openssh-server

Connect to your server:

ssh -p 2222 <username>@localhost

⁠📋 Features

Lightweight: Based on Alpine Linux for minimal footprint
Multi-architecture: Supports linux/amd64 and linux/arm64
Flexible Authentication: Password and/or SSH key-based authentication
Customizable: Full control over SSH server configuration
User Management: Configurable root and user accounts
Security: Follows OpenSSH best practices
Auto-configuration: Automatically generates host keys and user credentials

⁠📖 Usage Examples

⁠Basic Usage with Custom Credentials

docker run -d \
  --name openssh-server \
  -p 2222:22 \
  -e USER_NAME=myuser \
  -e USER_PASSWORD=mypassword \
  mkntz/openssh-server:10.3p1

⁠SSH Key Authentication

Using direct public keys:

docker run -d \
  --name openssh-server \
  -p 2222:22 \
  -e USER_NAME=myuser \
  -e USER_PUBLIC_KEYS="ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABAQC... user@host" \
  mkntz/openssh-server:10.3p1

Using GitHub public keys:

docker run -d \
  --name openssh-server \
  -p 2222:22 \
  -e USER_NAME=myuser \
  -e USER_PUBLIC_KEYS_URL="https://github.com/username.keys" \
  mkntz/openssh-server:10.3p1

⁠User with Sudo Access

docker run -d \
  --name openssh-server \
  -p 2222:22 \
  -e USER_NAME=admin \
  -e USER_PASSWORD=secure123 \
  -e USER_SUDO_ACCESS=true \
  mkntz/openssh-server:10.3p1

⁠Root Access Configuration

Enable root login with SSH keys:

docker run -d \
  --name openssh-server \
  -p 2222:22 \
  -e ROOT_PUBLIC_KEYS_URL="https://github.com/username.keys" \
  -e SSHD_CONFIG_PermitRootLogin=yes \
  mkntz/openssh-server:10.3p1

⁠Advanced Configuration with Docker Compose

Create a docker-compose.yml:

services:
  openssh-server:
    image: mkntz/openssh-server:10.3p1
    container_name: openssh-server
    ports:
      - "2222:22"
    environment:
      - USER_NAME=devuser
      - USER_PASSWORD=devpass123
      - USER_SUDO_ACCESS=true
      - SSHD_CONFIG_AllowTcpForwarding=yes
      - SSHD_CONFIG_GatewayPorts=yes
      - SSHD_CONFIG_PasswordAuthentication=yes
    volumes:
      - ssh-data:/home/devuser
    restart: unless-stopped

volumes:
  ssh-data:

Run with:

docker compose up -d

⁠Using Environment File

Create an .env file:

USER_NAME=myuser
USER_PASSWORD=mypassword
USER_SUDO_ACCESS=true
SSHD_CONFIG_Port=22
SSHD_CONFIG_AllowTcpForwarding=yes
SSHD_CONFIG_PasswordAuthentication=yes

Run the container:

docker run -d \
  --name openssh-server \
  --env-file .env \
  -p 2222:22 \
  mkntz/openssh-server:10.3p1

⁠⚙️ Configuration

⁠Environment Variables

⁠OpenSSH Server Configuration

You can configure any sshd_config parameter by prefixing it with SSHD_CONFIG_.

Variable	Description	Default
`SSHD_CONFIG_Port`	SSH server port	`22`
`SSHD_CONFIG_PasswordAuthentication`	Enable password authentication	`yes`
`SSHD_CONFIG_PubkeyAuthentication`	Enable public key authentication	`yes`
`SSHD_CONFIG_PermitRootLogin`	Allow root login	`prohibit-password`
`SSHD_CONFIG_AllowTcpForwarding`	Allow TCP forwarding	`no`
`SSHD_CONFIG_GatewayPorts`	Allow remote hosts to connect to forwarded ports	`no`
`SSHD_CONFIG_X11Forwarding`	Enable X11 forwarding	`no`
`SSHD_CONFIG_ClientAliveInterval`	Seconds before sending keepalive message	-
`SSHD_CONFIG_ClientAliveCountMax`	Maximum keepalive messages	-

Note: The PORT environment variable sets the initial default port before the entrypoint runs. If both PORT and SSHD_CONFIG_Port are set, SSHD_CONFIG_Port takes precedence.

Example:

docker run -d \
  -e SSHD_CONFIG_AllowTcpForwarding=yes \
  -e SSHD_CONFIG_GatewayPorts=clientspecified \
  -e SSHD_CONFIG_ClientAliveInterval=60 \
  -e SSHD_CONFIG_ClientAliveCountMax=3 \
  -p 2222:22 \
  mkntz/openssh-server:10.3p1

⁠Root User Configuration

Variable	Description	Default
`ROOT_NAME`	Username for the root account	`root`
`ROOT_GROUP`	Group name for the root account	`root`
`ROOT_HOME_DIR`	Home directory path for the root account	`/root`
`ROOT_PUBLIC_KEYS`	Direct SSH public keys (separate multiple with `\n`)	-
`ROOT_PUBLIC_KEYS_URL`	URL to fetch public keys (e.g., GitHub keys URL)	-

Note: ROOT_PUBLIC_KEYS takes precedence over ROOT_PUBLIC_KEYS_URL.

Variable	Description	Default
`USER_NAME`	Username for the login user	Random 16-char string
`USER_GROUP`	Group name for the login user	Same as `USER_NAME`
`USER_PASSWORD`	Password for the login user	Random 32-char string
`USER_SUDO_ACCESS`	Grant sudo privileges (`true`/`false`)	`false`
`USER_HOME_DIR`	Home directory path	`/home/<username>`
`USER_PUBLIC_KEYS`	Direct SSH public keys (separate multiple with `\n`)	-
`USER_PUBLIC_KEYS_URL`	URL to fetch public keys (e.g., GitHub keys URL)	-

Note: USER_PUBLIC_KEYS takes precedence over USER_PUBLIC_KEYS_URL.

⁠Multiple SSH Keys

To add multiple SSH keys, separate them with \n:

docker run -d \
  -e USER_PUBLIC_KEYS="ssh-rsa AAAAB3Nza...key1 user1@host\nssh-rsa AAAAB3Nza...key2 user2@host" \
  -p 2222:22 \
  mkntz/openssh-server:10.3p1

Note: The \n separator works because BusyBox echo inside the Alpine container interprets it as a literal newline. Depending on your host shell and how you quote the value, the \n may be passed literally (as two characters) instead of being converted to a newline. If keys are not being applied, verify that the value reaches the container with actual newlines (e.g., use printf or heredoc syntax instead of double-quoted strings).

⁠Volume Mounts

Mount volumes to persist data or provide additional configuration:

docker run -d \
  --name openssh-server \
  -p 2222:22 \
  -v /path/to/user/data:/home/myuser \
  -v /path/to/ssh/config:\/etc\/ssh\/sshd_config.d\/custom.conf:ro \
  -e USER_NAME=myuser \
  mkntz/openssh-server:10.3p1

⁠🔒 Security Recommendations

Disable Password Authentication (use SSH keys only):
```
-e SSHD_CONFIG_PasswordAuthentication=no
```
Disable Root Login:
```
-e SSHD_CONFIG_PermitRootLogin=no
```
Use Strong Passwords: If using password authentication, always set strong passwords.
Limit Port Exposure: Only expose SSH to necessary networks.
Use Docker Networks: For container-to-container communication, use Docker networks instead of exposing ports.
Regular Updates: Keep the image updated to receive security patches.

⁠🛠️ Common Use Cases

⁠SSH Tunneling

Create an SSH tunnel for secure database access:

# Run SSH server with tunneling enabled
docker run -d \
  --name ssh-tunnel \
  -p 2222:22 \
  -e USER_NAME=tunnel \
  -e USER_PASSWORD=secure123 \
  -e SSHD_CONFIG_AllowTcpForwarding=yes \
  mkntz/openssh-server:10.3p1

# Create tunnel from client
ssh -L 5432:database:5432 -p 2222 tunnel@localhost

⁠SFTP Server

Use as an SFTP server for file transfers:

docker run -d \
  --name sftp-server \
  -p 2222:22 \
  -v /path/to/files:/home/sftpuser/files \
  -e USER_NAME=sftpuser \
  -e USER_PASSWORD=sftppass \
  mkntz/openssh-server:10.3p1

# Connect via SFTP
sftp -P 2222 sftpuser@localhost

⁠Development Environment Access

Provide SSH access to a development container:

docker run -d \
  --name dev-env \
  -p 2222:22 \
  -v $(pwd)/project:/workspace \
  -e USER_NAME=developer \
  -e USER_SUDO_ACCESS=true \
  -e USER_PUBLIC_KEYS_URL="https://github.com/developer.keys" \
  mkntz/openssh-server:10.3p1

⁠🐳 Building the Image

⁠Standard Build

docker build -t openssh-server:10.3p1 .

⁠Multi-platform Build

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag openssh-server:10.3p1 \
  .

Note: Multi-arch builds with --platform require --push to send the image to a registry. The default builder cannot --load multi-platform images locally.

⁠🔍 Troubleshooting

⁠View Generated Credentials

docker logs openssh-server | grep -E "USER_NAME|USER_PASSWORD"

⁠Test SSH Connection

ssh -v -p 2222 username@localhost

⁠Access Container Shell

docker exec -it openssh-server sh

⁠Check SSH Server Status

docker exec openssh-server ps aux | grep sshd

⁠View SSH Configuration

docker exec openssh-server cat \/etc\/ssh\/sshd_config.d\/99-custom-config.conf

⁠📝 License

This project is licensed under the terms specified in the LICENSE⁠ file.

⁠🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

⁠📚 Additional Resources

Tag summary

Recent tags

Content type

Image

Digest

sha256:049ea91eb…

Size

5.5 MB

Last updated

26 days ago

docker pull mkntz/openssh-server