What rradius does
rradius is an AAA server. When someone wants to get online or log in, a network device (a NAS: wireless controller, switch, VPN gateway, BNG, router) asks it three things:
- Authentication: who is this, and is the password or certificate right.
- Authorization: once accepted, what do they get, such as a VLAN, a rate, a privilege level, or the commands they may run.
- Accounting: when they came online and went offline, and how much traffic they used.
Devices and rradius talk over these protocols:
| Protocol | Used for | Port |
|---|---|---|
| RADIUS (UDP) | User access: Wi-Fi, wired 802.1X, VPN, PPPoE | authentication 1812, accounting 1813 |
| RadSec (RADIUS over TLS) | RADIUS that has to cross an untrusted network (chapter 10) | 2083 |
| TACACS+ (TCP) | Administrators logging in to network devices (chapter 6) | 49 |
| TACACS+ over TLS | The same, with the whole connection inside TLS 1.3 (chapter 16) | 300 |
Other systems can also send “disconnect” and “change authorization” requests (Disconnect, CoA) to port 3799, and rradius forwards them to the NAS (chapters 7 and 10).
How a request is handled
NAS ──Access-Request──► rradius
│
├─ source is not a configured client ─► dropped, no reply
│ (with [radius.dynamic_clients] and a source in its ranges: look it up in the table first, chapter 14)
├─ Status-Server ─────────────────────► answered directly (when status_server = true)
├─ name's realm matches [proxy] ──────► forwarded upstream, reply relayed as is (chapters 9, 11)
├─ carries EAP-Message ───────────────► after EAP (TLS, PEAP, TTLS, AKA') completes,
│ the name goes to the chain below (chapters 3, 13, 15)
├─ carries a Wi-Fi 4-way handshake ───► [radius.dpsk] finds whose passphrase it is,
│ then hands that person to the chain below (chapter 12)
├─ client has auth = "name" ──────────► that named chain
├─ [[auth.handlers]] exist ───────────► the default chain
└─ none of these ─────────────────────► [lua].script
- An authentication chain (
[auth]) runs several handlers (sql,ldap,lua) in order. Withfirst_match, the first handler that has an opinion decides. Withall_accept, every handler must agree, which is the usual way to say “check the password first, then check policy”. See usage section 3. - The top-level script (
[lua].script) is always required. It handles all accounting and TACACS+ authorization, and also authentication when there is no chain. So in scenarios with a chain, the top-level script usually only does accounting. - Accounting (Accounting-Request) does not go through a chain. It always goes to the top-level script, or upstream when the name matches
[proxy]. - Requests that arrive over RadSec take the same path. The only differences are how the NAS is recognised (by certificate) and how packets are protected (TLS).
- No reply is deliberate. When the source is unknown, the signature is wrong, the server is too busy, or an upstream does not answer, rradius does not reply, so that the NAS retransmits or fails over. For how to investigate “no reply”, see chapter 20.
The configuration file
One configuration file is one server. The common sections:
| Section | Contents | Required |
|---|---|---|
dictionary | The RADIUS dictionary, share/dictionary in the repository | yes |
[lua] | The top-level script and script limits | yes |
[cluster] | Data directory, cluster secret, nodes, migrations | yes |
[auth] | Authentication chains | no |
[radius], [[radius.clients]] | RADIUS ports and the devices that may ask | for RADIUS |
[radius.tls] | RadSec (chapter 10) | no |
[radius.eap] | EAP and certificates for 802.1X (chapters 3, 13, 15) | for EAP |
[radius.dpsk] | A Wi-Fi passphrase per person (chapter 12) | no |
[radius.dynamic_clients] | NAS looked up from a table (chapter 14) | no |
[radius.coa] | Receiving disconnect requests from other systems (chapters 7, 10) | no |
[radius.accounting_spool] | Spooling accounting when the database cannot take writes (chapter 7) | no |
[tacacs], [[tacacs.clients]] | TACACS+ (chapter 6) | for TACACS+ |
[tacacs.tls] | TACACS+ over TLS (chapter 16) | no |
[proxy] | Forwarding by realm (chapters 9, 11) | no |
[lua.http] | Letting scripts call HTTP APIs (chapter 18) | no |
[accounts] | SQL run by the rradius-server user command (chapter 19) | no |
[metrics] | Prometheus metrics | no |
[log] | Log format, level, tracing particular users | no |
At least one of [radius] and [tacacs] is required. Every section rejects fields it does not know, so a misspelt field makes startup fail and names the field.
Relative paths are relative to the configuration file’s directory, not to where the server is started.
Secrets always go in files (
secret_file), never in the configuration file. A trailing newline in the file is removed.Key file permissions are checked. Keys that protect table contents (
aka.key,dpsk.key,ticket.seal) must have permissions such as 0600, 0640 or 0400. If others can read them, the server refuses to start. They are not in the repository; each scenario’ssetup.shcreates them.Configuration errors fail at startup (exit status 2), and the message names the field. Check before going live with
--check:rradius-server --check --config /etc/rradius/rradius.tomlIt checks the configuration, dictionary, certificates, migration file names and script syntax. It does not connect to the database or LDAP, so a wrong SQL statement or LDAP password only shows up after startup.
Clients: who may ask
[[radius.clients]] lists the devices that may send requests. Each has an address (a single IP or a range) and a shared secret.
[[radius.clients]]
name = "wlc" # logs, metrics and scripts all use this name for the client
address = "10.30.0.10" # or "10.30.0.0/24"
secret_file = "wlc.secret"
- Sources not on the list get no reply at all. This is the most common “the server does nothing” for newcomers; look for
unknown clientin the log. - Longest prefix wins: with both
10.0.0.0/8and10.30.0.10, the latter is more specific and is used. - Shared secrets should be long. Fewer than 16 characters gives a warning; 24 or more random characters is recommended. Each device can have its own.
- Message-Authenticator is required by default. Old devices that do not send it are dropped. Set
require_message_authenticator = "no"or"auto"on that client; see usage section 2.6. - When there are many NAS that change often, they can live in a table instead of the configuration file (chapter 14).
- When a NAS uses RadSec, it can be recognised by certificate alone, without a fixed address (chapter 10).
Tables and migrations
rradius has a built-in database (hiqlite: SQLite plus Raft replication), used the same way on one node and in a cluster. You define the tables for accounts, reply attributes and accounting yourself, as SQL files in migrations_dir, applied in numbered order at startup:
migrations/
1_schema.sql creates the tables
2_demo_users.sql demo data
File names are
<number>_<name>.sql, numbered consecutively from 1.An applied file cannot be changed; changing it makes startup fail. To change the structure or add data, add a file with the next number and restart (one node at a time in a cluster). See usage section 2.5.
Scripts read and write data:
sql_queryreads the local replica, andsql_executewrites and replicates to every node. Values from the request are always passed as parameters, never spliced into the SQL string:local rows = sql_query("SELECT plan FROM subscribers WHERE username = ?", {get_attr('User-Name')})
Adding accounts, changing passwords and disabling accounts need no migration: set up [accounts] and use the rradius-server user command, which takes effect across the cluster at once; see chapter 19.
Accounting must be safe to repeat
A NAS that gets no Accounting-Response retransmits, so:
- The accounting script replies only when it returns
'accept'. Any other result (including a script error) gets no reply; the NAS retransmits and the script runs again. - Handling the same packet twice must give the same result as once. The examples all use
INSERT ... ON CONFLICT DO UPDATEorINSERT OR IGNORE, keyed on the NAS plusAcct-Session-Id(a session ID is unique only within one NAS). One client can be a whole range, so “which NAS” must come from theNAS-IP-AddressorNAS-Identifierthe NAS reports, not from the client name alone. - Return
'accept'for packets you do not want to record too, or the NAS keeps retransmitting them.
Testing tools
The examples are tested with the FreeRADIUS client tools: the freeradius-utils package on Debian and Ubuntu, or Homebrew’s freeradius-server on macOS.
By default rradius drops Access-Requests without a Message-Authenticator. The project has tested with radclient from FreeRADIUS 3.2.10, which adds it automatically. Older versions may not, and their requests are dropped with no reply. In that case use radclient and add Message-Authenticator=0x00 to the input; it then computes the correct value:
echo 'User-Name=alice,User-Password=alice-password,Message-Authenticator=0x00' | radclient 127.0.0.1:1812 auth testing123-change-me
# PAP login: user, password, server, NAS port, shared secret
radtest alice alice-password 127.0.0.1 0 testing123-change-me
# CHAP login
radtest -t chap alice alice-password 127.0.0.1 0 testing123-change-me
# Accounting
echo 'User-Name=alice,Acct-Session-Id=s1,Acct-Status-Type=Start' | radclient 127.0.0.1:1813 acct testing123-change-me
# Is the server alive (Status-Server)
echo 'Message-Authenticator=0x00' | radclient 127.0.0.1:1812 status testing123-change-me
- For 802.1X (EAP), use
eapol_testfrom wpa_supplicant; an example configuration is in chapter 3. - For TACACS+, use
tacacs_client(the Python packagetacacs_plus) or a real device; see chapter 6. - For RadSec and TACACS+ over TLS, certificates and handshakes can be checked first with
openssl s_client; see chapter 10. - Some login methods have no ready-made command-line tool to simulate them (the Wi-Fi 4-way handshake, SIM cards, logins over TACACS+ over TLS). The chapters for those scenarios explain how the automated tests verify them, and which parts wait for real devices.
- Every login writes one line to the authentication log (
[log] auth = true, on by default), naming the client, the user name, the chain and the handler that decided. Start with that line when investigating.