L2TPv2 LNS subsystem

Ze includes a native L2TPv2 (RFC 2661) LNS/LAC implementation used as a BNG (Broadband Network Gateway) component: it terminates L2TP tunnels over UDP, runs PPP negotiation (LCP, authentication, IPCP/IPv6CP), assigns peer IPs, and hands the kernel data plane to the l2tp_ppp module via netlink. Subscriber routes are tracked for redistribution into the protocol RIB.

This page covers operator-facing use: configuration, the CLI surface, PPP negotiation, authentication, IP pools, traffic shaping, RADIUS, metrics, the web UI, reload semantics, and how subscriber routes flow out to BGP.

Configuration

The l2tp {} container carries protocol settings; listener endpoints live under environment { l2tp { server ... } }:

l2tp {
    enabled true;
    shared-secret <secret>;     // CHAP-MD5 tunnel auth (RFC 2661 S4.2)
    auth-method chap-md5;        // PPP Auth-Protocol first advertised
    allow-no-auth false;         // explicit opt-in required for no-auth
    hello-interval 60;           // seconds of peer silence before HELLO
    hello-retries 2;             // unanswered HELLO intervals before dead-peer teardown (0 disables)
    max-tunnels 1024;            // 0 explicitly means unbounded
    max-sessions 1024;           // per-tunnel, 0 explicitly means unbounded
}

environment {
    l2tp {
        server main {
            ip 0.0.0.0;
            port 1701;
        }
    }
}

Presence of l2tp {} with any content implies the subsystem is enabled. Set enabled false to disable explicitly. Listener endpoints use the standard zt:listener grouping (ip, port) with port conflict detection via ze:listener.

CLI commands

Read commands

Destructive commands

The clear l2tp session teardown command accepts optional keyword arguments:

• reason <text...> -- free-text audit reason, recorded in the per-session event ring
• cause <code> -- RADIUS Disconnect-Cause value (uint16), recorded alongside the reason

RFC 2661 S4.4.2 / S5.4.2 define the Result Codes and teardown semantics. Teardown of unknown IDs returns an error naming the ID.

Destructive commands live under the clear verb (not a top-level l2tp noun) to match ze's CLI grammar. The clear prefix is denied in the built-in read-only authz profile.

Offline dispatcher

ze l2tp show ... and the ze l2tp tunnel|session teardown[-all] commands forward to the running daemon via SSH. Output is the same JSON the daemon handler returns. (Inside the daemon CLI these teardowns dispatch as clear l2tp tunnel|session teardown ..., per the grammar note above.) ze l2tp decode is an offline wire-decode tool that does not require a running daemon.

echo c8020044... | ze l2tp decode --pretty

PPP negotiation

When a session is established (ICRQ/ICRP/ICCN exchange), the subsystem creates kernel L2TP tunnel and session resources via Generic Netlink, then opens a PPPoL2TP socket and attaches a /dev/ppp channel and unit. The kernel creates a pppN interface.

PPP negotiation proceeds through these phases:

1. LCP (RFC 1661) -- MRU, authentication method (PAP/CHAP-MD5/MS-CHAPv2), magic number, echo keepalive. 10-state FSM with ~30 transitions.
2. Authentication -- PAP (RFC 1334), CHAP-MD5 (RFC 1994), or MS-CHAPv2 (RFC 2759). Dispatched to the registered auth handler (l2tp-auth-local or l2tp-auth-radius plugin).
3. IPCP (RFC 1332) -- IPv4 address assignment + DNS options (RFC 1877). Dispatched to the registered pool handler (l2tp-pool plugin).
4. IPv6CP (RFC 5072) -- interface identifier negotiation. Runs in parallel with IPCP when both NCPs are enabled. NCPs are independent (RFC 1661 S2): if the pool handler declines IPv6 (for example an IPv4-only static pool), IPv6CP is dropped and the session stays up with IPv4 alone rather than being torn down.

