L2TPv2 LNS subsystem

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.

Initiator: dial targets and outgoing calls

Beyond answering tunnels, ze can INITIATE them (send SCCRQ) toward a configured remote. A remote list under l2tp {} declares dial targets; declaring one grants no dial by itself. An operator action (RPC) or a PPPoE relay binding drives the dial.

l2tp {
    enabled true;
    remote lns-retail {
        address 203.0.113.10;   // control-plane IP to dial (SCCRQ destination)
        port 1701;              // remote UDP port (default 1701)
        shared-secret <secret>; // per-remote CHAP-MD5 (empty = no Challenge)
        outgoing-calls true;    // permit `request l2tp outgoing-call` to this remote
    }
    relay <service-name> {      // PPPoE Service-Name -> L2TP incoming call (LAC)
        remote lns-retail;      // must reference an l2tp/remote above
    }
}

Place an LNS-side outgoing call (RFC 2661 S10.4) with:

request l2tp outgoing-call remote lns-retail called <number>

The command dials the remote if no tunnel is up, sends an OCRQ, and blocks until the call establishes (returning the local/remote session IDs) or fails (returning the cause and RFC 2661 Result Code: tunnel auth reject, tie-breaker loss, peer CDN, or timeout). The remote must have outgoing-calls true.

The relay binding is the LAC path: a PPPoE subscriber whose Service-Name matches is relayed into an L2TP incoming call (ICRQ) toward the bound remote instead of terminating PPP locally. The subscriber-PPP↔L2TP kernel channel bridge that carries frames at the LAC is Linux-only and exercised through ./le deployment l2tp-ppp-test. Initiator tunnel interop is proven against xl2tpd in test/interop-l2tp/scenarios/03-ze-lac-xl2tpd-lns.

Rejecting a malformed SCCRQ

RFC 2661 Section 6.1 makes five AVPs mandatory in an SCCRQ: Message Type, Protocol Version, Host Name, Framing Capabilities and Assigned Tunnel ID. An SCCRQ that omits one of them is a malformed control message under Section 7.1, and so is one whose value ze cannot read: a 3-octet Framing Capabilities AVP, an empty Host Name AVP, or an Assigned Tunnel ID of 0, which Section 4.4.3 makes "a 2 octet non-zero unsigned integer".

Ze answers each of these with a StopCCN that carries Result Code 2 (general error, see the Error Code), Error Code 3 (a field value out of range) and an Error Message that names the AVP, for example SCCRQ missing Framing Capabilities AVP. The reply goes out with Tunnel ID 0, because the peer supplied no tunnel id ze can address it by, and no tunnel entry is created for it.

The reply is rate-bounded: one StopCCN per source-address slot per second, over a fixed 256-slot table. A spoofed SCCRQ flood therefore allocates nothing and draws at most 256 replies per second from the whole reactor. Every other malformed TunnelID=0 datagram keeps its silent drop, an unrecognized mandatory vendor AVP and a message type that is not SCCRQ among them.

CLI commands

Read commands

Destructive commands

The clear l2tp session id 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 {id <id>|all} commands forward to the running daemon via SSH. Output is the same JSON the daemon handler returns. Each accepts --user <name> (short alias -u) to name the SSH login user; without it the login resolves to the zefs super-admin. The flag must come before the subcommand arguments (ze l2tp show --user alice tunnels), and one left in the positional tail is rejected rather than forwarded, so a misplaced --user never silently answers for the default user. Shell completion offers the flag on all three verbs. (Inside the daemon CLI these dispatch as clear l2tp tunnel|session {id <id>|all} ...; clear already means tear down, so no teardown token is needed.) 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.

Ze answers each RFC 5072 Section 4.1 comparison outcome for the peer's Interface-Identifier option:

A session can reach IPv6CP Opened without the peer ever supplying an identifier, through the missing-option case above. Ze starts no IPv6 service, installs no route and publishes no IPv6 address for such a session: an all-zero identifier would make the peer's link-local address fe80::, which is not the subscriber's. The session stays up with IPv4 alone, and the refusal is logged and counted (see Prometheus metrics).

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. The slot holds one handler, and configuration decides its owner: l2tp-auth-radius claims it when a RADIUS server is configured, and l2tp-auth-local keeps it otherwise. Both transports read that one slot, so the same rule governs a PPPoE subscriber.

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), reporting the subscriber address as Framed-IP-Address
• CoA/DM -- Change of Authorization and Disconnect-Message listener (RFC 5176) for RADIUS-initiated session changes and disconnects

