JohnWatsoon/WatTunnel

🪁 WatTunnel

Encrypted Iran ↔ Kharej port forwarding that keeps working when the network is filtered, even when only ping gets through.

English · فارسی

WatTunnel connects an Iran server (where your users connect) to a Kharej server (outside, where your service runs) and forwards any TCP or UDP port between them. It is one static binary with no dependencies, plus an interactive manager for setup, monitoring, diagnosis and updates. It was built for routes where TCP and UDP are cut and only ICMP echo (ping) passes. The same encrypted session also runs over UDP, TCP, TLS, WebSocket, HTTP/2 and gRPC, including through Cloudflare, so you can pick whatever your route lets through.

Full reference (every config key, flag, /stats field): docs/TECHNICAL.md.

• Works when only ping works. Nine carriers in one session: icmp, udp, tcp, tls, ws, wss, h2, h2c, grpc. Bond several into one link, or use reverse mode when only one side can dial out.
• Fast on lossy links. Pacing is delay-based, so random loss does not slow it down. Interactive traffic goes ahead of bulk downloads.
• Survives SNI filtering. Through Cloudflare with ECH, and the manager finds working edges by itself.
• One process, every port. TCP and UDP, ports added or removed live without a restart, per-port stats and quotas.
• Light and secure. About 40 MB of RAM for an ICMP tunnel. ChaCha20-Poly1305 with a pre-shared key, and unauthenticated packets get no reply.
• Easy to run. One-line installer, a one-paste connection token, a multi-tunnel dashboard, a connection doctor, auto-heal, update and rollback.

• ICMP: bigger packets, a setting change (no update needed). The Iran ⇄ Europe route passes full 1500-byte pings again. With mtu: 1400 on both ends and the same 30 MB/s cap, Kharej resends 0.3-0.8 % of its packets instead of 3-5 %, and in back-to-back tests downloads went from 22-24 to 27.5 MB/s and uploads from 21-22 to 26 MB/s, with ping unchanged (~41 ms under load). In production since 2026-10-12. Check your route first: ping -M do -s 1372 PEER_IP must get replies, and ip route get PEER_IP must not show mtu lock 680. Keep the total of all ICMP tunnels on this route at about 30 MB/s or less: above that, the route inside Iran switches to a slow path for minutes. Details.

Update both servers for every release below.

• 2.4.8: less RAM per user connection. Idle connections keep 4 KB copy buffers instead of 32 KB. Tip: if you set GOMEMLIMIT, give it at least twice the tunnel's normal memory. An Iran server limited to 256 MiB spent most of its CPU on memory cleanup (75-130 %). With 768 MiB it dropped to about 20 % (ICMP, ~200-300 connections, 2026-10-12).
• 2.4.7: CDN connection health. Each end now replaces a CDN connection that delivers far less than the others, and the tunnel no longer stays stuck at its lowest speed. Nothing changes for ICMP.
• 2.4.6: RAM stays low. Idle connections keep less memory and Go cleans up sooner. On a production CDN tunnel with about 250 user connections, the Iran server went from about 1 GB on 2.4.5 to about 100 MB, and Kharej to about 100 MB. Speed unchanged.
• 2.4.5: no more stuck CDN connections. When one Cloudflare connection stalls, the tunnel now stops using it and reconnects it, instead of losing packets into it. Fixes downloads dropping to a few MB/s and 1-second freezes. In production, sustained downloads went from 30 to 43-45 MB/s on average, measured back to back with 2.4.3.
• 2.4.4: CPU fix. 2.4.3 made the sending server (Kharej, for downloads) burn CPU on connections whose users read slowly: 40-73 % per thread under load instead of 2-13 %. Fixed. Update right away if you are on 2.4.3.
• 2.4.3: less RAM for slow users. Connections whose users read slowly no longer hold 4-8 MB each on both servers (the first step; 2.4.6 finishes the job).
• 2.4.2: CDN downloads no longer collapse. When Cloudflare's path is slower than the tunnel, the tunnel now backs off instead of flooding it. Sustained downloads stay fast (39 -> 50 MB/s average in the field), and the random half-second freezes are gone.
• 2.4.1: no more crawling under real traffic. TCP-based and CDN tunnels no longer slow to a crawl under bursty web traffic.
• 2.4.0: faster single downloads. Stream windows tune themselves, so one download or upload is faster on high-latency paths.

Also new in 2.x: CDN mode through Cloudflare with ECH (2.2), several sessions per tunnel (2.3, default 4 for TCP-type carriers), wattun alone opens the manager, and Auto mode tests every variant from one token.

On a heavily filtered route the usual tunnels fail in measurable ways:

Real VLESS (xray) traffic through each tunnel, same servers, same route. WatTunnel numbers are from version 1.8.0.

