Documentation
Quick start + feature guide for every section and device (continuously updated)
NAT Server Detection & Tunneling Guidance
This doc explains how the panel automatically detects NAT servers, distinguishes between "NAT with configurable ports" and "NAT without configurable ports", and guides users to Tunneling when necessary.
First, understand: what is NAT
A NAT server is a server that has "only a private IP and no independent public IP". For example, many cheap NAT VPSs give you a private address (like 192.168.x.x) that you cannot reach directly from the public internet — you can only access it through the port mapping provided by the vendor (forwarding a public port to your private address).
Feature overview
After adding a server, the panel automatically detects whether the machine is a NAT type (has only private addresses and no independent public IP) once the SSH connection succeeds. When NAT is detected, a small badge is shown on the server card, and a centralized notice is shown at the top of "Overview". The user can click the yellow badge to confirm whether the NAT server can set up port forwarding in the vendor panel themselves, and thus decide whether Tunneling is needed.
Why distinguish NAT types
"Private IP" ≠ "needs tunneling". NAT servers fall into two categories:
| Type | Characteristics | Needs tunneling? |
|---|---|---|
| NAT with configurable ports | The vendor provides a port-mapping panel; you can map public ports to private ports yourself | ❌ No — you can handle ports yourself |
| NAT without configurable ports | The vendor only fixed-maps a few ports such as SSH (22); other ports can't be reached from the public internet | ✅ Yes — needs Tunneling |
Only "NAT without configurable ports" needs Tunneling. A NAT with configurable ports can map its own ports and behaves just like a public-IP machine — it should not be nagged repeatedly.
How detection works
After the SSH connection succeeds, the panel runs the read-only command ip -4 addr show to read the server's local NIC IPs and checks whether they all fall within private ranges:
10.0.0.0/8172.16.0.0/12192.168.0.0/16100.64.0.0/10(CGNAT, carrier-grade NAT)127.0.0.0/8,169.254.0.0/16,0.0.0.0/8
As long as any public-range IP exists, the server is judged "has a public IP" (not NAT); if all IPs are private, it is judged "NAT".
> The detection command is read-only and does not change any server state. The result is written to the database and is detected only once at first connection; afterwards the result is reused, so it does not slow down connections.
Badge and notice locations
After NAT is detected, the prompt appears in two places:
1. System Panel → "Overview" tab: after clicking "System Panel" on a server card and entering the panel, the first tab "Overview" shows the corresponding NAT notice banner — yellow-marked servers show a yellow explanation (including how to clear it), and red-marked servers show a red tunneling guide. The prompt appears only on NAT, unconfirmed direct-connect servers and does not crowd the card.
2. Small badge on the card: only one small badge remains on the card, with three states:
| Badge | Color | Meaning | Click behavior |
|---|---|---|---|
NAT | Yellow | NAT detected (local IP in private range), pending confirmation | Opens a confirmation dialog |
Needs Tunneling | Red | Port cannot be reached from the public internet; needs tunneling | Opens the Tunneling guide |
| (no badge) | — | Confirmed "ports are fine", badge cleared | — |
The yellow NAT badge is the "pending confirmation" state: clicking it opens a confirmation dialog with two choices:
- "Ports are fine, clear the badge" → the badge disappears and won't appear again;
- "Port unreachable, mark as needs tunneling" → the badge turns red and guides to Tunneling.
The red Needs Tunneling badge is a "warning": clicking it goes directly to Tunneling + Port Tunneling.
> Why not "auto-probe whether the port is reachable": the panel server and the target server may be in the same datacenter, so the panel's probe travels over the internal network — "reachable" from the panel does not mean external visitors can reach it, so the result is unreliable. That's why "Needs Tunneling" is marked manually by the user in the yellow explanation dialog.
Why NAT servers "disconnect after a while"
NAT servers have an idle timeout at the vendor's gateway. After an SSH connection is idle for a few minutes, the gateway silently kills the connection (TCP half-open), and neither side notices.
The panel fixes this in two ways:
1. keepalive on SSH connections: after every connection is established, a keepalive packet is sent every 30 seconds — both preventing the NAT idle cutoff and detecting half-dead connections promptly.
2. periodic connection-pool cleanup: a background thread every 2 minutes closes connections idle for more than 2 minutes, preventing half-dead connections from piling up indefinitely.
Notes
1. Detection depends on a successful SSH connection: if the server is offline or the password is wrong, it can't be detected and no badge is shown.
2. Servers without a badge: public-IP servers, Android (Termux) machines, and already-tunneled devices (with a tunnel_token) show no NAT badge — they each go through their own channel and need no NAT reminder.
3. Leave room for special cases: a very few "1:1 NAT" servers (all ports open) also have private local IPs and will be detected as NAT. In that case just choose "OK" in the confirmation dialog — it does not affect usage.
4. Can change after confirmation: the badge state is decided by user confirmation and can be adjusted at any time by clicking the badge.