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-udp in the [General] section, e.g. proxy-test-udp = apple.com@8.8.8.8.
  • The per-policy test-udp parameter overrides the global setting, e.g. test-udp=google.com@1.1.1.1.

results matching ""

    No results matching ""