Scenario: a branch office’s rradius serves the branch’s NAS.
- The branch’s own accounts (
branch1, or[email protected]) are authenticated locally. - Visitors from a partner log in as
[email protected]and are forwarded to the partner’s RADIUS servers. The partner has two; when the first does not answer, the second is used. - Headquarters accounts (
@hq.example.comand subdomains like@eng.hq.example.com) are forwarded to headquarters.
Example directory: rradius-server/examples/scenarios/realm-proxy/
| File | Contents |
|---|---|
rradius.toml | [proxy] and the chain for local accounts |
partner.secret, hq.secret | Shared secrets with the upstreams |
migrations/ | Local accounts (same structure as the quick start) and the demo account branch1 |
How forwarding is decided
The realm is the part of User-Name after the last @.
[email protected] ─► exact realm "partner.example.org" ─► partner-1, then partner-2 if no answer
[email protected] ─► "*.hq.example.com" ────────────────► hq-1
[email protected] ─► "hq.example.com" ──────────────────► hq-1
[email protected] ─► no realm matches ──────────────────► local chain
branch1 ─► no @ ──────────────────────────────► local chain
- Matching order: exact → the
*.entry that covers it (longest first) →*, ignoring case.*.hq.example.comdoes not coverhq.example.comitself, so the example lists both. - Do not add
*casually. It forwards every name with an@, including your own accounts like[email protected].*is a suitable default exit only when there are no local accounts with a realm. - Forwarded requests are not handled locally: no chain, no script, no EAP. The whole EAP conversation of 802.1X is forwarded as is, and the keys come from the upstream.
- Accounting is forwarded by realm too, and the NAS gets its reply only after the upstream answers. It is not written to the local accounting spool (the one in chapter 7 only covers accounting the database cannot take). To keep a record when no upstream answers, use
[proxy.accounting_spool]; see chapter 11.
Steps
Local testing needs a server to play the “partner”. The simplest is a second copy of the quick start on other ports:
Copy the whole of
quick-start/outside the repository (for examplecp -R examples/scenarios/quick-start /tmp/partner), and in/tmp/partner/rradius.toml:- Change
dictionaryto the absolute path ofshare/dictionaryin the repository. - Set
auth_port = 11812,acct_port = 11813and[metrics] port = 19812. - Add
listen = "127.0.0.1"to[cluster], and add[[cluster.nodes]]at the end (id = 1,raft = "127.0.0.1:18100",api = "127.0.0.1:18200") to stay off this machine’s 8100 and 8200.listenis a must: once nodes are listed, the default is to listen on every interface, and the demoapi.secretis public.
Then start it.
- Change
In
realm-proxy/rradius.toml:- Change the
addressofbranch-nasto127.0.0.1. - Change
partner-2toaddress = "127.0.0.1",auth_port = 11812,acct_port = 11813, withsecret_filepointing to../quick-start/localhost.secret. - Leave
partner-1at its original address to simulate “the first server does not answer”.
- Change the
Start realm-proxy:
./target/release/rradius-server --config examples/scenarios/realm-proxy/rradius.tomlTest:
S=branch-nas-secret-change-me radtest [email protected] branch1-password 127.0.0.1 0 $S # local, Filter-Id = branch radtest [email protected] bob-password 127.0.0.1 0 $S # forwarded to partner, returns Welcome, bobThe second is a few seconds slower: partner-1 got no answer within
timeout_ms × attempts(3 seconds × 2), was marked down, and partner-2 was used. Later requests go straight to partner-2, and every 10 seconds a Status-Server checks whether partner-1 is back. The firstradtestmay time out before the answer arrives; sending it again succeeds.
The configuration explained
[proxy]
timeout_ms = 3000
attempts = 2
check_interval_ms = 10000
[[proxy.servers]]
name = "partner-1"
address = "198.51.100.10"
auth_port = 1812
acct_port = 1813
secret_file = "partner.secret"
[[proxy.realms]]
name = "partner.example.org"
servers = ["partner-1", "partner-2"]
strip_realm = true
serversare tried in order, those not marked down first. Authentication and accounting ports are judged separately.- Get the timing right: one server waits at most
timeout_ms × attempts. That must be shorter than the NAS’s timeout, or the NAS gives up first; andtimeout_msmust be longer than any deliberate delay before the upstream rejects (FreeRADIUS, for example, waits 1 second by default before an Access-Reject), or wrong passwords are mistaken for an upstream that does not answer. strip_realm = true: the partner only knowsalice, so@partner.example.orgis removed before sending. MS-CHAPv2 (not inside EAP) responses are computed with the full name; keep itfalsethen.- Upstream replies must carry a Message-Authenticator (
require_message_authenticator = true, the default). Setfalseonly for old upstreams that do not send it; not recommended. - When none answer, the NAS gets no reply. An Access-Reject would make the user think the password is wrong, so the NAS is left to time out and use its own backup.
- How a down upstream comes back: every
check_interval_msa Status-Server is sent, and an answer restores it. For upstreams that do not answer Status-Server, setstatus_check = falseon that server; it is then simply treated as restored when the time is up, and the next request decides. - Noticing a down server earlier (
probe_interval_ms): by default an upstream is marked down only when real requests time out, so the first batch of requests after it fails all have to wait first. Withprobe_interval_ms = 30000in[[proxy.servers]], once that server has given no answer of any kind for more than 30 seconds, Status-Server is sent actively, and 3 unanswered in a row mark it down. Backup servers that normally carry no traffic need this most. See chapter 11.
Local accounts
[auth.username]
strip_realm = "suffix"
lowercase = true
[email protected] matches no realm, so it stays local, and the account lookup uses branch1.
Roaming between organisations: RadSec upstreams
When the partner is another organisation across the internet, do not forward over UDP; use RadSec (RADIUS over TLS): the whole packet is inside TLS, and both sides verify each other by certificate.
Prepare certificates. Get the CA that issues the partner’s server certificate from the partner (or the roaming federation) and save it as
partner-ca.pem. When the partner verifies rradius, also prepare a certificate and private key issued by a CA the partner trusts (our-cert.pem,our-cert.key). Ask for the name on the partner’s server certificate, such asradius.partner.example.org.Change the upstream configuration. Turn
partner-1into RadSec:[[proxy.servers]] name = "partner-1" address = "198.51.100.10" transport = "tls" tls_name = "radius.partner.example.org" ca_file = "partner-ca.pem" cert_file = "our-cert.pem" key_file = "our-cert.key"- Without
portit is 2083, used for both authentication and accounting;auth_portandacct_portcan no longer be set. - No
secretis needed: the RadSec shared secret is fixed asradsec(RFC 6614), and the partner uses the same. Setsecretorsecret_fileonly when the partner specifies another. - A realm’s
serverscan mix RadSec and UDP upstreams, with failover in order as usual.
- Without
Check and start:
./target/release/rradius-server --check --config examples/scenarios/realm-proxy/rradius.tomlAn unreadable certificate file, a private key that does not match its certificate, or a missing
tls_nameorca_fileis reported here, naming the upstream and the field.Confirm: send a login that is forwarded to the partner. The log shows
proxy server partner-1: connected to 198.51.100.10:2083, andrradius_proxy_connections_total{server="partner-1",result="connected"}in/metricsis 1. Later requests use the same connection, without a new handshake each time.
Differences from UDP upstreams:
- No retransmission. TCP guarantees delivery, so a request is sent once and
attemptsdoes not apply; with no answer withintimeout_ms, the next server is used. One server waits at most onetimeout_ms. - Authentication and accounting are marked down together, because there is one port and one connection.
- One connection has at most 256 requests waiting for answers at once; more queue. With a partner far away and busy, this is the ceiling (about 25,000 requests per second at a 10 ms round trip, an estimate). Measured on one machine, one connection handles about 100,000 requests per second, around a tenth less than a UDP upstream; see usage section 2.13.
- CoA uses this connection too: Disconnect and CoA forwarded by realm to a RadSec upstream are sent on the same connection. The partner must be willing to receive them on it; check with the partner first.
- Revocation lists (
crl_file) are read only at startup and on SIGHUP; send SIGHUP when the partner replaces its list.
Before going live
- UDP upstreams must be on a trusted network (a leased line, a VPN), because RADIUS over UDP encrypts only the password. Across the internet, use RadSec upstreams (see the previous section).
- Upstream addresses must be IPs, not host names.
- Shared secrets with UDP upstreams should differ per organisation and be long.
- Loops: when two servers forward to each other, rradius drops and logs requests that carry its own Proxy-State.
- Monitoring: request counts, timeouts and down state of every upstream are in
/metrics; see usage section 2.8. - Reloading (SIGHUP) applies changes to
[proxy], and every upstream is treated as healthy again. - CoA can be forwarded by realm too: when no local NAS is found and the realm of
User-Namematches an entry, Disconnect and CoA requests go to that realm’s upstreams (to the upstream’scoa_port, 3799 by default); see usage section 4.8. - Not available yet: round robin, routing decided by a script, DTLS, TLS-PSK. See usage section 2.13.
More approaches
This chapter covers the most basic “failover in order”. The following are explained in chapter 11 with a roaming federation scenario:
| Need | Approach |
|---|---|
| Spread requests over several upstreams, optionally weighted | balance = "load-balance", weight |
| Too many upstreams to configure one by one | [proxy.discovery]: look up the other side’s RadSec servers in DNS by realm |
| Forwarded accounting must not be lost when no upstream answers | [proxy.accounting_spool] |
| The other side also sends requests in | [radius.tls]; see chapter 10 |
Common problems
| Symptom | Cause |
|---|---|
| Local accounts with a realm are forwarded | There is a *, or a *. entry covering your own domain |
| Forwarded logins are always slow | The first upstream never answers requests but does answer the Status-Server checks (it answers Status-Server but does not handle authentication). Remove it from servers, or set status_check = false |
| After a login with a wrong password, the upstream is marked down | timeout_ms is shorter than the upstream’s delay before rejecting |
A RadSec upstream never connects, with cannot connect ... TLS: in the log | The partner’s certificate is not signed by the CA in ca_file or is not valid for tls_name, or the partner does not accept the certificate rradius presents (cert_file not set, or not signed by a CA the partner trusts). The log message says which |
| A RadSec upstream connects but every request times out | The shared secret is not radsec, so the partner’s replies fail verification: ask which secret the partner uses, and set it in secret |