Troubleshooting¶

This section covers common problems seen in eduroam deployments and day-to-day operations.

Quick Diagnostic Checklist¶

Run through this checklist first — it resolves the majority of issues:

Common User Issues¶

Repeated password prompts¶

Typical causes:

• incorrect username format, for example missing @realm
• expired or changed password
• stale device profile
• server certificate not trusted

Recommended actions:

• confirm the username is in the format user@institution.ac.ke
• remove the old eduroam profile and install a fresh profile
• use eduroam CAT where available
• verify date and time on the device

Certificate warning during connection¶

Users must not ignore certificate warnings. A warning usually means:

• the device was not configured with the correct trust settings
• the institution changed its RADIUS server certificate
• the user connected to a misconfigured or rogue network

If certificate validation fails, reconnect only after installing the correct profile or confirming the expected server name and CA.

Connected but no Internet access¶

Check:

• DHCP scope availability
• user VLAN assignment
• firewall policy
• DNS reachability
• AP/controller policy for the eduroam SSID

FreeRADIUS Troubleshooting¶

Run in debug mode¶

Use debug mode when validating configuration changes:

systemctl stop freeradius
freeradius -X

For packaged FreeRADIUS 3.x on some platforms, radiusd -X is equivalent.

Debug mode shows:

• incoming requests
• realm matching and proxy decisions
• EAP state machine details
• LDAP, SQL, and policy processing
• accept or reject reasons

Validate configuration before restart¶

freeradius -XC

Use this after editing virtual servers, modules, clients, realms, or policy files.

Test local authentication¶

Simple PAP test against a local user or backend:

radtest user@institution.ac.ke 'test-password' 127.0.0.1 0 testing123

Use eapol_test for realistic 802.1X/EAP testing where available.

SP-Side Problems¶

Requests not leaving the SP¶

Check:

• clients.conf entries for APs/controllers
• source IP and shared secret
• firewall rules permitting UDP 1812 and 1813
• realm proxy configuration
• home server reachability

Requests proxied but no reply received¶

Check:

• upstream federation IPs and shared secrets
• NAT or firewall state expiry
• duplicate or incorrect home server definitions
• packet filtering between SP and federation servers

Users authenticate but land in the wrong VLAN¶

Check:

• whether the AP/controller honors standard tunnel attributes
• authorization policy order in sites-enabled/default
• group lookup results in LDAP or SQL
• controller-side VLAN mapping and role policy

Expected RADIUS attributes usually include:

Tunnel-Type = VLAN
Tunnel-Medium-Type = IEEE-802
Tunnel-Private-Group-Id = "20"

IdP-Side Problems¶

Inner authentication fails¶

Check:

• PEAP or TTLS inner method configuration
• LDAP bind account and search filter
• Active Directory group policy restrictions
• password expiry or account lockout

Realm is not routed correctly¶

Check:

• local realm definitions
• nostrip versus strip behavior
• federation registration for the institution realm
• whether the user is typing the correct realm

Certificate-related failures¶

Check:

• certificate chain completeness
• server name matching
• expiration dates
• EKU and KU fields
• whether the issuing CA is distributed to clients

Failure Scenarios¶

Scenario 1 — All users cannot connect (institution-wide outage)¶

This typically means the RADIUS server is down or the server certificate has expired.

Step 1 — Check the FreeRADIUS service

systemctl status freeradius
journalctl -u freeradius --since '1 hour ago'
freeradius -X        # run in debug mode to see startup errors

Step 2 — Check certificate expiry

openssl x509 -in /etc/ssl/certs/radius.crt -noout -enddate -subject
openssl verify -CAfile /etc/ssl/certs/ca-bundle.crt /etc/ssl/certs/radius.crt

If the certificate is expired: request emergency replacement from your CA, install it, run service freeradius reload, and update CAT profiles immediately.

Step 3 — Check configuration syntax

freeradius -C

Scenario 2 — Visitors cannot connect, locals work¶

The proxy chain is broken. The local RADIUS server is working but cannot forward foreign-realm requests to the NRO.

Step 1 — Test NRO connectivity

radtest testing@nrotest.eduroam.org Radius1 <NRO_IP> 1812 <shared_secret>
# Expected: Access-Accept or Access-Reject (not a timeout)

Step 2 — Check proxy configuration

grep -A5 'realm ~' /etc/freeradius/3.0/proxy.conf
grep -A8 'home_server eduroam' /etc/freeradius/3.0/proxy.conf

Step 3 — Check shared secret mismatch

A mismatch produces invalid Message-Authenticator errors in the debug log. Verify the shared secret matches the NRO's configuration exactly.

Step 4 — Review proxy log entries

freeradius -X 2>&1 | grep -i 'proxy\|home_server\|realm'

Scenario 3 — One specific user cannot connect¶

A user-specific issue: account problem, expired password, or device misconfiguration.

Step 1 — Search the RADIUS log for this user

grep 'username@domain' /var/log/freeradius/radius.log | tail -20
# Look for: Access-Reject, EAP failure, LDAP error

Step 2 — Test LDAP authentication directly

ldapsearch -x -H ldap://your-ad.institution.edu \
  -D 'uid=username,dc=inst,dc=edu' -W \
  -b 'dc=inst,dc=edu' '(uid=username)'

Step 3 — Common user-specific causes

• account locked or disabled in Active Directory/LDAP
• password expired — user must change it before eduroam works again
• user not in the required group for eduroam access
• device has an outdated or incorrect CAT profile
• device manually configured with wrong EAP type or wrong CA

Scenario 4 — Device or OS-specific failures¶

Scenario 5 — Intermittent or slow authentication¶

Slow authentication (5–30 second delays)

• DNS reverse lookup failure: add hostname_lookups = no in radiusd.conf
• LDAP query slow: check LDAP server load; optimize the search filter
• NRO response slow: increase response_window in proxy.conf; check the network path
• EAP session timeout too short: check eap { timer_expire = 60 }

Intermittent failures

• RADIUS server overloaded: check CPU/memory; increase max_requests in radiusd.conf
• Packet loss to NRO: run mtr --udp --port 1812 <NRO_IP> to identify the path
• LDAP connection pool exhausted: increase pool.max in the LDAP module configuration
• Auth race condition on roam: expected behavior; add retry_delay = 5 in client config

Log Reference — Common Error Messages¶

Escalation Path¶

Logging and Monitoring¶

Useful locations vary by distribution, but common paths include:

• /var/log/freeradius/radius.log
• /var/log/freeradius/radacct/
• journalctl -u freeradius

Monitor at least:

• authentication success and failure rate
• proxy latency
• certificate expiry
• AP/controller RADIUS timeout rate
• accounting volume and SQL write failures

Operational monitoring schedule¶