Scenario: a university (realm uni-a.example in the example) joins a roaming federation. Federation members accept each other’s accounts: a user from any member, visiting another member, can join the Wi-Fi with their own university’s account.
- Our own people on campus:
[email protected]is authenticated locally. - Visitors from other universities:
[email protected]is forwarded to his own university. There are too many members to configure one by one, so the other side’s servers are found by looking up the realm in DNS; realms not found go to the national proxy. - Our own people at other universities: their requests come back from the federation over RadSec and are authenticated locally.
- A sister university on the same leased line has two servers, and users should be spread across them.
- When every upstream is down, forwarded accounting must not be lost.
This chapter follows on from chapter 9 (the basics of forwarding by realm) and chapter 10 (RadSec); what those chapters covered is not repeated.
Example directory: rradius-server/examples/scenarios/roaming/
| File | Contents |
|---|---|
rradius.toml | [proxy], [proxy.discovery], [proxy.accounting_spool], [radius.tls] |
make-certs.sh | Creates a demo federation CA, our RadSec certificate, a certificate pretending to be the national proxy, and a server certificate for PEAP |
migrations/ | Our accounts (same structure as the quick start) and the demo account student1 |
wlc.secret, uni-b.secret | Shared secrets for the campus controller and the sister university |
Where a request goes
student1 no @ ───────────────────────────────► local
[email protected] in local_realms ────────────────────► local
[email protected] exact [[proxy.realms]] entry ───────► uni-b-1, uni-b-2 (spread)
[email protected] *.gov.example in [[proxy.realms]] ──► national proxy
[email protected] no entry → DNS lookup ─┬─ found ────► uni-c's own RadSec servers
├─ DNS says none ─► * in [[proxy.realms]] → national proxy
└─ lookup fails ──► dropped; looked up again when the NAS retransmits
- Order: exact realm → the
*.entry covering it →local_realms→ DNS →*.*is used only when DNS clearly says “none”. - Forwarded requests are not handled locally. The whole EAP conversation of 802.1X goes to the other side as is; passwords and keys are handled there, and this server never sees the password.
- The local
[radius.eap]serves only the requests that stay local (our own users).
Steps
1. Create the certificates and start
cd rradius-server/examples/scenarios/roaming
./make-certs.sh
cd ../../..
./target/release/rradius-server --check --config examples/scenarios/roaming/rradius.toml
--check confirms that every upstream’s certificate can be read and that private keys match their certificates. The upstream addresses in the example are documentation addresses, so after starting, our own accounts can log in but forwarded requests get no reply. To see forwarding locally, follow the steps in chapter 9 to start a second quick start as the sister university, and point uni-b-1 and uni-b-2 at it.
For local testing, change the address of campus-wlc to 127.0.0.1:
./target/release/rradius-server --config examples/scenarios/roaming/rradius.toml
radtest [email protected] student1-password 127.0.0.1 0 campus-wlc-secret-change-me
You get an Access-Accept with Filter-Id = "campus".
2. What to replace for production
- Apply to the federation for a RadSec certificate, and obtain the federation’s CA. They replace
certs/radius.pem,certs/radius.keyandcerts/federation-ca.pem. local_realms, the national proxy names in[[radius.clients]], and the addresses andtls_nameofflr-1/flr-2are replaced with the values the federation gives you.- The certificate in
[radius.eap]is replaced with the one you want your own users to see; see chapter 3. - Publish your own NAPTR and SRV records in DNS so other members can find you. The record format is set by the federation.
The configuration explained
Finding the other side’s servers in DNS
[proxy.discovery]
ca_file = "certs/federation-ca.pem"
cert_file = "certs/radius.pem"
key_file = "certs/radius.key"
service = "x-eduroam:radius.tls"
local_realms = ["uni-a.example", "*.uni-a.example"]
lookup_timeout_ms = 5000
realm_names_only = true
probe_interval_ms = 30000
Realms without a [[proxy.realms]] entry are looked up in DNS (RFC 7585): first the realm’s NAPTR records, taking those whose service matches, then the SRV records they point to and the hosts’ addresses, at most 8 addresses. Servers found this way always use RadSec, with failover in the order DNS gives.
local_realmsmust list your own realms. Federation members usually publish NAPTR records for their own realm too; without this, your own users would be looked up to your own RadSec server, forwarded out and back again, and never reach the local EAP and chains.servicedefaults to RFC 7585’saaa+auth:radius.tls.tcp; eduroam usesx-eduroam:radius.tls.ca_fileis the federation’s CA, which must have issued the other side’s certificate.cert_fileandkey_fileare the certificate presented to the other side; most federations require mutual verification.realm_names_only = true: the other side’s certificate must be valid for the realm itself (a DNS name or a NAIRealm field). Withfalse(the default), being valid for the host name the SRV record points to also counts. The difference: rradius does not do DNSSEC, so host names come from unverified DNS answers. Withfalse, someone who can tamper with DNS and holds any federation certificate (another member, for example) can steer another realm’s requests to themselves. Turn it on when the federation’s certificates carry realm names; when the federation issues only host name certificates, turning it on means you cannot connect.lookup_timeout_ms: the longest a whole lookup for one realm may take. Realms come from names users type, and DNS records are set by whoever owns the domain, so lookups are bounded: at most 16 lookups at once per node, and one realm is looked up only once at a time. When a lookup is in progress or the slots are used up, the request is simply dropped; by the time the NAS retransmits, the lookup has usually finished.- Results are remembered: found servers are kept for the DNS TTL (at least 60 seconds, at most a day); “none” answers for 5 minutes; at most 4,096 realms are remembered. SIGHUP clears them.
- A failed lookup is not “none”. On a timeout, SERVFAIL or an unreachable DNS server:
- If the realm was found before, the servers from last time keep being used, and the realm is looked up again after 30 seconds.
- If it was never found before, the realm’s requests are dropped for 30 seconds, neither sent to
*nor kept local. Accounting sent to the wrong place would be billed by someone else, so no reply is better.
probe_interval_ms: when a discovered server has been idle this long, a Status-Server checks that it is still there.
National proxy
[[proxy.servers]]
name = "flr-1"
address = "198.51.100.1"
transport = "tls"
tls_name = "flr1.roam.example"
ca_file = "certs/federation-ca.pem"
cert_file = "certs/radius.pem"
key_file = "certs/radius.key"
probe_interval_ms = 30000
[[proxy.realms]]
name = "*.gov.example"
servers = ["flr-1", "flr-2"]
[[proxy.realms]]
name = "*"
servers = ["flr-1", "flr-2"]
*is the exit when DNS finds nothing. Members that publish no DNS records rely on the national proxy to forward.- List organisations known to have no DNS records directly (
*.gov.examplein the example), saving a lookup every 5 minutes. probe_interval_ms(active checks): without it, an upstream is marked down only after real requests time out. The backupflr-2normally carries no traffic, and finding out it is down too only when the primary fails is too late. With it set, when an upstream has given no answer of any kind for this long, one Status-Server is sent; 3 unanswered in a row mark it down, andrradius_proxy_server_alivebecomes 0, which you can alert on. Upstreams carrying traffic receive no extra packets. The upstream must answer Status-Server.- For the other rules of RadSec upstreams (one long-lived connection, no retransmission, 256 requests at once), see chapter 9.
The federation connecting in
[radius.tls]
port = 2083
cert_file = "certs/radius.pem"
key_file = "certs/radius.key"
client_ca_file = "certs/federation-ca.pem"
network_clients_need_tls_name = true
[[radius.clients]]
name = "flr-1-in"
tls_name = "flr1.roam.example"
secret = "unused-on-radsec-change-me"
When our people log in at another university, their requests come through the national proxy to port 2083 here. The national proxies are recognised by certificate alone (only tls_name), so their addresses can change without a configuration change. The incoming name is [email protected], which is in local_realms, so it stays local and is handled by [radius.eap] and the chain.
Other members connecting directly: when another member finds you through DNS, it connects straight to your port 2083, not through the national proxy. A peer connecting in must match some [[radius.clients]] entry, or it is closed after the handshake. Two approaches:
- One entry per peer, with
tls_nameset to the name on its certificate. The strictest, but with many members the list never ends; you can ask them to come through the national proxy instead. - One range entry covering the peers’ addresses, without
tls_name. Any peer in that range with any certificate from the federation CA can then connect in (the table in chapter 10).network_clients_need_tls_namecannot be on in that case, and there is a warning at startup. The range can also get in over UDP (with thesecret), so use a long randomsecretand block its UDP with the firewall. The example does not set this up, and the scenario test does not cover it.
Spreading over several upstreams
[[proxy.servers]]
name = "uni-b-1"
address = "10.41.0.1"
secret_file = "uni-b.secret"
weight = 1
[[proxy.servers]]
name = "uni-b-2"
address = "10.41.0.2"
secret_file = "uni-b.secret"
weight = 3
[[proxy.realms]]
name = "uni-b.example"
servers = ["uni-b-1", "uni-b-2"]
balance = "load-balance"
strip_realm = true
balance = "load-balance": the defaultfailoveralways sends to the first server first. Withload-balance, each request gets a fixed order computed fromCalling-Station-IdandUser-Name, and goes first to the server ranked first.- The same device always reaches the same upstream: every request of a whole EAP conversation, and Start, Interim-Update and Stop of the same session, all reach the same server, with nothing more to configure. Every node computes the same result, across restarts too.
weight: the share a server gets is proportional to it;uni-b-2in the example gets about three quarters. Onlyload-balanceuses it.- When one server goes down, only the devices that ranked it first move; other devices are unaffected. EAP conversations in progress on the devices that move fail, and the NAS starts over.
- With few users the spread may lean to one server, because it depends on how names and MACs are distributed.
The automated test logs 24 devices with different MACs in with the same account: both upstreams receive requests, and the one with weight = 3 receives more.
Spooling accounting when every upstream is down
[proxy.accounting_spool]
dir = "spool/proxy"
replay_interval_ms = 5000
replay_window = 32
Without this section, forwarded accounting gets no reply when no upstream answers, and is lost after the NAS has retransmitted a few times. With it:
- When no upstream of the realm answers, the request is first written to the local
dir, and the NAS gets its reply once it is on disk. - A background task sends them again, oldest first, at most
replay_windowat a time, with the waiting time added toAcct-Delay-Time. When the upstream still does not answer, it tries again afterreplay_interval_ms. - A record is done only once the upstream answers.
- Only accounting is spooled. Logins need an answer now; when no upstream answers there is no reply, so the NAS uses its own backup.
- At least once: if the process stops between the upstream’s answer and recording progress, the same record is sent again. Upstreams must tolerate duplicates, usually judged by
Acct-Session-Id. - Order: within one batch, Start and Stop of the same session may arrive reversed. When the upstream requires strict order, set
replay_window = 1, at the cost of slower replay. - All realms share one queue. When one realm’s upstreams never answer, spooled accounting of other realms waits too.
- Make sure the spool is empty before removing a realm. When SIGHUP removes a realm, its unsent accounting moves to
rejected.log. Check thatrradius_proxy_acct_spool_bytesis 0. - Kept apart from the local accounting spool:
[radius.accounting_spool](chapter 7) covers accounting the database cannot take. The two directories must differ, and neither affects the other. - Changing this section needs a restart. The files contain personal data such as user names; keep them on a persistent disk.
Before going live
- Monitoring:
rradius_proxy_server_alive(alert on 0),rradius_proxy_acct_spool_bytes(staying above 0 means an upstream has not recovered),rradius_proxy_unanswered_total(requests no upstream answered). Servers found through DNS appear in these metrics too, with aserverlabel ofrealm host:address:port; a large federation produces many time series. - Get the timing right: each UDP upstream waits at most
timeout_ms × attempts, each RadSec upstream onetimeout_ms, and the first lookup of a realm adds the DNS time. The total must be shorter than the NAS’s timeout. - Anonymous outer names: users’ outer names are usually
[email protected]. Forwarding looks only at the realm, so this does not matter; butload-balancespreads by outer name plus MAC, so anonymous users of one realm are told apart by MAC. - CoA forwarded to upstreams by realm uses only named realm entries, not
*and not servers found through DNS. - Not tested:
- DNS discovery has not been connected to a real federation. Name matching, caching and forwarding were tested with simulated DNS; the lookup itself was tried against public DNS for one eduroam member’s records. The automated tests have no DNS, so this part is not in the scenario test.
- Replay of spooled accounting after the upstream recovers: the scenario test only checks “written to the spool and the NAS answered”; replay is covered by other tests in the project.
- The scenario test checks: our realm stays local,
*.gov.examplereaches the upstream over RadSec, the sister university is spread by weight, accounting is answered when every upstream is down, and the national proxy connects in over RadSec.
Common problems
| Symptom | Cause |
|---|---|
Our own users’ logins get no reply, with came back to this server in the log, or connections to our own port 2083 are closed | Our realm is not listed in local_realms, so it was looked up to our own server and forwarded out |
No request for some realm gets a reply, with a WARN [proxy.discovery]: realm ... in the log | The DNS lookup failed (rather than “none”), so the realm is dropped for 30 seconds. Check this host’s DNS settings (/etc/resolv.conf) |
Servers were found, but cannot connect ... TLS: | The other side’s certificate is not signed by ca_file; or realm_names_only is on and the other side’s certificate has only host names |
| A visitor’s first login is especially slow | The first lookup of the realm waits for DNS, and NAS retransmissions are dropped meanwhile. After that it is remembered for the TTL |
| A visitor’s connection fails halfway and works on retry | A load-balance upstream just went down or came back, and that device moved |
rradius_proxy_acct_spool_bytes never goes down | Some realm’s upstream has not recovered and is holding up the whole queue; rradius_proxy_server_alive shows which |
A federation peer connecting in is closed, with its certificate fits no client | No [[radius.clients]] entry has a tls_name that matches its certificate |