RFC 2865 Section 4.1 admits exactly three credential attributes in an Access-Request: User-Password, CHAP-Password, or State. A peer that supplied none of them supplies nothing to authenticate, so no Access-Request is built and the session is denied with no usable credential. This covers auth-method none while a RADIUS server is configured, and an MS-CHAPv2 response too short to carry a peer challenge and an NT response. Section 5 forbids sending text of length zero, so a peer that sends an empty PAP Peer-ID gets an Access-Request with no User-Name attribute rather than an empty one.

An Access-Accept naming a Service-Type other than Framed-User is treated as an Access-Reject, and the session is denied with unsupported Service-Type. The LNS provides framed PPP access and asks for it by name, so an Accept authorizing anything else authorizes a service ze cannot bring up (RFC 2865 Sections 5.6 and 1.1).

Every Accounting-Request carries Acct-Status-Type, Acct-Session-Id, Service-Type (Framed), Framed-Protocol (PPP), NAS-Port-Type (Virtual), NAS-Port and Event-Timestamp. User-Name and Calling-Station-Id are added when the session has one: a session the LNS never authenticated has no username, a call whose peer sent no Calling Number AVP has no station id, and RFC 2866 Section 5 forbids sending text of length zero. NAS-Port-Id is added when the operator configured a template. Stop and Interim-Update add Acct-Session-Time, the input and output octet and packet counters, and the RFC 2869 gigaword counters when a counter passes 2^32.

Event-Timestamp (type 55) is four octets of seconds since 1970-01-01 00:00 UTC, which RFC 2869 Section 5.3 defines. Calling-Station-Id (type 31) is the L2TP Calling Number AVP the peer sent, or the subscriber MAC address on the PPPoE relay path.

Acct-Delay-Time (type 41) reports how many seconds ze has been trying to send that record, counted from its first attempt, which is what RFC 2866 Section 5.2 asks for. It is zero on the first transmission and it is updated on every retransmission. RFC 2866 Section 4.1 makes that update change the Identifier and the Request Authenticator as well, so a server that sees a repeat of an accounting record sees a new Identifier. An Access-Request is unaffected: its retransmission is byte for byte the first packet, with the same Identifier, which is what RFC 2865 Section 2.5 requires.

The Stop record adds Acct-Terminate-Cause (type 49), and no other record carries it. RFC 2866 Section 5.10: "This attribute indicates how the session was terminated, and can only be present in Accounting-Request records where the Acct-Status-Type is set to Stop." The value is one of that section's integers: User Request (1) when LCP reaches Closed or Stopped, Lost Carrier (2) for unanswered LCP echo probes and for a peer that stops answering at the tunnel level, Lost Service (3) for every session on a tunnel the peer ended, Idle Timeout (4) and Session Timeout (5) for the two RADIUS timers, Admin Reset (6) for an operator clear and for a RADIUS Disconnect-Request, Admin Reboot (7) for the sessions ze stops on shutdown, NAS Request (10) when the PPP driver stops a running session, and NAS Error (9) for a failure ze detected or a teardown it cannot attribute. Ze reports NAS Error rather than guessing a more specific cause.

A subscriber hanging up reaches the record through the peer's Call-Disconnect- Notify. Ze reads that message's Result Code (RFC 2661 Section 4.4.2) and translates the two values RFC 2866 Section 5.10 also states: code 1, "Call disconnected due to loss of carrier", becomes Lost Carrier, and code 3, "Call disconnected for administrative reasons", becomes Admin Reset. The other ten codes describe a call the far end could not place, which no Section 5.10 cause states, so they become NAS Error rather than a guess.

Each of these four attributes is sent unless the operator holds it back with attributes exclude, described below. There is no leaf that turns one on: the default is to send it.