Each phase has a configurable timeout. LCP proxy (RFC 2661 S18) is supported: when the LAC provides proxy LCP AVPs, ze validates them and optionally renegotiates rather than starting LCP from scratch.

NCP enablement is controlled via the ncp container under l2tp:

l2tp {
    ncp {
        enable-ipcp true
        enable-ipv6cp true
        timeout 30
    }
}

Authentication

Ze separates PPP authentication wire format from credential validation. The subsystem handles the PPP auth protocol (PAP/CHAP wire framing), then dispatches an EventAuthRequest to the registered auth handler. The handler responds with accept/reject via a channel.

By default, new sessions advertise auth-method chap-md5 and allow-no-auth false. If a peer rejects every acceptable Auth-Protocol, the PPP session is disconnected after LCP instead of falling through to the no-auth accounting path. Set allow-no-auth true only for lab peers or explicit no-auth deployments; auth-method none is rejected unless that opt-in is present.

Two auth handlers ship with ze:

l2tp-auth-local

Built-in static user list with PAP/CHAP-MD5/MS-CHAPv2 support. Configured under the l2tp config tree:

l2tp {
    auth {
        local {
            user alice {
                password hunter2;
            }
        }
    }
}

When no users are configured, the local handler rejects sessions. Add at least one user or configure RADIUS before enabling subscriber access.

l2tp-auth-radius

RADIUS client plugin providing:

• Access-Request -- PAP/CHAP-MD5/MS-CHAPv2 credential forwarding to RADIUS servers with failover and retry
• Accounting -- Start, Stop, and Interim-Update records (RFC 2866)
• CoA/DM -- Change of Authorization and Disconnect-Message listener (RFC 5176) for RADIUS-initiated session changes and disconnects

Configured under the l2tp config tree:

l2tp {
    auth {
        radius {
            nas-identifier ze-lns;
            timeout 3;
            retries 3;
            acct-interval 300;
            server main {
                address 10.0.0.10;
                port 1812;
                shared-key radiussecret;
            }
        }
    }
}

Authentication timing is controlled via the authentication container under l2tp:

l2tp {
    authentication {
        timeout 30
        reauth-interval 0
    }
}

The timeout leaf (1-3600 seconds, default 30) bounds the PPP auth phase. The reauth-interval leaf (0 or 5-86400 seconds, default 0) enables periodic re-authentication when non-zero. Values 1-4 are rejected to prevent re-auth storms.

IP address pool

The l2tp-pool plugin provides bitmap-backed IPv4 address pools. Pools are registered via the handler registry and dispatched when IPCP negotiation needs to assign an address.

Configured under the l2tp config tree:

l2tp {
    pool {
        ipv4 {
            gateway 10.100.0.1;
            start 10.100.0.2;
            end 10.100.255.254;
            dns-primary 8.8.8.8;
            dns-secondary 8.8.4.4;
        }
    }
}

Address allocation prefers RADIUS metadata when present. Framed-Pool selects a named pool for gateway and DNS values; an unknown named pool rejects the IPCP request. Framed-IP-Address then bypasses bitmap allocation and uses the selected pool's gateway and DNS with the RADIUS-assigned peer address. Framed-IP-Netmask is parsed into session metadata, but the current IPv4 IPCP response has no netmask field to apply.

Session-down events release allocated addresses back to the pool.

Traffic shaping

The l2tp-shaper plugin applies TC (traffic control) rules on pppN interfaces. Session establishment uses the configured default rate. RADIUS CoA can update the rate dynamically after the session is up.

Configured under the l2tp config tree:

l2tp {
    shaper {
        qdisc-type tbf;            // tbf or htb
        default-rate 10mbit;       // download rate for new sessions
        upload-rate 2mbit;         // upload rate (defaults to default-rate)
    }
}

