Guide

PPPoE Access Concentrator

Ze implements an RFC 2516 PPPoE access concentrator for direct-attach subscriber access. PPPoE is the alternative to L2TP: subscribers connect over Ethernet to the BNG without an intermediate LAC/LNS tunnel.

Architecture

PPPoE uses the same transport-agnostic PPP Driver as L2TP. The PPPoE component handles discovery (PADI/PADO/PADR/PADS/PADT) and creates kernel PPPoE sessions via AF_PPPOX. The resulting /dev/ppp file descriptors feed into the PPP Driver, which runs LCP, authentication, and IPCP/IPv6CP through the shared state machines.

PPPoE applies RFC 2516's transport restrictions to LCP: neither role requests ACCM, ACFC or FCS Alternatives, and both reject peer requests for them. These restrictions do not change L2TP negotiation. A PADT matching the session ID and both MAC addresses ends the PPPoE transport immediately; PPP termination packets are not sent afterwards. Local teardown also stops PPP before sending PADT. A subscriber's LCP Terminate-Request is answered with a Terminate-Ack, and one configured Restart time later (3 seconds by default) the AC sends the PADT, with User Request as the accounting cause; a new LCP Configure-Request arriving before the PADT completes is still answered.

Subscriber CPE
    |
    | Ethernet (ethertype 0x8863 discovery, 0x8864 session)
    v
PPPoE Subsystem (internal/component/l2tp/pppoe/)
    |
    | StartSession{ChanFD, UnitFD, AccessInterface, SubscriberMAC, ...}
    v
PPP Driver (internal/component/l2tp/ppp/)
    |
    v
Auth/Pool/Shaper plugins (shared with L2TP)

Configuration

pppoe {
    enabled true
    ac-name "my-bng"
    service-name "internet"
    auth-method chap-md5
    cookie-timeout 5
    max-sessions 65535
    max-sessions-per-mac 8
    padi-rate-limit 100
    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
    }
    interface eth0 {
    }
    interface eth0.100 {
        service-name "vlan100"
        max-sessions 1000
        max-sessions-per-mac 2
    }
}

See configuration guide for all settings.

The access concentrator shares its LCP settings and defaults with the L2TP server. Each counter accepts 1 through 255. A silent subscriber receives exactly max-configure Configure-Requests before the session ends; the defaults give ten requests over 30 seconds. max-terminate bounds unanswered Terminate-Requests, and max-failure bounds Naks sent without a Configure-Ack before unacceptable options are rejected. The Restart timer controls each wait.

Discovery runs only when enabled is true and the block lists at least one interface. A pppoe block with no interface entry answers no PADI.

Changing the configuration

A committed change to the pppoe block applies to the running access concentrator at once, with no restart:

Change Effect
ac-name, service-name, cookie-timeout, padi-rate-limit, max-sessions, max-sessions-per-mac, auth-method, authentication-allow, allow-no-auth Apply to the next PADI and the next admitted session. A session already up keeps the terms it was admitted under. A lowered max-sessions refuses new sessions and ends none. AC-Cookies already handed out stay valid
lcp/restart-timer, lcp/max-terminate, lcp/max-configure, lcp/max-failure Apply to newly admitted PPP sessions. A running session retains its timing and limits, including during LCP renegotiation
An added interface Served at once. An interface that does not exist refuses the commit, naming it and the delete pppoe interface <name> that undoes it
A removed interface Stops answering PADI. Each of its sessions gets a PADT and its PPP session is stopped
enabled true, or a first interface Starts discovery, even when the daemon booted with PPPoE disabled
enabled false, or no interface left Ends every session with a PADT and stops discovery

Subscriber authentication

auth-method is the PPP Auth-Protocol the access concentrator puts in its own LCP Configure-Request: chap-md5 (the default), pap, ms-chap-v2, or none. With pap and its derived default policy, the first Configure-Request offers CHAP-MD5, and PAP is offered only after the subscriber sends a Configure-Nak that suggests PAP (RFC 1334 Section 2: an implementation that includes CHAP MUST offer it before PAP). An explicit [pap] policy offers PAP directly.

none requires allow-no-auth true. The daemon rejects none without that opt-in, and rejects an unknown authentication method, with parse pppoe config: ....

