Scenario: a regional broadband provider whose subscribers get online through a BNG (broadband network gateway) over PPPoE or IPoE.
- Each subscriber has a plan: the plan sets the rate and the number of simultaneous sessions (1 for home, 4 for business).
- Subscribers in arrears are suspended and can no longer log in.
- Accounting records each session’s time, traffic and assigned IP.
- When the billing system suspends someone, they must be disconnected at once, but the billing system does not know which BNG they are on or what the session ID is, and does not have the BNG’s shared secret.
- Accounting must not be lost when the database has a brief problem.
Example directory: rradius-server/examples/scenarios/broadband/
| File | Contents |
|---|---|
rradius.toml | all_accept chain, CoA forwarding, accounting spool |
accounting.lua | Accounting: one row per session, recording the NAS and the IP |
session-limit.lua | The simultaneous session check |
migrations/1_schema.sql | plans, plan_reply, subscribers, accounting |
migrations/2_demo_data.sql | Two plans, three subscribers (one suspended) |
The flow
Login: BNG ──► sql handler (password, plan attributes) ──► session-limit.lua (any slots left?) ──► Accept + rate
Accounting: BNG ──► accounting.lua ──► accounting table
Disconnect: billing system ──Disconnect-Request (User-Name only)──► rradius
rradius looks up the accounting table with session_query ──► each session found goes to its BNG
Session limits and disconnects both read the same accounting table, so as long as accounting is right, both features are right.
Steps
1. Change the clients and start
For local testing, change the address of both bng-1 and billing to 127.0.0.1, and the coa_port of bng-1 to 3800 (otherwise requests forwarded to the BNG go back to rradius’s own port 3799).
cd rradius-server
./target/release/rradius-server --config examples/scenarios/broadband/rradius.toml
2. Login and session limits
S=bng-shared-secret-change-me
radtest home0001 home0001-password 127.0.0.1 0 $S
# Access-Accept: Mikrotik-Rate-Limit = "100M/100M", Acct-Interim-Interval = 300
echo 'User-Name=home0001,Acct-Session-Id=bb-1,Acct-Status-Type=Start,Framed-IP-Address=100.64.0.9' \
| radclient 127.0.0.1:1813 acct $S
radtest home0001 home0001-password 127.0.0.1 0 $S
# Access-Reject: the home plan allows one session; the log says too many sessions
radtest home0002 ... is always rejected; its status is suspended.
3. The billing system disconnects someone
The billing system sends only User-Name, signed with its own shared secret, to rradius’s port 3799:
echo 'User-Name=home0001' | radclient 127.0.0.1:3799 disconnect billing-coa-secret-change-me
rradius finds home0001’s open session (bb-1, on bng-1), adds Acct-Session-Id = bb-1 to the Disconnect-Request and forwards it to bng-1’s coa_port, then passes the BNG’s answer back to the billing system. Locally there is no real BNG answering on port 3800, so after the retries (1 second × 3 by default) a NAK comes back with Error-Cause 505. Sending it for a subscriber with no session gets NAK 503 (Session Context Not Found).
The configuration explained
Check the password first, then the slots
[auth]
policy = "all_accept"
[[auth.handlers]]
type = "sql"
user_query = "SELECT password FROM subscribers WHERE username = ? AND status = 'active'"
reply_query = "SELECT r.attribute, r.value FROM subscribers s JOIN plan_reply r ON r.plan = s.plan WHERE s.username = ?"
[[auth.handlers]]
type = "lua"
script = "session-limit.lua"
all_accept: every handler must accept. Whensqlrejects (wrong password, suspended), the script does not run; only aftersqlaccepts does the script check the slots.- Do not use
first_match: then a namesqlcannot find goes to the script, which checks only the slots, and accounts that do not exist get in without a password. reply_queryreturns attributes by plan. The example uses MikroTik’sMikrotik-Rate-Limit; BNGs from other vendors use their own attributes, such as Cisco’sCisco-AVPairor Juniper’sERX-*. Replace them inplan_replywith names and values your BNG understands.Acct-Interim-Interval = 300asks the BNG to report every 5 minutes.STALE_AFTERinsession-limit.luaandsession_queryin[radius.coa]both treat a session not reported for more than 900 seconds as gone (a BNG that crashes sends no Stop), so this interval must be shorter than 900 seconds. To change the 900 seconds, change both places together.
[auth.username]
lowercase = true
allowed = "[a-z0-9._@-]+"
HOME0001 and home0001 are the same person; otherwise each would get its own slots. accounting.lua lowercases names too.
session-limit.lua
SELECT p.max_sessions AS allowed,
(SELECT count(*) FROM accounting a
WHERE a.username = s.username AND a.stopped IS NULL AND a.updated > ?) AS online
FROM subscribers s JOIN plans p ON p.name = s.plan
WHERE s.username = ?
- A slot is counted only from Accounting-Start. Two logins arriving at the same moment may both pass; every approach that counts slots from accounting shares this limit.
- In a cluster, the local replica is read, which can lag slightly behind accounting just written.
auth_useris the name after the chain normalised it (lowercase).
accounting.lua
The same as in the quick start (Start, Interim and Stop write to the same row, it is safe to repeat, and a NAS reboot ends that NAS’s sessions), plus:
- The
nascolumn: where CoA must be sent, taken from theNAS-IP-AddressorNAS-IPv6-Addressthe NAS reports, or the client name when there is neither. - The
framed_ipcolumn: the IP assigned to the subscriber, kept when a later Interim-Update does not carry it. Support staff need it to answer “who had this IP just now”.
CoA forwarding
[radius.coa]
port = 3799
session_query = "SELECT nas, session_id FROM accounting WHERE username = ? AND stopped IS NULL AND updated > strftime('%s', 'now') - 900 ORDER BY updated DESC"
[[radius.coa.clients]]
name = "billing"
address = "10.20.0.5"
secret_file = "billing.secret"
[[radius.coa.clients]]are the systems allowed to ask for disconnects, kept apart from the list of NAS.- A request that names a NAS (
NAS-IP-Addressand so on) goes straight to that NAS; only a request with justUser-Nameis looked up withsession_query. The query has a single?, filled withUser-Name, so the billing system cannot inject SQL. - Replies: ACK when any BNG answers ACK; one of the NAKs when all refuse; NAK 503 when no session is found; 502 when none of the NAS found is a configured client; 505 when the query fails or no BNG answers. At most 32 sessions per subscriber are forwarded.
- The BNG must have CoA (RFC 5176) enabled and accept rradius’s source address, on the client’s
coa_port(3799 by default; some devices use 1700). - Requests with only
User-Nameare convenient with many BNGs, but the lookup depends on accounting: if the BNG sent no Start, nothing is found. - To disconnect people yourself from a script or the command line, see
send_disconnectand therradius-server disconnectcommand in usage section 4.8.
The accounting spool
[radius.accounting_spool]
dir = "spool"
When the database cannot take writes (the cluster has lost its majority, or a timeout), accounting is first written to a local directory and the BNG gets its reply; once things recover, accounting.lua replays it. The script is safe to repeat, so replaying never counts twice. Spool files contain personal data, and the directory’s mode is 0700; if the disk fails, whatever has not been replayed is lost. See usage section 2.11.
- Only failures caused by the database are spooled. The script’s own errors, or a returned
'reject', are not spooled and get no reply, just as without this section, so errors are not hidden. - The script can tell when it is replaying: the global variable
replayedistrue, andAcct-Delay-Timealready includes the time spent in the spool. - Until recovery, features that depend on accounting cannot see this data: session limits and disconnects both read the
accountingtable.rradius_acct_spool_bytesabove 0 means there is a backlog; alert on it. query_timeout_msdecides how long before spooling. Without a cluster majority, a write fails only after[lua] query_timeout_ms(5 seconds by default), and the BNG gets no reply meanwhile. Lower it when that is longer than the BNG’s retransmission interval.- Replay speed (
replay_window): by default one record is replayed at a time, in write order, at a few thousand per second. After a long outage with a large backlog,replay_window = 8replays several at once; but Start, Interim and Stop of the same session may then run at the same time or out of order. The exampleaccounting.luawrites all three to the same row and keeps the larger value of each number, so order does not matter; if your script relies on order, keep it at 1. - When replay gets stuck: for how to read
rejected.logand.corruptfiles, see chapter 20.
Before going live
- Where do plans and subscribers come from? The demo subscribers in the example come from a migration file. The example configuration already has
[accounts], so subscribers can be managed withrradius-server user add|passwd|disable(disabling setsstatustosuspended); the billing system can also call these commands to stay in step, see chapter 19. - IP address pools: in the example, the BNG assigns addresses itself. To assign them from RADIUS, see
examples/ip-pool.lua, which guarantees across the whole cluster that an address is never given to two people at once. - Time quotas and allowed hours: see
examples/quota-and-hours.lua. - The
accountingtable keeps growing; for removing old data see chapter 19. - For several BNGs and several rradius servers, see chapter 8. Every BNG must be able to receive CoA from every rradius node.
- When the BNG is behind NAT or across an untrusted network, it connects in over RadSec, and disconnects travel over the connection it opened; see chapter 10.
- When subscriber data lives in the billing system and you do not want a copy, each login can ask the billing system’s API; see chapter 18.
Common problems
| Symptom | Cause |
|---|---|
| A subscriber who went offline is still told “too many sessions” | The BNG sent no Stop (a crash, a lost link), so it takes 900 seconds; or the BNG sent no Accounting-On when it rebooted |
| A disconnect gets 503 | No open session found: the BNG sent no accounting, the name differs in case, or nothing was reported for more than 900 seconds |
| A disconnect gets 505 | The BNG did not answer: CoA not enabled, wrong port, rradius’s source address not accepted, or a different shared secret |
| A disconnect request gets no reply at all | The sender is not in [[radius.coa.clients]] or the secret is wrong; counted in rradius_coa_relay_discarded_total |