Skip to main content

PPPoE Termination

PPPoE session termination via accel-ppp integration.

Overview​

AthenaBNG terminates PPPoE sessions using accel-ppp, a high-performance PPPoE server. Each subscriber establishes a PPP session over Ethernet, which is then used to negotiate IP configuration via IPCP.

accel-ppp is managed by abngd: it is unmasked and auto-started at boot when pppoe is enabled, and its config is rendered on commit. RADIUS authentication supports PAP, CHAP, and MS-CHAP (v1/v2). The rendered config does not emit a literal wildcard service-name, so an empty client Service-Name is accepted.

PPPoE sessions appear in show subscribers via accel-ppp's pppd-compat module — see IP-Up Hook below.

PPPoE Protocol​

Discovery Phase​

  1. PADI (PPPoE Active Discovery Initiation) — Subscriber broadcasts to find access concentrators
  2. PADO (PPPoE Active Discovery Offer) — BNG responds with offer
  3. PADR (PPPoE Active Discovery Request) — Subscriber requests session
  4. PADS (PPPoE Active Discovery Session-confirmation) — BNG confirms session

Session Phase​

Once session is established:

  1. LCP (Link Control Protocol) — Negotiate PPP link parameters
  2. IPCP (IP Control Protocol) — Negotiate IP configuration
  3. Data Transfer — Subscriber traffic flows
  4. PADT (PPPoE Active Discovery Terminate) — Session termination

Session Establishment​

1. VLAN Interface Creation​

When PADI is received:

  • abng-demux creates VLAN interface (e.g., eth1.111.500.100)
  • Notifies abngd of new interface
  • abngd tells accel-ppp to bind to interface

2. PPPoE Negotiation​

accel-ppp:

  • Sends PADO with the AC name (no literal wildcard service-name is configured, so an empty client Service-Name is accepted)
  • Receives PADR from subscriber
  • Sends PADS to establish session
  • Creates PPP interface (e.g., ppp0)

3. LCP Negotiation​

PPP Link Control Protocol:

  • Negotiate MTU/MRU (default 1492)
  • Enable LCP echo for keepalive (default 30s interval, 3 failures)
  • Agree on authentication method (PAP, CHAP, or MS-CHAP v1/v2)

4. IPCP Negotiation​

IP Control Protocol:

  • Subscriber requests IP address
  • accel-ppp requests from RADIUS
  • RADIUS returns Framed-IP-Address
  • IPCP assigns IP to subscriber

5. IP-Up Hook​

When IP is assigned, accel-ppp's pppd-compat module triggers the ip-up hook. This is what makes PPPoE sessions show up in show subscribers:

  • accel-ppp writes the RADIUS reply attributes to the radattr file <radattr-prefix>.<ifname> (configured radattr-prefix=/run/accel-ppp/radattr; the accel-ppp unit provides /run/accel-ppp via RuntimeDirectory=accel-ppp)
  • accel-ppp runs the ip-up hook /opt/athena-bng/etc/hooks/pppoe-up.sh
  • The hook reads Athena-Rate-Down / Athena-Rate-Up from the radattr file and calls abng-notify with the session details and rates
  • abngd registers the session (so it appears in show subscribers and gets a /32 host route) and applies QoS

On teardown, the ip-down hook (/opt/athena-bng/etc/hooks/pppoe-down.sh) calls abng-notify to clear the session from abngd.

Configuration​

pppoe:
  enabled: true
  ac_name: "AthenaBNG"
  mtu: 1492
  mru: 1492
  lcp_echo_interval: 30
  lcp_echo_failure: 3

RADIUS Integration​

Authentication​

RADIUS Access-Request:

  • User-Name — Subscriber username
  • User-Password — Subscriber password (PAP)
  • NAS-Identifier — "AthenaBNG"
  • NAS-Port-Id — VLAN interface name (Circuit ID)

Authorization​

RADIUS Access-Accept:

  • Framed-IP-Address — Assigned IP address
  • Framed-IP-Netmask — Subnet mask (usually 255.255.255.255)
  • Session-Timeout — Session timeout in seconds
  • Athena-Rate-Down — Download rate (optional)
  • Athena-Rate-Up — Upload rate (optional)

The rate attributes are optional. If RADIUS returns no rate, the session is left unmetered — there is no implicit default rate.

QoS Integration​

When a session is established and RADIUS supplied rate attributes, the rate (passed from the ip-up hook via the radattr file) is applied as per-subscriber CAKE shaping:

  1. CAKE qdisc on the PPP interface for the download rate (egress shaping)
  2. A per-session IFB device for the upload rate (ingress shaping)

No rate = unmetered. A session whose RADIUS reply carries no rate attribute is left unshaped; there is no implicit default rate.

Monitoring​

View PPPoE Sessions​

abng> show subscribers pppoe

View Session Details​

abng> show subscribers detail 1

Check accel-ppp Status​

sudo systemctl status accel-ppp

Monitor accel-ppp Logs​

sudo journalctl -u accel-ppp -f

Troubleshooting​

Sessions Not Appearing​

  1. Check PPPoE is enabled: show configuration | match pppoe
  2. Check VLAN demux is enabled: show configuration | match demux
  3. Check VLAN interfaces are created: show vlans
  4. Check RADIUS is reachable: radtest testuser testpass <radius-ip> 1812 <secret>
  5. Check accel-ppp logs: journalctl -u accel-ppp -f

Sessions Disconnecting Frequently​

  1. Check LCP echo settings: show configuration | match lcp_echo
  2. Check network stability: ping -c 100 <upstream-router>
  3. Check RADIUS timeout
  4. Check accel-ppp logs for errors

Sessions Not Getting IP​

  1. Check RADIUS is configured: show configuration | match radius
  2. Test RADIUS: radtest testuser testpass <radius-ip> 1812 <secret>
  3. Check RADIUS returns Framed-IP-Address
  4. Check abngd logs: journalctl -u abngd -f

Best Practices​

  1. AC Name — Use descriptive name (e.g., "AthenaBNG-Brisbane")
  2. MTU/MRU — Use 1492 for standard PPPoE
  3. LCP Echo — Use 30s interval with 3 failures for standard keepalive
  4. RADIUS — Always configure RADIUS before enabling PPPoE
  5. QoS — Enable QoS for per-subscriber rate limiting
  6. Monitoring — Monitor session count and churn rate

Next Steps​