Leaf Default Values Description
auth-method chap-md5 none, pap, chap-md5, ms-chap-v2 Auth-Protocol advertised in the AC's LCP Configure-Request (RFC 1661 Section 6.2)
authentication-allow Derived from auth-method ordered set of pap, chap-md5, ms-chap-v2 Permitted methods; must include auth-method, cannot include none or accompany auth-method none
allow-no-auth false boolean Admit a subscriber whose LCP ends with no Auth-Protocol negotiated

The default matches the L2TP LNS default, so an operator who configures a credential for one transport gets the same treatment on the other. Explicit no-auth sessions need no local user entry.

The flat authentication-allow leaf sits beside auth-method:

pppoe {
    auth-method chap-md5
    authentication-allow [chap-md5 ms-chap-v2 pap]
}

Absent or empty lists derive [chap-md5] for chap-md5, [ms-chap-v2] for ms-chap-v2, [chap-md5 pap] for pap, and no methods for none. Lists are ordered sets: duplicate entries do not add a second attempt. The configured CHAP variant is offered first; remaining CHAP variants follow written order, before PAP regardless of its written position. Changes affect newly admitted sessions only, not an existing session's policy.

A Configure-Nak selects an untried permitted method; an unlisted, unknown or already-tried suggestion advances through the remaining methods without repeating an offer. A PAP suggestion cannot skip an untried CHAP variant. A valid Configure-Reject removes Auth-Protocol for the whole negotiation, rather than trying a different method. Required authentication ends LCP with Terminate-Request before Opened when no acceptable method remains or the option is rejected, followed by PADT when termination completes. No PAP exchange or auth-handler request occurs on that refusal. Explicit allow-no-auth true instead permits the no-wire-auth handler after the option is dropped.

The editor accepts one method per command. To permit PAP explicitly while retaining CHAP-MD5, use set pppoe authentication-allow chap-md5, followed by set pppoe authentication-allow pap. Refusal messages print only PPPoE repair commands for a PPPoE subscriber. To repair an invalid explicit list by restoring the method-derived default, use delete pppoe authentication-allow.

Migration: CHAP-MD5 and MS-CHAPv2 no longer implicitly permit other methods. If subscribers previously relied on PAP fallback, explicitly include both the configured method and pap. Do not enable allow-no-auth as a substitute for permitting the authentication method those subscribers need. PPPoE's MRU ceiling remains fixed at 1492; there is no PPPoE MRU setting. The installed IP interface MTU is at most 1492, including when the peer omits its MRU option and thus advertises the PPP default of 1500. A smaller negotiated peer MRU still lowers the transmit MTU. The kernel receive buffer keeps its required 1500-octet capacity.

The credential comes from the same auth plugins the L2TP LNS uses. Configure a local user, or a RADIUS server:

l2tp {
    auth {
        local {
            user alice {
                password "s3cr3t"
            }
        }
    }
    pool {
        ipv4 {
            gateway 10.20.0.1
            start 10.20.0.2
            end 10.20.0.254
        }
    }
}

The l2tp block here configures the shared BNG plugins, not an L2TP listener: l2tp-auth-local verifies the credential and l2tp-pool supplies the IPCP address. A PPPoE-only BNG needs neither l2tp enabled nor an L2TP server. The IPCP DNS a PPPoE subscriber gets follows the pool's dns-source list, as on L2TP: with none written, RADIUS's MS DNS servers, then the pool's dns-primary and dns-secondary, then the resolvers Ze learned (docs/guide/l2tp.md, "IP address pool").

The PPP auth handler 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. A box with local users and no RADIUS block therefore authenticates against those users, on PPPoE and on L2TP.

PPPoE client keepalive and redial

The client's lcp restart-timer sets the Configure-Request retransmission interval in milliseconds (100 to 60000, default 3000). lcp max-configure sets the unanswered request budget (1 to 255, default 10). The first request counts. A valid negotiation reply renews the budget where the LCP state machine requires it. A timing-only reload keeps the current session and its LCP settings, including during renegotiation. The next session uses the new settings. A separate convergence deadline, twice the configured timer times the request budget, bounds a peer that repeatedly Naks each request. The lcp max-failure leaf limits consecutive Configure-Naks sent to the peer (1 to 255, default 5). Further unacceptable peer options receive a Configure-Reject containing the original options, and a successful Configure-Ack renews the Nak budget. It follows the same session snapshot and reload behavior as the other LCP settings.

