Skip to content

Latest commit

 

History

History
191 lines (132 loc) · 6.16 KB

README_en.md

File metadata and controls

191 lines (132 loc) · 6.16 KB

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. The setup allows you to easily map remote ports to local ports, making it convenient to access services on remote machines behind firewalls.

Table of Contents

Features

  • Dockerized: Uses Docker to encapsulate the environment, making it easy to deploy and manage.
  • Non-Root User: Runs the container as a non-root user for enhanced security.
  • YAML Configuration: Uses a config.yaml file to define multiple SSH tunnel mappings.
  • Autossh: Automatically maintains SSH connections, ensuring tunnels stay active.
  • Dynamic UID/GID Support: Dynamically sets the container user's UID and GID using PUID and PGID environment variables to match the host user's permissions.
  • Multi-Architecture Support: Now supports all Alpine-based architectures, including linux/amd64, linux/arm64/v8, linux/arm/v7, linux/arm/v6, linux/386, linux/ppc64le, linux/s390x, and linux/riscv64.

Prerequisites

  • Docker and Docker Compose installed on your local machine.
  • SSH keys set up for accessing remote hosts.

Release

I have released the first version to Docker Hub. You can access the version via the following link:

Docker Hub Link

Feel free to use it and provide feedback!

Setup

1. Clone the Repository

Clone this repository to your local machine:

git clone /~https://github.com/yourusername/ssh-tunnel-manager.git
cd ssh-tunnel-manager

2. Configure SSH Keys

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

3. Configure the YAML File

Edit the config.yaml file to define your SSH tunnel mappings. Each entry should specify the remote host, remote port, and local port.

Example config.yaml.sample (copy it to config.yaml and make necessary changes) :

tunnels:
  - remote_host: "user@remote-host1"
    remote_port: 8000
    local_port: 8001
  - remote_host: "user@remote-host2"
    remote_port: 9000
    local_port: 9001
  # Add more tunnels as needed

4. Build and Run the Docker Container

Use Dockerhub Release Image

docker compose up -d

Build and Run the Container Locally

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

5. Access the Services

Once the container is running, you can access the services on your local machine using the specified local ports. For example, if you mapped remote-host1:8000 to localhost:8001 , you can access the service at http://localhost:8001 .

Customization

Adding More Tunnels

To add more SSH tunnels, simply update the config.yaml file with additional entries. Each entry should follow the format:

- remote_host: "user@remote-host"
  remote_port: <remote_port>
  local_port: <local_port>

Modifying the 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.

Modifying the Entrypoint Script

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

Dynamic UID/GID Support

To ensure that the container user's permissions match the host user's permissions, you can dynamically set the container user's UID and GID using the PUID and PGID environment variables in the compose.yaml file. For example:

services:
  autossh:
    image: oaklight/autossh-tunnel:latest
    volumes:
      - ~/.ssh:/home/myuser/.ssh:ro
      - ./config:/etc/autossh/config:ro
    environment:
      - PUID=1000
      - PGID=1000
      - AUTOSSH_GATETIME=0
    network_mode: "host"
    restart: always

or use docker run with environment variables:

docker run --net host -v ~/.ssh:/home/myuser/.ssh:ro -v ./config:/etc/autossh/config:ro -e PUID=1000 -e PGID=1000 -e AUTOSSH_GATETIME=0 --restart always oaklight/autossh-tunnel:latest

You can adjust the PUID and PGID values to match your host user's UID and GID, ensuring that the container can access the host's .ssh directory correctly.

Troubleshooting

SSH Key Permissions

Ensure that 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, ensure your user is in the docker group:

sudo usermod -aG docker $USER

Logs

Check the 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

  • autossh for maintaining SSH connections.
  • yq for parsing YAML configuration files.
  • Docker for containerization.

Feel free to contribute to this project by submitting issues or pull requests. Happy tunneling!