Version 0.2.2 · GNU GPL v3 · Debian and Ubuntu

Standard OpenSSH tunnels, managed.

Tunnel Control™ keeps a set of plain OpenSSH tunnels (ssh -w) up between a Linux server on the local network and one or more VPS hosts, balances the traffic of the local network across them and fails over to the live channels when a channel or a whole VPS drops out. It watches every channel and shows the whole picture in a web panel. It is self-hosted: the manager and the panel run on your server. Nothing of its own is installed on the VPS: the tunnels are plain OpenSSH, and only the standard packages they need are added when missing.

$ curl -fsSL https://tunnelcontrol.app/install.sh | bash

Debian or Ubuntu with systemd, as root. Installs the latest release into /opt/tunnelcontrol; then fill in tun.config and run tun --install.

Tunnel Control™ Panel
Tunnel Control™ Panel, dashboard Tunnel Control™ Panel, dashboard

Install on clean systems only

Tunnel Control™ reconfigures the server and every VPS completely, so it goes on clean systems that run nothing else.

  • On the server it resets iptables on every start, takes over several routing tables and rule priorities, turns on IP forwarding and turns off IPv6.
  • The local network goes out only through the tunnels after installation, never directly: while they are stopped, its clients have no internet.
  • The server itself also goes out through the tunnels while they are up, except to the VPS hosts and the local network; while they are stopped, it goes out directly.
  • On every VPS it changes sshd_config, adds its key for root, installs the packages the tunnels need when they are missing, turns on IP forwarding and resets iptables, closing incoming connections except ping and SSH.

Features

Plain OpenSSH on the wire, everything else on the server

Tunnels on plain OpenSSH

Every channel is an ssh -w connection with its own point-to-point tunN interface on both sides. No installed service on the VPS, only the standard packages the tunnels need when they are missing.

The VPS sets itself up

On the first connection the key is installed, sshd_config gets PermitTunnel and keepalive, and the firewall, NAT and routing rules are built. Before each setup the VPS is checked: missing packages and kernel modules are installed, and a VPS that cannot run tunnels is held off with the reason. All it needs is the root password, once.

Monitoring and recovery

Each channel is checked by its own ping-pong inside the tunnel and by traffic counters. A channel that stops answering is reconnected and returns to the route once it answers again; a VPS that went down is set up again when it comes back.

Load balancing and failover

Live channels form one multipath (ECMP) default route with a weight per channel, so a faster VPS can take a larger share. A channel that drops out is taken out of the route, and its traffic fails over to the live ones.

Channel rotation

With more than one VPS the scheduler reconnects channels on a schedule: it waits until the channel's traffic drains, and keeps a minimum interval and a minimum uptime per channel.

Rate limit per channel

tc tbf in both directions, ingress through an ifb interface. One setting in tun.config, applied on the next start.

Web panel and console

Channel status, traffic charts, the log, a config editor, start and stop, push notifications. HTTPS with a certificate you can install on your devices, renewed by the panel itself, and a PWA for the phone's home screen. Or console only: tun --status and tun --monitor.

Updates keep your data

tun --update replaces only the code. tun.config, the per-VPS setup files, data/ and bak/ are never touched. Once a day the server checks for a newer release and tells you in the panel, in tun --status and with one push.

Logging levels

LOG_LEVEL 0–3: by default only key events, warnings and errors. Logrotate is set up by the installer; the VPS log can live in /tmp.

How it works

Local network → server → VPS hosts

Traffic that arrives on the local interface is routed into the tunnels. The subnet itself keeps using the normal routing table, so the server stays reachable from the local network. One line in TUNNELS is one channel. Three channels per VPS are recommended for the smoothest rotation: it reconnects one channel at a time, and while that channel is down, the other channels of the same VPS carry its share of the traffic.

Local network
192.168.0.0/16 · eth0
traffic
Server · Tunnel Control™
  • load balancing (ECMP)
  • monitoring and failover
  • rotation and shaping
  • web panel
ssh -w
tun1 · tun2 · tun3
VPS hosts
203.0.113.10
198.51.100.7

tun.config

