🪁 WatTunnel

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

English · فارسی

You need two Linux servers (amd64 or arm64) with systemd and root. Set up Kharej first: it makes 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. Run wattun, press n (new tunnel), choose Kharej, and pick Auto as the connection type. You get a token:

wat1:aWNtcHwyMDMuMC4xMTMuMTB8a1E3...

3. Iran. Run wattun, press n, choose Iran, and paste the token. The menu tests every connection type and offers the fastest that works: press Enter to take it. Then enter your ports, for example 443, 8443:443, 53/udp (8443:443 means users connect to Iran port 8443 and reach Kharej port 443).

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

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

Done. Users connect to the Iran server's IP, and Kharej forwards only to its own 127.0.0.1.

Auto uses data. The manager prints the worst case before it starts: up to 1184 MB for a normal test, about 416 MB more if the token was made with --extended, and far less on a filtered route. On a traffic-billed server, pick a type yourself:

wattun opens the dashboard. Press a tunnel's number for its page (logs, diagnose, speed test, ports, change connection type with c), u updates, and s holds rollback and auto-heal. Auto-heal restarts an Iran tunnel whose link has been down for 3 minutes.

wattun status          # one line per tunnel
wattun test NAME       # connection doctor + speed test
wattun ports NAME      # edit port mappings (applied live)
wattun update          # update the binary and the menu

After Iran picks a type, an auto Kharej tunnel closes everything unused about 5 minutes later and restarts the side that stays open, so its connections drop once. The Kharej main menu shows carriers open or closed under each auto tunnel, with the count and the time left. Press c there to switch it: what you open stays open until you close it. On the next check after that close, the type Iran uses becomes the tunnel under the same name, and the test listeners are deleted. Deleting the auto tunnel before that never deletes the side Iran is connected through.

To change the type or re-test later, open the carriers on Kharej first. If you skip that, the manager reopens by itself after 3 failed checks (at most once per 10 minutes).

WatTunnel connects an Iran server (where your users connect) to a Kharej server (where your service runs) and forwards any TCP or UDP port between them. One static binary, no dependencies.

• Rides what your route lets through: icmp, udp, tcp, tls, ws, wss, h2, h2c, grpc, gre, ipip, Cloudflare with ECH, reverse mode, or several of them bonded into one tunnel.
• Gets past filters: fake-SNI desync, udp-dns, tcp-mimic, connection rotation with pool-rotate, and wattun matrix NAME to try the combinations and apply the best. wattun blackout NAME turns the whole kit on.
• Hard to classify: no constant byte in a packet header, idle packets at random sizes, HTTP carriers that answer like nginx, and 13 shaped carriers such as vxlan and ntp-direct. Opt-in shape-data and noise cost bandwidth.
• Tunes itself: defaults follow the CPU and RAM, and the auto test tunes sessions and conns on your route.
• Loss does not slow it down: pacing follows delay, and fec: auto sends parity only while packets are really being lost.
• Runs itself: live port changes, per-port stats and quotas, auto-heal, update with rollback.

Real servers, unfiltered path. Full tables and how each was measured: docs/TECHNICAL.md.

On a route that cuts every direct Iran → Kharej flow within a second (UDP after 3 datagrams, TCP after 3 KB, on every port, with every payload), plain tunnels connect for a moment and die. Through that filter (3.0.0, one vCPU per server, 82 ms, one run each, so read these as orders of magnitude):

On another route, where Cloudflare passes only flows named www.cloudflare.com, wss with fake-mode: rst connected in 2 s at 9-15 MB/s down and 2-5 MB/s up (field test).

Same servers, same filtered route (only ICMP passes), real VLESS traffic through each tunnel:

On a clean, unfiltered link every tunnel reaches line rate and GOST uses a little less CPU; WatTunnel still halves small-request latency there (43 ms vs 83 ms) because interactive traffic goes first.

An idle tunnel sends about 2 small packets a second: ~11.5 MB a day on udp or icmp, 0.1-0.2 % of one CPU core and 10-17 MB of RAM. A busy ICMP tunnel with 250-300 users runs in about 40 MB. Under load the overhead is +0.25 % on tcp and about +5 % on udp or icmp with mtu: 1400. Details.

• Encryption: ChaCha20-Poly1305 with an X25519 exchange on every session, so recorded traffic stays unreadable if a key file leaks later.
• Only the Iran ↔ Kharej leg is protected. Between your users and Iran, run an end-to-end encrypted protocol such as VLESS+Reality, TLS or WireGuard inside the tunnel.
• The token contains the key. Treat it like a password and share it only over a private channel.
• Kharej dials only its own 127.0.0.1, and only allowed ports. On a direct carrier, allow-clients also limits the key to the client IPs you name. Keep metrics on 127.0.0.1.
• Signed installs: the installer checks the binary and manager against an RSA-signed SHA256SUMS and refuses a bad signature. The script itself, fetched through a mirror, is only trust-on-first-use.
• Still visible to the network: the server's address, and the volume and timing of packets.

What each anti-censor option hides, and what none of them hides: spoofing and shaping. Full security model.

Everything else is in docs/TECHNICAL.md: reverse mode · auto mode · Cloudflare / CDN · bonding · managing tunnels · config file · monitoring · troubleshooting · release history · Windows and building from source

• Telegram channel (news and releases): @WatxDev, developer: @watxox
• Bugs and ideas: issues. A change that makes the ICMP path slower won't be merged.
• 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.