Feature Request: Allow specifying SOCKS5 UDP ASSOCIATE advertised IP

[qq1052497512]

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.

[dyhkwong]

sing-box "advertises" a random UDP port (per RFC 1928) rather than a fixed UDP port (which is vulnerable) like some other software. Even if a fixed IP is "advertised", it won't make the random port behind NAT work.

Edit: I think a fixed UDP port behind NAT also doesn't work? This is only a coincidence for some NAT servers with a very special mapping behavior.

[qq1052497512]

sing-box "advertises" a random UDP port (per RFC 1928) rather than a fixed UDP port (which is vulnerable) like some other software. Even if a fixed IP is "advertised", it won't make the random port behind NAT work.

Edit: I think a fixed UDP port behind NAT also doesn't work? This is only a coincidence for some NAT servers with a very special mapping behavior.

Thanks for the explanation — I agree with you regarding random UDP ports and the security concerns around fixed ports. I’m not requesting a fixed UDP port, and I fully understand that the port should remain random per RFC 1928.

To clarify, my request is only about the advertised IP address, not the port.

In cloud SNAT environments such as Alibaba Cloud ECS:

• The server listens on a private NIC IP (e.g. 172.x.x.x)
• Outbound UDP traffic is SNATed to a public EIP
• The SNAT mapping is stable for the UDP flow once established
• The client can reach the server only via the public IP, never the private IP

Currently, sing-box advertises the private NIC IP in the UDP ASSOCIATE reply, which makes the UDP relay address unreachable for the client. In this case, UDP fails before NAT mapping or port behavior even matters, because the client cannot send packets to the advertised IP at all.

Allowing an override of the advertised IP only, while keeping:

• random UDP port
• existing NAT behavior
• current security properties

would solve this reachability issue without violating RFC semantics.

Xray-core exposes a similar option, not to force NAT behavior or fixed ports, but simply to advertise a client-reachable IP in NATed environments.

@dyhkwong

[dyhkwong]

It can work only bacause a coincidence that some special NAT mapping behaviors do not convert the port number. A more typical case is public_ip:port mapping to private_ip:another_port. Why add a special exception for this coincidence?

[nekohasekai]

Do you mean we should add a stun test to determine its public IP?

[dyhkwong]

Even if the public IP can be detected or configurable, the public port is not predictable on most cases. Maybe a server can just responds with 0.0.0.0 for requests from non-loopback addresses as if the server is listening on 0.0.0.0 and not aware of its public IP?

[qq1052497512]

I think there is a misunderstanding here, so let me clarify once more and I’ll stop here.

My request is not about port predictability, fixed ports, or relying on special NAT behavior.

I fully agree that:

• The UDP port should be random
• NAT may rewrite the port
• The public port is generally unpredictable

None of that is a problem for my use case.

The problem happens before any NAT or port mapping behavior matters.

In cloud SNAT environments (e.g. Alibaba Cloud ECS):

• sing-box advertises a private NIC IP (172.x.x.x) in the UDP ASSOCIATE reply
• This IP is not reachable by the client at all
• As a result, the client cannot send even the first UDP packet

So the failure is purely about IP reachability, not about port mapping.

If the advertised IP were the public EIP:

• The port can remain random
• NAT may freely rewrite the port
• No predictability is required
• No STUN or detection is required

I’m only asking for an option to override the advertised IP so that the client has a reachable address to send UDP packets to.

If this is against sing-box’s design goals, that’s totally fine — I just wanted to clarify that this is not about relying on NAT coincidences or fixed ports.

[dyhkwong]

NAT may freely rewrite the port

Example: If this feature is implemented and private_ip:1080 is mapped to public_ip:60000, server will respond with public_ip:1080 (as BND.ADDR:BND.PORT) and client must send the data to public_ip:1080. This does not make sense.

I think V2Ray's or Xray's "UDP response IP" is not for "Basic NAT", but for a NAT-free server listening on 0.0.0.0 or ::, which is unaware of its actual listening address, to prevent responding with unreachable 0.0.0.0 or ::. Maybe the protocol itself was too old to consider NAT.