FAKE_TCP

Status: Current

Last reviewed: 2026-05-30

FAKE_TCP is NexusNet's TCP-looking packet wrapper for traffic that is not actually TCP. It is used by the L4 UDP path when an underlay firewall, NAT, or cloud security policy is easier to pass with protocol 6 than with arbitrary UDP.

FAKE_TCP is a packet transform, not a TCP transport. It has no kernel TCP listener, SYN/SYN-ACK/ACK handshake, stream state, retransmission, ordering, or congestion control.

Contents

• Current Support
• Core Model
• Section Map
• Current Limits
• Development Direction

Current Support

Area	Payload	FAKE_TCP role	Current status
L3 WireGuard	WireGuard UDP	Removed for L3 tunnels	Rejected by backend and agent
L4 UDP listener	UDP datagram payload	Accept FAKE_TCP and forward payload to UDP upstream	Supported, RAW UDP only
L4 UDP upstream	UDP datagram payload	Send next-hop UDP payload over FAKE_TCP	Supported, RAW upstream only

For L4 chains, the supported profile is:

payload = udp
outer   = fake_tcp
security= raw

Core Model

FAKE_TCP creates an ordinary IP packet whose next protocol is TCP. The TCP header has no options and carries a NexusNet payload header followed by the real protocol payload.

On wire:

outer IP header
outer TCP header, flags ACK+PSH
NexusNet FAKE_TCP payload header
inner payload bytes

The TCP source and destination ports are classification fields. They do not come from the Linux TCP stack. The agent writes them directly in raw IP or tc eBPF programs.

Important consequences:

• A FAKE_TCP listener is not visible as an accepted TCP stream.
• The kernel may send TCP RST for unexpected packets unless NexusNet installs RST filters for the selected flow.
• Middleboxes that only check protocol and port can pass the traffic.
• Middleboxes that require a real TCP state machine may still drop the traffic.
• NAT44 source-port rewriting is accepted after destination port, magic, session id, and payload checksum checks pass.

Section Map

• Address and Port Semantics: underlay address selection, NAT44 behavior, endpoint listen ports, source ports, and auto allocation.
• Packet Format: common FAKE_TCP payload header, outer IPv4 and IPv6 packet layouts, checksum fields, and RFC-style diagrams.
• L4 UDP: inbound UDP listeners, outbound UDP upstream wrapping, gateway restrictions, and runtime reporting.
• Dataplane Modes: auto, pure eBPF, hybrid eBPF, raw socket fallback, RST filtering, and future dispatcher work.

Current Limits

• Runtime requires raw socket and tc/eBPF capabilities.
• There is no TCP connection state, retransmission, ordering, congestion control, or MSS negotiation.
• TCP options are not emitted.
• NAT44 source-port rewriting is tolerated.
• The diagnostics page is a control-plane assessment, not an active NAT probe. Current active probe state is reported as not_supported.
• Current tc eBPF programs are per-tunnel and static. A future dispatcher can move tunnel records into BPF maps to avoid repeated attach/detach on ordinary config refresh.

Development Direction

The current design intentionally separates stable behavior from future flow-learning work. Larger improvements should keep these boundaries:

1. Move per-route tc filters toward one ingress and one egress dispatcher per underlay interface.
2. Put route-specific match and rewrite state in BPF maps.
3. Add authenticated tuple learning before relaxing source-IP matching.
4. Report observed peer tuples and probe results separately from static reachability checks.
5. Keep tcp_port only as a compatibility default; prefer explicit listen, source, and peer listen fields in runtime snapshots.