Skip to content

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

  1. The NAS targets the local relay node’s LAN IP (192.168.1.50).
  2. The relay node uses iptables DNAT to rewrite the destination to the AWS WireGuard internal IP (10.0.0.1).
  3. The relay node uses MASQUERADE so the packet exits over the wg0 interface with source IP 10.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

  1. 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.
  2. Accounting Deduplication: Use a central cache layer keyed on Acct-Unique-Session-Id to prevent duplicate billing entries caused by UDP packet retries.