The route caps at about 50 - 55k ICMP packets per second (~33 MB/s), and WatTunnel fills it. In production it carries 250 - 300 real clients through a single process.

With 1400-byte packets (mtu: 1400, 2026-10-12, same route, 30 MB/s cap): 27.5 MB/s down, 26 MB/s up in a single speed test, 0.3-0.8 % of packets resent (3-5 % at 640 bytes), ping 41 ms under load.

Against other ICMP tunnels on the same route (WatTunnel 1.8.0):

Real measurements, Iran → Cloudflare → Kharej, 2-vCPU servers, wss + ECH. The first rows are from 2026-10-11 on a tunnel without users; the last row is production with real users on 2026-10-12.

We did not measure competitors' CDN speeds on this route, so there is no speed comparison here, only a feature one:

Honest note. On a clean emulated link (20 ms each way, 0.2 % loss, 100 Mbit) every tunnel reaches line rate and GOST uses a little less CPU, but WatTunnel halves small-request latency (p50 43 ms vs 83 ms) because it sends interactive streams first. WatTunnel's big advantage is on lossy, filtered routes. These numbers come from specific routes; yours will differ, so run wattun test NAME. Full table: bench/results-2026-10-09-final.md and docs/TECHNICAL.md.

You need two Linux servers with systemd (amd64 or arm64) and root. Set up Kharej first, because it creates the token that Iran needs.

1. Install on both servers

