XUDP Protocol

XUDP extends the mux protocol to support UDP with per-packet addressing, enabling Full-Cone NAT behavior over a single transport connection. It's used by VLESS, VMess, and other protocols to proxy UDP traffic.

Source: common/xudp/xudp.go

Why XUDP?

Standard mux creates one session per destination. For UDP:

• Client sends to Server_A → Session 1
• Client sends to Server_B → Session 2
• Server_A responds → Session 1 ✓
• Server_C responds → No session! ✗

XUDP solves this by:

1. Using a single session for all UDP traffic from one source
2. Including the destination address in each packet (not just the session header)
3. Supporting responses from any address (Full-Cone NAT)

Wire Format

First Packet (New Session)

+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Meta Len  | Session=0 | Status=New | Opt=Data      |
| (2B BE)   | (2B: 0x00)| (1B: 0x01) | (1B: 0x01)  |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Network=UDP | Port    | AddrType | Address         |
| (1B: 0x02)  | (2B BE) | (1B)     | (var)          |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| GlobalID (8 bytes)                                  |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Data Len  | UDP Payload                             |
| (2B BE)   | (var)                                   |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

Subsequent Packets (Keep Session)

+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Meta Len  | Session=0 | Status=Keep | Opt=Data     |
| (2B BE)   | (2B: 0x00)| (1B: 0x02)  | (1B: 0x01) |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Network=UDP | Port    | AddrType | Address         |
| (1B: 0x02)  | (2B BE) | (1B)     | (var)          |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+
| Data Len  | UDP Payload                             |
| (2B BE)   | (var)                                   |
+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+--+

Key differences from standard mux:

• Session ID is always 0 (XUDP uses a single session)
• Keep frames include destination address (per-packet addressing)
• GlobalID is sent only in the first (New) frame

PacketWriter

type PacketWriter struct {
    Writer   buf.Writer       // underlying mux/transport writer
    Dest     net.Destination  // initial destination
    GlobalID [8]byte          // connection identity
}

func (w *PacketWriter) WriteMultiBuffer(mb buf.MultiBuffer) error {
    for _, b := range mb {
        eb := buf.New()
        eb.Write([]byte{0, 0, 0, 0})  // meta len placeholder + session ID=0

        if w.Dest.Network == net.Network_UDP {
            // First packet: New session
            eb.WriteByte(1)  // Status: New
            eb.WriteByte(1)  // Option: Data
            eb.WriteByte(2)  // Network: UDP
            AddrParser.WriteAddressPort(eb, w.Dest.Address, w.Dest.Port)
            if b.UDP != nil {
                eb.Write(w.GlobalID[:])  // 8-byte GlobalID
            }
            w.Dest.Network = net.Network_Unknown  // switch to Keep for next packet
        } else {
            // Subsequent packets: Keep session
            eb.WriteByte(2)  // Status: Keep
            eb.WriteByte(1)  // Option: Data
            if b.UDP != nil {
                eb.WriteByte(2)  // Network: UDP
                AddrParser.WriteAddressPort(eb, b.UDP.Address, b.UDP.Port)
            }
        }

        // Write meta length
        l := eb.Len() - 2
        eb.SetByte(0, byte(l>>8))
        eb.SetByte(1, byte(l))

        // Write data length + data
        eb.WriteByte(byte(length >> 8))
        eb.WriteByte(byte(length))
        eb.Write(b.Bytes())

        mb2Write = append(mb2Write, eb)
    }
    return w.Writer.WriteMultiBuffer(mb2Write)
}

PacketReader

type PacketReader struct {
    Reader io.Reader
    cache  []byte  // 2-byte buffer for length reads
}

func (r *PacketReader) ReadMultiBuffer() (buf.MultiBuffer, error) {
    for {
        // Read meta length (2 bytes)
        io.ReadFull(r.Reader, r.cache)
        l := int32(r.cache[0])<<8 | int32(r.cache[1])

        // Read metadata
        b := buf.New()
        b.ReadFullFrom(r.Reader, l)

        switch b.Byte(2) {  // Status byte
        case 2:  // Keep
            if l > 4 && b.Byte(4) == 2 {  // Has UDP address
                b.Advance(5)
                addr, port, _ := AddrParser.ReadAddressPort(nil, b)
                b.UDP = &net.Destination{
                    Network: net.Network_UDP,
                    Address: addr,
                    Port:    port,
                }
            }
        case 4:  // KeepAlive (discard)
            discard = true
        default:  // End
            return nil, io.EOF
        }

        // Read data length + payload
        b.Clear()
        if b.Byte(3) == 1 {  // Option: Data
            io.ReadFull(r.Reader, r.cache)
            length := int32(r.cache[0])<<8 | int32(r.cache[1])
            b.ReadFullFrom(r.Reader, length)
            if !discard {
                return buf.MultiBuffer{b}, nil
            }
        }
    }
}

