7. Broadband Provider (PPPoE/IPoE)

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/

FileContents
rradius.tomlall_accept chain, CoA forwarding, accounting spool
accounting.luaAccounting: one row per session, recording the NAS and the IP
session-limit.luaThe simultaneous session check
migrations/1_schema.sqlplans, plan_reply, subscribers, accounting
migrations/2_demo_data.sqlTwo 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. When sql rejects (wrong password, suspended), the script does not run; only after sql accepts does the script check the slots.
  • Do not use first_match: then a name sql cannot find goes to the script, which checks only the slots, and accounts that do not exist get in without a password.
  • reply_query returns attributes by plan. The example uses MikroTik’s Mikrotik-Rate-Limit; BNGs from other vendors use their own attributes, such as Cisco’s Cisco-AVPair or Juniper’s ERX-*. Replace them in plan_reply with names and values your BNG understands.
  • Acct-Interim-Interval = 300 asks the BNG to report every 5 minutes. STALE_AFTER in session-limit.lua and session_query in [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_user is 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 nas column: where CoA must be sent, taken from the NAS-IP-Address or NAS-IPv6-Address the NAS reports, or the client name when there is neither.
  • The framed_ip column: 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-Address and so on) goes straight to that NAS; only a request with just User-Name is looked up with session_query. The query has a single ?, filled with User-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-Name are 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_disconnect and the rradius-server disconnect command 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 replayed is true, and Acct-Delay-Time already 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 accounting table. rradius_acct_spool_bytes above 0 means there is a backlog; alert on it.
  • query_timeout_ms decides 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 = 8 replays several at once; but Start, Interim and Stop of the same session may then run at the same time or out of order. The example accounting.lua writes 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.log and .corrupt files, 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 with rradius-server user add|passwd|disable (disabling sets status to suspended); 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 accounting table 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

SymptomCause
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 503No 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 505The 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 allThe sender is not in [[radius.coa.clients]] or the secret is wrong; counted in rradius_coa_relay_discarded_total
Built with Hugo
Theme Stack designed by Jimmy