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
proxy-lcp accept; // LNS: accept the LAC's proxy LCP, or renegotiate
mru 1500; // Information-field octets; 68..1500, IPv6 needs 1280
lcp {
restart-timer 3000; // milliseconds, 100..60000
max-terminate 2; // transmissions, including the first
max-configure 10; // transmissions without a valid reply
max-failure 5; // Naks before rejecting unacceptable options
}
authentication {
allow [ chap-md5 ]; // ordered permitted methods; optional
}
hello-interval 60; // seconds of peer silence before HELLO
hello-retries 2; // unanswered HELLO intervals before dead-peer teardown (0 disables)
max-retransmit 5; // retransmissions of an unacknowledged message before the tunnel is cleared
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.
The lcp settings control RFC 1661 retransmission on locally terminated PPP
sessions. Each limit accepts 1 through 255. The Restart timer is restarted by
each Configure-Request or Terminate-Request transmission, and by the
Zero-Restart-Count action after the peer terminates LCP. A silent peer receives
exactly max-configure requests before negotiation ends; the defaults give a
30-second budget. max-failure counts Configure-Naks sent without sending a
Configure-Ack: after that many Naks, unacceptable options are rejected.
An accepted proxy LCP starts already Opened and sends no initial requests.
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.
A dialed tunnel sends from the L2TP listener socket, so the listener's ip
is the tunnel's source address (RFC 2661 Section 8.1 requires the addresses
and ports to stay static for the life of the tunnel). Every dial, from this
command or from a relay, uses the first environment l2tp server. When that
listener is on a loopback address it cannot reach another host, so Ze refuses
a config that pairs it with an off-host remote: Ze does not start with it,
and a reload that adds such a remote is refused and changes nothing.
ze config validate does not check this yet. A dial that still meets the
case is refused at once. Each error names the remote, the listener and the fix: bind environment l2tp server <name> ip
to an address that reaches the remote, or to the wildcard of the remote's
family (0.0.0.0 for IPv4, :: for IPv6) to let the route choose it. Ze
binds a listener only when it starts, so after a reload that moves the
listener, a dial asks for a restart instead.
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. TestLACChannelBridge
shows only that the bridge ioctls reach the kernel, and
./le test deployment l2tp-ppp has xl2tpd dial Ze as an LNS with no PPPoE
and no Ze LAC, so it never reaches the bridge. The end-to-end proof of the
relay data path is the topology scenario access-up
(./le test integration interop-topology scenario access-up): a Ze CPE
dials with no Service-Name, a Ze LAC relays it with relay "" to a Ze LNS,
and the CPE pings the LNS across the session. It runs on a Docker host
running Ze's kernel, and it goes red when the LAC skips the bridge: the LNS
then logs an LCP negotiation timeout and the CPE never holds its address.
access-pool proves the LNS pool fallback and access-accounting the
RADIUS Start, Interim-Update and Stop over the same chain. Initiator tunnel interop is
proven against xl2tpd in test/interop-l2tp/scenarios/03-ze-lac-xl2tpd-lns.
Relay by realm (wholesale LAC)
A relay-realm binding selects the LNS from the realm of the PPP username,
the way a wholesale access network does:
l2tp {
relay-realm example.net { // username realm -> L2TP incoming call
remote lns-retail; // must reference an l2tp/remote above
}
}
The realm is the text after the last @ of the username, compared exactly
once case is ignored, so cpe@Example.NET matches example.net and
cpe@x.example.net does not. A Service-Name relay that matches at PPPoE
discovery wins, and a username whose realm names no binding is authenticated
by the local auth handler as for any PPPoE session.
For a matched realm the LAC runs LCP with the subscriber, starts
authentication (a CHAP Challenge, or the PAP Authenticate-Request it
receives, per the PPPoE authentication-allow list), dials the bound remote
and places an incoming call whose ICCN carries the proxy AVPs of RFC 2661
Section 4.4.5:
| AVP | Name | Content |
|---|---|---|
| 26 | Initial Received LCP CONFREQ | options of the first Configure-Request the subscriber sent |
| 27 | Last Sent LCP CONFREQ | options of the LAC's Configure-Request the subscriber Acked |
| 28 | Last Received LCP CONFREQ | options of the subscriber's Configure-Request the LAC Acked |
| 29 | Proxy Authen Type | 2 (CHAP) or 3 (PAP) |
| 30 | Proxy Authen Name | the username |
| 31 | Proxy Authen Challenge | CHAP only: the challenge the LAC sent |
| 32 | Proxy Authen ID | the CHAP or PAP Identifier |
| 33 | Proxy Authen Response | the CHAP response, or the PAP password hidden after a Random Vector |
Every proxy AVP carries M=0. A PAP password travels only hidden, so a PAP
subscriber's proxy authentication is sent only when the remote has a
shared-secret; without one the ICCN carries AVPs 26 to 28 alone, the LAC
logs why, and the LNS restarts authentication. An LNS may also ignore the
proxy data and renegotiate LCP and authentication; a Ze LNS does so under
proxy-lcp renegotiate (see PPP negotiation).
The access-wholesale topology scenario proves the relay end to end: a Ze LAC
runs LCP and CHAP with a Ze CPE, picks the LNS by the realm, and the LNS
renegotiates LCP and challenges again before the CPE reaches IPCP Opened.
ze config validate, a commit and the daemon at start refuse a binding
whose remote is not declared, an empty realm, a realm holding @ or
whitespace, a realm longer than 253 octets, and two bindings that differ only
in case, each with the change that fixes it. A reload applies to the next
authentication.
show l2tp session id <id> on the LAC adds relay-realm, relay-remote,
proxy-lcp-sent and proxy-auth-sent to a realm-relayed session, and
proxy-auth-reason (no-shared-secret, no-authentication,
proxy-data-too-large) when proxy authentication was not sent.
While the call is placed the LAC keeps the subscriber's link served: it
answers LCP Echo-Request and drops a retransmitted CHAP Response or PAP
Authenticate-Request, which the pending decision answers. Once the L2TP
session is ready the LAC stops reading the subscriber's PPP channel, bridges
it to the L2TP session, and from then on sends the subscriber nothing itself:
the LNS continues the PPP session. A matched realm whose call fails (no
listener, a refused tunnel, a CDN or a bridge error before the bridge) is
refused with a CHAP Failure or PAP Authenticate-Nak naming the realm, then an
LCP Terminate-Request; it is never authenticated locally. An MS-CHAPv2
subscriber of a matched realm is refused the same way, because RFC 2661
Section 4.4.5 defines no Proxy Authen Type for MS-CHAPv2; its Failure carries
the RFC 2759 Section 6 fields (E=691 R=0 C=<the challenge sent> V=3) with
the realm in the M= text. After the bridge, a
subscriber PADT ends the L2TP session with CDN Result Code 1 (loss of
carrier), and an L2TP session the LNS ends sends the subscriber PADT.
Subscribers of one remote share one tunnel, including those that arrive
while it is still connecting. ze_l2tp_relay_total counts each decision (see
Metrics).
Two topology scenarios prove the realm path against LNSes Ze does not
write. In l2tp-lac-realm-relay-accel-ppp a pppd subscriber is relayed by
its realm to accel-ppp, which ignores the proxy AVPs and renegotiates; the
subscriber reaches IPCP, the LAC session carries the relay-realm keys, and
a second subscriber of an unbound realm is refused locally and never reaches
the LNS. l2tp-lac-realm-relay-xl2tpd runs the same relay against xl2tpd and
its pppd. The Linux tests TestLACRealmBridgeAfterLocalLCP and
TestLACRealmHandoffRetransmission bridge real pppox channels after local
LCP, and pppoe-realm-relay-nomatch.ci shows an unbound realm terminated
locally and refused.
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.
An SCCRQ carrying an AVP ze does not recognize with the M-bit set is answered on the same path, with Error Code 8 rather than 3. That AVP is a vendor-specific AVP, or an IETF AVP whose Attribute Type RFC 2661 does not define. An AVP with a reserved flag bit set gets Error Code 3. RFC 2661 Section 4.4.2 gives that code to a "tunnel was shutdown due to receipt of an unknown AVP with the M-bit set", and Section 4.2 says the same AVP with the M-bit clear is ignored and the message accepted, which is what ze does. Each refusal states its own Error Code, so the code names the fault the peer has to correct.
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. A TunnelID=0 datagram whose message type is not SCCRQ keeps its silent drop.
CLI commands
Read commands
| Command | Output |
|---|---|
show l2tp |
Aggregate counters: tunnel count, session count, listener count |
show l2tp tunnels |
Array of tunnel summaries |
show l2tp tunnel <id> |
One tunnel detail (AVPs, capabilities, session list) |
show l2tp sessions |
Array of session summaries (flattened across tunnels) |
show l2tp session id <id> |
One session detail (PPP state, negotiated MRU/auth method, proxy-lcp outcome, assigned IP, speeds; the realm relay keys on a realm-relayed LAC session) |
show l2tp statistics |
Protocol counters (tunnel/session counts, per-message stats) |
show l2tp listeners |
Bound UDP endpoints |
show l2tp config |
Effective runtime config, including mru and authentication-allow; shared-secret redacted to <set>/<unset> |
show l2tp config reports the local requested mru (1500 when absent) and
the effective authentication-allow list, including the method-dependent
default when no list was written. It describes the policy for new sessions,
not what an established peer negotiated.
Session summaries and details report mru as the peer's negotiated receive
MRU before the local transmit cap, and auth-method as the method agreed by LCP.
These are the actual values from normal or accepted proxy negotiation, not
copies of the configured MRU or preferred method. Both keys are null
before LCP opens and after LCP goes down; negotiated no-auth is the distinct
value "none". LCP-up precedes authentication, so a reported method does not
by itself mean the subscriber has authenticated.
The installed IP interface MTU is bounded by both this peer MRU and the
session's configured MRU, so a reported peer MRU of 1500 can accompany an
installed MTU of 1492. An omitted peer option is reported as the PPP default
of 1500; it does not remove the local transmit cap.
Destructive commands
| Command | Effect |
|---|---|
clear l2tp tunnel id <id> |
Sends StopCCN Result Code 6 (administrative) to the named tunnel |
clear l2tp tunnel all |
Same, for every live tunnel |
clear l2tp session id <id> [reason <text...>] [cause <code>] |
Sends CDN Result Code 3 (administrative) to the named session |
clear l2tp session all |
Same, for every live session (tunnels remain) |
The clear l2tp session id command accepts optional keyword arguments:
reason <text...>-- free-text audit reason, recorded in the per-session event ringcause <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:
- LCP (RFC 1661) -- MRU, authentication method (PAP/CHAP-MD5/MS-CHAPv2), magic number, echo keepalive. 10-state FSM with ~30 transitions.
- 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). A CHAP or MS-CHAPv2 Challenge the subscriber does not answer is followed by a new one, with a new Identifier and Value, every 3 seconds (RFC 1994 Section 4.1); after 10 unanswered Challenges, or the auth timeout, the session ends. Only the newest Challenge is answerable, so a late Response to an earlier one is discarded.
- IPCP (RFC 1332) -- IPv4 address assignment + DNS options (RFC 1877).
Dispatched to the registered pool handler (l2tp-pool plugin).
A DNS option the subscriber asks for and the pool holds no server for
(no
dns-secondary, say) is Configure-Rejected (RFC 1661 Section 5.4), so the subscriber drops it and IPCP still opens. - 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.
The PPP MRU counts the Information field, not the two-octet Protocol field.
Ze's userspace buffers hold 1502 octets, and the kernel receive MRU stays at
1500 even when a smaller MRU was requested. The outgoing IP interface MTU
is the smaller of the peer's negotiated MRU and the session's configured
MRU, without subtracting PPP framing. An omitted peer option still means a
peer receive capacity of 1500; it cannot raise the interface MTU past the
configured cap.
Code-Reject, Protocol-Reject and Echo-Reply use the same effective transmit
limit for their returned payloads; a larger receive buffer does not permit an
oversized reply.
Set l2tp mru to the requested receive MRU (68..1500, default 1500), for
example 1492 behind a PPPoE LAC. It does not cap receive buffers or describe
the peer's receive MRU. show l2tp config reports the effective mru and
authentication-allow policy, not negotiated session values.
PPP descriptors use blocking os.File I/O rather than the runtime epoll path.
Closing a session prevents new operations while an in-flight blocking syscall
retains its descriptor reference. This keeps a late read or repeated close
from using a descriptor number the process has since recycled.
Each session reads both descriptors, one long-lived reader for each. LCP,
authentication and the first NCP negotiation all run on the channel, because
Ze connects the channel to the unit (PPPIOCCONNECT) only once NCP is up.
From then on Linux queues on the channel only a frame whose protocol is 0xc000
or above (LCP, PAP, CHAP) or a CCP fragment, and every other control frame
(IPCP, IPv6CP, CCP or an unknown protocol) on the unit (ppp_input and
ppp_receive_nonmp_frame, drivers/net/ppp/ppp_generic.c). The unit reader
sleeps until that connect, and both readers feed the one session loop, so an
IPCP Terminate-Request, renegotiation or unknown Code after session-up is
answered like any other. The unit reader reads EOF when the channel is
disconnected or unregistered, and waits for the next connect. A unit read
error ends the session. After an LCP restart disconnects the channel, Linux
still hands out the frames queued on the unit before the disconnect, and those
belong to the NCP lifetime that ended. So before it connects again, the session
discards everything the unit delivers until the reader reads EOF, and only then
connects.
The PPP driver closes both the channel and unit on natural exit or explicit stop. Shutdown, channel attachment and detachment, and post-NCP interface setup share a lock so an ioctl cannot use a recycled descriptor.
The L2TP kernel worker transfers the channel and unit to PPP only after the reactor confirms that the original session is still present. The transfer clears those descriptors from the worker; its teardown still closes the PPPoX transport. Bridged sessions and sessions without a PPP driver stay worker-owned. A cancelled delivery closes the claimed descriptors; an accepted queue item belongs to PPP even if rejected or drained during stop.
LCP accepts an Ack only when its Identifier and complete option bytes match the last request. Nak and Reject replies also need the matching Identifier; Reject options must be an unchanged, ordered subset of that request. Rejected options stay out of subsequent requests. Unanswered retransmissions retain their Identifier, while a changed request or valid reply advances it. An LCP or NCP configuration response must fit the session transmit limit with all required options intact. If it cannot, Ze reports session failure and stops negotiation before an unsent response can advance its state. Echo packets carry zero until Magic-Number negotiation succeeds, then the local Magic-Number; received Echo packets must carry the peer's value.
LCP enters Opened before authentication and NCP execute. If those phases receive an LCP restart or termination, they unwind into the new LCP state instead of restoring Opened. Periodic CHAP and MS-CHAPv2 authentication follow the same rule: the session loop resumes LCP negotiation or waits for the termination grace timer before notifying the transport to close. Echo and periodic authentication timers stop while LCP is outside Opened.
Leaving LCP Opened ends the previous PAP decision and both NCP lifetimes. Ze disconnects an attached channel from its PPP unit before replacement authentication and NCP, so control frames return to the channel reader. A failed disconnect or interface-resource removal ends the session instead of reusing the unit. Ze removes IPCP interface resources and stops the IPv6 service before clearing their negotiation state and cached frames. An LCP-down event then notifies the transport that the previous network phase has ended. If NCP had started, PPP waits for the transport to acknowledge resource cleanup before continuing LCP. This prevents old cleanup from removing a replacement allocation or profile for the same session.
NCP packets received before the new authentication completes are discarded, including while LCP is already Opened. Once NCP restarts, Configure replies must match the Identifier of its latest transmitted request. An Ack must also match all request options exactly; Reject options must remain an unchanged, ordered subset. These checks prevent an old reply from completing the replacement negotiation or changing its addresses.
Ze answers each RFC 5072 Section 4.1 comparison outcome for the peer's Interface-Identifier option:
| The peer's Configure-Request | Ze answers |
|---|---|
| A non-zero identifier that differs from Ze's | Configure-Ack, and the identifier is recorded as negotiated |
| A zero identifier, or one equal to Ze's | Configure-Nak carrying a freshly drawn non-zero identifier with the "u" bit clear |
| ✕ | Configure-Nak carrying a suggestion the FIRST time. Every later request that still omits it is Acked, so a client whose implementation does not support the option converges rather than being asked forever |
| Two Interface-Identifier options | Refused, the same as any other malformed option list |
| A zero identifier while Ze's own is also zero | Configure-Reject with the identifier set to zero, which ends that negotiation |
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).
Authentication and NCP have configurable timeouts. LCP negotiation and restart timers are fixed.
Proxy LCP (RFC 2661 Section 4.4.5) is the LAC's record of the LCP it already
negotiated with the subscriber, sent in ICCN as AVPs 26 to 28. The RFC lets an
LNS use it to continue "without renegotiation of LCP", and notes that "the LNS
policy may be to enter an additional round of LCP negotiation and/or
authentication if the LAC is not trusted". The proxy-lcp leaf picks the
policy:
proxy-lcp |
What the LNS does |
|---|---|
accept (default) |
When all three AVPs parse and the proxied method is in the auth allow-list and the proxied MRU fits mru, LCP opens on the LAC's values. Partial, malformed or out-of-policy proxy data is renegotiated. |
renegotiate |
The AVPs are ignored. Ze sends its own Configure-Request with its own Magic-Number, MRU and Auth-Protocol; the subscriber, Opened with the LAC, renegotiates (RFC 1661 Section 4.3). |
Under both values Ze then authenticates the subscriber itself, with a fresh
CHAP Challenge, or by waiting for a PAP Authenticate-Request. On renegotiate
the method is the configured one, never the LAC's. Ze does not use the proxy
authentication AVPs (RFC 2661 Section 9.5). show l2tp session id <id> reports
what happened in the proxy-lcp key: accepted, renegotiated, none (the
ICCN carried no proxy LCP), or null before LCP first opens. The leaf is global
to the LNS, not set per LAC.
l2tp {
proxy-lcp renegotiate;
}
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.
Authentication results obey the session transmit limit. PAP and CHAP trim only optional display text. MS-CHAPv2 preserves the complete authenticator response on success and the structured error fields on failure, shortening only human-readable text. Cached PAP replies preserve their original outcome with an empty message. A required structured result that cannot fit fails visibly instead of sending a truncated authenticator or challenge field.
By default, new sessions advertise auth-method chap-md5 and
allow-no-auth false. A peer's Configure-Nak can select only an untried
permitted method. Ze offers every available CHAP variant before PAP, even if
the peer keeps suggesting PAP; an unknown, unlisted or already-tried
suggestion advances to the next untried permitted method.
If none remains, required authentication closes LCP with Terminate-Request
before Opened: no authentication request or network-phase work runs. A valid
Configure-Reject removes the entire Auth-Protocol option for that negotiation,
even when unused methods remain; required authentication closes LCP in that
case too. With allow-no-auth true, either refusal instead continues without
the option and uses the no-wire-auth handler. Set that opt-in only for lab
peers or explicit no-auth deployments; auth-method none requires it.
With auth-method pap and no explicit allow-list, the first Configure-Request
offers CHAP-MD5 and a Nak toward PAP selects PAP next. An explicit PAP-only
policy offers PAP directly. RFC 1334 Section 2 requires an implementation that
includes CHAP to offer it before PAP.
authentication { allow [ chap-md5 ms-chap-v2 ]; } declares an ordered set
of permitted methods. It must include auth-method, cannot contain none,
and cannot accompany auth-method none. With no list, chap-md5 permits
only CHAP-MD5, ms-chap-v2 only MS-CHAPv2, pap permits CHAP-MD5 then PAP,
and none has an empty policy. Explicit ordering never makes PAP precede
an available CHAP method. Configuration validation and reload refuse invalid
lists rather than replacing malformed explicit input with a broader default.
The editor adds one allowed method per command. For example,
set l2tp authentication allow chap-md5, followed by
set l2tp authentication allow pap, permits both methods. A refusal prints
the commands for its transport, retaining permitted methods before adding the
peer's suggestion. Run them only if that additional method is intended;
changing the peer to accept an already permitted method needs no policy edit.
Proxy LCP is subject to the same policy. A proxied method outside the permitted
list, an unknown Auth-Protocol, or absent authentication when authentication is
required causes Ze to run normal LCP instead. Ze also renegotiates if the LAC's
Last-Sent receive MRU exceeds l2tp mru; an absent Last-Sent MRU means 1500.
The peer's Last-Received receive MRU remains the negotiated peer value.
The shared interface setup caps the transmit MTU at the smaller of that value
and the session's configured MRU, including when the peer omitted its option.
A peer receive MRU of 1500 or 9000 can therefore remain admitted under a
1492 local policy; authentication and IPCP still complete with a transmit
MTU of 1492.
Ze also runs normal LCP when a proxied MRU or Magic-Number is malformed: the wrong width, listed twice, or a Magic-Number of zero.
Ze never authenticates from the Proxy Authen AVPs. The Proxy Authen Name only seeds the displayed username until an authenticated identity replaces it. A session with no such identity (no authentication ran, or the peer authenticated with an empty name) keeps the LAC's unverified Name, and RADIUS accounting sends it as User-Name. A proxied CHAP or MS-CHAPv2 session gets a fresh Challenge from Ze. PAP is started by the peer, so a proxied PAP session waits 6 seconds for the peer's Authenticate-Request. A peer that sends none, because the LAC already finished PAP with it, gets a new round of LCP from Ze and authenticates again, so such a session comes up about 6 seconds later than one that needs no new round.
IPv6CP is enabled by default, so the configured MRU must be at least 1280.
For IPv4-only service, set l2tp ncp enable-ipv6cp false before using an
MRU from 68 through 1279. Validation checks the effective combination at
initial load and reload; a refused reload keeps the previous session policy.
The shared PPP driver also rejects a directly supplied cap that is too small
for its enabled protocols. The receive buffer capacity remains 1500.
When an otherwise valid peer negotiates an MRU smaller than 1280, Ze does not start IPv6CP or allocate an IPv6 address. IPv4 can still establish using the peer's smaller limit. An IPv6-only session fails with an MRU diagnostic rather than reporting usable service. A later LCP negotiation can restore IPv6 when the new directional MRUs support 1280: it starts from the configured MRU again, so a smaller value the peer Nakked in an earlier negotiation does not carry over. Peer MRUs smaller than 68 are Nakked to 68 instead of causing Ze to install an MTU larger than the agreed limit.
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 resolve
that slot for each authentication request. Applying a RADIUS configuration
switches subsequent requests to RADIUS; removing the auth radius block
returns them to the current local user table, including credentials changed
while RADIUS owned the slot. An in-process RADIUS plugin restart preserves
that local fallback.
l2tp-auth-local
Built-in static user list with PAP and CHAP-MD5 support.
Configured under the l2tp config tree:
l2tp {
auth {
local {
user alice {
password hunter2;
}
}
}
}
PAP and CHAP-MD5 require a configured user. Without one, the local handler
rejects authentication. Explicit no-auth sessions need no user entry;
allow-no-auth true must permit them.
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
Configure l2tp-auth-radius as an internal plugin. It refuses external startup
because authentication and accounting require the engine's process-local state.
The RADIUS handler accepts explicit no-auth sessions without an Access-Request. RADIUS remains available for accounting.
For sessions that require authentication, RFC 2865 Section 4.1 requires
User-Password, CHAP-Password, State, or authentication information defined by
an extension. The handler denies a request without a usable credential with
no usable credential. Section 5 forbids text of length zero, so an empty
PAP Peer-ID produces an Access-Request without User-Name rather than an empty
User-Name attribute.
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). The same holds for the framing: an Access-Accept whose Framed-Protocol
is anything but PPP (SLIP, ARAP, X.75, the other framings RFC 2865 lists, or
a value it does not define) is treated as an Access-Reject, and the session is
denied with unsupported Framed-Protocol, because L2TP carries PPP frames only. An Accept
with no Framed-Protocol is honored.
For MS-CHAPv2 the Accept must also carry a readable MS-CHAP2-Success, and one
that does not is denied with no MS-CHAP2-Success in Access-Accept. RFC 2759
completes the method with a 20-octet Authenticator Response the client checks,
so an Accept without one authorizes a session neither end can finish. The
attribute is not that value: RFC 2548 Section 2.3.3 defines it as an Ident
octet followed by the string S= and the response as 40 hexadecimal digits, so
ze strips the Ident and decodes the digits rather than passing the attribute
through.
A login whose handling meets a Ze defect (a Go panic) is denied with
internal error, and every other login is served as before. The panic is
logged at ERROR with the tunnel and session and the stack, counted in
ze_task_panics_total{component="radius-auth",task="request"}, and written as
a crash record that ze show crashes lists. Any count above zero is a Ze defect
to report with that record.
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. Their traffic counters measure the current network lifetime, excluding traffic from an earlier lifetime on the same PPP unit. Display-counter clears do not change them. RFC 2869 gigaword counters carry the upper 32 bits when nonzero. If the counter baseline or a later snapshot is unavailable, Ze logs the failure and omits the traffic counters instead of reporting zero.
The Acct-Session-Id is tunnelID-sessionID-boottag-sequence, and the Start,
Interim-Update and Stop records of one session carry the same one. The sequence
restarts with the process, so the boot tag keeps ids from repeating across a
restart: 24 hex digits, the Unix seconds read when the first session after
startup is accounted, then 64 random bits. On a box with no real-time clock that
starts sessions before NTP answers, two boots can read the same second, and the
random half still tells their ids apart.
PPP waits for address publication and the L2TP accounting callback to capture the initial raw interface counters before it enables forwarding. This includes a replacement network lifetime on the same PPP unit. Accounting-Start runs asynchronously; forwarding does not wait for a RADIUS server response. PPPoE accounting remains unconnected to subscriber events.
Each session's Start and Interim-Update records come from a task of its own. A
Ze defect (a Go panic) met in that task ends that session's Start and
Interim-Update records only: the session stays up, every other session accounts
as before, and the session's Stop record is still sent when it ends, because
RFC 2866 Section 2 ties the Stop to the end of service delivery. The panic is
logged at ERROR with the tunnel and session and the stack, counted in
ze_task_panics_total{component="radius-auth",task="accounting"}, and written
as a crash record that ze show crashes lists.
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 (a subscriber's LCP Terminate-Request reaches Stopped one Restart time after ze's Terminate-Ack, and ze then sends the CDN), 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.
| Attribute | Record types it accepts | What it feeds on the server |
|---|---|---|
calling-station-id (31) |
the three accounting records | the line the subscriber called from, and the key FreeRADIUS matches its IP pool rows on |
event-timestamp (55) |
the three accounting records | when the event happened on the NAS, where a server would otherwise use its own receive time |
acct-delay-time (41) |
the three accounting records | how long Ze has been trying to send the record, which a server subtracts to recover the event time |
acct-terminate-cause (49) |
accounting-stop |
why the session ended, which billing and churn reports read |
nas-port-id (87) |
the Access-Request and the three accounting records | the port text that joins one session's Access-Request to its accounting records |
framed-ip-address (8) |
the three accounting records | the address the session was given, which address-to-subscriber lookups read |
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;
accounting-port 1813;
shared-key radiussecret;
}
}
}
}
Each server entry has two destination ports. port (default 1812) receives
the Access-Request packets, and accounting-port (default 1813, the port RFC
2866 Section 3 assigns to accounting) receives every Accounting-Request: Start,
Interim-Update and Stop. A server that takes both kinds on one socket needs
accounting-port set to the same value as port, because without it the
accounting goes to 1813, where that server is not listening. The two ports share
the entry's address, shared key and failover position.
Ze signs every Access-Request with a Message-Authenticator, and by default it
discards any answer to one that carries no Message-Authenticator: this closes
BlastRADIUS (CVE-2024-3596), where an attacker forges an Access-Accept from an
Access-Reject. A server that predates 2024 and cannot sign its answers fails
every subscriber login until it is upgraded or its entry sets
require-message-authenticator false. Each discard steps
ze_radius_unsigned_response_discards_total{server} and logs a rate-limited
warning naming the server and the exact set command that accepts it, and
ze doctor reports such a server as doctor-radius-unsigned-response. A
require-message-authenticator value other than true or false is reported as
doctor-radius-invalid, with the command that sets it, and that server is not
probed. The leaf never applies to accounting.
docs/config-reference.md ("RADIUS answer signing") has both RADIUS leaves.
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.
| Check | Refused how |
|---|---|
Source address is a configured server |
Discarded |
| Request Authenticator matches the shared secret for that source | Discarded |
| Code is CoA-Request or Disconnect-Request | Discarded |
| Message-Authenticator, when the request carries one, is correct | Discarded |
| Event-Timestamp is within 5 minutes | Discarded when stale, NAK 404 when absent |
| CoA-Request carries no Service-Type | NAK 405 |
| Every attribute is one Ze supports | NAK 401 |
| Every supported fixed-length attribute (NAS-Port, Acct-Terminate-Cause and Event-Timestamp) has its length | NAK 407 |
| CoA-Request: every Filter-Id and Vendor-Specific is a rate or a CoS profile Ze applies, with at most one of each | NAK 407 |
| The identification attributes Ze evaluates match exactly one session (see below) | NAK 503 for none, NAK 508 for several |
| Every part of the requested change can be carried out (a CoS profile needs an access interface) | NAK 506 |
| Each authorization owner confirmed successful backend application | NAK 506 |
| Disconnect-Request: the matched session was torn down (NAK 504 when its teardown fails, or when the L2TP service stopped after the match) | NAK 504 |
Ze evaluates Acct-Session-Id, User-Name and NAS-Port as identification attributes in both CoA and Disconnect requests. Every occurrence narrows the match. User-Name must equal the session's user name and NAS-Port must equal its local session ID. A request carrying none of the three matches no session and gets NAK 503.
Other identification attributes, including NAS-Identifier and Framed-IP-Address, are unsupported on this listener and get NAK 401. Implementing an attribute for authentication or accounting does not imply support for its dynamic authorization semantics. No accepted identification attribute is ignored.
Before that match, Ze looks the Acct-Session-Id up in the subscriber registry, which compares the whole id. A hit must also match every User-Name and NAS-Port the request carries; NAS-Port is the local L2TP session ID or PPPoE session ID for that access type. A conflicting selector therefore cannot bypass the combination match through the registry. A matching Disconnect-Request for a PPPoE session still gets NAK 504, because PPPoE teardown from a Disconnect-Request is not connected yet.
For the L2TP fallback, Ze compares the complete Acct-Session-Id with the current
accountant's issued ID, tunnelID-sessionID-boottag-sequence. The registry can
hold a different internal session identifier, so an exact accountant ID still
selects its live session after a registry miss. The boot tag and sequence are
never discarded: an old ID cannot select a later incarnation merely because it
reuses the tunnel and session numbers. When no authoritative full ID is known,
an accounting-ID request gets NAK 503.
A CoA-Request prepares every requested control before changing either one. The listener then asks the shaper and class-of-service owners to apply through the command dispatcher and waits for their backend results before sending an ACK. A failed operation rolls the prepared owners back in reverse order. The shaper restores the complete state it last successfully programmed, including both rates and the queueing discipline; it does not claim to read arbitrary changes made outside that owner. A session with no confirmed shaping state is refused. The class-of-service owner captures the VLAN maps it reads from the interface backend. A pending rate transaction has a one-minute lease. Before the next admitted owner operation, the shaper rolls back an expired transaction; this also releases a prepare whose reply was lost. A failed restoration retains the original token and snapshot for retry. If restoration itself fails, the listener sends NAK 506 and records that failure; it cannot claim that the backend restored the old state. Notifications follow successful application and carry no acknowledgement authority. The command transport also reaches a forked owner, which refuses a change when it has no configured backend or confirmed session state; this does not establish support for shaping from a separate process.
show doctor on the running daemon retains a doctor-radius-coa-apply finding
after an owner fails to apply or restore a change. It includes the backend cause
and show l2tp shaper as the next inspection step. Repair the backend and retry
the authenticated request. A successful retry for the same session clears the
finding; session teardown and provider shutdown also clear it. Attribute refusals
handled before application do not raise that runtime finding.
A Disconnect-Request carries identification attributes, plus the Reply-Message, Class and Acct-Terminate-Cause the RFC 5176 Section 3.6 table admits. Ze reads no Vendor-Specific attribute in one, so it answers a Disconnect-Request that carries one with NAK 401.
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.
A retransmitted request is answered from a cache rather than applied twice. RFC 5176 Section 2.3 defines a duplicate by its source address, source UDP port and Identifier, and Ze also compares the Request Authenticator, which that section requires a retransmission to keep. A request from the same address and port with the same Identifier but another Authenticator is a new request: it is processed, and its response replaces the cached one. A request from another source port is never a duplicate, so two servers behind one NAT address do not get each other's answers; a NAT that changes the source port between retransmissions defeats the detection. The cache holds each response for five minutes, the Event-Timestamp window, and only an authenticated request that earned a response enters it.
A request whose handling meets a Ze defect (a Go panic) does not stop the
listener. When the request had passed every authentication check, Ze answers it
with a CoA-NAK or Disconnect-NAK carrying Error-Cause 506 (Resources
Unavailable), and the cache keeps that NAK for a retransmission; any other
packet is dropped, as one that fails those checks is. The listener then serves
the next request. The panic is logged at ERROR with the sender's address and
the stack, counted in ze_task_panics_total{component="radius-coa",task="request"},
and written as a crash record that ze show crashes lists. Any count above zero
is a Ze defect to report with that record.
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 coa-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.
The two special values of RFC 2865 Section 5.8 name no address:
255.255.255.254 ("the NAS should select an address for the user") and
255.255.255.255 (the user selects) leave the choice to the pool, so the
accounting records report the address the pool gave (RFC 2866 Section 4.1).
Framed-IP-Netmask is parsed into session metadata, but the current IPv4 IPCP
response has no netmask field to apply.
The IPCP DNS offered follows the pool's dns-source list. With none written,
an Access-Accept's MS-Primary-DNS-Server and MS-Secondary-DNS-Server (RFC 2548,
vendor 311 types 28 and 29) come first, then the pool's dns-primary and
dns-secondary, then the resolvers Ze learned on its WAN:
source radius configured received mode first-usable. Write
dns-source { source configured; } to offer only the pool's own servers, as
before this list existed. accel-ppp replaces each IPCP DNS option on its own,
so a RADIUS reply naming only the primary keeps its configured secondary;
under first-usable Ze offers the RADIUS primary alone, and under merge the
RADIUS primary followed by the pool's primary.
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.
| Direction | On the pppN interface |
Mechanism | Config leaf |
|---|---|---|---|
| Download, toward the subscriber | egress | the configured queueing discipline (tbf or htb) |
default-rate |
| Upload, from the subscriber | ingress hook | a token-bucket policer that drops traffic above the rate | upload-rate |
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.
For TBF, the download rate is a classless root rate; the shaper creates no
traffic class. HTB uses one default class with both rate and ceil set to the
download rate. Both paths convert configured bits per second to Linux's byte
rate. A 10mbit download therefore programs 1,250,000 bytes/s, not
10,000,000 bytes/s. The TBF burst is encoded in scheduler ticks, not bytes.
Invalid or unrepresentable rates are refused before replacing the root, so a
bad rate cannot install a download qdisc and then abort before upload policing.
See TBF root rates and bounds.
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
1s). It applies only when CQM is enabled, where it overrides the PPP
LCP echo interval used for sampling. An invalid or
non-positive value logs a warning and falls back to 1s.
Prometheus metrics
L2TP exposes metrics under the ze_l2tp_* and ze_radius_* namespaces.
Aggregate gauges
| Metric | Type | Description |
|---|---|---|
ze_l2tp_sessions_active |
gauge | Sessions in established state |
ze_l2tp_sessions_starting |
gauge | Sessions in negotiation |
ze_l2tp_sessions_finishing |
gauge | Sessions being torn down |
ze_l2tp_tunnels_active |
gauge | Active tunnels |
Per-session counters (labels: username, session_id, interface)
| Metric | Type | Description |
|---|---|---|
ze_l2tp_session_state |
gauge | FSM state as integer |
ze_l2tp_session_uptime_seconds |
gauge | Seconds since session creation |
ze_l2tp_session_rx_bytes_total |
counter | RX bytes on pppN interface |
ze_l2tp_session_tx_bytes_total |
counter | TX bytes on pppN interface |
ze_l2tp_session_rx_packets_total |
counter | RX packets on pppN interface |
ze_l2tp_session_tx_packets_total |
counter | TX packets on pppN interface |
CQM metrics (labels: username)
| Metric | Type | Description |
|---|---|---|
ze_l2tp_lcp_echo_rtt_seconds |
histogram | LCP echo round-trip time |
ze_l2tp_lcp_echo_loss_ratio |
gauge | Current 100s bucket echo loss ratio |
ze_l2tp_bucket_state |
gauge | CQM bucket state (established=0, negotiating=1, down=2) |
Relay counter (labels: kind, outcome)
| Metric | Type | Description |
|---|---|---|
ze_l2tp_relay_total |
counter | PPPoE relay decisions on a LAC. kind is service (a relay binding, decided at discovery) or realm (a relay-realm binding, decided at authentication). outcome is no-match (terminated locally), refused (a binding matched but the call could not start), placed (the incoming call was placed), and for realm also bridged or bridge-failed |
Session establishment counter (labels: proxy_lcp)
| Metric | Type | Description |
|---|---|---|
ze_l2tp_session_lcp_opened_total |
counter | Sessions whose LCP reached Opened for the first time, counted once per session (a later LCP reopen does not count again). proxy_lcp is the same value show l2tp session id <id> reports as proxy-lcp: none (the LAC sent no proxy LCP), accepted (LCP opened on the LAC's proxy LCP) or renegotiated (Ze negotiated LCP with the subscriber itself, because proxy-lcp renegotiate is set or the proxy LCP was malformed or outside the mru and authentication policy) |
PPP negotiation counters (labels: reason)
| Metric | Type | Description |
|---|---|---|
ze_ppp_ipv6cp_identifier_refusals_total |
counter | IPv6CP negotiations refused for want of a usable interface identifier |
ze_ppp_auth_failures_total |
counter | Authentication policy refusals before LCP Opened, with reason="auth-method-refused" |
The IPv6CP counter's 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.
| Reason | Meaning |
|---|---|
service-unnegotiated |
IPv6CP reached Opened with no negotiated peer identifier, so no IPv6 service was started for that session |
event-unnegotiated |
The same session's address was withheld from the session-up event, for the same reason |
suggestion-draw-failed |
Ze could not draw a valid identifier to suggest, and answered with a Configure-Reject rather than a Configure-Nak carrying a value it would refuse on receive |
This counter is shared with PPPoE subscribers, which run the same PPP driver.
The authentication counter also covers L2TP and PPPoE. It increments once when a required-auth session exhausts its permitted methods or the peer rejects Auth-Protocol. The warning and final session-down reason name the peer's suggestion, the permitted methods, and the operator configuration to change. No Accounting-Stop exists before authentication; use this counter and the log to diagnose those refusals.
Reader-loop error counters
A receiver goroutine that cannot classify a socket read error retries it with a growing delay, capped at 250ms, instead of spinning. Each swallowed error is counted, so a failing socket is visible on these counters without a profiler.
| Metric | Type | Description |
|---|---|---|
ze_l2tp_listener_read_errors_total |
counter | UDP read errors the L2TP listener's receiver goroutine swallowed and retried |
ze_ppp_reader_errors_total |
counter | Socket read errors a PPP reader goroutine swallowed and retried, labelled loop |
ze_ppp_reader_errors_total carries one series per reader: loop="ra" for
the IPv6 Router Advertisement listener, loop="dhcpv6" for the DHCPv6-PD
listener. Both run once per PPP session with a negotiated IPv6 interface
identifier, for L2TP and PPPoE subscribers alike.
The PPPoE discovery reader's own counter is listed in pppoe.md, because
it is PPPoE-specific.
RADIUS metrics (labels: server)
| Metric | Type | Description |
|---|---|---|
ze_radius_up |
gauge | Server reachability (1=up, 0=down) |
ze_radius_auth_sent_total |
counter | Access-Request packets sent |
ze_radius_acct_sent_total |
counter | Accounting-Request packets sent |
ze_radius_interim_sent_total |
counter | Interim-Update packets sent |
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).
| URL | Method | Purpose |
|---|---|---|
/l2tp |
GET | Session list with sortable columns |
/l2tp/<sid> |
GET | Session detail: state, PPP options, CQM chart, event timeline, disconnect |
/l2tp/<login>/samples |
GET | CQM buckets as columnar JSON (uPlot data shape) |
/l2tp/<login>/samples.csv |
GET | CQM buckets as CSV download |
/l2tp/<login>/samples/stream |
GET | SSE stream pushing new CQM buckets every 100s |
/l2tp/<sid>/disconnect |
POST | Disconnect session (requires reason form field; optional cause) |
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:
- Create L2TP tunnel via Generic Netlink (
L2TP_CMD_TUNNEL_CREATE) - Create L2TP session via Generic Netlink (
L2TP_CMD_SESSION_CREATE) - Create PPPoL2TP socket (binds session to L2TP kernel state)
- Open
/dev/ppp, attach channel (PPPIOCGCHAN,PPPIOCATTCHAN) - Create PPP unit (
PPPIOCNEWUNIT,PPPIOCCONNECT) - Kernel creates
pppNinterface - PPP negotiation runs over the
/dev/pppchannel fd
Teardown: reverse order. PPPoL2TP socket close triggers kernel session removal. Tunnel is removed after all sessions are gone.
When LCP restarts on the same transport, the PPP unit remains present. Ze removes its IPCP address using the installed local/peer pair before replacement negotiation. Linux creates the peer's connected route when the address is added and removes that route when the address is deleted. PPP does not issue a separate route deletion for this kernel-owned route. The next IPCP negotiation can reuse the address on the retained unit.
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:
policy {
match redistribute-bgp-l2tp {
family [ ipv4/unicast ipv6/unicast ];
}
}
redistribute {
destination bgp {
import l2tp {
filters [ redistribute-bgp-l2tp ];
final accept;
}
}
}
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:
| Field | Reload behaviour |
|---|---|
shared-secret |
Hot-apply; takes effect on new SCCRQs. Live tunnels keep the previously-negotiated state. |
hello-interval |
Hot-apply; new tunnels use the new interval. Live tunnels keep theirs. |
hello-retries |
Hot-apply to all reactors; affects the dead-peer deadline on the next tick. |
max-retransmit |
Hot-apply; new tunnels use the new count. Live tunnels keep theirs. |
max-tunnels |
Hot-apply at next admission decision. |
max-sessions |
Hot-apply at next admission decision. |
auth-method |
Hot-apply to new PPP sessions. |
allow-no-auth |
Hot-apply to new PPP sessions. |
proxy-lcp |
Hot-apply to new PPP sessions; a session already started keeps the policy and outcome it had. |
mru |
Hot-apply to new PPP sessions; established sessions retain their requested MRU. |
authentication/allow |
Hot-apply to new PPP sessions; existing sessions retain their policy. |
authentication/timeout |
Hot-apply to new PPP sessions. |
lcp/restart-timer, lcp/max-terminate, lcp/max-configure, lcp/max-failure |
Hot-apply to new PPP sessions. A running session retains all four admitted values, including across LCP renegotiation. |
authentication/reauth-interval |
Hot-apply to new PPP sessions. |
auth/local/user |
Apply replaces the local credential table, including removing users. Subsequent local authentication requests use it. |
auth/radius |
Apply replaces the RADIUS client and claims the shared authentication slot; removing the block restores local authentication. |
ncp/enable-ipcp |
Hot-apply to new PPP sessions. |
ncp/enable-ipv6cp |
Hot-apply to new PPP sessions. |
ncp/timeout |
Hot-apply to new PPP sessions. |
enabled flip |
Rejected with WARN. Restart to enable/disable. |
| Listener endpoint change | Rejected with WARN. Restart to rebind. |
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.
Authentication-provider verification stages the candidate without changing credential decisions. A rejected candidate leaves the active provider and credentials unchanged. If the transaction rolls back after apply, the plugins restore their previous configuration. Neither a credential change nor an authentication-provider switch disconnects an already authenticated subscriber.
Removing RADIUS stops new accounting admissions during apply, while existing accounting sessions continue until the whole daemon reload is accepted. A web listener bind failure or candidate-publication failure after plugin commit therefore leaves those sessions available for their eventual teardown. The hub restores the previous configuration through a new transaction; accounting keeps the original session identifiers and interim loops through that compensation.
After acceptance, Ze retires the remaining records asynchronously, with one ten-second network budget for Accounting-Stop attempts, then closes the retired client. Apply does not wait for those attempts. A later accepted reload also retires an unchanged pending removal, even when only another plugin's root changes. An older completion leaves a newer tentative apply intact; if that apply rolls back, Ze honours the acceptance of the restored state. Plugin shutdown still retires its own accounting and joins its retirement workers before restart. These rules concern removal of the RADIUS provider while L2TP remains running; teardown of the L2TP subsystem itself ends its subscriber sessions.
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.
max-retransmit sets that exhaustion budget: the number of retransmissions
of an unacknowledged control message before the tunnel and all its sessions
are cleared (RFC 2661 Section 5.8 recommends 5 and asks for it to be
configurable). The first retransmission waits 1s and each later one doubles
the wait up to 16s, so each retransmission above the default 5 adds 16s to
the time a silent tunnel takes to clear. The ~31s figures in this section
assume the default.
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 subsystemze.l2tp.metrics.poll-interval(default: 30s) -- kernel stats polling intervalze.l2tp.cqm.echo-interval-- echo probe interval for CQM RTT measurementze.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 fromskip-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 authenticationl2tp-auth-radius-- RADIUS authentication, accounting, CoA/DMl2tp-pool-- bitmap-backed IPv4 address poolsl2tp-shaper-- TC traffic shaping on pppN interfaces