Scenario: get rradius running on one machine, with accounts in a table, log in with radtest, then send some accounting and confirm it was written. Most later scenarios build on this one.
Example directory: rradius-server/examples/scenarios/quick-start/
| File | Contents |
|---|---|
rradius.toml | Configuration file |
migrations/1_schema.sql | Three tables: users, user_reply, accounting |
migrations/2_demo_users.sql | Demo accounts |
accounting.lua | Accounting script, also used by chapters 3, 5, 8 and 9 |
*.secret | Shared secrets for the cluster and the NAS (demo values) |
Steps
1. Build and check the configuration
cd rradius-server
cargo build --release
./target/release/rradius-server --check --config examples/scenarios/quick-start/rradius.toml
With a release archive there is nothing to build: unpack it, go into its rradius-server/ directory, and replace ./target/release/rradius-server below with ../bin/rradius-server (see the shared conventions for the examples).
cd rradius-0.1.0-macos-aarch64/rradius-server
../bin/rradius-server --check --config examples/scenarios/quick-start/rradius.toml
When it prints configuration ok, you can start it.
2. Start
./target/release/rradius-server --config examples/scenarios/quick-start/rradius.toml
The first start creates the database in examples/scenarios/quick-start/data/ and applies the two migration files. Once you see RADIUS Server listening on 127.0.0.1:1812 and 127.0.0.1:1813, it accepts requests.
3. Log in
radtest alice alice-password 127.0.0.1 0 testing123-change-me
You get an Access-Accept with Session-Timeout = 3600 and Filter-Id = "staff"; both attributes come from the user_reply table. Try a few more:
| Command | Result | Why |
|---|---|---|
radtest -t chap alice alice-password ... | Accept | alice is stored in plain text, so CHAP works |
radtest bob bob-password ... | Accept, with Reply-Message | bob is stored as a bcrypt hash |
radtest -t chap bob bob-password ... | Reject | CHAP needs plain text; a hash cannot do it |
radtest carol carol-password ... | Reject | carol’s enabled is 0 |
radtest alice wrong ... | Reject | wrong password |
4. Accounting
echo 'User-Name=alice,Acct-Session-Id=s1,Acct-Status-Type=Start' | radclient 127.0.0.1:1813 acct testing123-change-me
echo 'User-Name=alice,Acct-Session-Id=s1,Acct-Status-Type=Stop,Acct-Session-Time=120,Acct-Input-Octets=5000' | radclient 127.0.0.1:1813 acct testing123-change-me
Both get an Accounting-Response. The accounting table has one new row, with stopped filled in.
The configuration explained
[auth]
policy = "first_match"
[[auth.handlers]]
type = "sql"
user_query = "SELECT password FROM users WHERE username = ? AND enabled = 1"
reply_query = "SELECT attribute, value FROM user_reply WHERE username = ?"
user_queryreturns the password. The first column can be plain text or one of many hashes ({crypt},{argon2},{SSHA},{nthash}, …); see usage section 5. New deployments should use{argon2}or bcrypt. Accounts that must support CHAP or PEAP can only be stored in plain text or as{nthash}.- Disabled accounts are excluded in the query itself: no row means the account does not exist. This handler is the only one in the chain, so the login is rejected.
reply_queryreturns (attribute, value) pairs, one attribute per row, named as in the dictionary. If a value has the wrong format, the reply becomes an Access-Reject even with the right password, so check the data before going live.- With
[auth], the top-level script only handles accounting.accounting.luareturnsrejectfor anything that is not accounting right at the start, so even if the configuration changes it lets no one in.
What accounting.lua does
- Start, Interim-Update and Stop write to the same row. The key is the client, the NAS and
Acct-Session-Id. The NAS is theNAS-IP-Address,NAS-IPv6-AddressorNAS-Identifierit reports, or the client name when there is none, so NAS behind one client configured as a whole range stay apart. Writes useINSERT ... ON CONFLICT DO UPDATEand keep the larger value of each number, so retransmissions and reordering never move data backwards. - Stop only ends sessions that are still open, so a retransmitted Stop does not change the first end time.
- Accounting-On/Off (a NAS reboot) ends only the open sessions of the NAS that sent it, recording
terminate_cause11 (NAS-Reboot). Acct-Delay-Timeis used to restore the time, so packets the NAS sent late, or replayed from the accounting spool, are not treated as just having happened.- Traffic over 4 GiB gets its carry from
Acct-*-Gigawords. - Packets without
Acct-Session-Idare logged and answered, or the NAS would retransmit them forever.
Using your own data
- Delete
migrations/2_demo_users.sqland replace it with your own accounts, or keep it and add a3_*.sqlthat deletes the demo accounts. Decide before the first production start; an applied file cannot be changed. - Replace the contents of every
*.secret; see chapter 19. - Change
[[radius.clients]]to your devices’ addresses, and[radius] bindto the address to serve on (the example only listens on127.0.0.1). - Bind
[metrics]to an internal address only; it has no authentication.
Common problems
| Symptom | Cause |
|---|---|
radtest gets no reply | The source address is not in [[radius.clients]], the shared secret is wrong, or a firewall blocks the port. The log shows unknown client or a Message-Authenticator message |
migration file ... changed after it was applied at startup | An applied file was changed. In development, stop the server, delete data/ and start again; in production, restore the original contents and add a new file |
Right password but Reject, with RADIUS response attribute error in the log | An attribute name or value format in user_reply is wrong |
| Accounting keeps being retransmitted | The script failed or did not return 'accept'; the log shows Lua script error |
See usage section 8 for what other messages mean.