Architecture¶

This document describes the architecture of the SSH Tunnel Manager, including the Docker containers and their interactions.

System Overview¶

The SSH Tunnel Manager provides two Docker images:

1. autossh-tunnel (Required) - The core tunnel management container
2. autossh-tunnel-web-panel (Optional) - Web-based management interface

graph TB
    subgraph "Host Machine"
        SSH[~/.ssh<br/>SSH Keys & Config]
        CONFIG[./config<br/>config.yaml]
        BROWSER[Browser]
    end

    subgraph "Docker Containers"
        subgraph "autossh Container (Required)"
            ENTRY[entrypoint.sh]
            MONITOR[spinoff_monitor.sh]
            CLI[autossh-cli]
            API[API Server<br/>:8080]
            WSSERVER[ws-server<br/>:8022]
            AUTOSSH[autossh processes]
            STATE[State Manager]
        end

        subgraph "web Container (Optional)"
            WEBSERVER[Go Web Server<br/>:5000]
            WSPPROXY[WebSocket Proxy]
        end
    end

    subgraph "Remote Servers"
        REMOTE1[Remote Host 1]
        REMOTE2[Remote Host 2]
    end

    SSH -->|read-only mount| ENTRY
    CONFIG -->|read-write mount| ENTRY
    BROWSER -->|Static files| WEBSERVER

    ENTRY --> MONITOR
    MONITOR --> CLI
    CLI --> STATE
    CLI --> AUTOSSH
    API --> CLI
    WSSERVER -->|spawns auth| CLI

    BROWSER -->|API + WebSocket| WEBSERVER
    WEBSERVER -->|API Proxy| API
    WSPPROXY -->|WS Proxy| WSSERVER

    AUTOSSH -->|SSH Tunnel| REMOTE1
    AUTOSSH -->|SSH Tunnel| REMOTE2

autossh-tunnel Container¶

Image: oaklight/autossh-tunnel:latest

The core container that manages SSH tunnels using autossh.

Components¶

Volume Mounts¶

Environment Variables¶

API Endpoints (when API_ENABLE=true)¶

Minimal Docker Compose Example¶

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

With API Enabled¶

name: autotunnel
services:
  autossh:
    image: oaklight/autossh-tunnel:latest
    volumes:
      - ~/.ssh:/home/myuser/.ssh:ro
      - ./config:/etc/autossh/config:rw
    environment:
      - PUID=1000
      - PGID=1000
      - API_ENABLE=true
      - API_PORT=8080
    network_mode: "host"
    restart: always

autossh-tunnel-web-panel Container¶

Image: oaklight/autossh-tunnel-web-panel:latest

An optional web-based management interface that communicates with the autossh container's API.

Components¶

Volume Mounts¶

Environment Variables¶

Docker Compose Example¶

name: autotunnel
services:
  web:
    image: oaklight/autossh-tunnel-web-panel:latest
    ports:
      - "5000:5000"
    # No config volume needed - web panel uses Config API from autossh container
    environment:
      - TZ=Asia/Shanghai
      # API_BASE_URL is used by the web server to proxy API requests (server-side only)
      - API_BASE_URL=http://localhost:8080
      - WS_BASE_URL=ws://localhost:8022    # Optional: enable in-browser interactive auth
    restart: always

Full Stack Deployment¶

When using both containers together:

name: autotunnel
services:
  autossh:
    image: oaklight/autossh-tunnel:latest
    volumes:
      - ~/.ssh:/home/myuser/.ssh:ro
      - ./config:/etc/autossh/config:rw
    environment:
      - PUID=1000
      - PGID=1000
      - AUTOSSH_GATETIME=0
      - API_ENABLE=true
      - API_PORT=8080
      - WS_PORT=8022              # Optional: ws-server for interactive auth
    network_mode: "host"
    restart: always

  web:
    image: oaklight/autossh-tunnel-web-panel:latest
    ports:
      - "5000:5000"
    # No config volume needed - web panel uses Config API from autossh container
    environment:
      - TZ=Asia/Shanghai
      # API_BASE_URL is used by the web server to proxy API requests (server-side only)
      - API_BASE_URL=http://localhost:8080
      - WS_BASE_URL=ws://localhost:8022   # Optional: enable in-browser interactive auth
    restart: always