The config is yours: created from the example, never overwritten by updates, checked value by value before every start and as you type in the panel's editor. Everything else has a default in tun.defaults; put the line you want to change into tun.config.

CONFIG="eth0:192.168.0.0/16"

# HOST:PORT:PORT_RANGE:IN_IFACE:PUBLIC_IP:OUT_IFACE:WEIGHT

TUNNELS=(
    "203.0.113.10:22222:22223-65535:eth0:NA:NA:40"
    "203.0.113.10:22222:22223-65535:eth0:NA:NA:40"
    "203.0.113.10:22222:22223-65535:eth0:NA:NA:40"
    # "198.51.100.7:22222:22223-65535:eth0:198.51.100.8:eth0:40"
)

DATA_PATH="./data"

Tunnel Control™ Panel

The whole picture, on the desk and in the pocket

Dashboard with a switch per host, Global Stats and traffic charts, the tun.config editor, logs with auto-scroll, start, stop and push notifications, in a light and a dark theme. The panel is self-hosted on the server: HTTPS on port 8443 with a certificate you can install on your devices, which the panel renews by itself before it ends, and a PWA for the phone's home screen.

Tunnel Control™ Panel · Dashboard
Dashboard: active tunnels per host, global stats and the traffic chart Configuration: the tun.config editor Logs: the verbose log with auto-scroll System: start, stop and restart the tunnel service Dashboard: active tunnels per host, global stats and the traffic chart Configuration: the tun.config editor Logs: the verbose log with auto-scroll System: start, stop and restart the tunnel service
Dashboard on a phone
Traffic chart on a phone
System tab on a phone
Dashboard on a phone
Traffic chart on a phone
System tab on a phone

Push notifications

Add the panel to the phone's home screen and tap Enable Push Notifications on the System tab. Notifications then arrive even when the panel is closed; desktop browsers support them as well. You are notified when:

  • a VPS goes down (all its channels failed);
  • a VPS recovers and its channels are up again;
  • the tun service stops or fails;
  • a newer release is out (once per release).

The first notification confirms the subscription. Apple devices require a real contact e-mail in WEB_PUSH_EMAIL; tun --install asks for it.

10:24
Tuesday, 6 October
Tunnel Control Panelnow

Host 203.0.113.10 has recovered (3 tunnels OK)

Tunnel Control Panel4m ago

Host 203.0.113.10 is now DEAD (3 tunnels failed)

Tunnel Control Panel1h ago

⚠️ Tunnel service is stopped or failed.
Please check the system.

Console too

A server without the web panel and Node.js shows the same state in the terminal: tun --status once, tun --monitor redrawn every few seconds, keys 1–9 turn a host on or off.

$ tun --status
Tunnel Control™ Panel 0.2.2
Tunnels: running as the tun service (PID 1342); tun service: active, enabled at boot; client route: group
Web panel: https://192.168.1.10:8443 (active)

Global Stats
Total RX Speed   6.2 MB/s       Total TX Speed   923.5 KB/s     Active Tunnels  6 / 6
Total RX Bytes   26.8 GB        Total TX Bytes   3.1 GB

Active Tunnels

203.0.113.10, 3 tunnels: enabled
TUNNEL     STATE    SINCE           PORT   WEIGHT  RX SPEED    TX SPEED    RX TOTAL   TX TOTAL
Tunnel 1   ONLINE   09:12:05        41873  40      1.4 MB/s    208.3 KB/s  6.1 GB     702.4 MB
Tunnel 2   ONLINE   09:27:41        30512  40      1.3 MB/s    196.0 KB/s  5.8 GB     688.1 MB
Tunnel 3   ONLINE   09:43:18        57209  40      1.5 MB/s    214.9 KB/s  6.3 GB     731.0 MB

198.51.100.7 (198.51.100.8), 3 tunnels: enabled
TUNNEL     STATE    SINCE           PORT   WEIGHT  RX SPEED    TX SPEED    RX TOTAL   TX TOTAL
Tunnel 4   ONLINE   08:55:30        25981  20      0.7 MB/s    101.2 KB/s  2.9 GB     341.5 MB
Tunnel 5   ONLINE   09:58:02        48066  20      0.6 MB/s    98.7 KB/s   2.7 GB     330.8 MB
Tunnel 6   ONLINE   10:13:47        33147  20      0.7 MB/s    104.4 KB/s  3.0 GB     352.6 MB