bash <(curl -fsSL https://raw.githubusercontent.com/JohnWatsoon/WatTunnel/main/install.sh)

WAT_PROXY=https://ghproxy.net/ bash <(curl -fsSL https://ghproxy.net/https://raw.githubusercontent.com/JohnWatsoon/WatTunnel/main/install.sh)

2. Kharej (outside), do this first. Run wattun, press n (new tunnel) and choose Kharej. Pick a connection type (see below; auto is a good start). You get a token:

wat1:aWNtcHwyMDMuMC4xMTMuMTB8a1E3...

3. Iran (inside). Run wattun, press n, choose Iran, answer yes to "Do you have the token?" and paste it. Then enter the ports your service uses, for example 443, 8443:443, 53/udp. 8443:443 means users connect to Iran port 8443 and reach your service on Kharej port 443.

   #  Iran port (users)        Kharej port (service)   proto
   1  443                 ──►  443                     tcp
   2  8443                ──►  443                     tcp
   3  53                  ──►  53                      udp

  ✔ Writing key and config
  ✔ Starting wattun@iran
  ✔ CONNECTED (RTT 41.3 ms)

  users ──► Iran :8443 ══ icmp ══► Kharej ──► 127.0.0.1:443

Users now connect to the Iran server's IP. Kharej only ever forwards to its own 127.0.0.1.

If the route cuts TCP in both directions, only ICMP (and reverse ICMP) will do.

Reverse swaps who starts the connection. Users still connect to Iran, and traffic still goes to your service on Kharej. Reverse ICMP is for Iran IPs that are blocked one way: ping KHAREJ_IP fails on Iran but ping IRAN_IP works on Kharej. Both servers need 2.0.0 or newer.

1. Update both servers.
2. Kharej: wattun → open the tunnel → o (advanced) → d (direction). Enter Iran's IP and confirm the restart.
3. Iran: the same keys, confirm the restart. Then run wattun test NAME on Kharej.

For a new tunnel, pick reverse in the Kharej wizard's advanced settings: the token carries it. By hand:

# Kharej: /etc/wattun/kharej.yml
mode: server
carrier: icmp
reverse: true
peer: 198.51.100.20     # Iran's IP: Kharej sends the pings here

# Iran: /etc/wattun/iran.yml
mode: client
carrier: icmp
reverse: true
peer: 203.0.113.10      # Kharej's IP, as before

Reverse also works for the TCP-type carriers (Iran listens, Kharej dials Iran's IP:port, 1.8.0 or newer). udp has no reverse mode. Details, certificates, and what to keep in mind: Reverse ICMP, Reverse pool carriers.

Not sure what works on your route? Pick auto as the carrier in the Kharej wizard. One bonded tunnel listens on every carrier at once and prints one token. Paste it on Iran, and the manager tests each variant (direct, then through Cloudflare if you gave a domain, then reverse) with a short speed test, in about 2 to 3 minutes. It shows a table ranked by download plus upload: Enter uses the best, b bonds the working ones, 1-N picks one.

Re-run it with wattun auto-test NAME. If the reverse side cannot learn Iran's IP, run wattun auto-ip NAME IRAN_IP on Kharej. Auto-heal can switch to another working carrier by itself. Kharej needs 2.1.0 or newer. Details: docs/TECHNICAL.md#auto-mode.

For routes where only HTTPS to a CDN gets out, or the filter looks at the SNI.

1. Put a domain on Cloudflare, with the proxy (orange cloud) on and SSL mode Full. For grpc, turn on gRPC in Cloudflare's Network settings if your plan shows that switch.
2. In the Kharej wizard choose wss (or grpc) and enter the domain. h2 does not work through Cloudflare, and plain ws on HTTP ports can hang at the upgrade.
3. On Iran, the manager finds the ECH config by itself and scans Cloudflare edge IPs for ones that really work for your domain. It then tests the Chrome fingerprint, ECH, plain TLS and ClientHello fragmentation, and writes the winner to the config.
4. Use several sessions (default 4) to fill the pipe. Re-tune any time with wattun cdn-tune NAME. Auto-heal replaces dead edges.

Manual keys (fp, ech, tls-frag, several peer addresses) and troubleshooting: docs/TECHNICAL.md#cdn-tuning. More on sessions: docs/TECHNICAL.md#several-sessions-230.

Run wattun for the dashboard of all tunnels (wattun-manager still works). Press a tunnel's number to manage it, n for a new one, m for the live monitor, u to update, s for settings (rollback, uninstall, auto-heal), q to quit. A tunnel's page has diagnose and speed test, logs, port-mapping editor, token, advanced settings, restart, and delete. The doctor names the likely cause when a link is down.

wattun                 # dashboard
wattun new kharej      # new tunnel (kharej or iran); do Kharej first
wattun status          # one line per tunnel
wattun monitor         # live dashboard
wattun ports NAME      # edit the port mappings of a tunnel
wattun test NAME       # connection doctor + speed test
wattun speedtest NAME  # speed test only (10 MB each way)
wattun logs NAME       # follow the log
wattun token NAME      # print the Kharej token
wattun auto-test NAME  # re-run the Auto mode test
wattun cdn-tune NAME   # re-tune a Cloudflare tunnel
wattun auto-ip NAME IP # tell an auto tunnel Iran's IP (on Kharej)
wattun update | rollback | help

Config. Each tunnel is /etc/wattun/NAME.yml, run by systemd as wattun@NAME. Keys are the flag names. Only the ports: list reloads live (within 3 seconds); anything else needs systemctl restart wattun@NAME.

# /etc/wattun/iran.yml
mode: client
key-file: /etc/wattun/iran.key
carrier: icmp
peer: 203.0.113.10
metrics: 127.0.0.1:19750
ports:
  - 443          # users connect to Iran :443, delivered to Kharej 127.0.0.1:443
  - 8443:443     # users connect to Iran :8443, delivered to Kharej 127.0.0.1:443
  - 53/udp
  - 5353:53/udp

On Kharej, ports: is an allowlist of target ports (leave it out to allow any). Every key: docs/TECHNICAL.md#config-file.

Auto-heal. A systemd timer (wattun-heal) restarts an Iran tunnel whose link has been down for 3 minutes. It is turned on for Iran tunnels automatically (off: wattun → s → h) and does not restart a tunnel you stopped.

Each tunnel serves a small HTTP API on 127.0.0.1 only (never expose it):

curl -s 127.0.0.1:19750/stats       # alive, last_rx_age_ms, srtt_ms, rate_bps, loss_pct, streams, sessions, bytes...
curl -s 127.0.0.1:19750/ports       # traffic per port
curl -s '127.0.0.1:19750/speedtest?dir=down&mb=10'   # built-in speed test (client side)

Use last_rx_age_ms rather than ping to judge a link's health. Field reference: docs/TECHNICAL.md#metrics.

• The pre-shared key is never sent. Each session derives its own key and every packet is sealed with ChaCha20-Poly1305. A packet that does not authenticate gets no reply, so scans see nothing.
• Kharej only forwards to its own 127.0.0.1, and only to allowed ports. The metrics address is forced to 127.0.0.1.
• /etc/wattun is mode 700 and key files 600. The token contains the key, so share it privately.
• WatTunnel encrypts and authenticates your traffic. It does not hide that a tunnel exists, and it is not an anonymity tool.

Start with wattun test NAME. Then systemctl status wattun@NAME and journalctl -u wattun@NAME -f.

More (address already in use, restart needed for KEY, MTU, CDN errors): docs/TECHNICAL.md#troubleshooting.

Go 1.26 or newer:

git clone https://github.com/JohnWatsoon/WatTunnel && cd WatTunnel
go test ./...
sh build.sh                     # dist/wattun-linux-amd64 and -arm64, each with a .sha256
sudo bash install.sh            # installs the binary you just built

Issues and pull requests are welcome. A change that makes the ICMP path slower won't be merged.

• Reference: docs/TECHNICAL.md
• Telegram channel (news and releases): @WatxDev, developer: @watxox
• Bugs: issues
• License: MIT. Uses golang.org/x/crypto, x/net and x/sys (BSD-3-Clause). GOST, Backhaul and BackPack were studied for ideas and as benchmarks; no code was copied.