A pppoe-client entry detects a dead access concentrator with LCP Echo-Requests. keepalive interval sets the seconds between two requests (default 10), and keepalive failures sets how many unanswered requests in a row end the session (default 3), so the default detection time is about 30 seconds. These play the part of pppd's lcp-echo-interval and lcp-echo-failure, with one difference in counting: Ze ends the session when it sends the request that reaches failures, while pppd ends it at the next tick after its Nth unanswered request. pppd's lcp-echo-failure 3 therefore matches keepalive failures 4. After a session ends or a dial fails, the client waits before it dials again: the first wait is reconnect delay-min (default 1 second), and each further failure doubles it up to reconnect delay-max (default 60 seconds). A change to any of these leaves keeps the running session up: the next session and the next wait use the new values. Every leaf and its range is listed in Configuration, "PPPoE Client".

The access-reconnect topology scenario proves the redial: after the LNS drops the session and RADIUS hands out a new address, the CPE comes back with it, the IKE SA follows it and masquerade uses it.

PPPoE client IPv6

ipv6 enabled true on a pppoe-client negotiates IPv6CP beside IPCP. The client installs the link-local address formed from the negotiated interface identifier on the session device. An access concentrator that rejects or ignores IPv6CP leaves the IPv4 session up. The same container takes accept-ra, autoconf and forwarding, written to the session device each time a session creates it, and a dhcpv6 block that runs the DHCPv6 client on the session device. Ze refuses the other ipv6 leaves while enabled is not true. For a router that learns its default route from the access concentrator's Router Advertisements and asks for a delegated /56:

pppoe-client pppoe0 {
    source-interface eth2
    authentication { username user@isp.example; password secret; }
    ipv6 {
        enabled true
        accept-ra 2
        autoconf true
        forwarding true
        dhcpv6 { enabled true; pd { length 56; } }
    }
}

A PPP device has no hardware address, so the DHCPv6 client builds its DUID-LL and IAIDs from the source interface unless dhcpv6 duid is set. The delegated prefix is published as a lease on pppoe0.

A LAN unit takes a /64 from it with ipv6 delegated-prefix, named after the pppoe-client:

interface ethernet eth1 {
    unit 0 {
        ipv6 {
            forwarding true
            delegated-prefix pppoe0 { subnet-id 1; interface-identifier ::1; }
            router-advertisement { enabled true; }
        }
    }
}

With 2001:db8:aa00::/56 delegated, eth1 holds 2001:db8:aa00:1::1/64. The subnet id sits in the bits between the delegated length and 64, so a /56 holds ids 0 to 255; interface-identifier defaults to ::1. The address takes the lifetimes that remain of the delegation, and a renew refreshes them (RFC 9915 Section 6.3). When the lease ends the address is removed. Config verify refuses a subnet-id the pd length cannot hold, two units taking the same id from one source, and a source that is not a pppoe-client asking for a prefix. A server may delegate a longer prefix than the hint; when it is too small for the id, Ze logs an error naming the unit and the fix, and the unit gets no /64.

With router-advertisement enabled, the unit advertises the /64 for SLAAC and a Route Information option for the whole delegated prefix, both bounded by what remains of the delegation. Its Router Lifetime is the configured one only while pppoe0 holds an IPv6 default route and the unit has a prefix, and an advertisement with Router Lifetime 0 leaves at once when either is lost (RFC 7084 G-4, G-5, L-4). While a LAN unit holds space from the prefix, the client never releases it.

show interface pppoe-client lists, under delegated-prefixes, each prefix the client's lease holds with its valid-lifetime and preferred-lifetime: the whole seconds that remain when you ask, 4294967295 meaning infinite. show interface delegated-prefix answers one row per delegated-prefix entry of an enabled unit, naming the interface, unit, source and subnet-id. A unit whose state is installed also carries its address, the derived /64 as prefix, the whole delegated prefix and the lifetimes that remain. The other states carry a reason: waiting (the source holds no delegated prefix), too-small (the delegated prefix cannot hold the subnet id, with the fix) and not-installed (the address install failed, and the log names why).

The interop scenarios pppoe-ipv6cp-ze-client and pppoe-ipv6cp-rejected-ze-client prove this against accel-ppp: the first the negotiated link-local address, the RA default route and SLAAC, the second an access concentrator that rejects IPv6CP (docs/labs/pppoe-interop.md).

interface pppoe-client <name> ipv6cp restart-timer sets the IPv6CP retry wait in milliseconds, from 100 to 60000, default 3000. It starts after each Configure-Request and is independent of IPCP's timer. Ten unanswered requests stop IPv6CP while IPv4 can continue. A timing-only reload keeps the established session and changes the next session's timing.

