L4 UDP over FAKE_TCP

Status: Current

Last reviewed: 2026-05-30

L4 UDP over FAKE_TCP carries one UDP datagram payload inside a TCP-looking raw packet. It is not TCP tunneling and does not turn UDP into a stream.

Contents

• Supported Profile
• Inbound Listener
• Outbound Upstream
• Processing Logic
• Current Constraints
• Runtime Reporting

Supported Profile

The supported L4 profile is:

payload = udp
outer   = fake_tcp
security= raw

The gateway has two directions:

Direction	Proto fields	Current behavior
Inbound listener	UdpRule.fake_tcp	A TCP-looking raw packet arrives at the agent, is decoded, and the inner UDP payload is sent to the configured UDP upstream.
Outbound upstream	UdpRule.upstream_fake_tcp=true	A normal UDP route payload is wrapped as FAKE_TCP before being sent to the next hop.

Inbound Listener

Inbound listener packet:

Client or previous hop sends:

+-------------------------------+
| Outer IP                      |
|  proto = TCP(6)               |
+-------------------------------+
| TCP header                    |
|  dport = fake_tcp.listen_port |
+-------------------------------+
| FAKE_TCP payload header       |
+-------------------------------+
| UDP datagram payload          |
+-------------------------------+

Agent forwards to UDP upstream:

+-------------------------------+
| UDP socket send               |
|  dst = upstream endpoint      |
+-------------------------------+
| UDP datagram payload          |
+-------------------------------+

The listener path decodes in userspace and installs an RST filter for the selected TCP-looking flow. There is no kernel TCP socket accepting a stream.

Outbound Upstream

Outbound upstream packet:

Client sends ordinary UDP to Nexus listener:

+-------------------------------+
| UDP datagram payload          |
+-------------------------------+

Agent sends next hop as FAKE_TCP:

+-------------------------------+
| Outer IP                      |
|  proto = TCP(6)               |
+-------------------------------+
| TCP header                    |
|  sport = source port          |
|  dport = upstream port        |
+-------------------------------+
| FAKE_TCP payload header       |
+-------------------------------+
| UDP datagram payload          |
+-------------------------------+

Outbound upstream wrapping is a packet construction step. The upstream endpoint port becomes the TCP-looking destination port.

Processing Logic

Inbound FAKE_TCP listener path:

raw TCP-looking packet arrives
  match destination listen address and listen port
  validate magic, session id, length, and checksum
  extract UDP datagram payload
  forward payload with normal UDP socket send
  report listener as tcp + fake_tcp + udp payload

Outbound FAKE_TCP upstream path:

normal UDP route receives datagram
  resolve upstream endpoint address and port
  build outer IP header
  build TCP-looking header
  write FAKE_TCP payload header
  copy UDP datagram payload
  send raw packet to next hop

The payload remains a datagram in both directions. FAKE_TCP does not provide backpressure, retransmission, fragmentation repair, or stream ordering.

Current Constraints

• Inbound FAKE_TCP listener supports RAW UDP only.
• It rejects inbound Noise, upstream Noise, upstream QUIC REALITY, and nested upstream FAKE_TCP for that same listener path.
• Outbound UDP over FAKE_TCP does not support upstream Noise in the current runtime.
• Duplicate UDP FAKE_TCP RAW listeners on the same TCP-looking address:port are reduced to one route because there is no early route discriminator yet.

Runtime Reporting

Runtime listener reports show inbound L4 FAKE_TCP as:

transport = tcp
payload   = udp
outer     = fake_tcp
security  = raw

Normal UDP routes that send to an upstream FAKE_TCP hop report:

outer = udp->fake_tcp