FreeRADIUS
FreeRADIUS is an open-source implementation of the RADIUS protocol, an IETF standard for AAA (Authentication, Authorization, and Accounting) used to manage network access and security.[1] It functions as a high-performance, modular server that supports centralized authentication for various systems, including Wi-Fi (802.1x), dial-up, PPPoE, VPNs, and VoIP services.[2] Originating in June 1999 with development led by Miquel van Smoorenburg and Alan DeKok, FreeRADIUS saw its first alpha release that August and version 0.1 in May 2001.[3] Today, it is maintained primarily by Alan DeKok and a core team including Arran Cudbard-Bell, Matthew Newton, and Alexander Clouter, with regular releases emphasizing stability and security—the latest stable version being 3.2.8 as of August 2025.[1] Licensed under the GNU General Public License version 2, the project includes a GPL-licensed AAA server, a BSD-licensed client library, and modules for PAM and Apache integration, making it freely available for download and modification.[3][2] As the world's most widely deployed RADIUS server, FreeRADIUS powers major Internet Service Providers, telecommunications companies, enterprises, and educational networks like eduroam, authenticating over one-third of all Internet users and serving more than 100 million people daily across over 50,000 sites.[1] It scales efficiently from small setups of 10 users to massive deployments exceeding 10 million, supporting back-end databases such as MySQL, PostgreSQL, Oracle, Microsoft Active Directory, Apache Cassandra, Redis, and OpenLDAP.[2] Beyond core RADIUS functionality, it extends to multi-protocol capabilities including DHCPv4, DHCPv6, DNS, TACACS+, and VMPS, offering more authentication methods than any other open-source alternative.[3][2] Commercial support is provided by InkBridge Networks, ensuring 24/7 reliability for production environments.[1]Introduction and Background
Overview
FreeRADIUS is the leading open-source implementation of the RADIUS (Remote Authentication Dial In User Service) protocol, providing centralized authentication, authorization, and accounting (AAA) services for network access control.[1][4] The RADIUS protocol operates on a client-server model, where network access servers (NAS), such as routers or Wi-Fi access points, act as clients that send authentication requests to a central RADIUS server over UDP ports 1812 for authentication and 1813 for accounting.[5] Originally developed in 1991 for dial-up remote access, RADIUS has evolved to support modern applications including Wi-Fi networks, virtual private networks (VPNs), and mobile data services.[4][5] As the most widely deployed RADIUS server globally, FreeRADIUS powers AAA infrastructure for major internet service providers (ISPs), telecommunications companies, enterprises, educational institutions like those in the eduroam federation, and cellular providers, serving over 100 million people daily across over 50,000 sites.[3][1] Production deployments often scale to handle tens of millions of users and millions of requests per day through features like request proxying, failover, and load balancing across multiple servers.[6] The latest stable version, 3.2.8, was released on August 20, 2025, with enhancements focused on stability and security.[7] FreeRADIUS includes a core GPL-licensed AAA server, a BSD-licensed RADIUS client library, a Pluggable Authentication Module (PAM) for integrating with Unix-like systems, and an Apache authentication module, enabling broad interoperability and scalability for environments supporting up to over 10 million users.[3][6]History
FreeRADIUS was founded in June 1999 by Miquel van Smoorenburg and Alan DeKok as a fork of the Cistron RADIUS server, with the goal of improving modularity and promoting open-source collaboration.[3][8] The project emphasized extensible design to support diverse authentication needs in network environments. The first public alpha release appeared in August 1999, followed by version 0.1 in May 2001.[3] The initial stable release, version 1.0.0, arrived on July 17, 2004, marking a significant milestone in its maturation as a production-ready server.[9] Major advancements came with subsequent versions. FreeRADIUS 2.0.0, released on January 10, 2008, introduced virtual servers for isolated configurations, IPv6 support for modern networking, and a policy language to simplify complex setups.[10] This version enhanced scalability for enterprise deployments. Version 3.0.0 followed on October 7, 2013, incorporating TLS-based transport via RadSec for secure proxying and expanded support for contemporary EAP methods to bolster wireless authentication.[11][12] Adoption surged in the mid-2000s, with a November 2006 survey of over 500 respondents estimating that FreeRADIUS authenticated approximately 100 million users daily, representing about one-third of global Internet access at the time.[3] By the 2010s, the project had evolved to underpin large-scale international networks, including eduroam, serving millions across educational and research institutions worldwide.[3] Over 50,000 sites now rely on it, ranging from small setups to those handling tens of millions of users.[3] As of 2025, Alan DeKok remains the project leader since its inception, supported by a core team that includes Arran Cudbard-Bell (joined 2012), Matthew Newton (joined 2016), and Alexander Clouter (joined 2009).[3] The 2.2.x series entered maintenance mode around 2014, receiving only security updates thereafter, while new development centers on the 3.x branch for ongoing innovation and stability.[9][13]Technical Architecture
Core Components
FreeRADIUS operates primarily through its core daemon,radiusd, which serves as the main server binary responsible for handling incoming and outgoing RADIUS packets. This daemon processes authentication, authorization, and accounting requests from network access servers (NAS), supporting a range of protocols including RADIUS, DHCP, and others. It can be run in foreground mode for testing or as a background service for production use. For troubleshooting, the -X option launches radiusd in debug mode, providing verbose output on packet reception, processing steps, and errors directly to stdout without requiring external tools like tcpdump.[14]
The configuration structure is centered on the primary file radiusd.conf, located by default in /etc/raddb/, which defines global server settings such as ports, logging destinations, and module instantiations. Virtual servers are managed via directories like sites-enabled/ and sites-disabled/, where symlinks in sites-enabled/ activate specific configuration files from sites-available/ to define isolated processing environments. Request processing logic is implemented using the unlang policy language, a simple scripting system embedded in configuration files that controls conditional flows, attribute manipulations, and module invocations during packet handling.[15][16]
Packet processing follows a structured flow beginning with request reception on configured UDP ports (default 1812 for authentication and authorization, 1813 for accounting). Upon receipt, the server loads relevant modules based on the virtual server configuration and evaluates the request in phases: first, the authorization phase where modules inspect attributes and set an Auth-Type to determine handling; next, the authentication phase where the selected module verifies credentials against backends; and finally, response generation, where the server constructs an Access-Accept, Access-Reject, or Accounting-Response packet with appropriate attributes before transmission back to the NAS. This flow ensures modular and policy-driven decision-making without altering the core engine.[17]
Virtual servers enable the deployment of multiple isolated instances within a single radiusd process, each with its own policies tailored to specific NAS clients, IP addresses, or proxy pools, thereby supporting diverse network environments without interference. This feature was introduced in FreeRADIUS version 2.0 to enhance scalability and flexibility in multi-tenant setups.[18]
Logging and debugging are integrated into the core runtime, with support for syslog output configured in radiusd.conf under the log section, directing messages to facilities like daemon or local0 for system-wide monitoring. Detailed packet tracing is achieved natively via the -X debug mode, which logs every step of the processing flow, including attribute decoding and module interactions, eliminating the need for additional packet capture tools.[14][19]
Modules and Extensibility
FreeRADIUS employs a modular architecture that allows for flexible extension of its core functionality through plug-in modules, enabling administrators to tailor the server to specific authentication, authorization, and accounting (AAA) needs without modifying the base code.[20] These modules, prefixed with "rlm_" (e.g., rlm_sql for database interactions), are dynamically loaded at runtime, promoting scalability and ease of maintenance.[20] The module system is configured via the mods-enabled directory, where symbolic links to modules in mods-available activate them for use in virtual servers.[20] Core module categories include authentication modules for verifying user credentials, such as PAP (Password Authentication Protocol) and CHAP (Challenge-Handshake Authentication Protocol); authorization modules for enforcing access policies, exemplified by attr_filter for attribute manipulation; and accounting modules for logging sessions, like detail for flat-file records.[20] This categorization ensures that modules can be selectively invoked during the RADIUS request processing phases. Extensibility is achieved through custom module development in C, leveraging the server's API for integrating proprietary logic or hardware-specific features, with documentation and code examples provided for developers.[1] Interoperability with network access servers (NAS) is facilitated by 92 vendor-specific dictionaries, which define attributes for devices from vendors like Cisco and Juniper, allowing seamless handling of proprietary RADIUS extensions.[21] For example, integrations with external systems include the rlm_sql module supporting databases such as MySQL, PostgreSQL, and Oracle for centralized user storage, contrasting with simpler file-based setups using modules like files for local configurations. Similarly, rlm_ldap enables authentication against directory services like OpenLDAP. The unlang policy language further enhances extensibility by providing a domain-specific syntax for conditional request routing and module selection, using constructs like if/else statements to apply logic based on attributes (e.g.,if (&User-Name) { [pap](/page/PAP) } else { reject }).[16] This allows dynamic decision-making, such as load-balancing across multiple SQL backends, without hardcoding behaviors in individual modules.[16]
Key Features
Authentication and Authorization
FreeRADIUS provides robust authentication capabilities through support for multiple protocols, enabling secure user verification in network environments. It handles basic challenge-response mechanisms such as Password Authentication Protocol (PAP), which transmits credentials in cleartext but is useful for simple integrations; Challenge Handshake Authentication Protocol (CHAP), offering one-way hashed challenges for added security; and Microsoft CHAP (MS-CHAP) variants, including MS-CHAPv2, which incorporate NTLM hashing for compatibility with Windows ecosystems.[22][23] For enterprise-grade wireless and wired access, FreeRADIUS supports Extensible Authentication Protocol (EAP) methods under IEEE 802.1X, including EAP-Transport Layer Security (EAP-TLS) for mutual certificate-based authentication, Protected EAP (PEAP) for tunneling inner methods like MS-CHAPv2 within a TLS-encrypted channel, and EAP-Tunneled TLS (EAP-TTLS) for flexible inner authentication options such as PAP or CHAP inside a TLS wrapper, facilitating secure Wi-Fi deployments like WPA2-Enterprise.[24][23] Authorization in FreeRADIUS occurs post-authentication, leveraging Attribute-Value Pairs (AVPs) to define user permissions and session parameters returned in Access-Accept responses. Standard AVPs enable assignment of user roles via attributes like Filter-Id or Class, which can specify access policies or downloadable user roles for network devices; dynamic VLAN assignment through Tunnel-Type and Tunnel-Medium-Type AVPs as defined in RFC 4675, allowing segmentation of users into specific broadcast domains; and session limits using attributes such as Session-Timeout for time-based restrictions or Simultaneous-Use checks to enforce concurrent login caps, often integrated with database modules for real-time enforcement.[25][26][27] These processes integrate with external authorization sources via modular extensions in the authorize section of the server configuration, permitting checks against LDAP, SQL, or custom scripts without altering core logic.[25][23] To enhance security in distributed setups, FreeRADIUS introduced RADIUS over TLS (RadSec) in version 3.0, providing encrypted transport for authentication and authorization packets between proxies and servers, mitigating eavesdropping risks on untrusted networks.[11][28] Compatibility with diverse hardware is ensured through included dictionary files for nearly 100 vendors, defining over 4000 vendor-specific attributes (AVPs), translating attributes for Network Access Servers (NAS) from manufacturers like Cisco, Aruba, and Juniper, supporting seamless interoperability across more than 100 device types.[21][29] Performance is optimized via a multi-threaded architecture, where a pool of child threads processes requests in parallel from a central queue, enabling high-throughput authentication suitable for large-scale deployments.[30][23] In optimized configurations with in-memory user storage and lightweight methods like PAP, FreeRADIUS can handle tens of thousands of requests per second, equating to millions of authentications per day in production environments such as ISPs or enterprise campuses.[23] For EAP-based methods like PEAP, throughput remains in the thousands per second, limited primarily by CPU-intensive TLS operations rather than architectural constraints.[23][31]Accounting and Integration
FreeRADIUS implements RADIUS accounting through the Accounting-Request packets sent by Network Access Servers (NAS) to track user sessions, utilizing Accounting-Response packets from the server to acknowledge receipt.[32] These requests support three primary types: Start (indicating session initiation), Stop (session termination), and Interim-Update (periodic updates during active sessions for real-time monitoring).[33] The protocol captures attributes such as session duration, data transferred (e.g., AcctInputOctets and AcctOutputOctets), and NAS identifiers to enable comprehensive session logging.[32] Accounting data in FreeRADIUS can be stored in SQL databases via the rlm_sql module, which inserts records into tables like radacct for structured querying and long-term retention.[34] Alternatively, the detail module provides flat-file storage by appending textual logs of all accounting requests to directory-based files (e.g., /var/radacct/Configuration and Administration
Setup and Configuration
FreeRADIUS can be installed using package managers on various Linux distributions for a straightforward deployment. On Debian and Ubuntu systems, the server is available through the Advanced Package Tool (APT) with the commandapt install freeradius, which installs the latest stable version along with essential utilities.[43] Similarly, on Red Hat Enterprise Linux (RHEL), CentOS, or Rocky Linux, the Yellowdog Updater, Modified (YUM) or DNF package manager handles installation via yum install freeradius or dnf install freeradius, pulling from official repositories.[44] For environments requiring custom builds, compiling from source involves downloading the tarball from the official site (e.g., version 3.2.8), extracting it, and running ./configure && make && make install. Key dependencies include libtalloc for memory management and development libraries such as OpenSSL (libssl-dev on Debian) for TLS support, along with build tools like gcc and make.[45][46][47]
Initial configuration begins with the default files in /etc/freeradius/ (or /etc/raddb/ on some systems), which provide a functional starting point. The main radiusd.conf file defines listen directives, such as listen { type = auth port = 1812 ipaddr = * } for authentication on the standard UDP port, and similar for accounting on port 1813; these defaults suffice for basic setups but can be adjusted for specific interfaces.[48] The clients.conf file specifies Network Access Servers (NAS) with entries like client localhost { ipaddr = 127.0.0.1 secret = testing123 } to allow local testing, extending to remote clients by adding their IP addresses and shared secrets.[43] For simple authentication testing, the users file (or mods-config/files/authorize in version 3.x) is edited to include entries such as "testing" Cleartext-Password := "password", enabling flat-file user validation without external backends.[48]
To verify the configuration, start the server in debug mode using radiusd -X from the configuration directory, monitoring the output for "Ready to process requests" and any syntax errors. Local testing employs the radtest utility, for example, radtest testing password 127.0.0.1 0 testing123, which should return an "Access-Accept" if successful, with debug logs showing packet reception, authentication flow, and response.[43][48]
Basic security hardening involves restricting the server's runtime environment and network exposure. In radiusd.conf, set user = freerad and group = freerad to run the process with minimal privileges, ensuring configuration files are owned by root with group freerad and permissions like 640 to prevent unauthorized access. Firewall rules must allow inbound UDP traffic on ports 1812 (authentication) and 1813 (accounting) only from trusted client IP ranges, using tools like iptables or firewalld (e.g., firewall-cmd --add-port=1812/[udp](/page/UDP) --permanent). For TLS-enabled setups, generate certificates by running ./bootstrap in the /etc/freeradius/certs/ directory to create self-signed test keys, which should be replaced with CA-issued ones in production.[49][50][23]
Common pitfalls during setup include incorrect module enablement order, where unlinked modules in mods-enabled/ fail to load—resolved by symlinking in dependency sequence via ln -s ../mods-available/sql /etc/freeradius/mods-enabled/ and restarting. Dictionary loading errors often arise from mismatched vendor dictionaries; debug mode reveals these as "Failed to find dictionary" messages, fixed by verifying dictionary directives in radiusd.conf. IPv6 configuration issues occur if listen blocks lack ipaddr = ::, causing bind failures—add explicit IPv6 addresses and test with radtest over IPv6.
Management Tools
FreeRADIUS administration is supported by a variety of graphical user interfaces (GUIs) and command-line utilities designed to simplify ongoing management tasks such as user provisioning, monitoring, and reporting. Web-based GUIs like daloRADIUS provide MySQL-backed interfaces for comprehensive user management, including listing, creating, editing, searching, and deleting users, as well as quick-add features for hotspot environments.[51] daloRADIUS, in its 2.2 beta release dated July 3, 2024, also offers graphical reporting on online users, connection attempts, top bandwidth consumers, and system logs, alongside geolocation integration using OpenStreetMap for mapping hotspot locations and statuses.[52] Another prominent web GUI is RADIUSdesk, version 2021-B released on November 29, 2021, which focuses on advanced provisioning for OpenWrt-based hardware in Wi-Fi mesh networks supporting standards from Wi-Fi 3 to Wi-Fi 6.[53][54] Command-line utilities bundled with FreeRADIUS enable efficient testing and validation without graphical overhead. The radclient tool sends authentication and accounting requests to the server, displaying responses to verify functionality during troubleshooting or development. For EAP-based scenarios, eapol_test simulates client authentication, allowing administrators to test Extensible Authentication Protocol methods directly from the terminal. Configuration validation is handled by the radiusd -XC command, which parses server files for syntax errors and reports issues without starting the full daemon, aiding in safe deployments.[55] Additional tools include phpRADmin, a PHP-based web interface for basic configuration, client (NAS) administration, and user provisioning, suitable for simpler setups.[56] ezRadius offers a web-based management application for FreeRADIUS and hotspot integrations like Chillispot, emphasizing ease of use for administrators, though it receives limited updates with the last major activity in 2013.[57] Across these tools, common capabilities encompass user provisioning via database backends, NAS device monitoring for status and performance, visualization of accounting data such as session durations and usage, and hooks for billing system integrations to automate revenue tracking.[51][54] Maintenance considerations favor actively supported projects; for instance, daloRADIUS benefits from ongoing GitHub contributions and community issue resolution.[51] In contrast, Dialup Admin, an older PHP4-based web interface for user and client management, is deprecated and unmaintained, potentially incompatible with modern PHP versions and carrying security risks.[58] Administrators are recommended to prioritize tools like daloRADIUS for robust, current support in production environments.[51]Deployment and Applications
Installation Guidelines
FreeRADIUS supports deployment on various Unix-like platforms, including Linux distributions such as Ubuntu and CentOS, BSD variants like FreeBSD, and Windows through the Cygwin environment for development or testing purposes.[59][60] For containerized environments, official Docker images are available, enabling straightforward deployment in modern orchestration setups like Kubernetes.[61] These options ensure compatibility with diverse production infrastructures, though official support prioritizes Unix-based systems for optimal performance.[1] Before installation, ensure the system meets key prerequisites. Core dependencies include development tools like gcc and make for building from source, as well as libraries such as libtalloc for memory management and OpenSSL for TLS support.[62] If using SQL backends for authentication or accounting, install a database server like MySQL or PostgreSQL and prepare the schema by importing FreeRADIUS-provided SQL scripts, typically located in the source distribution'sraddb/mods-config/sql/ directory after installation. Basic system administration knowledge is required, but no prior RADIUS expertise is necessary.[63]
Linux Distributions
For Debian-based systems like Ubuntu, the simplest method is using the package manager. Update the repositories withsudo apt update, then install the server via sudo apt install freeradius. This pulls in core packages including freeradius-common and utilities. For the latest stable version (3.2.8 as of August 2025), consider adding the InkBridge Networks repository by downloading their GPG key (curl -fsSL https://packages.inkbridgenetworks.com/keyring.gpg | gpg --dearmor -o /etc/apt/keyrings/inkbridge-freeradius.gpg) and creating the sources list (echo "deb [signed-by=/etc/apt/keyrings/inkbridge-freeradius.gpg] https://packages.inkbridgenetworks.com/freeradius-3.2/debian $(lsb_release -cs) main" | [sudo](/page/Sudo) tee /etc/apt/sources.list.d/freeradius.list), followed by sudo apt update && [sudo](/page/Sudo) apt install freeradius.[60][7] After installation, verify the service with [sudo](/page/Sudo) systemctl status freeradius; if not running, enable and start it using [sudo](/page/Sudo) systemctl enable --now freeradius.[64]
On Red Hat-based distributions like Rocky Linux or AlmaLinux, use DNF or YUM. Enable the EPEL repository (sudo dnf install epel-release), then install with sudo dnf install freeradius. Similarly, for the latest from InkBridge, add their repository key and sources (sudo rpm --import https://packages.inkbridgenetworks.com/RPM-GPG-KEY-InkBridge-Networks and sudo tee /etc/yum.repos.d/freeradius.repo <<EOF [inkbridge] name=InkBridge Networks baseurl=https://packages.inkbridgenetworks.com/freeradius-3.2/rhel-\$releasever/\$basearch gpgcheck=1 gpgkey=https://packages.inkbridgenetworks.com/RPM-GPG-KEY-InkBridge-Networks enabled=1 EOF), followed by sudo dnf install freeradius.[60] Verification follows the same systemd commands as above. Building from source is recommended for custom needs: download the tarball from freeradius.org/releases/, extract it, run ./configure, make, and sudo make install.[47]
BSD and Windows
On FreeBSD, install via the ports system or packages:sudo pkg install freeradius3 for the latest version, which handles dependencies automatically. The configuration directory defaults to /usr/local/etc/raddb/, and the service can be enabled with sudo sysrc freeradius_enable="YES" and started via sudo service freeradius start. For Windows, FreeRADIUS lacks native binaries but can be compiled using Cygwin; install Cygwin with packages including gcc, make, openssl-devel, and talloc-devel, then build from source as on Linux, though this is primarily for testing and not recommended for production due to performance limitations.
Docker
For containerized deployments, pull the official image withdocker pull freeradius/freeradius-server:latest. Run it using docker run -d --name freeradius -p 1812:1812/udp -p 1813:1813/udp -v /path/to/raddb:/etc/freeradius freeradius/freeradius-server, mounting a local directory for persistent configuration. This setup supports SQL backends by linking to an external database container.[61] Ensure Docker is installed and the host firewall allows UDP ports 1812 (authentication) and 1813 (accounting).[65]
In production environments, deploy FreeRADIUS in high-availability configurations using multiple server instances behind a load balancer to distribute traffic and ensure failover. Shared storage for configurations and a replicated database (e.g., MySQL Galera Cluster) prevents data loss during outages.[66][67] Regularly back up the raddb or /etc/freeradius/ directory and database schemas. For upgrades from version 2 to 3, note that while much of the configuration is compatible, v3 introduces structural changes like unlang policy language; install v3 alongside v2 initially, migrate users and modules incrementally, and test thoroughly before switching, as direct replacement is not supported.[68][69]
Common installation issues include missing dependencies, leading to configure or make failures—resolve by installing required packages like libssl-dev on Debian or openssl-devel on Red Hat. Permission errors on configuration files (e.g., /etc/freeradius/ owned by root) can prevent startup; fix with sudo [chown](/page/Chown) -R freerad:freerad /etc/freeradius/. If the service fails to start, run radiusd -X in debug mode to identify errors like invalid modules or port conflicts. Post-installation, perform security scans using tools like Lynis or OpenVAS to check for vulnerabilities in dependencies.[70][71] For persistent problems, consult the official mailing list with debug output.[72]