UDP Relay
Surge processes UDP traffic with the same rule system as TCP. When UDP traffic matches a rule that resolves to a proxy policy, the policy must support UDP relay to forward it. This page lists which protocols support UDP relay and the related parameters.
Protocol Support
| Protocol | UDP relay |
|---|---|
| SOCKS5 / SOCKS5-TLS | Yes, requires udp-relay=true |
| Shadowsocks | Yes, requires udp-relay=true |
| Snell | Yes, version 3 and above (automatic) |
| VMess | Yes |
| Trojan | Yes |
| TUIC | Yes |
| Hysteria 2 | Yes |
| MASQUE | Yes |
| AnyTLS | Yes |
| VLESS | Yes (XUDP) iOS 6.0.0+ Mac 6.12.0+ |
| WireGuard | Yes |
| Tailscale | Yes |
| External Proxy Program (Mac) | Yes, requires udp-relay=true |
| HTTP / HTTPS | No |
| HTTP/2 CONNECT | Yes, requires udp-relay=true iOS 5.22.0+ Mac 6.9.0+ |
| Trust Tunnel | No |
| SSH | No |
The built-in DIRECT and REJECT policy families always handle UDP traffic.
Parameters
udp-relay
Optional, boolean, default: false. Applies to SOCKS5, SOCKS5-TLS, Shadowsocks, External Proxy Program, and HTTP/2 CONNECT policies.
Since UDP relay is an optional feature for these servers, it must be enabled explicitly:
[Proxy]
ProxySOCKS5 = socks5, 1.2.3.4, 1080, username, password, udp-relay=true
ProxySS = ss, 1.2.3.4, 8388, encrypt-method=chacha20-ietf-poly1305, password=pwd, udp-relay=true
ProxyH2 = h2-connect, example.com, 443, udp-relay=true
For HTTP/2 CONNECT policies, UDP is relayed with the standard CONNECT-UDP protocol; see the udp-relay parameter in HTTP proxy parameters for the server requirements. iOS 5.22.0+ Mac 6.9.0+
udp-port iOS 5.14.0+ Mac 5.9.0+
Optional, port number, default: the main server port. Applies to Shadowsocks and Snell policies.
Use another server port when performing UDP forwarding. This can be used when the server's TCP and UDP services do not listen on the same port, for example when Shadow TLS occupies the TCP port.
SOCKS5 Inbound UDP iOS 6.0.0+ Mac 6.11.0+
The Surge SOCKS5 proxy service (socks5-listen on Mac, wifi-access-socks5-port on iOS) accepts the UDP ASSOCIATE command, so SOCKS5 clients can send UDP through Surge without Enhanced Mode or a VPN tunnel.
- Each association gets a dedicated relay port, bound to the address the client used for the control connection. Only datagrams from the client's IP address are accepted, and the association ends when the control connection closes.
- The policy is selected once per association by rule-matching the first datagram's destination, in the same way as a UDP flow from a client source port in Enhanced Mode. Later datagrams of the same association follow that policy even when they target other destinations; the Dashboard shows them as additional destinations of the request.
- Domain destinations (ATYP
0x03) are matched by name, so DOMAIN rules apply. IP destinations are matched by address, or by the original domain when the address is a fake IP assigned by Surge. Domains are resolved once per association. - An association uses one address family. With the DIRECT policy, datagrams to the other family than the first destination's are dropped (a note is added to the request).
- Replies to a fake IP destination are rewritten to carry the fake IP as the source, as in Enhanced Mode; replies to a real IP or domain destination carry the real source address.
- Fragmented datagrams (
FRAG != 0) are not supported and are dropped. - QUIC detection and blocking apply only to Enhanced Mode traffic, not to UDP ASSOCIATE associations.
Behavior for Unsupported Policies
When UDP traffic matches a policy that does not support UDP relay, the fallback behavior is controlled by the udp-policy-not-supported-behaviour option in the [General] section. Possible values are DIRECT and REJECT. Starting from Surge Mac 6.0.0, the default is REJECT to avoid leaking traffic unknowingly.
UDP Testing
Latency tests only measure the TCP path. To test a policy's UDP relay, Surge performs a DNS lookup through the relay, configured as hostname@server-ip:
- The global default endpoint is set by
proxy-test-udpin the [General] section, e.g.proxy-test-udp = apple.com@8.8.8.8. - The per-policy
test-udpparameter overrides the global setting, e.g.test-udp=google.com@1.1.1.1.