FAKE_TCP Address and Port Semantics

Status: Current

Last reviewed: 2026-05-30

FAKE_TCP address and port fields describe packet classification and raw packet construction. They are not kernel TCP socket ownership.

Contents

• Terms
• Address Resolution
• NAT44 Source Semantics
• L4 Port Semantics

Terms

Term	Meaning
Tunnel overlay address	The IP address assigned inside the tunnel interface. It must not be used as FAKE_TCP underlay.
Local underlay address	The local interface address used as the default FAKE_TCP source address.
Reachable underlay address	The address other nodes should target. This can be a public interface address, public NAT address, EIP, or manually configured address.
source_address	Per-endpoint FAKE_TCP source IP written into outgoing packets. Defaults to the resolved local underlay address.
listen_address	Per-endpoint FAKE_TCP destination IP expected on inbound packets. It is used for classification, not for TCP listen(2).
remote_endpoint	Peer target address before DNS resolution and port completion. This is where outbound FAKE_TCP packets are sent.
expected_remote_source	Source IP expected on inbound packets from the peer. This may be the peer public NAT address instead of the peer private interface address.
tcp_port	Compatibility default port in the transport profile.
listen_port	Effective inbound FAKE_TCP destination port for this endpoint.
source_port	Effective outbound FAKE_TCP source port for this endpoint.
peer_listen_port	Peer endpoint's effective FAKE_TCP listen port.
bind_device	Optional underlay interface hint for tc eBPF attachment. Alias suffixes such as eth0:1 are normalized to eth0.
session_id	32-bit FNV-derived session discriminator from the network or service key. It is not cryptographic authentication.

Address Resolution

The backend builds a per-endpoint FAKE_TCP tuple before pushing L3TunnelConfig to the agent.

local_bind             = local source/bind underlay address
remote_target          = peer reachable target address
expected_remote_source = peer source address expected after NAT

Selection order:

1. Prefer a manually selected local underlay address when underlay_mode is manual.
2. Otherwise prefer detected interface addresses on the selected interface.
3. Then use other detected interface addresses marked underlay-capable.
4. Then use node manual addresses and reported public addresses.
5. Match local and peer addresses by IP family, preferring IPv4 when both IPv4 and IPv6 candidates exist.
6. Reject the configuration if the chosen local and peer addresses use different IP families.
7. Reject a FAKE_TCP listen_address or source_address that equals the tunnel overlay address.

The local source IP is the address the agent can legally write on the underlay. The reachable peer address is the address the peer expects other nodes to target. In NAT and cloud edge deployments, those are often different concepts.

NAT44 Source Semantics

For NAT44, the local VM may send from a private interface address while the peer observes a public NAT address:

Before NAT:
  src = 10.0.1.10:53158
  dst = 198.51.100.20:443

After NAT:
  src = 203.0.113.10:31844
  dst = 198.51.100.20:443

The local source IP is still the interface address that the agent can legally write. The public address belongs to the NAT, load balancer, or cloud edge.

Receive validation accepts NAT44 source-port rewriting after these fields pass:

• source IP matches expected_remote_source;
• destination port matches the local listen_port;
• magic is NNFTCP01;
• session id matches the tunnel or route;
• payload length and checksum are valid.

Source-IP rewriting is not learned automatically in the current dataplane. If a peer is behind NAT, its observed public source address must be represented as expected_remote_source by backend address selection.

L4 Port Semantics

L4 UDP over FAKE_TCP uses TCP-looking source and destination ports for packet classification, but the payload remains one UDP datagram.

Inbound listener:

• UdpRule.fake_tcp.listen_port is the TCP-looking destination port.
• The agent installs an RST filter for the selected flow.
• No TCP socket accepts a stream on that port.
• Duplicate UDP FAKE_TCP RAW listeners on the same address and port collapse to one route because there is no early route discriminator yet.

Outbound upstream:

• UdpRule.upstream_fake_tcp=true means the next-hop UDP datagram payload is wrapped as FAKE_TCP.
• The upstream endpoint port becomes the TCP-looking destination port.
• Source port selection is an outbound packet construction detail, not a kernel TCP bind.