SIP003u - UDP Extension for SIP003 Plugins

[database64128]

As a new generation of proxy protocols emerges, good robust UDP support has become a holy grail when designing a new proxy protocol. XTLS/Xray-core makes aggressive architectural changes and adds patches over v2ray to make the proxy act like a full-cone NAT when handling UDP traffic. Qv2ray/gun is an experimental proxy implementation that utilizes gRPC to proxy TCP and UDP traffic.

However, the original proposal of SIP003 didn't include support for UDP. The lack of UDP support has significantly limited the possible use cases of SIP003.

I'm starting this discussion in the community to draft an UDP extension for SIP003 plugins. Feel free to post your ideas and suggestions down there.

TODO

Edit to add draft proposal details.

[database64128]

Related issues/discussions

• SIP003 - A simplified plugin design for shadowsocks #28
• support udp? Qv2ray/gun#17

Mentions

Shadowsocks

• @zonyitoo
• @madeye
• @Mygod

Qv2ray

• @DuckSoft
• @U-v-U
• @studentmain

V2Fly

• @kslr

XTLS

• @RPRX

[database64128]

Preliminary proposal by @studentmain:

• For Shadowsocks clients that can check local ports, before starting the plugin, check to make sure both TCP and UDP are available for the specified port. When the plugin is started, check if the plugin is listening for UDP on SS_LOCAL_PORT.
  • If the plugin is listening for UDP, the Shadowsocks client must proxy UDP traffic to the port.
  • Otherwise, treat it as a vanilla SIP003 plugin.
• For Shadowsocks clients that cannot check local ports, the plugin must resort to other means to communicate its UDP support status to the Shadowsocks client.
• An SIP003u-compliant plugin must use SS_LOCAL_ADDR and SS_LOCAL_PORT as the listening address and port for UDP. Client-side plugins must have UDP support.
• No modifications are needed at Shadowsocks servers.

[zonyitoo]

When the plugin is started, check if the plugin is listening for UDP on SS_LOCAL_PORT.

Why not just add a flag in configuration? For example, "plugin_mode": "tcp_and_udp".

[database64128]

The new plugin_mode option in shadowsocks-rust does not communicate to plugins about UDP support. Plugins would have to define their own option, which could cause fragmentation.

Maybe we should reserve a special key in SS_PLUGIN_OPTIONS for this purpose, and require that the shadowsocks client/server prepends the key-value pair to SS_PLUGIN_OPTIONS when plugin_mode is tcp_and_udp. A few things to keep in mind:

1. We must be very careful when choosing the special key. Collision with existing plugins could cause issues. SIP003u=true might be a good candidate.
2. How do existing plugins handle unknown keys in SS_PLUGIN_OPTIONS? Do they simply ignore them or abort? Maybe this should be clarified in an update to the SIP003 spec.
3. SS_PLUGIN_OPTIONS is not mandatory and some plugins might not check it at all.
4. We could also just drop plugin_mode and have the shadowsocks client and server check whether SS_PLUGIN_OPTIONS contains the special key. But that could confuse users of implementations or versions without SIP003u support.

So many caveats! We might as well start over and define new environment variables.

• SS_CLIENT_PLUGIN_LISTEN_UDP: Plugin's listen address in host:port form. IPV6_V6ONLY MUST be turned off on supported platforms.
• SS_SERVER_PLUGIN_CONNECT_UDP: The plugin forwards decrypted packets to this address.
• SS_PLUGIN_UDP_NAT_TIMEOUT_SEC: UDP NAT timeout in seconds. Required when UDP is enabled.

The life cycle section in the spec also needs some clarification. What signal to send to the plugin process? How long to wait before sending SIGKILL? What about Windows?

• Send SIGTERM on Unix platforms.
• Wait up to 5 seconds.
• Windows support is optional. (AttachConsole(plugin_pid) + SetConsoleCtrlHandler(null, true) + GenerateConsoleCtrlEvent(CTRL_C_EVENT, 0) + SetConsoleCtrlHandler(null, false) + FreeConsole())

[zonyitoo]

If a plugin supports SIP003u, it will only need to provide a UDP tunnel, the process steps would be:

For the local plugin:

1. recv() a UDP packet from sslocal, with peer_addr (A)
2. Check if there is an existed UDP tunnel for (A), if no, create one.
3. Send all packets received with peer_addr = (A) into this tunnel.

For the server plugin:

1. Accept a new connection (maybe a TCP connection)
2. Create a new UDP socket that connect() to ssserver's UDP port
3. Read UDP packets from the connection and then sendto the UDP socket

So the implementation would be quite simple, and I don't think it actually need a NAT. Well, there should be a full-cone NAT in it.

[zonyitoo]

https://github.com/zonyitoo/shadowsocks-yamux-plugin
This is a plugin that supports SIP003u. It use YAMUX protocol as TCP stream multiplexer.

[zonyitoo]

I don't think plugins should know "plugin_mode", because it only affects the behavior of sslocal and sserver about which address to connect or listen. If a plugin supports SIP003u, it can just listen to both TCP and UDP.

[database64128]

Fair enough. I guess you could open a PR to update the spec doc and then close this issue?

[zonyitoo]

It is still an experimental feature. Let's keep it open and see if there are any other comments.

[zonyitoo]

I used this feature with shadowsocks-yamux-plugin for more than a week, everything works perfect as expected.

UDP (H3) felt more stable with UoT (supported by the shadowsocks-yamux-plugin) than direct UDP mode.