Hedioum-Pool-Tunnel

module
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Aug 18, 2026 License: GPL-3.0

README

Hedioum Dynamic Pool Tunnel (Chaos Mesh)

Downloads Latest release Stars

🌐 🇬🇧 English · 🇮🇷 فارسی · 🇷🇺 Русский · 🇨🇳 中文 · Latest release

Hedioum Pool Tunnel is a high-performance, enterprise-grade connection multiplexer designed to bypass strict Deep Packet Inspection (DPI) and thwart TCP Meltdown under heavy load. It operates as a Custom SDN Overlay, wrapping encrypted VLESS/Trojan traffic into highly obfuscated, dynamically scaling connection pools that wear interchangeable disguises — SSH, TLS/HTTPS, SMTP/IMAP, and a DirectAdmin control panel — over a modern authenticated-encryption transport.

🌟 Key Features

  • Chaos Mesh Dynamic Balancing: Replaces traditional Round-Robin with a smart "Least Loaded" distribution algorithm. The system actively monitors real-time bandwidth (Mbps) and scales physical connections up or down based on actual traffic volume, not just stream count.
  • DPI Evasion (Fluctuating Caps): Implements dynamic bandwidth jitter. Each physical connection operates under a randomized, fluctuating bandwidth limit (e.g., 8 Mbps ± 2 Mbps) to break static patterns, making the tunnel indistinguishable from organic, noisy internet traffic.
  • Zero-Downtime Connection Draining: During scale-down events, idle physical connections are placed in a Draining state. They wait for active logical streams (like open socket connections) to finish naturally before closing, ensuring zero lag or disconnections for end-users.
  • Enterprise Lifecycle Management: Features an interactive TUI dashboard equipped with a Blue-Green Self-Updater (with automatic rollback on failure) and a Clean Uninstaller that purges all traces without leaving orphaned files.
  • Authenticated Encryption (ChaCha20-Poly1305): The transport is wrapped in a modern AEAD stream keyed via HKDF from your token. ChaCha20 needs no AES-NI, so overhead stays minimal on cheap/ARM VPS. The token is never sent on the wire and also keys the cipher, so a passive observer sees only random salts followed by ciphertext.
  • Real Certificate (Let's Encrypt) or DirectAdmin Persona: Point a domain at the foreign node (--domain) and the TLS mimic serves a genuine, auto-renewing Let's Encrypt certificate (ACME) — CT-logged like any real HTTPS host, with a DNS A/AAAA pre-check, a self-healing warm-and-renew loop, and a graceful self-signed fallback so a certificate hiccup can never break the tunnel. Without a domain, a self-signed cert is used. Optionally the node wears a DirectAdmin control-panel persona: a pixel-faithful DirectAdmin Evolution login (light + dark mode, real assets embedded in the binary) on :2222, where a self-signed certificate is authentic — and the web ports answer exactly like a real DirectAdmin box.
  • Protocol-Aware Connection Lifecycle: After raw volume, the strongest real-world tunnel tell is protocol × connection lifetime. SSH is the trusted long-lived backbone (rotating on a randomized multi-hour schedule); every non-SSH mimic is auxiliary with a randomized 5–60 min lifetime + 1–5 GB transfer budget, then it drains and the pool churns to a fresh pipe with a new random mimic. Each server's timings are seeded from its secret token, so no two servers churn alike.
  • Full TCP + UDP: A single local SOCKS5 port serves both TCP (CONNECT) and UDP (ASSOCIATE), so QUIC/HTTP3, DNS, and voice/video calls work. UDP rides its own dedicated (still SSH-masked) connection sub-pool, isolated from TCP so a bulk download can't stall a call, with drop-on-congestion so a slow link never buffers unboundedly. UDP never touches the wire between the nodes — it is tunnelled over the masked TCP link.
  • Optional IPv6: The inter-node link and egress-to-internet can use IPv6 (egress_ip_mode: ipv4 default / ipv6 / dual), opt-in so the server's IPv6 identity is never leaked by default.
  • Pluggable Protocol Mimicry (Arsenal): A single node can listen behind several camouflages at once — SSH (real SSH-2.0 banner mirrored byte-for-byte from the host's own sshd), TLS/HTTPS (a real TLS handshake; a real Let's Encrypt cert with a domain, self-signed otherwise), STARTTLS SMTP/IMAP (587/143), implicit-TLS SMTPS/IMAPS (465/993), and a DirectAdmin panel on :2222 (a faithful Evolution login). The hub spreads its physical pipes across these with a per-install fluctuating distribution (Chaos Mesh v2), so two servers running the same build present different, shifting on-wire signatures. Every mimic routes unauthorized probes to a protocol-appropriate decoy — the real sshd, the DirectAdmin login, or a web persona (Apache2 Ubuntu default page or a DirectAdmin hosting box, selectable via --decoy-style) whose Server/ETag/Last-Modified are per-install unique (seeded from the token, no fleet-wide signature). A plaintext decoy runs on :80 (redirecting to HTTPS when a domain is set) so even the bare IP looks like an ordinary web host to reputation scanners. See docs/MIMICS.md.
  • No DNS Leak by Design: the SOCKS5 ingress forwards the destination domain (never a locally-resolved IP) through the tunnel, so DNS is resolved on the foreign node — configure your client for remote DNS (domainStrategy: AsIs) and the Iran box emits no DNS query for tunneled destinations. See the verification steps in docs/MIMICS.md.
  • Channel-Bound Token Auth (no double crypto): The TLS mimic authenticates the peer with an HMAC bound to the server's live certificate fingerprint — proving knowledge of the token without ever sending it and defeating MITM — while keeping a single crypto layer (the TLS session itself) for uniform, high-throughput performance. The client uses uTLS (a real Chrome ClientHello) to defeat JA3 fingerprinting.
  • Throughput Engineering: BBR congestion control + fq qdisc are enabled on install, Yamux stream windows are widened to 16 MB for high bandwidth-delay-product links, and a built-in speedtest command measures real end-to-end egress throughput (un-shaped) per endpoint.

🏗 Architecture Topology

  1. X-UI (Iran): Authenticates the user, splits domestic traffic, and forwards international traffic to the local SOCKS5 Bridge.
  2. Hedioum Hub (Iran): Receives the SOCKS5 payload, evaluates pool health, and multiplexes the stream (via HashiCorp Yamux) over an authenticated, encrypted physical connection pool using the Chaos Mesh algorithm.
  3. Hedioum Egress (Foreign): Authenticates the Hub via the channel-bound handshake (unauthenticated probes are diverted to a protocol-appropriate decoy — the real sshd, or a plausible web page for the TLS/mail mimics), enforces SSRF protections (resolve-once, blocks private/link-local/CGNAT), resolves the destination DNS here (no leak in Iran), and dials the open internet over IPv4/IPv6/dual per egress_ip_mode.

🚀 Installation & Updates

The binary is self-sufficient: it installs its own systemd service, opens the firewall, and manages its config — so install.sh is just a thin bootstrap (detect architecture → download → run the binary). See docs/DEPLOY.md for the full guide, including non-interactive (Ansible-friendly) setup and the GitHub-blocked path.

Installation Order: install the Foreign (egress) node first to generate the auth token the Iran node needs.

One-line bootstrap (GitHub reachable)

Run on each VPS as root (foreign first):

bash <(curl -fsSL https://raw.githubusercontent.com/hedioum/Hedioum-Pool-Tunnel/main/install.sh)
Manual (GitHub blocked)

Copy the matching binary (hedioum-tunnel / hedioum-tunnel-arm64) to the server, then:

chmod +x hedioum-tunnel && ./hedioum-tunnel install && hedioum-tunnel
Non-interactive (automation)
hedioum-tunnel install
hedioum-tunnel setup-foreign --mimics all --move-ssh --domain vpn.example.com --decoy-style directadmin   # foreign; prints the token
hedioum-tunnel setup-iran   --alias DE-01 --target-ip <IP> --mimics all --socks-port 40001 --token <hex>
systemctl start hedioum.service

--mimics all enables the whole arsenal (ssh,tls,smtp,imap,smtps,imaps,directadmin); pass a comma list to pick a subset. --domain is optional (a real Let's Encrypt cert once DNS points at the node; self-signed otherwise) and --decoy-style is apache (default) or directadmin. Updates are rollback-safe (hedioum-tunnel update, or update --file <path> when GitHub is blocked).

Editing a node in place (only the flags you pass change; the token is kept unless --token/--rotate-token):

hedioum-tunnel edit-foreign --tls-port 2087 --decoy-style directadmin   # on the foreign
hedioum-tunnel edit-node --alias DE-01 --bw 12                          # on the Iran hub
Diagnostics
hedioum-tunnel probe     --node DE-01                 # per-mimic reachability of every endpoint (hub)
hedioum-tunnel speedtest --node DE-01 --mimic tls     # real un-shaped egress throughput (hub)
hedioum-tunnel check-ip                               # egress IP reputation: CLEAN / LIKELY-FLAGGED (foreign)

⚙️ Management Dashboard

To manage servers, view live connection status, or perform lifecycle operations, run the interactive dashboard from your terminal at any time:

hedioum-tunnel

Dashboard Capabilities:

  • View active egress pools, per-node endpoints (mimic → target), and live DPI Evasion dynamics (Limits & Jitter).
  • Monitor real-time daemon logs for Scale-Up/Down events and bandwidth usage.
  • Add, Edit, or Remove foreign egress nodes dynamically (edit pre-fills each field with its current value — press Enter to keep it), and Edit the foreign configuration in place.
  • Run a Speedtest or Probe endpoints (per-mimic reachability) straight from the menu.
  • Perform a safe Self-Update (fetches latest GitHub release).
  • Completely Uninstall and purge the daemon.

🛠 Building from Source

If you wish to compile the static binary manually:

git clone https://github.com/hedioum/Hedioum-Pool-Tunnel.git
cd Hedioum-Pool-Tunnel
make build-linux

☕ Support & Donate

If you found this project helpful for maintaining a free and open internet, and you want to support further development, consider buying the team a coffee!

USDT (Tether) Donation Addresses:

  • TRC20 (Tron): TRhwZFoHRZ9oux4emFXTj63aib9nuC2J2J
  • BEP20 (BSC): 0x051e31cb70076854C0b62F816d5a89D3def4A22E
  • ERC20 (Ethereum): 0x051e31cb70076854C0b62F816d5a89D3def4A22E
  • TON (The Open Network): UQCqq0wYNDVhq9AXAZ5vOQ2ZgMmP6O0UTgvU1YhNeIpkUp1s

Thank you for your support!

Directories

Path Synopsis
cmd
hedioum command
internal
firewall
Package firewall best-effort opens a TCP listen port on whichever firewall the host is running, so users are not silently blocked when the tunnel binds a non-default port.
Package firewall best-effort opens a TCP listen port on whichever firewall the host is running, so users are not silently blocked when the tunnel binds a non-default port.
ipcheck
Package ipcheck assesses the reputation of the server's egress public IP, so an operator can tell before/after deploying whether the address is a "clean" range or a pre-flagged datacenter IP (which silently degrades AI sites, some CDNs, etc.).
Package ipcheck assesses the reputation of the server's egress public IP, so an operator can tell before/after deploying whether the address is a "clean" range or a pre-flagged datacenter IP (which silently degrades AI sites, some CDNs, etc.).
logging
Package logging configures structured, journald-friendly logging for the daemon side (systemd, no TTY).
Package logging configures structured, journald-friendly logging for the daemon side (systemd, no TTY).
mimic
Package mimic provides pluggable camouflage layers.
Package mimic provides pluggable camouflage layers.
pairing
Package pairing defines the self-contained pairing token a foreign node prints and an operator pastes into the hub.
Package pairing defines the self-contained pairing token a foreign node prints and an operator pastes into the hub.
persona
Package persona groups the mimic library into coherent server identities.
Package persona groups the mimic library into coherent server identities.
securestream
Package securestream implements Hedioum's authenticated, encrypted wire protocol.
Package securestream implements Hedioum's authenticated, encrypted wire protocol.
tlscert
Package tlscert generates and loads the foreign node's self-signed TLS certificate for the TLS mimic.
Package tlscert generates and loads the foreign node's self-signed TLS certificate for the TLS mimic.
tunproto
Package tunproto defines the framing that rides inside each authenticated yamux stream between the Iran hub and the foreign egress.
Package tunproto defines the framing that rides inside each authenticated yamux stream between the Iran hub and the foreign egress.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL