autossh-tunnel-dockerized

SSH Tunnel Manager with Docker and Autossh

中文版 English

This project provides a Docker-based solution to manage SSH tunnels using autossh and a YAML configuration file. This setup allows you to easily expose local services to a remote server through an SSH tunnel or map remote services to a local port, making it convenient to access services behind a firewall. Additionally, it detects changes in config.yaml and automatically reloads the service configuration.

Table of Contents

Features

Prerequisites

Releases

The packaged Docker images are available on Docker Hub. You can access them via the following link:

Docker Hub Link

Feel free to use it and provide feedback!

Setup

1. Download Required Files

For most users, you only need to download the Docker Compose file. You can either:

Option A: Download files directly

Create a new directory and download the required files:

mkdir autossh-tunnel
cd autossh-tunnel

# Download docker-compose.yaml (includes both autossh tunnel and web panel services)
curl -O https://oaklight.github.io/autossh-tunnel-dockerized/compose.yaml

# Create config directory
mkdir config

# Option 1: Download sample config (if you want to configure manually)
curl -o config/config.yaml.sample https://oaklight.github.io/autossh-tunnel-dockerized/config/config.yaml.sample
cp config/config.yaml.sample config/config.yaml

# Option 2: Create empty config (if you want to use web panel for configuration)
touch config/config.yaml

Note: The compose.yaml file includes both the autossh tunnel service and the web panel service. The web panel is optional - you can disable it by commenting out the web service section in the compose file if you prefer manual configuration.

Option B: Clone the repository (for developers)

If you want to modify the source code or build locally:

git clone https://github.com/Oaklight/autossh-tunnel-dockerized.git
cd autossh-tunnel-dockerized

2. Configure SSH Keys

Ensure your SSH keys are located in the ~/.ssh directory. This directory should contain your private key files (e.g., id_ed25519) and any necessary SSH configuration files.

Important: This project heavily relies on the ~/.ssh/config file for SSH connection configuration. The SSH config file allows you to define connection parameters such as hostnames, usernames, ports, and key files for each remote host. Without proper SSH config setup, the tunnels may fail to establish connections.

For detailed SSH config file setup instructions, please refer to: SSH Config Configuration Guide

3. Configure YAML File

You have two options for configuring your SSH tunnels:

Option A: Manual Configuration

Edit the config.yaml file to define your SSH tunnel mappings. Each entry should specify the remote host, remote port, local port, and direction (local_to_remote or remote_to_local).

Sample configuration:

tunnels:
  # Expose local service to a remote server
  - remote_host: "user@remote-host1"
    remote_port: 22323
    local_port: 18120
    direction: local_to_remote
  # Map remote service to a local port
  - remote_host: "user@remote-host2"
    remote_port: 8000
    local_port: 8001
    direction: remote_to_local
  # Add more tunnels as needed

Option B: Web Panel Configuration

If you’re using the web panel (included in compose.yaml), you can:

Important Notes for Web Panel Users:

Advanced Configuration: Specify Bind Addresses

If you want to bind remote port or local service to a specific IP address, use the ip:port format.

1. Specify Remote Bind Address

Bind the remote port to a specific IP address (e.g., 192.168.45.130):

tunnels:
  - remote_host: "user@remote-host1"
    remote_port: "192.168.45.130:22323" # Bind remote to 192.168.45.130
    local_port: 18120 # Local service port
    direction: local_to_remote
2. Specify Local Bind Address

Bind the local service to a specific IP address (e.g., 192.168.1.100):

tunnels:
  - remote_host: "user@remote-host1"
    remote_port: 22323 # Remote port
    local_port: "192.168.1.100:18120" # Bind local to 192.168.1.100
    direction: local_to_remote
3. Specify Both Remote and Local Bind Addresses
tunnels:
  - remote_host: "user@remote-host1"
    remote_port: "192.168.45.130:22323" # Bind remote to 192.168.45.130
    local_port: "192.168.1.100:18120" # Bind local to 192.168.1.100
    direction: local_to_remote

This allows you to flexibly control the IP addresses to which tunnels bind, meeting different network environments and security needs.

4. Configure User Permissions (PUID/PGID)

Important: Before running the containers, make sure to set the correct PUID and PGID values in your environment or compose.yaml file to match your host user’s UID and GID. This ensures proper file permissions for the SSH keys and configuration files.

You can check your user’s UID and GID with:

id

To set the values, you can either:

  1. Set environment variables:

    export PUID=$(id -u)
export PGID=$(id -g)

  2. Edit the compose.yaml file directly:

    environment:
  - PUID=1000
  - PGID=1000

5. Build and Run the Docker Container

Use Dockerhub Release Image

docker compose up -d

Build and Run Container Locally

# build
docker compose -f compose.dev.yaml build
# run
docker compose -f compose.dev.yaml up -d

6. Access Services

Once the container is running, you can access the local service via the specified port on the remote server (e.g., remote-host1:22323) or access the remote service through the local port (e.g., localhost:8001).

Web-Based Configuration

The project includes an optional web-based configuration panel for easier tunnel management. The web panel is included in the default compose.yaml file but can be disabled if not needed.

Features

Access

Once the containers are running, access the web panel at: http://localhost:5000

Web Panel Interface

Backup Management

The web panel automatically creates backups in config/backups/ every time you save changes. You may need to manually clean up old backup files to prevent disk space issues.

Customization

Add More Tunnels

To add more SSH tunnels, simply add more entries to the config.yaml file. Each entry should follow this format:

- remote_host: "user@remote-host"
  remote_port: <remote_port>
  local_port: <local_port>
  direction: <local_to_remote or remote_to_local> (default: remote_to_local)

Modify Dockerfile

If you need to customize the Docker environment, you can modify the Dockerfile. For example, you can install additional packages or change the base image.

Modify Entrypoint Script

The entrypoint.sh script is responsible for reading the config.yaml file and starting SSH tunnels. If you need to add extra functionality or change how tunnels are managed, you can modify this script.

Security Considerations

When enabling the -R parameter, remote ports are by default bound to localhost. If you want to access the tunnel via other IP addresses on the remote server, you need to enable the GatewayPorts option in the remote server’s sshd_config:

# Edit /etc/ssh/sshd_config
GatewayPorts clientspecified  # Allow clients to specify binding address
GatewayPorts yes              # Or bind to all network interfaces

Restart the SSH service:

sudo systemctl restart sshd

Enabling GatewayPorts may expose services to the public. Ensure to take appropriate security measures, such as configuring firewall or enabling access control.

Troubleshooting

SSH Key Permissions

Ensure the .ssh directory and its contents have the appropriate permissions:

chmod 700 .ssh
chmod 600 .ssh/*

Docker Permissions

If you encounter permission issues when running Docker commands, make sure your user is in the docker group:

sudo usermod -aG docker $USER

Logs

Check Docker container logs for any errors:

docker compose logs -f

License

This project is licensed under the MIT License. See the LICENSE file for details.

Acknowledgments

Contributions to the project are welcome via issues or pull requests. Happy tunneling!

This site is open source. Improve this page.