# Realm Full-Featured One-Click Network Forwarding Management β€” Pure Script Relay Server Setup [δΈ­ζ–‡](README.md) | [English](README_EN.md) | [Port Traffic Dog Introduction](port-traffic-dog-README.md) --- > πŸš€ **Network Forwarding Management Script** β€” Tracks every feature of the latest official Realm release, network link testing, Port Traffic Dog, stays true to a minimalist core, visual rule management for maximum efficiency, built entirely with shell scripts ## Script Interface Preview
Click to view interface screenshots ### xwPF.sh Realm Forwarding Script ![81ce7ea9e40068f6fda04b66ca3bd1ff.gif](https://i.mji.rip/2025/12/12/81ce7ea9e40068f6fda04b66ca3bd1ff.gif) ### Port Traffic Dog ![cc59017896d277a8b35109ae44eac977.gif](https://i.mji.rip/2025/12/12/cc59017896d277a8b35109ae44eac977.gif) ### Relay Network Link Testing Script ``` ===================== Network Link Test β€” Full Report ===================== ✍️ Parameter Test Report ───────────────────────────────────────────────────────────────── Initiated from local machine (client) Target: 92.112.*.*:5201 Direction: Client ↔ Server Duration per test: 30 seconds System: Debian GNU/Linux 12 | Kernel: 6.1.0-35-cloud-amd64 Local: cubic+htb (congestion control + qdisc) TCP receive buffer (rmem): 4096 131072 6291456 TCP send buffer (wmem): 4096 16384 4194304 🧭 TCP Large-Packet Route Analysis (via nexttrace) ───────────────────────────────────────────────────────────────── AS path: AS979 > AS209699 ISP: Private Customer - SBC Internet Services Geo path: Japan > Singapore Map: https://assets.nxtrace.org/tracemap/b4a9ec9f-8b69-5793-a9b6-0cd0981d8de0.html ───────────────────────────────────────────────────────────────── 🌐 BGP Peering Analysis (via bgp.tools) ───────────────────────────────────────────────────────────────── Upstreams: 9 β”‚ Peers: 44 AS979 β”‚AS21859 β”‚AS174 β”‚AS2914 β”‚AS3257 β”‚AS3356 β”‚AS3491 NetLab β”‚Zenlayer β”‚Cogent β”‚NTT β”‚GTT β”‚Lumen β”‚PCCW AS5511 β”‚AS6453 β”‚AS6461 β”‚AS6762 β”‚AS6830 β”‚AS12956 β”‚AS1299 Orange β”‚TATA β”‚Zayo β”‚Sparkle β”‚Liberty β”‚Telxius β”‚Arelion AS3320 DTAG ───────────────────────────────────────────────────────────────── Image: https://bgp.tools/pathimg/979-55037bdd89ab4a8a010e70f46a2477ba7456640ec6449f518807dd2e ───────────────────────────────────────────────────────────────── ⚑ Link Parameter Analysis (via hping3 & iperf3) ───────────────────────────────────────────────────────────────────────────────── PING & Jitter ⬆️ TCP Upload ⬇️ TCP Download ───────────────────────── ───────────────────────────── ───────────────────────────── Avg: 72.3ms 220 Mbps (27.5 MB/s) 10 Mbps (1.2 MB/s) Min: 69.5ms Total transferred: 786 MB Total transferred: 35.4 MB Max: 75.9ms Retransmits: 0 Retransmits: 5712 Jitter: 6.4ms ───────────────────────────────────────────────────────────────────────────────────────────── Direction β”‚ Throughput β”‚ Packet Loss β”‚ Jitter ───────────────────────────────────────────────────────────────────────────────────────────── ⬆️ UDP Up β”‚ 219.0 Mbps (27.4 MB/s) β”‚ 2021/579336 (0.35%) β”‚ 0.050 ms ⬇️ UDP Down β”‚ 10.0 Mbps (1.2 MB/s) β”‚ 0/26335 (0%) β”‚ 0.040 ms ───────────────────────────────────────────────────────────────── Completed: 2025-08-28 20:12:29 | Source: https://github.com/zywe03/realm-xwPF ```
## Quick Start ### One-Click Install ```bash wget -qO- https://raw.githubusercontent.com/zywe03/realm-xwPF/main/xwPF.sh | sudo bash -s install ``` ### Behind a Restricted Network? Use an Accelerated Mirror ```bash wget -qO- https://v6.gh-proxy.org/https://raw.githubusercontent.com/zywe03/realm-xwPF/main/xwPF.sh | sudo bash -s install ``` If the mirror is down, retry a few times or switch to another proxy with built-in acceleration. ## Offline Installation (No Internet Access)
Click to expand offline installation method For servers with absolutely no network connectivity. **1. Download the following files on a machine that does have internet access** - **Main script**: [xwPF.sh](https://github.com/zywe03/realm-xwPF/raw/main/xwPF.sh) - **Module files** (all required): https://github.com/zywe03/realm-xwPF/tree/main/lib - **Realm binary** (pick the one matching your architecture): | Architecture | Typical Systems | Download Link | Detection | |---|---|---|---| | x86_64 | Standard 64-bit servers | [realm-x86_64-unknown-linux-gnu.tar.gz](https://github.com/zhboner/realm/releases/latest) | `uname -m` β†’ `x86_64` | | aarch64 | ARM64 servers | [realm-aarch64-unknown-linux-gnu.tar.gz](https://github.com/zhboner/realm/releases/latest) | `uname -m` β†’ `aarch64` | | armv7 | ARM32 (e.g. Raspberry Pi) | [realm-armv7-unknown-linux-gnueabihf.tar.gz](https://github.com/zhboner/realm/releases/latest) | `uname -m` β†’ `armv7l` / `armv6l` | **2. Place the files on the target server** ``` /usr/local/bin/ ← Script install directory (fixed path) β”œβ”€β”€ xwPF.sh ← Main script └── lib/ ← Create this subdirectory β”œβ”€β”€ core.sh β”œβ”€β”€ rules.sh β”œβ”€β”€ server.sh β”œβ”€β”€ realm.sh └── ui.sh ~/ ← Put the Realm tarball anywhere else └── realm-xxx.tar.gz ``` **3. Run the offline installation** ```bash chmod +x /usr/local/bin/xwPF.sh ln -sf /usr/local/bin/xwPF.sh /usr/local/bin/pf bash /usr/local/bin/xwPF.sh ``` Select **1. Install & Configure**, then: 1. When prompted **Update script? (y/N):** β†’ Press Enter to skip (cannot update offline) 2. When prompted **Enter full path for offline Realm installation (press Enter to download automatically):** β†’ Provide the full path to the Realm tarball
## ✨ Core Features - **Full Native Realm Feature Set** β€” Tracks every feature in the latest Realm release - TCP / UDP - WS / WSS / TLS encryption, decryption, and forwarding - Single relay β†’ multiple exits - Multiple relays β†’ single exit - Proxy Protocol - MPTCP - Bind specific entry or exit IP on the relay (for multi-IP, one-to-many, many-to-one) - Bind specific entry or exit NIC on the relay (for multi-NIC setups) - More at [zhboner/realm](https://github.com/zhboner/realm) - **Multi-Distro Support** β€” Works on Debian/Ubuntu, Alpine, CentOS/RHEL and derivatives, auto-detects package manager and init system (systemd / OpenRC) - **Quick Start** β€” One-click install, lightweight, get up and running with network forwarding fast - **Smart Detection** β€” Auto-detects system architecture, port conflicts, and connection availability - **Tunnel Building** β€” Dual-Realm architecture with TLS, WS, WSS tunnel support - **Load Balancing** β€” Round-robin, IP hash, and configurable weight distribution - **Failover** β€” Automatic failure detection using native system tools, keeping things lightweight - **Rule Annotations** β€” Clear labeling for every rule β€” no more memorizing port mappings - **Port Traffic Dog** β€” Per-port traffic stats, rate limiting, throttling, with configurable notifications - **Intuitive MPTCP Configuration** β€” Clean, visual MPTCP interface - **Network Link Testing** β€” Measure latency, bandwidth, stability, and large-packet routing (powered by hping3, iperf3, nexttrace, bgp.tools) - **One-Click Export** β€” Bundle everything into a tarball for seamless migration (annotations and all) - **One-Click Import** β€” Recognize and restore from an exported bundle - **Batch Import** β€” Parse and import custom Realm rule configs for easy rule-set management - **Clean Uninstall** β€” Phased, thorough cleanup β€” *"I leave as quietly as I came"* ## Architecture Diagrams β€” How It Works in Different Scenarios (Recommended Reading)
Single-End Realm: Forward-Only (Most Common) The relay server runs Realm; the exit server runs your application. Realm on the relay simply passes packets received on the configured listen IP:port straight through to the exit β€” encryption and decryption are handled entirely by the application on the exit server. The encryption protocol for the entire link is therefore determined by the exit server's application. ![e3c0a9ebcee757b95663fc73adc4e880.png](https://i.mji.rip/2025/07/17/e3c0a9ebcee757b95663fc73adc4e880.png)
Dual-End Realm: Building Tunnels The relay server runs Realm; the exit server runs **both** Realm and your application. An extra Realm-to-Realm encrypted transport layer is added between the two Realm instances. #### The relay's encryption type, SNI domain, etc. must match the exit server's β€” otherwise decryption will fail ![4c1f0d860cd89ca79f4234dd23f81316.png](https://i.mji.rip/2025/07/17/4c1f0d860cd89ca79f4234dd23f81316.png)
Load Balancing + Failover - Same port forwarding across multiple exit servers ![a9f7c94e9995022557964011d35c3ad4.png](https://i.mji.rip/2025/07/15/a9f7c94e9995022557964011d35c3ad4.png) - Frontend > Multiple Relays > Single Exit ![2cbc533ade11a8bcbbe63720921e9e05.png](https://i.mji.rip/2025/07/17/2cbc533ade11a8bcbbe63720921e9e05.png) - `Round Robin` mode (roundrobin) Continuously rotates traffic across exit servers in the rule group - `IP Hash` mode (iphash) Routes traffic based on a hash of the source IP, ensuring the same client always hits the same exit server - Weight = allocation probability - Failover When an exit is detected as down, it is temporarily removed from the load-balancing pool. Once it recovers, it is automatically added back. Native Realm does not currently support failover. - How the script implements it ``` 1. systemd timer fires (every 4 seconds) ↓ 2. Run health-check script ↓ 3. Read rule configuration files ↓ 4. TCP connectivity probe for each target β”œβ”€β”€ nc -z -w3 target port └── Fallback: telnet target port ↓ 5. Atomically update health status file β”œβ”€β”€ Success: success_count++, fail_count=0 └── Failure: fail_count++, success_count=0 ↓ 6. Evaluate state transitions β”œβ”€β”€ 2 consecutive failures β†’ mark as DOWN └── 2 consecutive successes + 120 s cooldown (prevents flapping) β†’ mark as UP ↓ 7. If state changed, create an update marker file ``` Monitor IP changes in real time from the client: `while ($true) { (Invoke-WebRequest -Uri 'http://ifconfig.me/ip' -UseBasicParsing).Content; Start-Sleep -Seconds 1 }` or `while true; do curl -s ifconfig.me; echo; sleep 1; done`
Dual-End Realm with System MPTCP **Q: Does an MPTCP endpoint create a new virtual NIC?** No. It tells the MPTCP protocol stack: *this IP address is available for MPTCP connections on a specific path β€” data can flow through this IP and its associated NIC.* This lets a single TCP connection use multiple network paths simultaneously. **Q: Why do you need to specify both IP and NIC?** NIC: the kernel needs to know which physical interface this IP maps to for routing decisions. IP: the MPTCP stack needs to know which addresses it may use to establish subflows. `192.168.1.100 dev eth0 subflow fullmesh` = MPTCP may establish subflows via eth0 at this IP `10.0.0.50 dev eth1 subflow fullmesh` = MPTCP may establish subflows via eth1 at this IP For finer-grained control, consider also configuring `signal` endpoints on the server side.
Port Forwarding vs. Chained Proxies (Segmented Proxy) Two concepts that are easy to confuse. **In a nutshell** Port forwarding simply relays traffic from one port to another. A chained (segmented) proxy splits the connection into two separate proxy hops β€” also called a two-tier proxy. (Detailed setup may be covered in a future guide.) **Each approach has its strengths** β€” it depends on the use case | Note: some regional servers prohibit installing proxy software | That said, chained proxies can be very flexible in certain scenarios | Chained Proxy | Port Forwarding | | :--- | :--- | | Every hop in the chain needs proxy software | Relay runs a forwarder (no proxy needed), exit runs the proxy | | Higher configuration complexity | Lower complexity (L4 forwarding) | | Unpack / repack overhead at each hop | Native TCP/UDP passthrough β€” theoretically faster | | Finer outbound control (per-hop exit config) | Limited outbound control |
### Dependencies All dependencies are **native Linux lightweight tools** β€” keeping the system clean and minimal. | Tool | Purpose | Tool | Purpose | |---|---|---|---| | `curl` | Downloads & IP lookup | `wget` | Fallback downloader | | `tar` | Archive extraction | `unzip` | ZIP extraction | | `bc` | Arithmetic | `nc` | TCP connectivity probe | | `bash /dev/tcp` | TCP connectivity probe (built-in) | `inotify` | File-change markers | | `grep`/`cut` | Text processing | `jq` | JSON processing | | `iproute2` | MPTCP endpoint mgmt | `nftables` | Per-port traffic stats | | `tc` | Traffic shaping | | | ## File Structure > The script fetches components on demand β€” additional features are downloaded only when you select them from the menu. ### Core Install (included by default) ``` System Files β”œβ”€β”€ /usr/local/bin/ β”‚ β”œβ”€β”€ realm # Realm binary β”‚ β”œβ”€β”€ xwPF.sh # Management script entry point β”‚ β”œβ”€β”€ lib/ # Module directory β”‚ β”‚ β”œβ”€β”€ core.sh # Core utilities (system detection / deps / network / validation) β”‚ β”‚ β”œβ”€β”€ rules.sh # Rule management (CRUD / load balancing / weights) β”‚ β”‚ β”œβ”€β”€ server.sh # Server config (relay & exit interaction / MPTCP management) β”‚ β”‚ β”œβ”€β”€ realm.sh # Realm install / config generation / service management β”‚ β”‚ └── ui.sh # Interactive menu / status display / uninstall β”‚ └── pf # Quick-launch shortcut β”‚ β”œβ”€β”€ /etc/realm/ # Realm configuration directory β”‚ β”œβ”€β”€ manager.conf # State management file β”‚ β”œβ”€β”€ config.json # Realm working config β”‚ └── rules/ # Forwarding rules directory β”‚ β”œβ”€β”€ rule-1.conf # Rule 1 config β”‚ └── ... β”‚ └── /etc/systemd/system/ └── realm.service # Realm service unit ``` ### Downloaded on Demand (fetched when you select the feature) ``` Failover (downloaded when failover is enabled) β”œβ”€β”€ /usr/local/bin/xwFailover.sh # Failover management script β”œβ”€β”€ /etc/realm/health/ β”‚ └── health_status.conf # Health status file └── /etc/systemd/system/ β”œβ”€β”€ realm-health-check.service # Health check service └── realm-health-check.timer # Health check timer Port Traffic Dog (downloaded when selected) β”œβ”€β”€ /usr/local/bin/port-traffic-dog.sh # Port Traffic Dog script β”œβ”€β”€ /usr/local/bin/dog # Quick-launch shortcut └── /etc/port-traffic-dog/ β”œβ”€β”€ config.json # Monitoring configuration β”œβ”€β”€ traffic_data.json # Traffic data backup β”œβ”€β”€ notifications/ # Notification modules β”‚ └── telegram.sh # Telegram notification module └── logs/ # Log directory Relay Network Link Test (downloaded when selected) └── /usr/local/bin/speedtest.sh # Network link test script Config Recognition Import (downloaded when selected) └── /etc/realm/xw_realm_OCR.sh # Realm config recognition script MPTCP (created when MPTCP is enabled) └── /etc/sysctl.d/90-enable-MPTCP.conf # MPTCP sysctl config ``` ## 🀝 Support - **More Projects:** [https://github.com/zywe03](https://github.com/zywe03) - **Homepage:** [https://zywe.de](https://zywe.de) - **Bug Reports:** [GitHub Issues](https://github.com/zywe03/realm-xwPF/issues) - **Chat:** [Telegram Group](https://t.me/zywe_chat) --- **⭐ If this project is useful to you, a Star would be much appreciated!** [![Star History Chart](https://api.star-history.com/svg?repos=zywe03/realm-xwPF&type=Date)](https://www.star-history.com/#zywe03/realm-xwPF&Date)