Feature Request: Allow specifying SOCKS5 UDP ASSOCIATE advertised IP

Summary

Request an option to explicitly configure the IP address returned in the SOCKS5 UDP ASSOCIATE response.

This is required for cloud environments where the server listens on a private NIC IP but exposes traffic through a public EIP/SNAT address.

---

Background

According to the SOCKS5 protocol, when a client issues a UDP ASSOCIATE command, the server replies with an IP:PORT indicating where the client should send UDP packets.

In many cloud environments (Alibaba Cloud ECS, AWS EC2, GCP, etc.):

• The server listens on a private NIC IP (e.g. 172.x.x.x)
• Outbound traffic is SNATed to a public EIP
• The private NIC IP is not reachable from the client

When sing-box returns the private NIC IP in the UDP ASSOCIATE reply, the client sends UDP packets to an unreachable address, causing SOCKS5 UDP to fail completely.

---

Current Behavior

• sing-box automatically selects the IP address used in the SOCKS5 UDP ASSOCIATE reply
• Users cannot override this value
• In SNAT / cloud NAT environments, SOCKS5 UDP is unusable

---

Expected Behavior

Provide a configuration option that allows users to explicitly specify the IP address advertised in the SOCKS5 UDP ASSOCIATE response.

Conceptual example:

{
  "type": "socks",
  "listen": "::",
  "listen_port": 1080,
  "udp_advertise_ip": "PUBLIC_EIP"
}

Scope of this option

• Only affects the IP returned to the client in the UDP ASSOCIATE reply

• Does not change:

  • Actual UDP source IP
  • Routing logic
  • NAT / SNAT behavior

This is purely a protocol-level advertisement setting.

---

Comparison

xray-core provides similar functionality via:

"settings": {
  "udp": true,
  "ip": "PUBLIC_EIP"
}

This setting has proven necessary and effective in cloud NAT environments.

---

Use Cases

• Cloud servers with SNAT (Alibaba Cloud ECS, AWS EC2, GCP)
• Docker / containerized deployments
• Servers with private NIC + public EIP
• Multi-IP hosts

Without this capability, SOCKS5 UDP cannot function correctly in these environments.

---

Notes

• This request aligns with SOCKS5 protocol semantics
• It improves usability without impacting existing behavior
• Default behavior can remain unchanged if the option is not set

Thank you for considering this feature request.

Start by locating the SOCKS5 UDP ASSOCIATE handling and the SOCKS inbound configuration entry point. Verify that a configured advertised IP changes only the IP in the UDP ASSOCIATE response, while existing UDP routing, source addressing, and default behavior remain unchanged.