L4 Upstreams

Status: Current

Last reviewed: 2026-05-15

Route: /gateway/l4-upstreams

L4 upstreams are reusable target endpoints for L4 chains. They also carry inbound SNI match names used by Port Management to derive split routes for TCP TLS listeners.

Upstream Table

Column	Meaning
Status	Whether the upstream is enabled.
Name	Operator-facing upstream name.
Endpoint	Target host/IP and port. IPv6 endpoints are stored as [addr]:port.
SNI	Optional inbound TLS/SNI names used for L4 port split routing.
Actions	Edit or delete.

Data Rules

• Create requires name and endpoint.
• The current UI treats name as create-only. Editing an upstream updates the endpoint, SNI names, interval, and enabled state, but not the name.
• server_names are trimmed, lowercased, deduplicated, and blank lines are dropped.
• health_check_interval_ms defaults to 0; that means off.
• health_check_path is no longer accepted by the API.

Create an Upstream

Required role: admin or operator

1. Open L4 Upstreams.
2. Click Add.
3. Enter name.
4. Enter IP address or host.
5. Enter port.
6. Optional: enter one or more SNI names, one per line.
7. Optional: enter TCP ping interval in milliseconds. 0 means off.
8. Click Create.

The frontend stores the endpoint as host:port; IPv6 addresses are normalized to [ipv6]:port. Saved SNI names are lowercased and deduplicated.

Edit an Upstream

Required role: admin or operator

Click edit, change endpoint, SNI names, interval, or enabled state, and save. L4 chains reference selected upstreams by upstream id, so endpoint changes do not break new chain references. Older endpoint-only chains still use endpoint fallback and should be reviewed after endpoint changes.

Delete an Upstream

Required role: admin or operator

Delete only after checking L4 chains that use the endpoint.

Usage In L4 Chains

When creating a target stage in L4 Chains, select an upstream from the target endpoint dropdown. The saved chain uses the upstream id and keeps the endpoint value only as a legacy fallback.

SNI Routing

server_names are inbound ClientHello match names. They are used by L4 Port Management to show and compute TCP TLS split routes for selected target upstreams. They do not override outbound dial SNI.