Communication Flow¶

Web Panel to Tunnel Control (Proxy Architecture)¶

The web panel uses a proxy architecture where all browser requests go through the Go web server, which proxies them to the autossh backend. This ensures reliable operation even when the Docker host is accessed remotely.

sequenceDiagram
    participant User
    participant Browser as Browser
    participant WebServer as Go Web Server (:5000)
    participant API as API Server (:8080)
    participant WSSERVER as ws-server (:8022)
    participant CLI as autossh-cli
    participant Tunnel as autossh process

    Note over Browser,WebServer: Initial page load
    User->>Browser: Open web panel
    Browser->>WebServer: GET / (static files)
    WebServer-->>Browser: HTML/CSS/JS
    Browser->>WebServer: GET /api/config/api
    WebServer-->>Browser: {ws_enabled}

    Note over Browser,API: API calls proxied through web server
    User->>Browser: Click "Start Tunnel" (non-interactive)
    Browser->>WebServer: POST /api/autossh/start/{hash}
    WebServer->>API: POST /start/{hash} (reverse proxy)
    API->>CLI: autossh-cli start-tunnel {hash}
    CLI->>Tunnel: Start autossh process
    Tunnel-->>CLI: PID
    CLI-->>API: Success + output
    API-->>WebServer: JSON response
    WebServer-->>Browser: JSON response
    Browser-->>User: Update UI

    Note over Browser,WSSERVER: Interactive auth via WebSocket
    User->>Browser: Click "Start" on interactive tunnel
    Browser->>WebServer: WebSocket /ws/auth/{hash}
    WebServer->>WSSERVER: Proxy WebSocket connection
    WSSERVER->>CLI: Spawn autossh-cli auth {hash}
    CLI-->>WSSERVER: Password prompt
    WSSERVER-->>Browser: Terminal output (xterm.js)
    User->>Browser: Enter password/2FA
    Browser->>WSSERVER: User input
    WSSERVER->>CLI: Forward input
    CLI-->>WSSERVER: Auth success
    WSSERVER-->>Browser: Success status
    Browser-->>User: Auto-close modal, refresh status

Configuration Change Detection¶

sequenceDiagram
    participant User
    participant WebUI as Web UI
    participant Config as config.yaml
    participant Monitor as spinoff_monitor.sh
    participant CLI as autossh-cli
    participant Tunnels as autossh processes

    User->>WebUI: Save configuration
    WebUI->>Config: Write config.yaml
    Monitor->>Config: Detect file change (inotify)
    Monitor->>CLI: autossh-cli start
    CLI->>Tunnels: Smart restart
    Note over CLI,Tunnels: Only restart changed tunnels

Network Mode¶

The containers use different network modes based on their requirements:

autossh Container (Host Network)¶

The autossh container uses network_mode: "host" to:

1. Allow direct access to host network interfaces
2. Enable tunnels to bind to specific IP addresses
3. Simplify port forwarding configuration

web Container (Bridge Network)¶

The web container uses bridge networking with port mapping:

ports:
  - "5000:5000"

This is possible because:

1. The web server proxies all API and WebSocket requests to the autossh backend
2. The browser only needs to reach the web panel (port 5000)
3. API_BASE_URL and WS_BASE_URL are server-side URLs for the proxy, not browser-facing

File Structure¶

/home/myuser/                    # In containers
├── .ssh/                        # SSH keys and config (from host)
│   ├── config                   # SSH host configurations
│   ├── id_ed25519              # Private key
│   └── known_hosts             # Known hosts
└── config/                      # Tunnel configuration (web container)
    └── config.yaml             # Tunnel definitions

/etc/autossh/config/             # In autossh container
└── config.yaml                  # Tunnel definitions

/tmp/                            # Runtime files
├── autossh_tunnels.state       # Tunnel state tracking
└── autossh-logs/               # Tunnel log files
    └── tunnel-{hash}.log       # Per-tunnel logs

Security Considerations¶

1. SSH Keys: Mounted read-only to prevent modification
2. Non-root User: Containers run as myuser (configurable via PUID/PGID)
3. State Isolation: Each tunnel has isolated state and logs
4. API Access: API server only accessible on localhost by default (host network mode)