System Information
CPU: 4.5%   RAM: 492M/913M (53%)   Disk: 11G/19G (60%)   CPU: +58.6°C   GPU: +52.0°C   SSD: +41.9°C

Install

Three steps on a clean Debian or Ubuntu

$ curl -fsSL https://tunnelcontrol.app/install.sh | bash

Another folder: … | TUNNELCONTROL_DIR=/srv/tunnelcontrol bash. Installing as a copy of the repository is in the docs. Console only, without the web panel and Node.js: WEB_PANEL=0 in tun.config before tun --install.

  1. Fill in CONFIG and TUNNELS in /opt/tunnelcontrol/tun.config.
  2. Run tun --install: dependencies, systemd units, the panel, the first VPS setup and the tunnels. It asks for an e-mail for push notifications until one is set, and for the VPS root password whenever a VPS needs its first setup. Running it again is safe.
  3. Set the panel login with tun --web-password, then open https://<server address>:8443.

Server requirements

Debian or Ubuntu with systemd, root. tun --install installs what is missing (iproute2, iptables, conntrack, openssh-client, sshpass, gawk, and Node.js 20+ for the web panel) and checks in a scratch network namespace that the kernel supports tun devices, policy routing, ECMP, conntrack, tc tbf and ifb.

VPS requirements

Debian or Ubuntu with systemd, root over SSH, /dev/net/tun available. On OpenVZ or LXC hosting enable TUN/TAP in the hosting panel first. Missing packages are installed with apt during the setup.

Commands

tun --installinstall and initialize: dependencies, services, first VPS setup
tun --start / --restart / --stop / --killstart, restart, graceful stop, immediate stop
tun --updateupdate to the latest release (a copy of the repository: to its latest code), then tun --install
tun --web-passwordset the panel login and password
tun --statusstate of the tunnels, the service and the panel, Global Stats, Active Tunnels, System Information
tun --monitor [N]the same, redrawn every N seconds; keys 1–9 turn a host on or off, q quits
tun --toggle <IP>turn a host on or off, like its switch in the panel
tun --version, tun --helpversion, list of commands

What's new

0.2.2

Released , after 0.2.1 the same day and 0.2.0 on

Installed servers update with tun --update; settings and data stay.

Steadier routing, a VPS setup that finishes, word of every new release

Security
The panel checks the login against the route a request really reaches, whatever form its address takes. Clients never go out directly, in any state, not even for a moment after a reboot of the server: IP forwarding comes on only after the firewall. 0.2.1 The VPS hosts can no longer open connections into the local network, and the VPS root password travels by file descriptor and is cleared from memory once no VPS waits for it.
Channels and routing
Clients use a resilient nexthop group, so a dropped channel no longer takes the route of the others down. A tunnel device held on the VPS by an old SSH session is freed at once, and rotation keeps its minimum interval and logs why it pauses. After a crash or a hard reset of the server the channels come up without a minute of waiting. 0.2.1
VPS setup
One setup job per VPS, shown step by step, that survives dropped connections, reboots and a closed terminal; several VPS are set up in parallel. Missing packages and kernel modules are installed, and a VPS that cannot run tunnels is held off with the reason.
Web panel
Its own certificate authority (tun --web-cert) and a site certificate the panel renews by itself, without a restart. The config editor checks the text as you type and highlights the rejected lines. An app name per server, and push alerts kept for 12 hours. The browser tab and the certificate file carry the name and the address of the server, so several servers do not mix on one device. 0.2.1
Install and update
Once a day the server asks for the latest release and tells you about a newer one: a banner in the panel, a line on the System tab and in tun --status, and one push notification. 0.2.2 tun.config.check checks every value. tun --install asks its questions first and stops the tunnels only after the install; tun --update installs the latest release without questions and removes the files that left it.