2. Quick Start

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/

FileContents
rradius.tomlConfiguration file
migrations/1_schema.sqlThree tables: users, user_reply, accounting
migrations/2_demo_users.sqlDemo accounts
accounting.luaAccounting script, also used by chapters 3, 5, 8 and 9
*.secretShared 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:

CommandResultWhy
radtest -t chap alice alice-password ...Acceptalice is stored in plain text, so CHAP works
radtest bob bob-password ...Accept, with Reply-Messagebob is stored as a bcrypt hash
radtest -t chap bob bob-password ...RejectCHAP needs plain text; a hash cannot do it
radtest carol carol-password ...Rejectcarol’s enabled is 0
radtest alice wrong ...Rejectwrong 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_query returns 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_query returns (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.lua returns reject for 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 the NAS-IP-Address, NAS-IPv6-Address or NAS-Identifier it reports, or the client name when there is none, so NAS behind one client configured as a whole range stay apart. Writes use INSERT ... ON CONFLICT DO UPDATE and 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_cause 11 (NAS-Reboot).
  • Acct-Delay-Time is 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-Id are logged and answered, or the NAS would retransmit them forever.

Using your own data

  1. Delete migrations/2_demo_users.sql and replace it with your own accounts, or keep it and add a 3_*.sql that deletes the demo accounts. Decide before the first production start; an applied file cannot be changed.
  2. Replace the contents of every *.secret; see chapter 19.
  3. Change [[radius.clients]] to your devices’ addresses, and [radius] bind to the address to serve on (the example only listens on 127.0.0.1).
  4. Bind [metrics] to an internal address only; it has no authentication.

Common problems

SymptomCause
radtest gets no replyThe 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 startupAn 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 logAn attribute name or value format in user_reply is wrong
Accounting keeps being retransmittedThe script failed or did not return 'accept'; the log shows Lua script error

See usage section 8 for what other messages mean.

Built with Hugo
Theme Stack designed by Jimmy