Skip to main content

RADIUS AAA

RADIUS authentication, authorization, and accounting integration.

Overview​

AthenaBNG integrates with your existing RADIUS server for:

  • Authentication — Verify subscriber credentials
  • Authorization — Assign IP addresses, rates, session timeouts
  • Accounting — Track session usage for billing
  • Change of Authorization (CoA) — Modify session rates on-the-fly
info

AthenaBNG is a RADIUS client. You can point it at any RADIUS server (e.g., FreeRADIUS, Cisco ISE, Radiator), or run the companion Athena-RAD product (a FreeRADIUS + web UI) — including on the BNG itself with radius servers pointing at 127.0.0.1. Example FreeRADIUS configurations are provided in docs/examples/radius/.

Authentication​

PPPoE Authentication​

RADIUS Access-Request:

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

DHCP/IPoE Authentication​

RADIUS Access-Request:

  • User-Name — MAC address
  • Calling-Station-Id — MAC address
  • NAS-Port-Id — Circuit ID (VLAN interface name)
  • NAS-Identifier — BNG identifier

Authorization​

RADIUS Access-Accept attributes:

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

Speed plans​

Per-subscriber speed plans are delivered with the Athena-Rate-Down and Athena-Rate-Up VSAs (strings such as "250mbit"/"100mbit"; gbit/kbit units and plain bits-per-second integers are also accepted). The BNG parses these and applies per-subscriber CAKE shaping.

A subscriber returned without a rate attribute is left UNMETERED — no shaping is applied. This is the default. (The DHCP/IPoE path previously defaulted to 25/10 Mbps; it no longer does.)

These attributes are honored for both access types:

  • DHCP/IPoE (MAC authentication) — via abng-dhcpd's built-in RADIUS client.
  • PPPoE — via accel-ppp, which writes the RADIUS reply attributes to a radattr file (pppd-compat radattr-prefix); the ip-up hook then forwards the rate to abngd.

Accounting​

RADIUS Accounting-Request:

  • Acct-Session-Id — Session ID
  • Acct-Status-Type — Start, Stop, or Interim-Update
  • Acct-Input-Octets — Bytes received
  • Acct-Output-Octets — Bytes sent
  • Acct-Session-Time — Session duration in seconds

Change of Authorization (CoA)​

Your RADIUS server can modify session rates dynamically:

Acct-Session-Id = "abng-1709312400-1"
Athena-Rate-Down = "25mbit"
Athena-Rate-Up = "10mbit"

abngd receives CoA and:

  1. Looks up session by Acct-Session-Id
  2. Updates session rates
  3. Applies new rates to CAKE qdisc (no packet loss)
  4. Sends CoA-ACK to RADIUS server

Configuration​

radius:
  servers:
    - host: "10.255.0.10"
      port: 1812
      secret: "your-secret"
  nas_identifier: "AthenaBNG"
  nas_ip_address: "10.255.0.1"
  coa_enabled: true
  coa_port: 3799

See RADIUS Configuration for all options.

FreeRADIUS Setup​

Example configurations for FreeRADIUS are provided in docs/examples/radius/:

FileDescription
clients.confDefine the BNG as a RADIUS client
usersFlat-file subscriber database (testing / small deployments)
authorizeDefault site authorize section
sql-schema.sqlPostgreSQL schema for SQL-backed deployments

See the example README for quick-start instructions.

Running the RADIUS server on the BNG​

The Athena-RAD companion product can run on the BNG itself; point radius servers at 127.0.0.1. Two requirements apply whether the server is local or remote:

  1. VSA dictionary — FreeRADIUS must load the Athena VSA dictionary to parse and return Athena-Rate-Down/Athena-Rate-Up (and the other Athena VSAs). Athena-RAD ships this dictionary; for a stock FreeRADIUS install see Dictionary Installation.
  2. Allowed client — The BNG must be an allowed RADIUS client in clients.conf for whatever source IP it uses. For a local server that source IP is 127.0.0.1.

MAC / username case sensitivity​

FreeRADIUS matches User-Name case-sensitively, and the BNG sends client MAC addresses in lowercase. MAC-based subscriber entries must therefore be stored in lowercase. (Athena-RAD normalizes MAC entries automatically.)

RADIUS over the management VRF​

When the management interface is in a VRF, the BNG installs ip rule policy routing so RADIUS (and DNS) traffic to servers on the management subnet uses the management VRF table. Loopback servers (127.0.0.0/8) are explicitly not policy-routed — they use the host route — so a local 127.0.0.1 RADIUS server works even when the management interface is in a VRF.

Applying server changes​

A change to radius servers is applied to abng-dhcpd on commit by restarting it (it has no live reload); PPPoE/accel-ppp picks up the change via configuration re-render.

Dictionary Installation​

Install the Athena VSA dictionary on your RADIUS server:

sudo cp /opt/athena-bng/config/dictionary.athena /etc/freeradius/3.0/
echo '$INCLUDE dictionary.athena' | sudo tee -a /etc/freeradius/3.0/dictionary

Testing​

Test with radclient​

echo "User-Name = user1, User-Password = password123" | \
  radclient -x 10.255.0.10:1812 auth YourRadiusSecret

Send a CoA​

echo "Acct-Session-Id = 'abng-1709312400-42', Athena-Rate-Down = '200mbit', Athena-Rate-Up = '80mbit'" | \
  radclient -x 10.255.0.1:3799 coa YourCoaSecret

Monitoring​

Check RADIUS Logs​

sudo journalctl -u abngd -f | grep -i radius

Troubleshooting​

RADIUS Authentication Fails​

  1. Check RADIUS server is running: ping 10.255.0.10
  2. Test with RADIUS client: radtest testuser testpass 10.255.0.10 1812 my-secret
  3. Check shared secret matches in both clients.conf and AthenaBNG config
  4. Check RADIUS logs on server
  5. Check firewall allows UDP 1812

CoA Not Working​

  1. Check CoA is enabled: show configuration | match coa_enabled
  2. Check CoA port is correct: show configuration | match coa_port
  3. Check RADIUS server sends CoA to correct port
  4. Check firewall allows UDP 3799
  5. Check abngd logs: journalctl -u abngd -f

Sessions Not Getting RADIUS Attributes​

  1. Test RADIUS returns attributes: radtest testuser testpass 10.255.0.10 1812 secret
  2. Check attribute names match (case-sensitive)
  3. Check Athena VSAs are installed on RADIUS server
  4. Check abngd logs: journalctl -u abngd -f

Best Practices​

  1. Shared Secret — Use strong, unique secrets for each server
  2. Multiple Servers — Configure redundant RADIUS servers
  3. NAS Identifier — Use descriptive identifier (e.g., "BNG-Brisbane-01")
  4. NAS IP — Use a stable IP (management interface or loopback)
  5. CoA — Enable for dynamic rate changes
  6. Timeouts — Configure appropriate timeouts in RADIUS server
  7. Accounting — Enable accounting for billing and auditing
  8. Security — Protect RADIUS shared secrets in configuration management

Next Steps​