L3 Tunnels

Status: Current

Last reviewed: 2026-05-30

Route: /gateway/l3-networks

L3 tunnels are point-to-point networks between two agents. Current protocol families are QUIC L3 and userspace WireGuard. QUIC L3 currently uses REALITY security and CONNECT-IP payload framing. The backend accepts only these current L3 families.

Current L3 support:

Protocol	Transport	Notes
QUIC	QUIC DATAGRAM by default	Current security profile: REALITY. Payload framing: RFC 9484-style CONNECT-IP with HTTP Datagram quarter stream ID.
WireGuard	userspace UDP	BoringTun runtime, no kernel module dependency.

Tunnel Table

Column	Meaning
Status	Enabled or disabled.
Name	Tunnel name.
Tunnel	Address family and IPv4 prefix length.
MTU	Tunnel MTU.
Protocol	Tunnel protocol and transport mode.
Actions	Deploy, edit, or delete.

Prerequisites

• Two different registered nodes.
• A REALITY profile in Security Credentials. The profile references an X25519 key.
• Agents connected to the control plane before deployment.

Create a Tunnel

Required role: admin or operator

1. Open L3 Tunnels.
2. Click Create L3 Tunnel.
3. Enter name.
4. Enable or disable the tunnel.
5. Select Endpoint A and Endpoint B nodes. They must be different.
6. Set interface names. Defaults are nn-l3-left and nn-l3-right.
7. Optional: set endpoint IPv4 host addresses.
8. Optional: set endpoint IPv6 host addresses. For dual_stack and ipv6 tunnels, the agent derives link-local addressing when IPv6 host addresses are omitted.
9. Set allowed source CIDRs for each endpoint.
10. Select connection mode and listener address.
11. Set listener port.
12. Select address family, MTU, and REALITY profile.
13. Select capabilities.
14. Save.

Endpoint Roles

The tunnel always has two endpoint roles:

Endpoint	Role	Notes
Endpoint A	listener	Can use manual connection info.
Endpoint B	connector	Connects to the listener side.

The backend stores normalized roles as listener and connector.

Addressing Rules

Field	Rule
Address family	dual_stack, ipv4, or ipv6.
IPv4 prefix length	1 through 32; default 30.
IPv6 prefix length	1 through 128; default 64.
MTU	576 through 9000; default 1280. Use 4096 only on paths where larger UDP packets are known to work.
Endpoint IPv4	Optional host address; /32 is accepted but network prefix is configured separately.
Endpoint IPv6	Optional host address; /128 is accepted but network prefix is configured separately.
IPv6 link-local	dual_stack and ipv6 tunnels derive IPv6 link-local endpoint addresses when explicit IPv6 hosts are omitted.

For ipv4 tunnels, each endpoint needs at least one explicit tunnel IPv4 or IPv6 address.

MTU Overhead

The tables below calculate the tunnel MTU loss for the protocols currently accepted by the backend and agent. Use the MTU of the narrowest underlay IP path as PMTU.

Scope and assumptions:

• Values are IP-layer sizes. Ethernet headers, FCS, preamble, VLAN tags, PPPoE, and other L2 overheads are not included. Subtract those from the usable underlay PMTU before using these tables.
• IPv4 underlay and IPv6 underlay refer to the outer packet between the two nodes. The inner tunneled address family can be IPv4, IPv6, or dual-stack.
• IPv4 headers are assumed to be 20 bytes, IPv6 headers 40 bytes, and UDP headers 8 bytes.
• QUIC transport has variable wire overhead. L3 over QUIC uses QUIC DATAGRAM only.
• WireGuard data packets can pad encrypted payloads to a 16-byte boundary. For MTU sizing, use the standard 60-byte IPv4 and 80-byte IPv6 WireGuard loss.

Formula:

tunnel_mtu <= PMTU - overhead

QUIC L3

QUIC L3 is not a fixed-header tunnel on the wire. QUIC packet number length, connection ID length, DATAGRAM frame encoding, ACK coalescing, and TLS AEAD expansion can vary.

L3 over QUIC uses QUIC DATAGRAM only. Each L3 datagram is:

QUIC DATAGRAM payload = 8-byte NexusNet session id + 1-byte HTTP/3 Quarter Stream ID + 1-byte CONNECT-IP Context ID + inner IP packet

That is 10 bytes before QUIC's own DATAGRAM frame and packet protection overhead. The agent configures Quinn with an additional 96-byte reserve:

Current agent budget:

outer_udp_payload_budget = tunnel_mtu + 1 + 1 + 8 + 96
                         = tunnel_mtu + 106

When the underlay PMTU is 1500:

Underlay	Maximum UDP payload without fragmentation	Safe tunnel MTU with current budget
IPv4	1500 - 20 - 8 = 1472	1472 - 106 = 1366
IPv6	1500 - 40 - 8 = 1452	1452 - 106 = 1346

Important operational notes:

• The agent default NEXUS_QUIC_OUTER_UDP_PAYLOAD_SIZE is 1472, which is IPv4-sized. On a strict IPv6 underlay with PMTU 1500, set it to 1452 or lower if no fragmentation is allowed.
• The default tunnel MTU 1280 remains within the CONNECT-IP QUIC DATAGRAM budget for both IPv4 and IPv6 underlay, and is the recommended starting point for Internet paths.

Quick 1500-byte PMTU Recommendations

Protocol mode	IPv4 underlay MTU setting	IPv6 underlay MTU setting	Conservative dual-stack setting
QUIC L3	1366 for one-packet DATAGRAM budget	1346 for one-packet DATAGRAM budget	1280
Userspace WireGuard	1440	1420	1280

For unknown Internet paths, start from the conservative dual-stack value or the default 1280, then raise MTU only after PMTU testing between the two underlay addresses.

Allowed Source CIDRs

Allowed source CIDRs can be comma-separated or newline-separated. The default input is:

0.0.0.0/0, ::/0

The backend validates CIDR syntax and supports route directions:

• allowed_source
• advertise
• install

The current UI writes allowed_source routes.

REALITY Port Reuse

L3 listener endpoints can share the same QUIC REALITY listener port when their routes are distinguishable by SNI and short ID.

The backend enforces this rule for L3 tunnels and L4 chains:

• Same listener node + protocol + port + SNI must use the same X25519 key.
• Same listener node + protocol + port + SNI + short ID cannot be duplicated.
• Multiple tunnels can reuse one port and SNI by selecting REALITY profiles that reference the same X25519 key and use different short IDs.

This matches the agent route selection behavior: a single listener can host multiple routes, but same-SNI routes must share the X25519 identity and use short IDs for per-tunnel selection.

Capabilities

Capability	Meaning
Install routes	Agent should install tunnel routes.
Multicast	Allow multicast traffic.
Broadcast	Allow broadcast traffic.
Offload	Enable supported dataplane offload behavior. Disabled by default because current L3 QUIC DATAGRAM tests are faster without TUN offload.
Multi-queue	Enable multi-queue behavior when supported.
QUIC GSO	Enable Quinn UDP segmentation offload for QUIC packets. Enabled by default.
Keepalive	Enable point-to-point keepalive.

Deploy a Tunnel

Required role: admin or operator

Click deploy. The backend refreshes all enabled L3 tunnel configs and pushes per-node config to connected agents. A success toast lists nodes that received the config.

Edit or Delete

Editing reloads full tunnel details, including endpoints and routes, before opening the form. Deleting removes the L3 network definition.