KKRainbow
887c701ee8
* test(connector): label the convergence waits of the direct connect test foreign_network_advertises_listeners_for_direct_connect failed in run 39903378976 with a bare "Timeout" from wait_for_condition, so the log cannot tell which convergence gate was hit: each of the two node pairs has four waits (remote sees client-net, client learns the route, remote learns the client peer, direct connection established). Add wait_for_condition_with_reason and use it for all four waits, with the node pair and the step in the message. Timeouts and assertions are unchanged. * test(connector): wait for the reply route the router actually uses The reverse-route wait added in #2738 checked the foreign network peer list, which only holds direct connections. The packet router also routes through the route table, so the wait could time out although a reply would have been routed, and a direct connection often appears only later in the flow. Call the router lookup (get_gateway_peer_id for the client peer on the remote foreign network) through a test accessor and wait until any gateway is available. CI run 39911533854 timed out on the previous condition for both tcp and udp. * test(connector): wait for the reply route the router actually uses The reverse-route wait added in #2738 checked the foreign network peer list, which only holds direct connections. The packet router routes through the route table as well (get_gateway_peer_id), so the wait could time out although a reply would have been routed, and a direct connection often appears only later in the flow. Add a test accessor that performs the router lookup on the remote foreign network and wait until any gateway is available. Drops the gate labels from this branch, they are covered by #2749. CI run 39911533854 timed out on the previous condition for both tcp and udp. * test(connector): report remote routing state when get_ip_list times out CI run 39921692334 failed after the gateway wait succeeded: the RPC itself timed out with all waits green, so the gateway was available but the reply still did not arrive. On RPC error, print the remote client-net state next to the error: the gateway chosen for the client, whether that gateway is a direct peer, and the peer ids currently connected. This makes the next failure attributable without changing any assertion or timeout. * test(connector): also report the origin mapping of the chosen gateway A wrapped foreign network packet is forwarded by mapping the gateway foreign peer id to its origin (parent network) peer id and sending it through the parent peer map, so a gateway that is not directly connected does not by itself mean the reply is dropped. Extend the RPC failure snapshot with get_origin_my_peer_id for the chosen gateway and whether the parent peer map can route to that origin id. * test(connector): capture the foreign network forwarding decisions The routing snapshot taken after the timeout cannot explain a lost RPC reply: it is sampled after the timeout, re-queries the state (which may converge later) and does not show whether the request reached the remote at all. Install a test-scoped tracing subscriber that keeps debug events from easytier_core::peers, so a failing run prints the forwarding decisions (dropped relay data, missing origin peer id, failed direct send) when they happen. Only this test process is affected. * test(connector): isolate foreign listener discovery The foreign DirectConnectorRpc handler collects interface addresses in the default network namespace. Although the three-node fixture gives each instance its own namespace, the RPC still observes host bridges and veth interfaces created and removed by concurrent tests. Add both protocol cases to the existing exclusive override for host interfaces. Preserve the reply route readiness check, RPC deadline, listener assertion, and final direct connection assertion. Diagnostics with 32 test threads on four CPUs showed interface enumeration delaying the RPC handler by over two seconds. With this override, the same mixed workload kept all observed handlers below 1.1 ms. Remove the temporary routing snapshot accessors, failure dump, and test tracing setup. Keep only the helpers used by the readiness check.
EasyTier
✨ A simple, secure, decentralized virtual private network solution powered by Rust and Tokio
📚 Full Documentation | 🖥️ Web Console | 📝 Download Releases | Nightly | 🧩 Third Party Tools | ❤️ Sponsor
Features
Core Features
- 🔒 Decentralized: Nodes are equal and independent, no centralized services required
- 🚀 Easy to Use: Multiple operation methods via web, client, and command line
- 🌍 Cross-Platform: Supports Win/MacOS/Linux/FreeBSD/Android and X86/ARM/MIPS architectures
- 🔐 Secure: AES-GCM or WireGuard encryption, prevents man-in-the-middle attacks
Advanced Capabilities
- 🔌 Efficient NAT Traversal: Supports UDP and IPv6 traversal, works with NAT4-NAT4 networks
- 🌐 Subnet Proxy: Nodes can share subnets for other nodes to access
- 🔄 Intelligent Routing: Latency priority and automatic route selection for best network experience
- ⚡ High Performance: Zero-copy throughout the entire link, supports TCP/UDP/WSS/WG protocols
Network Optimization
- 📊 UDP Loss Resistance: KCP/QUIC proxy optimizes latency and bandwidth in high packet loss environments
- 🔧 Web Management: Easy configuration and monitoring through web interface
- 🛠️ Zero Config: Simple deployment with statically linked executables
Quick Start
📥 Installation
Choose the installation method that best suits your needs:
Linux (Recommended):
curl -fsSL "https://github.com/EasyTier/EasyTier/blob/main/script/install.sh?raw=true" | sudo bash -s install
Homebrew (MacOS/Linux):
brew tap brewforge/chinese
brew install --cask easytier-gui
Windows (Recommended, run with administrator privileges):
irm "https://github.com/EasyTier/EasyTier/blob/main/script/install.ps1?raw=true" | iex
Install via cargo (Latest development version):
cargo install --git https://github.com/EasyTier/EasyTier.git easytier
Install prebuilt CLI tools with cargo-binstall (specify an existing release version):
cargo binstall --git https://github.com/EasyTier/EasyTier.git --version 2.6.4 easytier
This installs easytier-core and easytier-cli using the repository's metadata, independently of crates.io publication. On Windows, also copy the DLL and driver files from the matching release ZIP beside the installed binaries; binstall only installs executables.
Install pre-built binary (Recommended, All platforms supported)
For a smaller executable, try easytier-mini, which supports basic TCP/UDP networking. See its documentation for supported features and usage.
Additional steps:
One-Click Register Service (Automatically start when the system boots and run in the background)
🚀 Basic Usage
Quick Networking with Shared Nodes
EasyTier supports quick networking using shared public nodes. When you don't have a public IP, you can use the free shared nodes provided by the EasyTier community. Nodes will automatically attempt NAT traversal and establish P2P connections. When P2P fails, data will be relayed through shared nodes.
When using shared nodes, each node entering the network needs to provide the same --network-name and --network-secret parameters as the unique identifier of the network.
Taking two nodes as an example (Please use more complex network name to avoid conflicts):
- Run on Node A:
# Run with administrator privileges
sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<SharedNodeIP>:11010
- Run on Node B:
# Run with administrator privileges
sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<SharedNodeIP>:11010
After successful execution, you can check the network status using easytier-cli:
| ipv4 | hostname | cost | lat_ms | loss_rate | rx_bytes | tx_bytes | tunnel_proto | nat_type | id | version |
| ------------ | -------------- | ----- | ------ | --------- | -------- | -------- | ------------ | -------- | ---------- | --------------- |
| 10.126.126.1 | abc-1 | Local | * | * | * | * | udp | FullCone | 439804259 | 2.6.2-70e69a38~ |
| 10.126.126.2 | abc-2 | p2p | 3.452 | 0 | 17.33 kB | 20.42 kB | udp | FullCone | 390879727 | 2.6.2-70e69a38~ |
| | PublicServer_a | p2p | 27.796 | 0.000 | 50.01 kB | 67.46 kB | tcp | Unknown | 3771642457 | 2.6.2-70e69a38~ |
You can test connectivity between nodes:
# Test connectivity
ping 10.126.126.1
ping 10.126.126.2
Note: If you cannot ping through, it may be that the firewall is blocking incoming traffic. Please turn off the firewall or add allow rules.
To improve availability, you can connect to multiple shared nodes simultaneously:
# Connect to multiple shared nodes
sudo easytier-core -d --network-name abc --network-secret abc -p tcp://<SharedNodeIP1>:11010 -p udp://<SharedNodeIP2>:11010
Once your network is set up successfully, you can easily configure it to start automatically on system boot. Refer to the One-Click Register Service guide for step-by-step instructions on registering EasyTier as a system service.
Decentralized Networking
EasyTier is fundamentally decentralized, with no distinction between server and client. As long as one device can communicate with any node in the virtual network, it can join the virtual network. Here's how to set up a decentralized network:
- Start First Node (Node A):
# Start the first node
sudo easytier-core -i 10.144.144.1
After startup, this node will listen on the following ports by default:
- TCP: 11010
- UDP: 11010
- WebSocket: 11011
- WebSocket SSL: 11012
- WireGuard: 11013
- Connect Second Node (Node B):
# Connect to the first node using its public IP
sudo easytier-core -i 10.144.144.2 -p udp://FIRST_NODE_PUBLIC_IP:11010
- Verify Connection:
# Test connectivity
ping 10.144.144.2
# View connected peers
easytier-cli peer
# View routing information
easytier-cli route
# View local node information
easytier-cli node
For more nodes to join the network, they can connect to any existing node in the network using the -p parameter:
# Connect to any existing node using its public IP
sudo easytier-core -i 10.144.144.3 -p udp://ANY_EXISTING_NODE_PUBLIC_IP:11010
🔍 Advanced Features
Subnet Proxy
Assuming the network topology is as follows, Node B wants to share its accessible subnet 10.1.1.0/24 with other nodes:
flowchart LR
subgraph Node A Public IP 22.1.1.1
nodea[EasyTier<br/>10.144.144.1]
end
subgraph Node B
nodeb[EasyTier<br/>10.144.144.2]
end
id1[[10.1.1.0/24]]
nodea <--> nodeb <-.-> id1
To share a subnet, add the -n parameter when starting EasyTier:
# Share subnet 10.1.1.0/24 with other nodes
sudo easytier-core -i 10.144.144.2 -n 10.1.1.0/24
Subnet proxy information will automatically sync to each node in the virtual network, and each node will automatically configure the corresponding route. You can verify the subnet proxy setup:
- Check if the routing information has been synchronized (the proxy_cidrs column shows the proxied subnets):
# View routing information
easytier-cli route
- Test if you can access nodes in the proxied subnet:
# Test connectivity to proxied subnet
ping 10.1.1.2
WireGuard Integration
EasyTier can act as a WireGuard server, allowing any device with a WireGuard client (including iOS and Android) to access the EasyTier network. Here's an example setup:
flowchart LR
ios[[iPhone<br/>WireGuard Installed]]
subgraph Node A Public IP 22.1.1.1
nodea[EasyTier<br/>10.144.144.1]
end
subgraph Node B
nodeb[EasyTier<br/>10.144.144.2]
end
id1[[10.1.1.0/24]]
ios <-.-> nodea <--> nodeb <-.-> id1
- Start EasyTier with WireGuard portal enabled:
# Register one WireGuard client as virtual peer 10.144.144.3
sudo easytier-core -i 10.144.144.1 \
--network-secret portal-secret \
--vpn-portal wg://0.0.0.0:11013 \
--vpn-portal-private-key "$(wg genkey)" \
--vpn-portal-client phone=10.144.144.3
- Get WireGuard client configuration:
# Get WireGuard client configuration
easytier-cli vpn-portal
- In the output configuration, replace a wildcard
Peer.Endpointwith the public IP/domain of your EasyTier node, then import it.Interface.Addressis local to that WireGuard client and may be changed to any IPv4 address; EasyTier translates it to the registered virtual-peer address.
Self-Hosted Public Shared Node
You can run your own public shared node to help other nodes discover each other. A public shared node is just a regular EasyTier network (with same network name and secret) that other networks can connect to.
To run a public shared node:
# No need to specify IPv4 address for public shared nodes
sudo easytier-core --network-name mysharednode --network-secret mysharednode
Related Projects
- ZeroTier: A global virtual network for connecting devices.
- TailScale: A VPN solution aimed at simplifying network configuration.
Contact Us
- 💬 Telegram Group
- 👥 [QQ Group]
License
EasyTier is released under the LGPL-3.0.
Responsible Use
Use EasyTier only for lawful purposes and in compliance with applicable laws and regulations. You are responsible for ensuring that you are authorized to connect to and administer the networks and devices involved.
Sponsor
CDN acceleration and security protection for this project are sponsored by Tencent EdgeOne.
Special thanks to Langlang Cloud and RainCloud for sponsoring our public servers. We also thank Linfeng Cloud (林枫云) for supporting EasyTier.
If you find EasyTier helpful, please consider sponsoring us. Software development and maintenance require a lot of time and effort, and your sponsorship will help us better maintain and improve EasyTier.
