ssh-tunnel-manager

README

🔐 SSH Tunnel Manager

Manage multiple SSH tunnels with auto-reconnect, health checks and SOCKS5 proxy.

Why SSH Tunnel Manager?

Developers constantly need SSH tunnels to access databases, Redis, and internal services. Manually typing ssh -L commands is error-prone and hard to manage. autossh only handles one tunnel at a time. SSH Tunnel Manager gives you:

• 📋 Config file management — Define all tunnels in one YAML file
• 🔄 Auto-reconnect — Automatically reconnect on connection loss
• 💚 Health checks — Monitor tunnel connectivity and latency
• 🧦 SOCKS5 proxy — Dynamic port forwarding support
• 🔗 Connection pooling — Share SSH connections across multiple tunnels
• 🎨 Colored output — Clear, colored terminal output for tunnel status

Comparison with autossh

Feature	SSH Tunnel Manager	autossh
Multiple tunnels	✅	❌ (one at a time)
Config file	✅ YAML	❌
SOCKS5 proxy	✅	❌
Health checks	✅ TCP + latency	✅ TCP only
Connection pooling	✅	❌
Remote forwarding	✅	✅
Status dashboard	✅	❌
Environment variables	✅	❌

Quick Start

Install

go install github.com/gal111111/ssh-tunnel-manager@latest

Create Config

# Initialize a sample config file
ssh-tunnel-manager add --name mysql --type local --local 3306:localhost:3306 --ssh-host bastion.example.com

Or create tunnels.yaml manually:

tunnels:
  - name: mysql
    type: local
    local_addr: "127.0.0.1:3306"
    remote_addr: "localhost:3306"
    ssh_host: "bastion.example.com"
    ssh_user: "deploy"
    ssh_key: "~/.ssh/id_rsa"

  - name: redis
    type: local
    local_addr: "127.0.0.1:6379"
    remote_addr: "10.0.0.5:6379"
    ssh_host: "bastion.example.com"
    ssh_user: "deploy"
    ssh_key: "~/.ssh/id_rsa"

  - name: socks5
    type: dynamic
    local_addr: "127.0.0.1:1080"
    ssh_host: "bastion.example.com"
    ssh_user: "deploy"
    ssh_key: "~/.ssh/id_rsa"

CLI Usage

# Start all tunnels
ssh-tunnel-manager start

# Start a specific tunnel
ssh-tunnel-manager start --name mysql

# Stop all tunnels
ssh-tunnel-manager stop

# Check tunnel status
ssh-tunnel-manager status

# Add a new tunnel
ssh-tunnel-manager add --name api --type local --local 8080:internal.api:80 --ssh-host jumpbox

# List all configured tunnels
ssh-tunnel-manager list

Configuration

Environment Variables

Use ${VAR_NAME} or $VAR_NAME syntax in config values:

tunnels:
  - name: db
    type: local
    local_addr: "127.0.0.1:${DB_PORT}"
    remote_addr: "${DB_HOST}:5432"
    ssh_host: "${BASTION_HOST}"
    ssh_user: "${SSH_USER}"
    ssh_key: "${SSH_KEY_PATH}"

Auto-Reconnect

tunnels:
  - name: mysql
    type: local
    local_addr: "127.0.0.1:3306"
    remote_addr: "localhost:3306"
    ssh_host: "bastion.example.com"
    auto_reconnect: true    # Enable auto-reconnect (default: true)
    reconnect_delay: 5s     # Delay before reconnect (default: 5s)
    max_retries: 0          # Max retries, 0 = unlimited (default: 0)

Health Checks

tunnels:
  - name: mysql
    # ... other config ...
    health_check:
      enabled: true         # Enable health checks (default: true)
      interval: 10s         # Check interval (default: 10s)
      timeout: 5s           # Check timeout (default: 5s)

Examples

See the examples directory for sample configuration files.

License

MIT License. See LICENSE for details.

Documentation

Overview

Package tunnel 提供 SSH 隧道的配置管理功能。 支持从 YAML 配置文件加载隧道配置，支持环境变量替换， 以及配置文件的保存和更新操作。

Package tunnel 提供 SSH 连接管理功能。 封装 SSH 客户端的创建、认证和 KeepAlive 机制。 支持密钥认证和密码认证两种方式。

Package tunnel 提供 SSH 隧道的健康检查功能。 定期检测隧道端口的可达性和响应延迟， 在隧道异常时发出告警，帮助用户及时发现和处理问题。

Package tunnel 提供彩色日志输出功能。 支持不同级别的日志（Info/Warn/Error/Debug）， 每个级别使用不同的颜色，方便在终端中快速区分。 同时记录连接事件，便于排查问题。

Package main 提供 SSH Tunnel Manager 的命令行入口。 支持以下子命令：

• start: 启动隧道（全部或指定名称）
• stop: 停止隧道
• status: 查看隧道状态
• add: 添加新隧道配置
• list: 列出所有隧道配置

Package tunnel 提供 SSH 隧道管理的核心功能。 TunnelManager 是整个系统的核心组件，负责管理所有隧道的生命周期： 启动、停止、重启、状态查询等。 支持连接池复用、自动重连和健康检查。

Package tunnel 提供 SSH 连接池功能。 多个隧道可以共享同一个 SSH 连接，减少连接开销。 连接池自动管理连接的创建、复用和关闭。

Package tunnel 提供 SOCKS5 代理功能。 实现动态端口转发（ssh -D），允许客户端通过 SSH 隧道 动态访问任意远程目标地址。 支持标准的 SOCKS5 协议（RFC 1928）。

Package tunnel 提供 SSH 隧道的定义和基础操作。 Tunnel 是隧道管理的基本单元，封装了隧道的配置、 启动、停止和状态查询等功能。 支持三种隧道类型：本地转发、远程转发和动态转发（SOCKS5）。