RFC 2866 Section 4.1 requires either NAS-IP-Address or NAS-Identifier in every Accounting-Request, and RFC 2865 Section 4.1 requires the same of every Access-Request, so ze always sends one of the two. A configured source-address becomes NAS-IP-Address and a configured nas-identifier becomes NAS-Identifier. When neither leaf is set, the host name is sent as NAS-Identifier, which is what the RADIUS admin backend already does.

Framed-IP-Address carries the address the session was actually given, which RFC 2866 Section 4.1 requires of the attribute. The value is the IPCP-negotiated peer address the reactor put on pppN. RFC 2865 Section 5.8 makes the attribute four octets, so a session with no address yet, or one whose only assignment is IPv6, sends no attribute rather than a wrong one.

Holding an attribute back

The four attributes above are sent by default, which is what a billing system usually wants. An operator whose server or billing pipeline does not want one of them writes an attributes exclude container beside server:

l2tp {
    auth {
        radius {
            attributes {
                exclude {
                    calling-station-id {
                        packet-type [ accounting-interim ];
                    }
                    acct-terminate-cause;
                }
            }
        }
    }
}

Naming an attribute alone holds it back from every packet that would carry it. Adding a packet-type list holds it back from the record types named there and keeps it in the others.

Six attributes can be held back, and each accepts only the record types Ze puts it in. A line naming any other record type is refused when the configuration is committed.

Check the server before you hold Calling-Station-Id back. FreeRADIUS is not uniform about its fallbacks. Its default accounting queries are defensive: they fall back to the server clock when Event-Timestamp is absent, and they default Acct-Terminate-Cause to NAS-Reboot, so a record without either is still stored. Its IP pool queries are not. raddb/mods-config/sql/ippool/mysql/queries.conf matches AND callingstationid = '%{Calling-Station-Id}' in stop_clear, alive_update and start_update with no fallback value, so a pool served by FreeRADIUS keeps leases that never expire once attribute 31 stops arriving. Acct-Delay-Time appears in no default query at all.

Acct-Status-Type, Acct-Session-Id and the NAS identity cannot be held back, and the schema does not name them. RFC 2866 Section 5.13 counts the first two as "1 Exactly one instance of this attribute MUST be present", and its Note 1 reads "An Accounting-Request MUST contain either a NAS-IP-Address or a NAS-Identifier (or both)". Ze offers no numeric form for the same reason: a number accepts a line that suppresses a mandatory attribute and gives the operator no diagnostic either way.

Three attributes an operator may look for are deliberately absent, because no runtime value exists for them: Framed-Interface-Id, Framed-IPv6-Prefix and Delegated-IPv6-Prefix.

Configured under the l2tp config tree:

l2tp {
    auth {
        radius {
            nas-identifier ze-lns;
            nas-port-id-format "{nas-id}:{tunnel-id}.{session-id}";
            timeout 3;
            retries 3;
            acct-interval 300;
            coa-port 3799;
            server main {
                address 10.0.0.10;
                port 1812;
                shared-key radiussecret;
            }
        }
    }
}

nas-port-id-format is the template for the NAS-Port-Id attribute (RFC 2869 Section 5.17). An LNS has no physical port to number, so the operator composes one from {nas-id}, {tunnel-id} and {session-id}. Every other character is copied. All three values are known before the session has an interface, so the Access-Request and every accounting record of one session carry the same text and a billing system can join them. The text is resolved once per session, so a config reload does not move it mid-session.

Four templates are refused when the config is committed: one naming a placeholder that does not exist, one longer than 253 characters (the largest value a RADIUS attribute can carry), one using {nas-id} with no nas-identifier set, and one whose widest resolution passes 253 octets because the nas-identifier it expands is long. The last is a separate check because {nas-id} is nine characters that expand to a name the config does not bound. Unset sends no attribute.

acct-interval is the interim accounting cadence in seconds, and it has no default. RFC 2869 Section 2.1 states that a locally configured value on the NAS MUST override the value found in an Access-Accept. A leaf that is set therefore pins the cadence of every session, and a RADIUS server cannot move it. An unset leaf gives that decision to each session's Access-Accept. The value arrives in the Acct-Interim-Interval attribute (type 85), which Ze clamps to 60..3600 seconds. A session runs at 300 seconds when neither side states an interval.

