Freeradius Setup and Scaling
Setting up a robust Authentication, Authorization, and Accounting (AAA) infrastructure is a cornerstone of modern network engineering. Whether you are connecting remote branch offices, managing a campus Wi-Fi network, or scaling an Internet Service Provider (ISP), FreeRADIUS remains the industry gold standard.
In this deep dive, we’ll walk through the modern architecture of FreeRADIUS: running it in Docker, routing across dynamic WANs using secure relays, calling external APIs via rlm_rest, and scaling across multiple nodes in an ISP environment.
Core Architecture: FreeRADIUS + Docker + Remote NAS
A standard RADIUS deployment consists of three main entities: 1. Supplicant / Client: The user device trying to connect. 2. Network Access Server (NAS): The router, switch, OpenVPN gateway, or access point enforcing network access. 3. AAA Server: FreeRADIUS processing credentials and accounting metrics.
Secure WAN Relay Architecture
When your NAS resides in a remote location (like a home office or branch behind a dynamic IP) and FreeRADIUS is hosted in the cloud (e.g., AWS EC2), sending unencrypted PAP (Password Authentication Protocol) traffic over the public internet exposes credentials to eavesdropping and brute-force attacks.
To solve this without opening public ports or requiring complex hardware site-to-site VPNs, you can deploy a local WireGuard Relay Node (such as a Raspberry Pi or Mini PC):
[ Home Router (NAS) ]
|
| 1. Cleartext RADIUS / PAP (Local LAN: UDP 1812 / 1813)
v
[ Local Relay Node (WireGuard Client) ]
|
| 2. Encrypted Tunnel (UDP 51820 over Public WAN)
v
[ AWS EC2 / FreeRADIUS Docker (10.0.0.1) ]
Running freefadius in docker container
# cat docker-compose.yaml
services:
freeradius:
image: freeradius/freeradius-server:latest
container_name: freeradius
restart: unless-stopped
ports:
- "1812:1812/udp" # RADIUS Authentication
- "1813:1813/udp" # RADIUS Accounting
volumes:
- ./config/clients.conf:/etc/freeradius/clients.conf:ro
- ./config/users:/etc/freeradius/mods-config/files/authorize:ro
- ./config/default:/etc/freeradius/sites-enabled/default:ro
- ./logs/radacct:/var/log/freeradius/radacct
command: ['-X']
config file
# Allow requests from local container loopback for testing
client localhost {
ipaddr = 127.0.0.1
secret = testing123
shortname = localhost
}
# Allow requests from your local network range (e.g., Access Points/Routers)
client local_subnet {
ipaddr = 192.168.1.0/24
secret = MySharedSecret123
shortname = local-network
}
client docker_network {
ipaddr = 172.16.0.0/12
secret = testing123
shortname = docker
}
authorize file
"john_doe" Cleartext-Password := "MySecurePassword123"
Reply-Message = "Hello John, access granted."
"alice" Cleartext-Password := "SecretPass456"
Reply-Message = "Hello Alice, access granted."
sites-enabled/default file
server default {
listen {
type = auth
ipaddr = *
port = 0 # use default (1812)
}
listen {
type = acct
ipaddr = *
port = 0 # use default (1813)
}
authorize {
files
pap
}
authenticate {
Auth-Type PAP {
pap
}
}
accounting {
detail
}
session {
}
post-auth {
Post-Auth-Type REJECT {
attr_filter.access_reject
}
}
}
NAT & Routing Mechanics on the Relay Node
- The NAS targets the local relay node’s LAN IP (
192.168.1.50). - The relay node uses
iptablesDNAT to rewrite the destination to the AWS WireGuard internal IP (10.0.0.1). - The relay node uses MASQUERADE so the packet exits over the
wg0interface with source IP10.0.0.2.
# On the Relay Node (e.g., Raspberry Pi)
sudo iptables -t nat -A PREROUTING -p udp --dport 1812 -j DNAT --to-destination 10.0.0.1:1812
sudo iptables -t nat -A PREROUTING -p udp --dport 1813 -j DNAT --to-destination 10.0.0.1:1813
sudo iptables -t nat -A POSTROUTING -o wg0 -j MASQUERADE
FreeRADIUS Production Configuration
Below are the key configuration files required to run a secure FreeRADIUS instance accepting requests over the WireGuard overlay network.
clients.conf (Defining Authorized NAS Clients)
# /etc/freeradius/3.0/clients.conf
client wireguard_relay {
ipaddr = 10.0.0.2
secret = SuperComplexSharedSecret2026!
shortname = home-relay-node
}
users (File-Based User Authorization)
# /etc/freeradius/3.0/mods-config/files/authorize
"john_doe" Cleartext-Password := "MySecurePassword123"
Reply-Message = "Welcome to the Network!",
Acct-Interim-Interval = 300
default (Virtual Server configuration with Accounting & Interim Updates)
The Acct-Interim-Interval instructs the NAS to send periodic bandwidth and session updates (every 300 seconds in this example).
# /etc/freeradius/3.0/sites-available/default
server default {
listen {
type = auth
ipaddr = *
port = 1812
}
listen {
type = acct
ipaddr = *
port = 1813
}
authorize {
filter_username
preprocess
files
}
authenticate {
Auth-Type PAP {
pap
}
}
post-auth {
# Inject Interim Update Interval for all authenticated sessions
update reply {
Acct-Interim-Interval := 300
}
}
accounting {
detail
}
}
Dynamic Management: CoA & Disconnect Packets (RFC 3576 / 5176)
In standard RADIUS, communication is purely client-initiated. Change of Authorization (CoA) flips this model, allowing FreeRADIUS to push unsolicited requests to the NAS on UDP port 3799.
CoA-Request: Updates active session attributes (e.g., throttling bandwidth when a quota is reached).Disconnect-Request(PoD): Immediately drops an active user session.
# Example: Disconnecting an active user session using radclient
echo "User-Name = john_doe, Acct-Session-Id = session-xyz" | \
radclient -x 10.0.0.2:3799 disconnect SuperComplexSharedSecret2026!
Note on OpenVPN as a NAS: Standard OpenVPN does not include a native RADIUS CoA listener on port 3799 out of the box. To terminate sessions dynamically, integrate FreeRADIUS with OpenVPN’s local management socket (
management 127.0.0.1 7505) or leverage an external script.
Modern Integrations: Webhooks via rlm_rest
FreeRADIUS can integrate with modern microservice architectures using the rlm_rest module. This allows you to evaluate login attempts against an external HTTP API in real time.
[ User ] --> (Access-Request) --> [ FreeRADIUS ] --> (HTTP POST JSON) --> [ External API ]
| |
Evaluates Unlang Returns HTTP 200 OK
v |
[ User ] <-- (Access-Accept) ------------+<------------------------------------+
Configuration (mods-available/rest)
rest {
connect_uri = "https://api.yourdomain.com/v1"
timeout = 5
authenticate {
uri = "${..connect_uri}/radius/auth"
method = 'post'
body = 'json'
data = '{ \
"username": "%{User-Name}", \
"nas_ip": "%{NAS-IP-Address}", \
"mac_address": "%{Calling-Station-Id}" \
}'
headers {
"Content-Type" = "application/json"
"Authorization" = "Bearer YOUR_API_KEY"
}
}
}
Unlang Logic (sites-available/default)
authorize {
filter_username
rest
if (handled) {
update control {
Auth-Type := Accept
}
} else {
reject
}
}
Scaling Out: ISP-Grade High Availability & Load Balancing
For service providers handling millions of authentication requests, a single server creates a dangerous single point of failure. ISPs deploy a tiered architecture:
[ BNG / BRAS Edge Routers ]
|
(Anycast / VIP: UDP 1812/1813)
v
+------------------------------------+
| Tier 1: FreeRADIUS Proxies | <-- Intelligent Layer 7 Routers
+------------------------------------+
/ | \
(Load Balance) (Load Balance) (Load Balance)
v v v
+-------+ +-------+ +-------+
| Node1 | | Node2 | | Node3 | <-- Tier 2: Stateless Worker Nodes
+-------+ +-------+ +-------+
\ | /
v v v
+------------------------------------+
| Tier 3: Shared Central Storage | <-- Redis Cluster / MySQL Galera
+------------------------------------+
Proxy Configuration (proxy.conf)
FreeRADIUS can act as a high-performance, application-aware load balancer that monitors backend health using Status-Server probes:
home_server worker_1 {
type = auth+acct
ipaddr = 10.0.1.11
port = 1812
secret = SharedInternalSecret
status_check = status-server
}
home_server worker_2 {
type = auth+acct
ipaddr = 10.0.1.12
port = 1812
secret = SharedInternalSecret
status_check = status-server
}
home_server_pool isp_pool {
type = load-balance
home_server = worker_1
home_server = worker_2
}
realm default {
auth_pool = isp_pool
acct_pool = isp_pool
}
Key Scaling Considerations
- Stateful EAP Sessions: EAP handshakes require multiple round trips. Use Keyed Load Balancing (hashing on
Calling-Station-Id) or share session states across nodes using an in-memory Redis Cluster. - Accounting Deduplication: Use a central cache layer keyed on
Acct-Unique-Session-Idto prevent duplicate billing entries caused by UDP packet retries.