0. Guide to the Manual

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

ChapterContents
1. ConceptsHow rradius handles a request, how the configuration is laid out, where data lives, how to test
2. Quick StartOne 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 certificate3; revocation and roaming in 15
Let devices that cannot do 802.1X join Wi-Fi, each person with their own passphrase12
Let devices with our own SIM cards join Wi-Fi13
Put printers and IP phones on the wired network4
Let VPN users log in with the company directory, or add a one-time code5
Control who can log in to routers and which commands they may run6; over TLS in 16
Run broadband: plans, simultaneous sessions, disconnects, accounting7
Keep serving when any one server stops8
Send other organisations’ accounts to their own servers9; joining a roaming federation in 11
Serve NAS on the other side of the internet or behind NAT10
Manage hundreds of NAS that change often14
Use accounts that already live in another system, without copying themdirectory (LDAP/AD) in 5, HTTP API in 18
Move from an old authentication system without making everyone reset passwords17
Day-to-day work after going live19
Find the cause of a problem from its symptom20

By scenario

ChapterScenarioFeatures usedExample directory
3. Enterprise Wi-Fi802.1X: company laptops use certificates, staff phones use passwords, VLAN by groupEAP-TLS, PEAP, certificate_query, dynamic VLANenterprise-wifi/
4. Wired MAC authenticationPrinters, IP phones and other devices that cannot do 802.1XLua scripts, range clientswired-mab/
5. Remote accessVPN logins against the company directory (LDAP/AD), TOTP codes for the jump hostLDAP, groups, named chains, Access-Challengeremote-access/
6. Network device administrationAdministrators log in to routers, with commands limited and recorded by roleTACACS+ authentication, authorization, accounting, authorization groupsdevice-admin/
7. Broadband providerPPPoE/IPoE: plan rates, simultaneous sessions, disconnects from the billing systemall_accept, accounting, CoA forwarding, accounting spoolbroadband/
8. High-availability clusterThree nodes, service continues when any one stopshiqlite cluster, WireGuard, migrationsha-cluster/
9. Forwarding by realmAccounts of partners or headquarters go to their own servers[proxy], failover, RadSec upstreamsrealm-proxy/
10. RadSecNAS across untrusted networks or behind NAT; disconnects travel over the NAS’s own connection[radius.tls], tls_name, CoA over RadSec, coa_senderradsec/
11. Roaming federationeduroam 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 accountingroaming/
12. A Wi-Fi passphrase per personOne WPA2-PSK SSID, each person with their own passphrase and VLAN[radius.dpsk], dpsk-seal, passphrase replied by MACpsk-wifi/
13. Wi-Fi login with SIM cardsUSIM cards you issue yourself, no certificates and no passwordsEAP-AKA’, aka-seal, master key, rate limitssim-wifi/
14. Hundreds of branch NASNAS listed in a table, so adding one needs no configuration change[radius.dynamic_clients], the client commandbranch-nas/
15. Certificate revocation and fast reconnectionRevoke lost laptops; avoid a full handshake every time a device roamsCRL, OCSP, resumption_ms, shared_ticketswifi-certs/
16. TACACS+ over TLSMove device administration from shared secrets to TLS 1.3 and device certificates[tacacs.tls], tls_name, tls_onlydevice-admin-tls/
17. Moving accounts from an old systemBring old password hashes over as they are, then move to new formats graduallyPassword formats, name normalisation, [accounts]migrate-users/
18. Accounts in another systemAsk the membership system’s API over HTTPS on every login[lua.http], http_request, verifies_passwordexternal-api/

After going live

ChapterContents
19. OperationsChanging accounts and configuration, reloading, rotating secrets and keys, metrics, overload, the accounting spool, upgrades, backups
20. Troubleshooting by symptomNo 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.toml
    
  • With a release archive, unpack rradius-<version>-<platform>.tar.gz; its directory layout is the same as the repository. Go into its rradius-server/ directory and replace ./target/release/rradius-server in each chapter with ../bin/rradius-server. Every other command and path stays the same, and there is no cargo build:

    cd rradius-0.1.0-linux-x86_64/rradius-server
    ../bin/rradius-server --config examples/scenarios/quick-start/rradius.toml
    
  • Some scenarios need a script run before they can start, because certificates and keys do not belong in the repository:

    ScriptScenariosWhat 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.sh does not overwrite files that already exist; to start over, stop the server and delete the files it created and data/.

  • Secret files (*.secret) all hold demo values, marked change-me. Always replace them in production; see chapter 19.

  • Demo data is in migrations/2_demo_*.sql (2_imported_users.sql in the account migration scenario), and the structure is in 1_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 delete data/.

  • NAS addresses are demo private ranges. For local testing, change the client address to 127.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.lua for accounting, and device-admin-tls/ uses the scripts and tables of device-admin/. When copying a scenario elsewhere, take the directories it refers to with it.

Built with Hugo
Theme Stack designed by Jimmy