FreeRADIUS

Last reviewed Sep 13, 2026 · 849 words

The reason a self-hoster runs FreeRADIUS is one feature: giving every person and every device on the Wi-Fi its own username and password, so revoking the ex-housemate means deleting one line rather than changing the shared key on 40 devices. That is WPA-Enterprise, it needs a RADIUS server, and FreeRADIUS has been the reference implementation since 1999. It is GPL-2.0, written in C, runs in 256 MB with room to spare, and is rated Hard in the catalogue for a reason that is entirely about configuration, not resources.

The config directory is the learning curve

FreeRADIUS is not configured; it is programmed, in a directory of text files with its own policy language. On Debian the tree is /etc/freeradius/3.0/, upstream it is /etc/raddb/, and either way the files that matter for a first install are three. clients.conf lists the devices allowed to ask questions, with a shared secret each:

client unifi-aps {
    ipaddr = 192.168.1.0/24
    secret = a-long-random-string-for-the-aps
}

mods-config/files/authorize (the users file in older docs) holds local accounts, and can attach attributes such as the VLAN a user lands on:

alice   Cleartext-Password := "correct-horse-battery"
        Tunnel-Type = VLAN,
        Tunnel-Medium-Type = IEEE-802,
        Tunnel-Private-Group-ID = 20

And mods-available/eap configures the certificate and inner methods for Wi-Fi. Start with freeradius -X in a terminal, which runs in the foreground with full debug output, and keep radtest alice correct-horse-battery localhost 0 testing123 in the other window. Every FreeRADIUS problem I have ever had was solved by reading the -X output slowly, and the project's own documentation says the same. Open UDP 1812 for authentication and 1813 for accounting, and point your access points at it. UniFi, Omada, OpenWrt, and most enterprise-grade switches have a RADIUS profile field waiting for exactly this.

The PEAP-versus-LDAP trap

The default Wi-Fi method on Windows, Android, and iOS is PEAP with MSCHAPv2 inside. MSCHAPv2 requires the server to know the user's password in cleartext or as an NT hash; it cannot verify against a salted hash. So wiring FreeRADIUS to an LDAP directory that stores hashed passwords, which is what lldap and most sensible directories do, results in every Wi-Fi login failing with a debug log that says the password is wrong when it is not. This is the single most common reason a homelab FreeRADIUS install stalls.

Three ways out. Store NT hashes in the directory (Samba-style sambaNTPassword, which FreeIPA can maintain). Use EAP-TTLS with PAP inside instead of PEAP, which sends the password to FreeRADIUS inside the TLS tunnel so any backend can check it, at the cost of fiddlier client configuration on Windows. Or skip passwords for Wi-Fi entirely and issue certificates.

EAP-TLS is the grown-up answer

EAP-TLS authenticates a device by client certificate rather than a password, which sidesteps the hash problem, cannot be phished, and survives a directory outage. Run a small private CA, sign one certificate per device, install it in the device's Wi-Fi profile, and give FreeRADIUS the CA to trust in mods-available/eap. It is more work per device and needs an MDM-shaped plan for phones, but for laptops and IoT that stay in the house it is the setup I would build today. Per-device VLAN assignment then keys off the certificate's common name in the authorize file, and the smart-TV that phones home lands on a VLAN that goes nowhere.

When a simpler tool is enough

If the goal is VPN or switch login with plain passwords rather than Wi-Fi, authentik has a RADIUS outpost that answers PAP requests against its own user database, and Keycloak has community RADIUS bridges. Those cover "log in to OpenVPN with my SSO password" without learning the FreeRADIUS policy language, and the SSO comparison covers that stack. They do not cover EAP-TLS, PEAP, dynamic VLANs, or the accounting side, and the moment you need any of those you are back to FreeRADIUS, which is also the only option in the identity category with a Docker image, freeradius/freeradius-server, that behaves exactly like the package install if you mount the config directory over /etc/raddb.

What I'd do

Install the distribution package on a small VM or LXC, not Docker, because you will be in -X mode a lot and the package layout matches every tutorial. Get radtest passing against a local user first, then one access point with PEAP and a local NT-hashed user, then VLAN assignment. Only then decide between EAP-TLS for devices and a directory for people. Budget a weekend for the first working Wi-Fi login and an evening for each step after. It is the most flexible AAA server there is; the Hard rating is the cost of that flexibility, and there is no lighter tool that does the same job.