RADIUS Filter-Id can override the default shaping rate when it contains a parseable rate, otherwise Ze keeps the configured default rate. Session-Timeout and Idle-Timeout start per-session teardown timers, and Acct-Interim-Interval overrides the accounting update cadence within the supported clamp range. RADIUS CoA rate updates do not tear down the session.

CQM (Call Quality Metrics)

Ze provides Firebrick-style CQM monitoring for L2TP sessions. The Observer records per-session events and per-login sample rings:

Per-session event ring -- circular buffer of state transitions (tunnel-up, session-up, session-down, echo-rtt, disconnect-requested). Disconnect events include the actor, reason text, and optional cause code. Used for the event timeline in the web UI.

Per-login CQM sample ring -- 100-second aggregated buckets with: - Echo RTT statistics (min, avg, max) - Echo count and loss ratio - Session state (established, negotiating, down) - Retention: 24h by default (864 buckets)

CQM data feeds: - LCP echo probes measure RTT; lost echoes contribute to loss ratio - Each 100s bucket is closed and appended to the sample ring - The web UI streams new buckets via SSE for live chart updates

Echo interval for CQM: ze.l2tp.cqm.echo-interval (env var, default derived from LCP echo configuration).

Prometheus metrics

L2TP exposes metrics under the ze_l2tp_* and ze_radius_* namespaces.

Aggregate gauges

Per-session counters (labels: username, session_id, interface)

CQM metrics (labels: username)

RADIUS metrics (labels: server)

Kernel interface stats are polled at ze.l2tp.metrics.poll-interval (default: 30s).

Web UI

The web interface at /l2tp provides session management and CQM graphing. All endpoints require authentication (session cookie or Basic Auth).

CQM chart

The detail page renders a client-side CQM graph using uPlot. The chart loads 24h of historical data via JSON, then appends new 100-second buckets in real time via SSE.

