RADIUS Configuration

Configure RADIUS servers for authentication, authorization, and accounting (AAA).

Overview

The radius section configures how AthenaBNG connects to your RADIUS server for:

• Authentication — Verify subscriber credentials (PPPoE username/password, DHCP MAC)
• 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 the BNG's radius servers pointing at 127.0.0.1. See Running the RADIUS server locally.

Example FreeRADIUS configurations are available in docs/examples/radius/.

Speed plans (rate attributes)

Per-subscriber speed plans are delivered with the Athena VSAs Athena-Rate-Down and Athena-Rate-Up (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.

See the RADIUS Attributes Reference for the full Athena VSA list and accepted rate-string formats.

Configuration Options

servers

List of RADIUS servers (required when PPPoE or DHCP is enabled).

radius:
  servers:
    - host: "10.255.0.10"
      port: 1812
      secret: "your-secret"

Server Options

host

RADIUS server IP address or hostname (required).

servers:
  - host: "10.255.0.10"

Type: IPv4 address or hostname
Required: Yes
Constraints: Valid IP or resolvable hostname

port

RADIUS server port (optional).

servers:
  - port: 1812

Type: Integer
Required: No
Default: 1812
Constraints: Valid port number (1-65535)

secret

RADIUS shared secret (required).

servers:
  - secret: "your-secret"

Type: String
Required: Yes
Constraints: Non-empty string (change from default!)

Security: Store in secure configuration management system.

nas_identifier

NAS (Network Access Server) identifier (required).

radius:
  nas_identifier: "AthenaBNG"

Type: String
Required: Yes
Constraints: 1-64 characters

Purpose: Identifies this BNG to RADIUS servers.

CLI:

abng# set radius nas_identifier "AthenaBNG"

nas_ip_address

NAS IP address for RADIUS (optional).

radius:
  nas_ip_address: "10.255.0.1"

Type: IPv4 address
Required: No
Default: None
Constraints: Valid IPv4 address

Purpose: IP address reported to RADIUS server (for callbacks, etc.).

CLI:

abng# set radius nas_ip_address "10.255.0.1"

coa_enabled

Enable Change of Authorization (optional).

radius:
  coa_enabled: true

Type: Boolean
Required: No
Default: false
Valid values: true, false

Purpose: Listen for RADIUS CoA packets to modify session rates.

CLI:

abng# set radius coa_enabled true

coa_port

CoA listen port (optional).

radius:
  coa_port: 3799

Type: Integer
Required: No
Default: 3799
Constraints: Valid port number (1-65535)

Purpose: UDP port for receiving CoA packets from RADIUS server.

CLI:

abng# set radius coa_port 3799

Example Configurations

Single RADIUS Server

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

Multiple RADIUS Servers (Redundancy)

radius:
  servers:
    - host: "10.255.0.10"
      secret: "my-secret"
    - host: "10.255.0.11"
      secret: "my-secret"
  nas_identifier: "AthenaBNG"
  nas_ip_address: "10.255.0.1"
  coa_enabled: true
  coa_port: 3799

RADIUS with Custom Ports

radius:
  servers:
    - host: "10.255.0.10"
      port: 1812
      secret: "my-secret"
    - host: "10.255.0.11"
      port: 1813
      secret: "my-secret"
  nas_identifier: "AthenaBNG"
  nas_ip_address: "10.255.0.1"

Running the RADIUS server locally

The Athena-RAD companion product can run on the BNG itself. In that case point the BNG at the loopback address:

radius:
  servers:
    - host: "127.0.0.1"
      secret: "your-secret"
  nas_identifier: "AthenaBNG"

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 RADIUS Attributes Reference.
2. Allowed client — The BNG must be an allowed RADIUS client in the server's 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 to lowercase automatically.)

RADIUS over the management VRF

When the management interface is in a VRF, the BNG installs ip rule policy routing so that RADIUS (and DNS) traffic to servers on the management subnet uses the management VRF routing table.

Loopback servers (127.0.0.0/8) are explicitly not policy-routed — they use the host route — so a RADIUS server running locally at 127.0.0.1 works correctly even when the management interface is in a VRF.

Applying configuration changes

A change to radius servers is applied to abng-dhcpd on commit by restarting the service (it has no live reload). For PPPoE, accel-ppp picks up the change via configuration re-render. Expect a brief restart of abng-dhcpd when you commit a RADIUS server change.

Configuration via CLI

Add RADIUS Server

abng> configure
abng# set radius servers[0] host "10.255.0.10"
abng# set radius servers[0] secret "my-secret"
abng# commit

Set NAS Identifier

abng# set radius nas_identifier "AthenaBNG"
abng# commit

Enable CoA

abng# set radius coa_enabled true
abng# set radius coa_port 3799
abng# commit

Verification

View RADIUS Configuration

abng> show configuration | match "^radius:"
radius:
  servers:
    - host: 10.255.0.10
      port: 1812
      secret: my-secret
  nas_identifier: AthenaBNG
  nas_ip_address: 10.255.0.1
  coa_enabled: true
  coa_port: 3799

Test RADIUS Authentication

Use radclient or radtest from the BNG to verify your RADIUS server:

radtest testuser testpass 10.255.0.10 1812 my-secret

Expected output for a successful authentication:

Received Access-Accept Id 42 from 10.255.0.10:1812
    Framed-IP-Address = 203.0.113.100
    Framed-IP-Netmask = 255.255.255.255
    Athena-Rate-Down = "100mbit"
    Athena-Rate-Up = "40mbit"

Check RADIUS Logs

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

RADIUS Attributes

Authentication (Access-Request)

Attribute	Value	Purpose
User-Name	username or MAC	Subscriber identifier
User-Password	password	Subscriber password (PAP)
NAS-Identifier	nas_identifier	BNG identifier
NAS-IP-Address	nas_ip_address	BNG IP address
NAS-Port-Id	interface name	Circuit ID
Calling-Station-Id	MAC address	Subscriber MAC

Authorization (Access-Accept)

Attribute	Value	Purpose
Framed-IP-Address	IP address	Assigned IP
Framed-IP-Netmask	netmask	Subnet mask
Session-Timeout	seconds	Session timeout
Athena-Rate-Down	bandwidth	Download rate (Athena VSA)
Athena-Rate-Up	bandwidth	Upload rate (Athena VSA)

Accounting (Accounting-Request)

Attribute	Value	Purpose
Acct-Session-Id	session ID	Unique session ID
Acct-Status-Type	Start/Stop/Interim	Session event
Acct-Input-Octets	bytes	Bytes received
Acct-Output-Octets	bytes	Bytes sent
Acct-Session-Time	seconds	Session duration

Change of Authorization (CoA-Request)

Attribute	Value	Purpose
Acct-Session-Id	session ID	Session to modify
Athena-Rate-Down	bandwidth	New download rate
Athena-Rate-Up	bandwidth	New upload rate

Validation Rules

Field	Validation
servers[].host	Valid IPv4 address or hostname
servers[].port	Integer 1-65535
servers[].secret	Non-empty string
nas_identifier	1-64 characters
nas_ip_address	Valid IPv4 address
coa_enabled	Boolean
coa_port	Integer 1-65535
coa_secret	Non-empty, not a placeholder (required when coa_enabled)
coa_allowed_clients	IP address or CIDR per entry
coa_bind_address	Valid IP address
coa_vrf	VRF name (required when the bind address is VRF-enslaved)
status_server_interval	Integer 0-3600 (seconds; 0 disables probing)
dead_time	Integer 0-86400 (seconds a failed server is skipped)
vrf	VRF name, or none
source_address	Valid IP address

Sourcing RADIUS traffic (VRF and source address)

By default RADIUS follows the management interface's VRF, if it has one: abngd installs a policy rule per server so auth/accounting egress the management interface with the management source address. That is the right default when your RADIUS servers live on the management network.

It is the wrong answer when RADIUS is reachable over the upstream and the server's client list is keyed on a loopback. Two settings control this:

radius:
  vrf: "none"                  # unset = follow the mgmt VRF; "none" = global
                               # routing table; or name a specific VRF
  source_address: "160.30.37.3"   # originate RADIUS from this address

abng# set radius vrf none
abng# set radius source_address 160.30.37.3
abng# commit

• unset — follow the management VRF (historical behaviour; an upgrade does not move existing RADIUS traffic).
• none — do not policy-route RADIUS at all; it follows the global table, so it can egress the upstream and be sourced from a loopback.
• a VRF name — steer RADIUS into that VRF's table instead of the mgmt one.

source_address is the address the RADIUS server's client entry must match. It is applied to every RADIUS client on the box: abngd's own client, abng-dhcpd (auth and accounting) and accel-ppp (rendered as bind= in [radius], with ,bind-device= added per server when a VRF is named). Verify it on the wire with tcpdump -nn -i any 'udp port 1812' — every outbound packet should carry the configured source.

note

This affects only RADIUS. DNS resolvers continue to follow the management VRF.

Redundancy and server health

List every server under servers; they are tried in configured order.

abng# set radius servers 10.178.0.57 secret <secret>
abng# set radius servers 10.178.0.58 secret <secret>
abng# set radius status_server_interval 30
abng# set radius dead_time 300
abng# commit

Health probing. Each server is probed with a Status-Server request (RFC 5997) every status_server_interval seconds, carrying the mandatory Message-Authenticator. A server that answers is marked up; one that does not is marked down and logged:

WARN RADIUS server marked DOWN — it will be skipped until the dead time expires
     server=10.178.0.58:1812 dead_time_secs=300 reason="Status-Server probe failed…"
WARN RADIUS server pool health changed healthy=1 servers=2

Recovery is logged the same way, and losing the last server is an ERROR.

Skipping, not retrying. A server marked down is skipped outright for dead_time seconds — it is never contacted, so a subscriber never waits out its timeout before failover. When every server is down the request fails fast rather than stalling. This matters most for DHCP: a DISCOVER answered after the client has given up means the subscriber never binds.

Set status_server_interval to 0 to disable probing, in which case a server is only discovered to be down when a real request to it times out. Set dead_time to 0 to retry a failed server on every request (the old behaviour).

accel-ppp

PPPoE inherits the same behaviour through accel-ppp's own server list: the BNG renders every configured server plus fail-timeout=<dead_time>, which is what makes accel-ppp skip a failed server instead of retrying it on every session. accel-ppp has no Status-Server probe, so it recovers a server on the timeout rather than on a probe.

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

Troubleshooting

RADIUS Authentication Fails

Error: RADIUS authentication failed for user1

Solutions:

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
4. Check RADIUS logs on server
5. Check firewall allows UDP 1812

CoA Not Working

Error: CoA request rejected

Solutions:

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. Check RADIUS returns attributes: radtest testuser testpass 10.255.0.10 1812 my-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

Next Steps

• QoS Configuration — CAKE traffic shaping
• PPPoE Configuration — PPPoE server settings
• DHCP Configuration — DHCP/IPoE server settings
• Configuration Overview — All configuration sections