UDPlex

README

UDPlex

English | 中文

UDPlex is a high-performance, component-based UDP traffic replication, forwarding, filtering, and smart routing tool that fans out the same UDP stream to multiple targets in parallel while handling return traffic, with support for authentication/encryption, protocol detection, load balancing, and multi-path redundancy or bandwidth-threshold smart splitting (useful for link acceleration and bandwidth aggregation).

Features

• Listen on specified UDP ports to receive packets
• Forward packets in parallel to multiple target servers
• Support bidirectional traffic forwarding
• Automatic reconnection for broken connections
• Configurable buffer sizes and timeout parameters
• Support authentication and encrypted transmission
• Support protocol detection and filtering
• Support Docker deployment

Usage

1. Edit the config.yaml file to configure listening addresses and forwarding targets
2. Run the program:

# Use default configuration file
./UDPlex

# Or specify configuration file path
./UDPlex -c /path/to/config.yaml

Docker Usage

Using Docker Commands

# Pull the image
docker pull ghcr.io/tao08141/udplex:latest

# Run container (using host network mode)
docker run -d --name udplex --network host \
  -v $(pwd)/config.yaml:/app/config.yaml \
  ghcr.io/tao08141/udplex:latest

# Using port mapping mode (if not using host network mode)
docker run -d --name udplex \
  -v $(pwd)/config.yaml:/app/config.yaml \
  -p 9000:9000/udp \
  ghcr.io/tao08141/udplex:latest

Using Docker Compose

1. Download the docker-compose.yml file:

mkdir udplex && cd udplex
# Download docker-compose.yml file
curl -o docker-compose.yml https://raw.githubusercontent.com/tao08141/UDPlex/refs/heads/master/docker-compose.yml
# Download configuration file
curl -o config.yaml https://raw.githubusercontent.com/tao08141/UDPlex/refs/heads/master/examples/basic.yaml

1. Start the service:

docker-compose up -d

1. View logs:

docker-compose logs -f

1. Stop the service:

docker-compose down

Note: For UDP forwarding applications, it is recommended to use host network mode (network_mode: host) for optimal performance.

WireGuard One-click Deployment Tutorial

• UDPlex + WireGuard: One-click deployment guide (English): docs/udplex_wireguard_en.md

The current udplex-wg-manager.sh workflow uses embedded wireguard-go inside UDPlex instead of system wg-quick. It supports:

• automatic creation of the WireGuard interface inside the UDPlex runtime
• per-line outer transport selection, including UDP+UDP, UDP+TCP, TCP+UDP, and TCP+TCP
• low-bandwidth dual-line redundancy
• high-bandwidth strategy selection: balance across both lines by packet sequence, or keep all high-bandwidth traffic on one preferred line
• WireGuard traffic forwarding through forward or tcp_tunnel_* components instead of relying on a kernel WireGuard port

UDPlex Parameter Details

Global Configuration

Parameter	Description
buffer_size	UDP packet buffer size (bytes), recommended to set to MTU size, usually 1500
queue_size	Inter-component packet queue size, increase for high traffic scenarios
worker_count	Reserved for compatibility; the current router routes packets in the caller goroutine
services	Component configuration array, defines all processing components in the system
protocol_detectors	Protocol detector configuration for identifying and filtering packets of specific protocols

Service Component Parameters

UDPlex supports multiple component types, each with specific functions and configuration parameters. For detailed documentation, please refer to:

• Listen Component - Listen on UDP ports and receive packets
• Forward Component - Forward packets to target servers
• Filter Component - Filter and classify packets based on protocol characteristics
• WireGuard Component - Embed wireguard-go and route WireGuard packets through UDPlex
• TCP Tunnel Listen Component - TCP tunnel listening endpoint
• TCP Tunnel Forward Component - TCP tunnel forwarding endpoint
• Load Balancer Component - Load balancing component
• IP Router Component - Route by source IP/CIDR and GeoIP2

Authentication Configuration

UDPlex supports packet authentication and encryption features. For detailed documentation, please refer to:

• Authentication Protocol - Detailed authentication protocol description

Protocol Detectors

UDPlex supports configuring protocol detectors to identify and classify specific protocols in UDP packets. For detailed documentation, please refer to:

• Protocol Detectors - Protocol detector configuration and usage instructions

RESTful API Interface

UDPlex provides RESTful API interfaces to query component status and connection information.

• RESTful - RESTful interface configuration and usage instructions

Use Cases

• Game Acceleration: Simultaneously forwards game traffic through multiple paths, greatly reducing packet loss.
• Bandwidth Aggregation: Aggregates the bandwidth of multiple network connections to improve overall network speed.
• Protocol-based Classification: Uses protocol detectors to distribute different protocol traffic to different processing paths, such as prioritizing important heartbeat packets.
• UDP over TCP Tunnel: Transmits UDP traffic in network environments that do not support UDP.
• Network Debugging: Forwards UDP traffic to a specified server for debugging and analysis without affecting the original network structure.
• Load Balancing: Intelligently distributes packets based on traffic volume and load balancing strategies. For example, when traffic is low, packets can be forwarded to both servers for redundancy; when traffic exceeds a threshold, they can either be split across both lines or pinned to a single preferred line.

Configuration Examples

The examples directory contains configuration examples for various use cases:

• basic.yaml - Basic UDP forwarding configuration example
• auth_client.yaml - Authenticated UDP client configuration
• auth_server.yaml - Authenticated UDP server configuration
• redundant_client.yaml - UDP redundancy client configuration, sends traffic to multiple servers simultaneously
• redundant_server.yaml - UDP redundancy server configuration, receives client traffic and forwards
• wg_bidirectional_client.yaml - WireGuard UDP upstream/downstream separation client configuration
• wg_bidirectional_server.yaml - WireGuard UDP upstream/downstream separation server configuration
• wg_component_forward_client.yaml - Embedded WireGuard client over UDP forward
• wg_component_forward_server.yaml - Embedded WireGuard server over UDP forward
• wg_component_load_balancer_client.yaml - Embedded WireGuard client with dual-line load balancing
• wg_component_load_balancer_server.yaml - Embedded WireGuard server with dual-line load balancing
• wg_component_tcp_tunnel_client.yaml - Embedded WireGuard client over TCP tunnel
• wg_component_tcp_tunnel_server.yaml - Embedded WireGuard server over TCP tunnel
• tcp_tunnel_server.yaml - TCP tunnel server configuration, listens for TCP connections and forwards UDP traffic
• tcp_tunnel_client.yaml - TCP tunnel client configuration, connects to TCP tunnel service and forwards UDP traffic
• load_balancer_bandwidth_threshold.yaml - Bandwidth threshold-based load balancing configuration, forwards to two servers when traffic ≤ 100M, forwards to one server when > 100M
• load_balancer_equal_distribution.yaml - Equal load distribution configuration, distributes data to two servers in 1:1 ratio
• ip_router.yaml - Route by IP/CIDR and GeoIP