Chart colors are CSS custom properties (configurable via theme): - --color-l2tp-established (default: green #22c55e) - --color-l2tp-negotiating (default: amber #f59e0b) - --color-l2tp-down (default: purple #a855f7)

Disconnect

The disconnect button triggers a confirm dialog requiring a free-text reason (1-256 characters) and an optional Disconnect-Cause code. The POST dispatches through the CLI as clear l2tp session teardown <sid> reason <text> [cause <code>], so authz is enforced at the CLI layer. Read-only profiles are denied by the existing clear prefix rule.

The disconnect reason and actor are recorded in the per-session event ring for audit trail purposes.

Kernel integration

Ze uses the Linux kernel's L2TP and PPP subsystems for the data plane. Control plane (L2TP control messages, PPP negotiation) runs entirely in userspace.

Startup: the subsystem probes for l2tp_ppp and pppol2tp kernel modules via modprobe. If modules are not available, Start fails with a clear error. Set ze.l2tp.skip-kernel-probe=true for testing without kernel support.

Per-session kernel setup: 1. Create L2TP tunnel via Generic Netlink (L2TP_CMD_TUNNEL_CREATE) 2. Create L2TP session via Generic Netlink (L2TP_CMD_SESSION_CREATE) 3. Create PPPoL2TP socket (binds session to L2TP kernel state) 4. Open /dev/ppp, attach channel (PPPIOCGCHAN, PPPIOCATTCHAN) 5. Create PPP unit (PPPIOCNEWUNIT, PPPIOCCONNECT) 6. Kernel creates pppN interface 7. PPP negotiation runs over the /dev/ppp channel fd

Teardown: reverse order. PPPoL2TP socket close triggers kernel session removal. Tunnel is removed after all sessions are gone.

Redistribute

Ze registers l2tp as a redistribution source at subsystem Start. When a PPP NCP (IPCP or IPv6CP) completes for a session, the subsystem's RouteObserver emits a (l2tp, route-change) batch on the EventBus with the assigned peer IP as a /32 (IPv4) or /128 (IPv6) prefix. Session-down emits matching remove batches, one per address family that was up.

The redistribute orchestrator discovers L2TP as a producer at startup, subscribes to its events, and dispatches the prefixes to registered consumers (BGP) when a matching import rule is configured:

redistribute {
    destination bgp {
        import l2tp {
            family [ ipv4/unicast ipv6/unicast ];
        }
    }
}

Each peer's UPDATE carries origin=incomplete, an empty AS-path, and NEXT_HOP resolved to the peer's local session address.

Reload semantics

SIGHUP triggers Subsystem.Reload. The implementation diff-applies each knob according to this policy:

Rationale: the tunnel FSM carries per-tunnel state (sequence numbers, kernel fds, PPP sessions). Pushing a new hello-interval or new secret onto an existing tunnel would invalidate in-flight state. Listener changes require full driver teardown which is safer as an explicit restart.

Dead-peer detection

A HELLO is sent after hello-interval seconds of peer silence and is delivered reliably, so the peer's ZLB ACK proves the control channel is alive. Two independent clocks govern an established tunnel:

• lastActivity (delivered control messages only) decides when to send the next HELLO. A ZLB ACK does not refresh it, so HELLOs keep probing a quiet peer.
• lastLiveness (any delivered message or an acknowledgement of one of our messages, including a ZLB ACK of a HELLO) decides when the peer is dead. An idle-but-alive peer that only ZLB-ACKs HELLOs refreshes lastLiveness and is never torn down.

hello-retries is the dead-peer threshold: when no liveness signal arrives for hello-retries x hello-interval, the tunnel is torn down (sessions cleared, subscriber routes withdrawn, StopCCN sent, (l2tp, tunnel-down) emitted with reason keepalive-timeout). With the default hello-retries 2, a tunnel using hello-interval 5 is declared dead ~10s after the peer goes silent -- far faster than the reliable engine's ~31s retransmit exhaustion, which is the only signal when a peer (e.g. xl2tpd) dies without sending StopCCN.

Dead-peer detection is deliberately separate from the reliable-transport retransmit backoff and runs only for established tunnels, so setup (pre-established) and teardown (closed) retain the full ~31s retransmit budget for link-loss tolerance. Set hello-retries 0 to disable dead-peer detection and fall back to retransmit exhaustion alone. When hello-retries x hello-interval exceeds ~31s (e.g. the defaults 2 x 60s), retransmit exhaustion fires first and the threshold has no effect; lower hello-interval to get faster detection.

Environment variables

Remaining ze.l2tp.* env vars (not promoted to YANG config):

• ze.log.l2tp -- log level for the L2TP subsystem
• ze.l2tp.metrics.poll-interval (default: 30s) -- kernel stats polling interval
• ze.l2tp.cqm.echo-interval -- echo probe interval for CQM RTT measurement
• ze.l2tp.skip-kernel-probe (default: false) -- skip modprobe at Start (test-only)

PPP authentication and NCP settings are now YANG config leaves under l2tp { authentication { ... } } and l2tp { ncp { ... } }.

Architecture

The subsystem uses a reactor pattern: a single reactor goroutine reads the shared UDP socket and dispatches to tunnel state machines. A separate timer goroutine handles retransmission and HELLO keepalive. PPP negotiation runs on a worker pool for blocking /dev/ppp I/O. No goroutine-per-tunnel.

UDP socket ---> Reactor goroutine ---> Tunnel FSM ---> Session FSM
                                                         |
                                                   Kernel worker
                                                   (Generic Netlink,
                                                    PPPoL2TP socket,
                                                    /dev/ppp)
                                                         |
                                                   PPP worker pool
                                                   (LCP, auth, NCP)
                                                         |
                                                   Observer (events,
                                                    CQM buckets)

Four L2TP plugins register at startup via init(): - l2tp-auth-local -- static user/password authentication - l2tp-auth-radius -- RADIUS authentication, accounting, CoA/DM - l2tp-pool -- bitmap-backed IPv4 address pools - l2tp-shaper -- TC traffic shaping on pppN interfaces