GlobalID

The GlobalID identifies a client's UDP "connection" for server-side Full-Cone NAT:

func GetGlobalID(ctx context.Context) (globalID [8]byte) {
    // Only generate for cone mode
    if cone := ctx.Value("cone"); cone == nil || !cone.(bool) {
        return  // zero ID: no cone NAT
    }

    // Only for supported inbounds
    inbound := session.InboundFromContext(ctx)
    if inbound != nil && inbound.Source.Network == net.Network_UDP &&
        (inbound.Name == "dokodemo-door" ||
         inbound.Name == "socks" ||
         inbound.Name == "shadowsocks" ||
         inbound.Name == "tun") {

        // BLAKE3 hash of source address
        h := blake3.New(8, BaseKey)
        h.Write([]byte(inbound.Source.String()))
        copy(globalID[:], h.Sum(nil))
    }
    return
}

How GlobalID Works

1. Client A (source=10.0.0.1:5000) sends UDP → server hashes "10.0.0.1:5000" → GlobalID abc123
2. Server creates cone session keyed by GlobalID abc123
3. Any return UDP packet with GlobalID abc123 is routed back to 10.0.0.1:5000
4. Different client B (source=10.0.0.2:3000) → different GlobalID → separate session

BaseKey

The BLAKE3 key is randomly generated at startup:

BaseKey = make([]byte, 32)
rand.Read(BaseKey)

Or configured via environment variable XRAY_XUDP_BASEKEY (for reproducible behavior, e.g., across restarts).

XUDP in VLESS Outbound

When the VLESS outbound handles UDP with cone NAT:

// Convert UDP to mux+XUDP
if command == UDP && (flow == XRV || cone) {
    request.Command = Mux
    request.Address = "v1.mux.cool"
    request.Port = 666  // magic port: indicates XUDP
}

// Wrap writer with XUDP framing
serverWriter = xudp.NewPacketWriter(serverWriter, target, xudp.GetGlobalID(ctx))

// Wrap reader with XUDP deframing
serverReader = xudp.NewPacketReader(conn)

XUDP Detection on Server

The VLESS inbound detects XUDP by checking the first mux frame:

func isMuxAndNotXUDP(request, first) bool {
    if request.Command != Mux { return false }
    if first.Len() < 7 { return true }  // assume regular mux

    firstBytes := first.Bytes()
    // XUDP: session=0 (bytes 2,3), network=UDP (byte 6)
    return !(firstBytes[2] == 0 &&
             firstBytes[3] == 0 &&
             firstBytes[6] == 2)
}

If XUDP is detected, the server uses the XUDP-aware packet reader instead of the regular mux server worker.

Data Flow Example

Client sends DNS query to 8.8.8.8:53:

PacketWriter writes:
  [00 0C]             # meta length = 12
  [00 00]             # session ID = 0
  [01]                # status = New
  [01]                # option = Data
  [02]                # network = UDP
  [00 35]             # port = 53
  [01]                # addr type = IPv4
  [08 08 08 08]       # address = 8.8.8.8
  [a1 b2 c3 d4 e5 f6 g7 h8]  # GlobalID (8 bytes)
  [00 2A]             # data length = 42
  [... DNS query ...]  # payload

Response arrives from 8.8.8.8:53:

PacketReader reads:
  [00 0C]             # meta length
  [00 00]             # session ID = 0
  [02]                # status = Keep
  [01]                # option = Data
  [02]                # network = UDP
  [00 35]             # port = 53
  [01 08 08 08 08]    # addr = 8.8.8.8
  [00 XX]             # data length
  [... DNS response ...]
  → b.UDP = {Network: UDP, Address: 8.8.8.8, Port: 53}

Implementation Notes

1. Session ID 0 is special: In XUDP, the session ID is always 0. Regular mux starts session IDs from 1.

2. GlobalID is per-source: Each client source address gets a unique GlobalID. The server uses this to maintain per-client cone NAT state.

3. Per-packet addressing: Every Keep frame can have a different destination address. This is what enables Full-Cone NAT — the response can come from any address.

4. Buffer.UDP propagation: The Buffer.UDP field flows through the entire pipeline: XUDP reader sets it, pipe preserves it, XUDP writer reads it. Never strip this field.

5. Cone mode is configurable: The cone context value (from config) controls whether XUDP is used. When disabled, each UDP destination gets a separate mux session (Symmetric NAT behavior).

6. BLAKE3 for hashing: The 8-byte hash provides sufficient uniqueness while being compact. The BaseKey prevents clients from guessing each other's GlobalIDs.