Interoperability

Docker lab scenarios run Ze in each PPPoE role; the table names the two baseline ones and the CPE reconnect, and docs/labs/pppoe-interop.md lists every scenario. ./le test deployment docker-pppoe-accel runs them all.

Scenario Ze role Peer Proves
01-pppoe-chap-ipv4 client accel-ppp Discovery, LCP, CHAP-MD5, the IPCP address on the kernel device pppoe0, named after the pppoe-client key, a ping to the AC gateway through the session, and a clean teardown
pppoe-named-device-reconnect-ze-client client accel-ppp A home CPE: the device is pppoe0 and the client creates no pppN; a static default next { interface pppoe0 } reaches the kernel through it; LAN traffic masqueraded on output-interface "pppoe0" crosses it and the nft counter rises; after accel-ppp terminates the session, a new pppoe0 comes up and the route and NAT work again with no reload
02-ze-ac-pppd-client access concentrator pppd 2.5.5 with the rp-pppoe plugin Discovery, LCP demanding CHAP-MD5, the credential accepted, an IPCP pool address, ICMP across the session, and a wrong password refused before IPCP

./le test qemu pppoe-accel runs the client half in QEMU, and ./le test qemu pppoe runs the access concentrator's test/pppoe/ suite on Ze's runtime kernel. The stock Alpine kernel has no CONFIG_PPPOE.

CLI Commands

Command Description
show pppoe Subsystem summary
show pppoe sessions List active sessions
show pppoe session <sid> Show one session
show pppoe statistics Per-interface counters
show pppoe interfaces Configured access interfaces

Security

  • AC-Cookie: HMAC-SHA256 cookie in PADO/PADR prevents PADR flooding. Cookies expire after cookie-timeout seconds (default 5).
  • PADI rate limiting: Per-source-MAC rate limit prevents discovery flooding. Configurable via padi-rate-limit (default 100/s).
  • Per-MAC session cap: A MAC address holding max-sessions-per-mac sessions is refused a further PADR (PADS error, no allocation). Configurable via max-sessions-per-mac (default 8), global and per-interface. The AC-Cookie proves a MAC completed a PADI/PADO round trip, not that a given PADR is fresh, so this cap is the actual bound on how many sessions a replayed or forged PADR can make the AC allocate.
  • Service-Name filtering: Only PADIs matching configured service names are accepted. Empty list means accept any.
  • MAC binding: Sessions are bound to the subscriber MAC from PADR. PADTs from other MACs are rejected.

Metrics

  • ze_pppoe_discovery_refusals_total -- discovery packets Ze refuses, labelled by reason. A PADI refused for an unoffered service name gives no reply on the wire (RFC 2516 Section 5.2), so this counter is the only way to see that refusal without a packet capture.
Reason Meaning
rate-limited The PADI rate limiter dropped a packet from this source MAC
service-name-mismatch The requested service does not match any configured service-name
service-name-missing A PADR carried no Service-Name tag (RFC 2516 Section 5.3)
cookie-invalid A PADR's AC-Cookie was missing, malformed, or expired
session-id-exhausted The interface's usable session ID space (1 to 65534) is full; 0 and 65535 are reserved
per-mac-cap-reached The PADR's source MAC already holds max-sessions-per-mac sessions
  • ze_ppp_ipv6cp_identifier_refusals_total -- IPv6CP negotiations refused for want of a usable interface identifier, labelled by reason. Emitted by the shared PPP driver, so it counts L2TP and PPPoE subscribers alike; the three reasons are listed under "PPP negotiation counters" in l2tp.md.

  • ze_pppoe_discovery_read_errors_total -- discovery socket read errors the discovery reader swallowed and retried, after ruling out the socket being closed. A separate counter from the refusal series above: a refusal is a decision about a well-formed read, this one is the socket itself failing to read at all. One AF_PACKET socket serves every configured access interface, so this counter is not split by interface.

  • ze_ppp_reader_errors_total -- socket read errors a PPP reader goroutine swallowed and retried, labelled loop (ra, dhcpv6). Emitted by the shared PPP driver, so it counts L2TP and PPPoE subscribers alike; listed under "Reader-loop error counters" in l2tp.md.

Concurrent Operation

PPPoE and L2TP run concurrently on the same daemon. Both share the same PPP Driver, auth handlers, IP pools, and shaper plugins. The PPP component distinguishes sessions by TunnelID (ifindex for PPPoE, tunnel ID for L2TP) and SessionID.