FAKE_TCP Dataplane Modes

Status: Current

Last reviewed: 2026-05-30

FAKE_TCP has multiple runtime modes because different deployments have different kernel, permission, and underlay constraints. The mode controls where packet rewrite happens; it does not change the common wire format.

Contents

• Support Matrix
• Pure eBPF Dataplane
• Hybrid eBPF Dataplane
• Auto and Raw Mode Semantics
• RST Filtering
• Operational Requirements

Support Matrix

Mode	Config value	Runtime meaning
Auto	auto or empty	Try pure eBPF first. If it fails during startup, fall back to hybrid eBPF where that fallback is implemented.
Pure eBPF	ebpf_tc or pure_ebpf	Attach tc ingress and egress programs that rewrite packets in kernel space.
Hybrid eBPF	hybrid_ebpf or raw	Use tc eBPF for capture or egress assistance and raw sockets for userspace encode/decode.

For inbound L4 UDP FAKE_TCP listeners, the current runtime decodes in userspace and installs an RST filter. The pure/hybrid distinction mainly applies to the L4 UDP upstream client fast path.

Pure eBPF Dataplane

Pure eBPF mode attaches one tc egress and one tc ingress filter per tunnel on the resolved underlay interface.

Egress flow:

tc egress
  match native UDP packet
  verify source, destination, protocol, and ports
  grow skb by TCP header + FAKE_TCP header
  rewrite IP protocol from UDP to TCP
  write TCP header
  write FAKE_TCP header
  recompute IPv4/TCP or IPv6/TCP checksums
  return TC_ACT_OK

Ingress flow:

tc ingress
  match TCP packet to local listen address and listen port
  verify remote source IP, FAKE_TCP magic, and session id
  shrink skb by TCP header + FAKE_TCP header
  restore IP protocol to UDP
  restore destination to local native endpoint
  recompute checksums where required
  return TC_ACT_OK

Non-matching packets return TC_ACT_UNSPEC so later tc filters can still run. This is important because the current implementation installs per-tunnel tc filters rather than a single map-driven dispatcher per interface.

Hybrid eBPF Dataplane

Hybrid mode keeps raw sockets in the data path.

L4 UDP hybrid:

egress native UDP
  tc egress redirects matching UDP traffic toward loopback
  userspace raw receiver reads the UDP payload
  userspace encodes outer IP + TCP + FAKE_TCP
  userspace raw IP sender transmits to remote endpoint

ingress FAKE_TCP
  userspace raw TCP receiver reads TCP-looking packets
  userspace validates and decapsulates
  userspace forwards UDP payload to the configured upstream

Auto and Raw Mode Semantics

Auto mode uses hybrid as a startup fallback when pure eBPF installation fails. Explicit pure_ebpf fails the tunnel if pure eBPF cannot be installed.

The raw value is accepted as the hybrid path. It should not be documented as a zero-eBPF implementation because current startup still uses tc assistance for capture, redirect, filtering, or fast-path work depending on the traffic direction.

RST Filtering

Because FAKE_TCP packets look like TCP but are not owned by a TCP socket, the host kernel can emit TCP RST for packets that arrive on the selected tuple. NexusNet installs RST filters for supported FAKE_TCP listener paths so the underlay compatibility wrapper does not fight the local TCP stack.

RST filtering does not make FAKE_TCP a TCP connection. It only prevents the kernel from terminating a flow it does not understand.

Operational Requirements

• Raw socket capability for userspace encode/decode paths.
• tc/eBPF capability for pure eBPF, hybrid eBPF, and RST filtering.
• A resolved underlay interface for tc attachment.