This manual walks through setting up rradius for common deployment scenarios, step by step. Each scenario comes with a configuration file, tables and Lua scripts that can be started as they are, in rradius-server/examples/scenarios/. Every field is described in full in the reference document docs/usage.md; the manual covers only what each scenario needs and points to the matching section.
The examples are tested automatically (rradius-server/tests/scenarios_test.rs). The tests start each scenario the way the manual does, send login, accounting, TACACS+ and CoA requests, and check that the results match what the manual says. So if an example breaks, a test fails. What the tests cannot cover (real devices, a real roaming federation, external services) is listed in each chapter’s “Before going live”.
Read these two chapters first
| Chapter | Contents |
|---|---|
| 1. Concepts | How rradius handles a request, how the configuration is laid out, where data lives, how to test |
| 2. Quick Start | One node, accounts in a table, your first Access-Accept within ten minutes |
What do you want to do
| I want to… | Chapter |
|---|---|
| Let staff join the company Wi-Fi with a password or a certificate | 3; revocation and roaming in 15 |
| Let devices that cannot do 802.1X join Wi-Fi, each person with their own passphrase | 12 |
| Let devices with our own SIM cards join Wi-Fi | 13 |
| Put printers and IP phones on the wired network | 4 |
| Let VPN users log in with the company directory, or add a one-time code | 5 |
| Control who can log in to routers and which commands they may run | 6; over TLS in 16 |
| Run broadband: plans, simultaneous sessions, disconnects, accounting | 7 |
| Keep serving when any one server stops | 8 |
| Send other organisations’ accounts to their own servers | 9; joining a roaming federation in 11 |
| Serve NAS on the other side of the internet or behind NAT | 10 |
| Manage hundreds of NAS that change often | 14 |
| Use accounts that already live in another system, without copying them | directory (LDAP/AD) in 5, HTTP API in 18 |
| Move from an old authentication system without making everyone reset passwords | 17 |
| Day-to-day work after going live | 19 |
| Find the cause of a problem from its symptom | 20 |
By scenario
| Chapter | Scenario | Features used | Example directory |
|---|---|---|---|
| 3. Enterprise Wi-Fi | 802.1X: company laptops use certificates, staff phones use passwords, VLAN by group | EAP-TLS, PEAP, certificate_query, dynamic VLAN | enterprise-wifi/ |
| 4. Wired MAC authentication | Printers, IP phones and other devices that cannot do 802.1X | Lua scripts, range clients | wired-mab/ |
| 5. Remote access | VPN logins against the company directory (LDAP/AD), TOTP codes for the jump host | LDAP, groups, named chains, Access-Challenge | remote-access/ |
| 6. Network device administration | Administrators log in to routers, with commands limited and recorded by role | TACACS+ authentication, authorization, accounting, authorization groups | device-admin/ |
| 7. Broadband provider | PPPoE/IPoE: plan rates, simultaneous sessions, disconnects from the billing system | all_accept, accounting, CoA forwarding, accounting spool | broadband/ |
| 8. High-availability cluster | Three nodes, service continues when any one stops | hiqlite cluster, WireGuard, migrations | ha-cluster/ |
| 9. Forwarding by realm | Accounts of partners or headquarters go to their own servers | [proxy], failover, RadSec upstreams | realm-proxy/ |
| 10. RadSec | NAS across untrusted networks or behind NAT; disconnects travel over the NAS’s own connection | [radius.tls], tls_name, CoA over RadSec, coa_sender | radsec/ |
| 11. Roaming federation | eduroam and the like: visitors go to their home institution, our own people come back through the federation | [proxy.discovery] (DNS), load balancing and weights, active checks, spool for forwarded accounting | roaming/ |
| 12. A Wi-Fi passphrase per person | One WPA2-PSK SSID, each person with their own passphrase and VLAN | [radius.dpsk], dpsk-seal, passphrase replied by MAC | psk-wifi/ |
| 13. Wi-Fi login with SIM cards | USIM cards you issue yourself, no certificates and no passwords | EAP-AKA’, aka-seal, master key, rate limits | sim-wifi/ |
| 14. Hundreds of branch NAS | NAS listed in a table, so adding one needs no configuration change | [radius.dynamic_clients], the client command | branch-nas/ |
| 15. Certificate revocation and fast reconnection | Revoke lost laptops; avoid a full handshake every time a device roams | CRL, OCSP, resumption_ms, shared_tickets | wifi-certs/ |
| 16. TACACS+ over TLS | Move device administration from shared secrets to TLS 1.3 and device certificates | [tacacs.tls], tls_name, tls_only | device-admin-tls/ |
| 17. Moving accounts from an old system | Bring old password hashes over as they are, then move to new formats gradually | Password formats, name normalisation, [accounts] | migrate-users/ |
| 18. Accounts in another system | Ask the membership system’s API over HTTPS on every login | [lua.http], http_request, verifies_password | external-api/ |
After going live
| Chapter | Contents |
|---|---|
| 19. Operations | Changing accounts and configuration, reloading, rotating secrets and keys, metrics, overload, the accounting spool, upgrades, backups |
| 20. Troubleshooting by symptom | No reply, rejected, slow, missing accounting, TLS failing, startup failing: where to look first for each |
Shared conventions for the examples
Relative paths in a configuration file are relative to that file’s directory, so every scenario can be started inside the repository:
cd rradius-server cargo build --release ./target/release/rradius-server --config examples/scenarios/quick-start/rradius.tomlWith a release archive, unpack
rradius-<version>-<platform>.tar.gz; its directory layout is the same as the repository. Go into itsrradius-server/directory and replace./target/release/rradius-serverin each chapter with../bin/rradius-server. Every other command and path stays the same, and there is nocargo build:cd rradius-0.1.0-linux-x86_64/rradius-server ../bin/rradius-server --config examples/scenarios/quick-start/rradius.tomlSome scenarios need a script run before they can start, because certificates and keys do not belong in the repository:
Script Scenarios What it creates make-certs.shenterprise-wifi/,radsec/,roaming/,device-admin-tls/A demo CA and certificates in certs/setup.shpsk-wifi/,sim-wifi/,wifi-certs/Key files (mode 0600), and demo data or certificates sealed with them These are for testing only.
setup.shdoes not overwrite files that already exist; to start over, stop the server and delete the files it created anddata/.Secret files (
*.secret) all hold demo values, markedchange-me. Always replace them in production; see chapter 19.Demo data is in
migrations/2_demo_*.sql(2_imported_users.sqlin the account migration scenario), and the structure is in1_schema.sql. In production, delete the demo data files or replace them with your own data before the first start. Once applied, a file cannot be changed; see chapter 1.Ports are the standard ones (1812, 1813, 2083, 3799, 49, 300). Starting two scenarios on the same machine at once conflicts; start one at a time or change the ports.
data/,spool/,certs/and key files created at runtime are not in git. To start over, stop the server and deletedata/.NAS addresses are demo private ranges. For local testing, change the client
addressto127.0.0.1(quick start already does), or requests are treated as coming from an unknown source and get no reply.Some scenarios share files: most use
quick-start/accounting.luafor accounting, anddevice-admin-tls/uses the scripts and tables ofdevice-admin/. When copying a scenario elsewhere, take the directories it refers to with it.