The choice is which side owns the cadence. An operator who sized the interval for the NAS and the network sets the leaf. An operator who leaves it unset lets one server retime every session that server accepts.

coa-port enables the UDP Change of Authorization and Disconnect-Message listener. It has no default: leaving it unset keeps the listener off, so an upgrade cannot expose a new RADIUS endpoint unexpectedly. Port 3799 is the standard deployment choice. Ze accepts CoA/DM requests only from addresses listed under server; the authentication and accounting destination port on each server is configured separately. When no server address resolves to an IP the listener does not start at all, because there is then no dynamic authorization client to trust and the port would answer anybody.

Ze answers a request only when every check below passes. A failed check either discards the packet without a reply, which is what RFC 5176 requires where a reply would confirm the shared secret to a sender that guessed wrong, or answers a NAK carrying an Error-Cause.

One of these is stricter than RFC 5176, deliberately. Section 6.3 makes the Event-Timestamp a SHOULD and lets an implementation be configurable about its absence; Ze refuses a request that omits it, because the port takes unsolicited packets that tear subscriber sessions down and without the attribute there is no replay protection.

The response echoes the request's Proxy-State and State attributes unchanged, and Ze never reads their contents.

RFC 5176 Section 3.4 makes the Message-Authenticator attribute optional, and Ze follows the RFC by default: a CoA-Request or Disconnect-Request that carries none is accepted, and one that carries a wrong value is discarded with no reply. The request still has to come from a configured Dynamic Authorization Client and still has to carry a correct Request Authenticator, both keyed on the shared secret, so an absent attribute is not an unauthenticated request.

Set require-message-authenticator true to refuse a request that carries none. Requiring the attribute is the mitigation for the Blast-RADIUS class of attack on the RADIUS/UDP MD5 authenticator, so enable it wherever the Dynamic Authorization Client can send one. FreeRADIUS radclient and the radiusd CoA originator both can. The default is permissive because a Dynamic Authorization Client that omits the attribute is conformant, and refusing it outright made Ze unable to talk to one at all.

Both authenticators are computed in the order RFC 5176 Section 3.4 fixes. The Message-Authenticator is the HMAC-MD5 over the packet with the Request Authenticator field and the Message-Authenticator value each replaced by sixteen octets of zero, and the Request Authenticator is computed afterwards, over the packet the finished Message-Authenticator is part of. A client that inverts the two is refused.

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.

A subscriber session is shaped in both directions, and each direction uses a different mechanism.

The upload direction uses a policer because the ingress hook holds no queue. A queueing discipline shapes by delaying a packet, and there is nothing to delay into on that hook, so the enforcement available is to drop what exceeds the rate. The policer attaches at tc priority 200 on the shared clsact qdisc, so interface mirroring (priority 1) and flow-export sampling (priority 100) keep working on the same interface.

A PPPoE subscriber gets the same pair of mechanisms. Both access types terminate on a pppN, so one implementation serves them both.

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. The forms 10mbit, 20mbit/5mbit, rate:10mbit and rate:20mbit/5mbit are accepted, at Access-Accept and in a CoA-Request alike. A MikroTik Mikrotik-Rate-Limit of 10M/5M is read the same way. The two-value forms set the download rate and the upload rate separately. Session-Timeout and Idle-Timeout start per-session teardown timers. Acct-Interim-Interval sets the accounting update cadence, clamped to 60..3600 seconds. It applies to a session whose deployment left acct-interval unset. RFC 2869 Section 2.1 gives a configured acct-interval precedence over it. 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)

PPP negotiation counters (labels: reason)

The label set is closed and holds three values. A session or tunnel ID is deliberately not a label: a subscriber daemon carries thousands of sessions.

This counter is shared with PPPoE subscribers, which run the same PPP driver.

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 colours 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 id <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)
• ze.l2tp.disable-kernel-dataplane (default: false) -- build no kernel worker, so a session establishes on the control plane and nothing is programmed into the kernel (test-only). It is separate from skip-kernel-probe, which bypasses only the modprobe and still needs the data plane.

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