L4 Chains

Status: Current

Last reviewed: 2026-05-30

Route: /gateway/l4-chains

L4 chains define deployable forwarding pipelines. A chain contains one or more transit stages followed by exactly one target stage.

Chain Table

Column	Meaning
Status	Enabled or disabled.
Name	Chain name.
Protocol	Entry protocol: TCP, UDP, or TCP+UDP.
Topology	Stage summary, such as transit count followed by target count.
Actions	Deploy, edit, or delete.

Transport Presets

Current UI presets:

Preset	Status	Credential
TCP RAW	Supported	None
TCP TLS	Supported	TLS Cert credential
TCP REALITY	Supported	REALITY credential
UDP RAW	Supported	None
UDP Noise	Supported	UDP Noise credential
TCP over QUIC REALITY	Supported	REALITY credential
UDP over QUIC REALITY	Supported	REALITY credential
UDP over FAKE_TCP	Supported	None
TCP over UDP Noise	Planned	X25519 credential

Planned transports appear in the selector as planning placeholders. The backend marks them planned through TransportSupport and does not deploy them as supported agent rules.

UDP over FAKE_TCP is a packet wrapper, not TCP tunneling. The agent carries UDP datagram payloads inside TCP-looking raw IP packets. See L4 UDP over FAKE_TCP for the L4 inbound listener and upstream forwarding logic.

Create a Chain

Required role: admin or operator

1. Open L4 Chains.
2. Click Create Chain.
3. Enter chain name.
4. Select entry protocol: TCP, UDP, or TCP+UDP.
5. Add zero or more transit stages.
6. Add one target stage.
7. For each transit node, select an online node.
8. For each target node, select an upstream from the target dropdown.
9. Select transport and credential where required.
10. Save.

Stage Rules

• A target stage is required.
• Transit stages must come before the target stage.
• A transit stage requires a registered node.
• A target stage requires an upstream selection or a legacy endpoint value.
• Multiple nodes in a stage act as parallel/load-balanced options.
• The first transit stage and the target stage are locked to raw transport for the currently selected payload.

Target stages save the selected upstream id and keep the endpoint string as a legacy fallback. Backend deploy/replay resolves the upstream id first, then falls back to matching the saved endpoint string for older data.

For TCP SSLPREREAD chains that go directly to the target stage, the selected upstream must have server_names. Port Management derives the inbound SNI split routes from those names. Plain TCP TLS chains use their TLS certificate domain as the listener SNI; upstream server_names are not outbound dial SNI overrides.

Same-Port Behavior

L4 chains can intentionally target the same listener port when the agent can separate traffic early:

• TCP REALITY and TCP TLS/SSLPREREAD are both handled by the TCP SNI-family listener. REALITY uses SNI first, then tries SNI-matching REALITY routes by short ID, so multiple REALITY routes with the same SNI are valid when their short IDs differ.
• One TCP RAW chain can be kept as fallback under that TCP SNI-family listener. This is the expected way to run an SSH RAW fallback on a port that also hosts TLS or REALITY control traffic.
• UDP Noise routes can share one UDP listener by local X25519 key, and one UDP RAW chain can be retained as fallback.
• QUIC REALITY can be embedded into the same UDP socket as UDP Noise or UDP RAW when the packets can be dispatched by QUIC Initial detection and REALITY route material.

Use Port Management runtime preview after deploy to compare the intended chains with the listener table the agent actually applied.

Connection Info

For transit stages after the first stage, the chain editor can store connection info for the previous hop:

Mode	Behavior
Auto	Backend/agent uses detected node connectivity data.
Manual	Operator provides address or comma-separated addresses.

Credentials

Credential selectors are filtered by transport:

• TLS transports require tls_cert.
• REALITY transports require reality.
• UDP Noise transports require udp_noise or legacy x25519.
• RAW transports require no credential.

Deploy a Chain

Required role: admin or operator

Click the rocket/deploy action. The backend sends config updates to connected agents. A success toast lists nodes that received config. If no transit agents are connected, the UI warns that nothing was deployed.

Edit or Delete

Editing requires the current chain version and updates the saved chain. Deleting removes the control-plane definition; review live traffic impact before deleting.