How To Install FreeRADIUS on Debian 13
Setting up a centralized authentication system has become essential for modern IT infrastructure. Network administrators face increasing challenges managing user access across multiple devices and services. FreeRADIUS emerges as the premier solution for implementing robust authentication, authorization, and accounting (AAA) services.
This comprehensive guide walks through the complete installation and configuration process of FreeRADIUS on Debian 13. The tutorial covers everything from initial system preparation to advanced security hardening, ensuring your RADIUS server meets enterprise-grade standards.
Prerequisites and System Requirements
System Specifications
FreeRADIUS installation on Debian 13 requires specific hardware and software prerequisites. Your system needs a minimum of 2GB RAM and a dual-core processor running at 2GHz or higher. Storage requirements include at least 1GB of free disk space for the base installation, though production environments should allocate significantly more space for logs and database storage.
Network connectivity proves crucial for package downloads and client communications. Ensure your Debian 13 system maintains stable internet access during the installation process. The system should also have properly configured DNS resolution to avoid connectivity issues during package installation.
Required Knowledge Base
Successful FreeRADIUS deployment demands familiarity with Linux command-line operations and basic networking concepts. Understanding TCP/UDP protocols, IP addressing, and subnet configurations helps troubleshoot connectivity issues. System administrators should possess sudo privileges and know how to navigate file systems, edit configuration files, and manage system services.
RADIUS protocol fundamentals include authentication flows, client-server communication patterns, and shared secret mechanisms. While deep protocol knowledge isn’t mandatory for basic installations, understanding these concepts facilitates advanced configurations and troubleshooting scenarios.
Pre-installation System Verification
Before beginning the FreeRADIUS installation process, verify your Debian 13 system version and architecture compatibility. Execute the following commands to confirm system specifications:
lsb_release -a
uname -a
df -h
free -mCheck network interface configurations and firewall settings that might interfere with RADIUS communications. Document current iptables rules and network configurations for rollback purposes if needed. Verify that ports 1812 (authentication) and 1813 (accounting) remain available for RADIUS services.
Plan your authentication backend strategy during this phase. Decide whether to implement file-based user management, database integration, or external authentication systems like LDAP. This decision influences subsequent configuration steps and package selections.
System Preparation and Updates
Comprehensive System Updates
Debian 13 system preparation begins with updating all existing packages to their latest versions. This process ensures compatibility with FreeRADIUS packages and resolves potential security vulnerabilities. Execute the following commands in sequence:
sudo apt update
sudo apt upgrade -y
sudo apt autoremove -y
sudo apt autocleanThe update process might require system restart if kernel updates occur. Monitor the update output for any error messages or package conflicts that require manual intervention. Some packages might prompt for configuration decisions during the upgrade process.
Installing Essential Dependencies
FreeRADIUS requires several supporting packages and libraries for optimal functionality. Install the core dependencies using the following command:
sudo apt install -y build-essential libssl-dev libpam0g-dev \
libtalloc-dev libpcre3-dev libsqlite3-dev libmysqlclient-dev \
libpq-dev libldap2-dev libkrb5-dev wget curl gitDatabase integration options require additional packages depending on your chosen backend. For MariaDB/MySQL support, install the mysql-server package. PostgreSQL users should install postgresql-server-dev-all. LDAP integration requires libldap2-dev and related authentication modules.
SSL/TLS functionality demands openssl and certificate management tools. These packages enable secure communications between RADIUS clients and servers, essential for production deployments. Development tools facilitate building additional modules or compiling from source when needed.
Network and Security Configuration
Configure firewall rules to allow RADIUS traffic while maintaining system security. FreeRADIUS uses UDP ports 1812 and 1813 for authentication and accounting respectively. Create firewall rules that permit these ports while restricting access to trusted network segments:
sudo ufw allow from 192.168.1.0/24 to any port 1812
sudo ufw allow from 192.168.1.0/24 to any port 1813
sudo ufw enableTime synchronization plays a critical role in authentication protocols and certificate validation. Install and configure NTP services to maintain accurate system time:
sudo apt install -y ntp
sudo systemctl enable ntp
sudo systemctl start ntpFreeRADIUS Installation Methods
Repository-Based Installation
Installing FreeRADIUS from Debian repositories represents the most straightforward approach for most deployments. This method provides pre-compiled packages with automatic dependency resolution and integrated system management. Execute the installation using apt package manager:
sudo apt update
sudo apt install -y freeradius freeradius-utils freeradius-commonThe repository installation includes essential FreeRADIUS modules and utilities required for basic operation. Additional modules for database integration, LDAP authentication, or specialized protocols install separately based on requirements. Check available modules using:
apt search freeradius-Repository installations benefit from automatic security updates and seamless integration with Debian’s package management system. The installation creates system users, directory structures, and service definitions automatically. However, repository versions might lag behind the latest FreeRADIUS releases.
Building from Source Code
Source compilation provides maximum flexibility and access to the latest FreeRADIUS features. This approach suits environments requiring specific module combinations or custom modifications. Download the source code from the official FreeRADIUS GitHub repository:
cd /tmp
wget https://github.com/FreeRADIUS/freeradius-server/releases/download/release_3_2_8/freeradius-server-3.2.8.tar.gz
tar -xzf freeradius-server-3.2.8.tar.gz
cd freeradius-server-3.2.8Configure the build environment with desired options and module selections:
./configure --prefix=/usr/local --sysconfdir=/etc --with-openssl
make -j$(nproc)
sudo make installSource installations require manual service management and update procedures. Create systemd service files and user accounts manually. While more complex, this method enables customized installations tailored to specific requirements.
Version Selection Considerations
Debian 13 repositories typically include FreeRADIUS version 3.2.x, which provides stable, well-tested functionality suitable for production environments. This version includes comprehensive protocol support, mature module ecosystem, and extensive documentation. Consider version 4.x for cutting-edge features, though it may require source compilation.
Evaluate long-term support implications when choosing installation methods. Repository installations receive security updates through Debian’s update mechanisms, while source installations require manual maintenance. Balance feature requirements against maintenance overhead when making this decision.
Initial Configuration Setup
Understanding Directory Structure
FreeRADIUS configuration files reside in /etc/freeradius/ directory structure. The main configuration file, radiusd.conf, controls global server behavior and module loading. Individual module configurations exist in the mods-available directory, with active modules linked from mods-enabled.
Key configuration directories include:
/etc/freeradius/radiusd.conf– Main server configuration/etc/freeradius/clients.conf– Network client definitions/etc/freeradius/users– File-based user accounts/etc/freeradius/sites-available/– Virtual server configurations/etc/freeradius/mods-available/– Available modules/etc/freeradius/certs/– SSL certificates and keys
Log files typically store in /var/log/freeradius/ directory, though this location is configurable. Understanding this structure facilitates efficient configuration management and troubleshooting procedures.
Basic Server Configuration
Primary server configuration occurs in radiusd.conf file, which defines global parameters, security settings, and module loading behavior. Edit this file to configure basic server operations:
sudo nano /etc/freeradius/radiusd.confKey configuration parameters include:
# Basic server settings
prefix = /usr
exec_prefix = ${prefix}
sysconfdir = /etc
localstatedir = /var
sbindir = ${exec_prefix}/sbin
logdir = ${localstatedir}/log/radius
raddbdir = ${sysconfdir}/freeradius
radacctdir = ${logdir}/radacct
# Security settings
security {
max_attributes = 200
reject_delay = 1
status_server = yes
}
# Thread pool configuration
thread pool {
start_servers = 5
max_servers = 32
min_spare_servers = 3
max_spare_servers = 10
}Configure network listeners to specify which interfaces and ports FreeRADIUS monitors for incoming requests. Default configurations listen on all interfaces, but production deployments should restrict this for security purposes.
Client Configuration Management
Network client configuration defines which devices can communicate with your RADIUS server. Edit the clients.conf file to add network access servers (NAS), wireless access points, and other authentication clients:
sudo nano /etc/freeradius/clients.confAdd client definitions using the following format:
client switch01 {
ipaddr = 192.168.1.10
secret = your_shared_secret_here
require_message_authenticator = yes
shortname = sw01
nas_type = cisco
}
client wireless_controller {
ipaddr = 192.168.1.0/24
secret = another_shared_secret
shortname = wlc
nas_type = other
}Shared secrets provide authentication between RADIUS clients and servers. Use strong, unique secrets for each client and avoid default values. Consider implementing certificate-based authentication for enhanced security in high-security environments.
Initial Testing Procedures
Verify FreeRADIUS installation and basic functionality using debug mode and command-line testing tools. Start the server in debug mode to observe initialization and identify configuration errors:
sudo freeradius -XDebug mode output reveals module loading sequences, configuration parsing results, and error messages. Look for “Ready to process requests” message indicating successful startup. Address any error messages before proceeding with client testing.
Test basic authentication using the radtest utility:
radtest testuser testpass localhost 0 testing123This command attempts authentication against the local RADIUS server using default test credentials. Successful responses indicate proper server operation, while failures require debugging through log analysis and configuration review.
Database Integration Configuration
Database Server Installation
Database integration enhances FreeRADIUS scalability and management capabilities. MariaDB provides excellent compatibility and performance for RADIUS deployments. Install and configure the database server:
sudo apt install -y mariadb-server mariadb-client
sudo mysql_secure_installationThe security script prompts for root password configuration, anonymous user removal, and test database deletion. Follow security best practices by enabling all recommended security measures. Create a dedicated database and user account for FreeRADIUS operations:
CREATE DATABASE radius;
CREATE USER 'radiususer'@'localhost' IDENTIFIED BY 'secure_password';
GRANT ALL PRIVILEGES ON radius.* TO 'radiususer'@'localhost';
FLUSH PRIVILEGES;Configure MariaDB for optimal performance with FreeRADIUS workloads. Adjust buffer pool sizes, connection limits, and query cache settings based on expected authentication volumes. Monitor database performance during initial deployment phases.
Schema Import and Configuration
FreeRADIUS includes standard database schemas for common database systems. Import the MariaDB schema to create required tables and indexes:
mysql -u radiususer -p radius < /etc/freeradius/mods-config/sql/main/mysql/schema.sqlThe schema creates tables for user accounts (radcheck, radreply), group memberships (radgroupcheck, radgroupreply), and accounting data (radacct). Additional tables support NAS client definitions and other advanced features.
Verify schema import success by connecting to the database and examining table structures:
USE radius;
SHOW TABLES;
DESCRIBE radcheck;Populate initial user accounts and group definitions using SQL INSERT statements or administrative tools like phpMyAdmin. Consider implementing stored procedures for complex account management operations.
SQL Module Configuration
Enable and configure the SQL module for database connectivity. Edit the SQL module configuration file:
sudo nano /etc/freeradius/mods-available/sqlConfigure database connection parameters:
sql {
driver = "rlm_sql_mysql"
dialect = "mysql"
server = "localhost"
port = 3306
login = "radiususer"
password = "secure_password"
radius_db = "radius"
read_clients = yes
client_table = "nas"
# Connection pool settings
pool {
start = 5
min = 4
max = 32
spare = 3
uses = 0
retry_delay = 30
lifetime = 0
idle_timeout = 60
}
}Enable the SQL module by creating a symbolic link:
sudo ln -s /etc/freeradius/mods-available/sql /etc/freeradius/mods-enabled/Test database connectivity by starting FreeRADIUS in debug mode and observing SQL module initialization messages. Connection failures require reviewing credentials, network connectivity, and database server status.
User Management and Authentication
Database User Account Creation
Database-driven user management provides scalability and centralized control over authentication credentials. Create user accounts by inserting records into the radcheck and radreply tables. Basic user creation follows this pattern:
INSERT INTO radcheck (username, attribute, op, value)
VALUES ('testuser', 'Cleartext-Password', ':=', 'testpassword');
INSERT INTO radreply (username, attribute, op, value)
VALUES ('testuser', 'Framed-IP-Address', '=', '192.168.100.10');Group-based management simplifies administrative overhead for large user populations. Create groups with common attributes and assign users to appropriate groups:
INSERT INTO radgroupcheck (groupname, attribute, op, value)
VALUES ('employees', 'Cleartext-Password', ':=', '%{User-Password}');
INSERT INTO radgroupreply (groupname, attribute, op, value)
VALUES ('employees', 'Framed-Protocol', '=', 'PPP');
INSERT INTO radusergroup (username, groupname, priority)
VALUES ('testuser', 'employees', 1);Implement password policies through database constraints and application logic. Consider password complexity requirements, expiration dates, and account lockout mechanisms for enhanced security.
Authentication Protocol Configuration
FreeRADIUS supports multiple authentication protocols to accommodate diverse client requirements. Configure common protocols including PAP (Password Authentication Protocol), CHAP (Challenge Handshake Authentication Protocol), and various EAP methods.
PAP provides simple password-based authentication suitable for basic deployments:
# In /etc/freeradius/sites-available/default
authenticate {
Auth-Type PAP {
pap
}
}CHAP offers enhanced security by avoiding plaintext password transmission:
authenticate {
Auth-Type CHAP {
chap
}
}EAP methods support advanced authentication scenarios including certificate-based authentication and tunneled protocols. Configure EAP-TLS for certificate-based authentication:
eap {
default_eap_type = tls
tls-config tls-common {
private_key_password = whatever
private_key_file = ${certdir}/server.pem
certificate_file = ${certdir}/server.pem
ca_file = ${cadir}/ca.pem
}
}Authorization and Access Control
Authorization policies determine user access rights and network resource allocation. Configure authorization rules through database attributes, unlang policies, or external systems. Common authorization attributes include VLAN assignments, bandwidth limitations, and session timeouts.
Implement VLAN-based network segmentation:
INSERT INTO radreply (username, attribute, op, value)
VALUES ('employee1', 'Tunnel-Type', '=', 'VLAN');
INSERT INTO radreply (username, attribute, op, value)
VALUES ('employee1', 'Tunnel-Medium-Type', '=', 'IEEE-802');
INSERT INTO radreply (username, attribute, op, value)
VALUES ('employee1', 'Tunnel-Private-Group-Id', '=', '100');Time-based access controls restrict authentication during specific periods. Implement login hour restrictions using unlang policies:
if ("%{sql:SELECT COUNT(*) FROM radcheck WHERE username='%{User-Name}' AND attribute='Login-Time'}") {
if ("%{Login-Time}" !~ /Al0800-1700/) {
reject
}
}Configure accounting policies to track user sessions, bandwidth consumption, and connection patterns. Accounting data supports billing systems, capacity planning, and security monitoring initiatives.
Advanced Security Configuration
SSL/TLS Certificate Management
SSL/TLS certificates secure communications between RADIUS clients and servers, particularly for EAP-TLS authentication scenarios. Generate server certificates using OpenSSL or obtain certificates from trusted certificate authorities. Create self-signed certificates for testing environments:
cd /etc/freeradius/certs
sudo openssl genrsa -out server.key 2048
sudo openssl req -new -key server.key -out server.csr
sudo openssl x509 -req -days 365 -in server.csr -signkey server.key -out server.crtProduction deployments should use certificates from trusted CAs to avoid client certificate validation issues. Configure certificate paths in the EAP module:
eap {
tls-config tls-common {
private_key_file = ${certdir}/server.key
certificate_file = ${certdir}/server.crt
ca_file = ${cadir}/ca.crt
dh_file = ${certdir}/dh2048.pem
random_file = /dev/urandom
}
}Implement certificate revocation checking through OCSP or CRL mechanisms for enhanced security. Monitor certificate expiration dates and implement automated renewal procedures to prevent service disruptions.
Network Access Server Configuration
Network infrastructure devices require proper RADIUS client configuration to communicate with FreeRADIUS servers. Configure switches, wireless controllers, and VPN concentrators with appropriate shared secrets and RADIUS server addresses.
Cisco switch configuration example:
aaa new-model
aaa authentication login default group radius local
aaa authorization network default group radius local
radius-server host 192.168.1.100 key shared_secret
radius-server timeout 3
radius-server retransmit 2Implement RADIUS server redundancy by configuring multiple RADIUS servers on network devices. This approach ensures authentication availability during server maintenance or failures:
radius-server host 192.168.1.100 key secret1 auth-port 1812 acct-port 1813
radius-server host 192.168.1.101 key secret2 auth-port 1812 acct-port 1813Test NAS connectivity using device-specific testing commands and monitor authentication logs for successful communications. Document all shared secrets securely and implement regular rotation schedules.
Security Hardening Measures
Implement comprehensive security hardening to protect FreeRADIUS installations from unauthorized access and attacks. Restrict file system permissions on configuration files and certificate keys:
sudo chmod 640 /etc/freeradius/clients.conf
sudo chown root:freerad /etc/freeradius/clients.conf
sudo chmod 600 /etc/freeradius/certs/*.keyConfigure system-level access controls using PAM and sudo policies. Limit shell access for the freerad user account and implement logging for all administrative activities. Enable fail2ban protection against brute-force attacks:
sudo apt install -y fail2ban
sudo nano /etc/fail2ban/jail.localAdd FreeRADIUS protection rules:
[freeradius]
enabled = true
port = 1812,1813
protocol = udp
filter = freeradius
logpath = /var/log/freeradius/radius.log
maxretry = 6
bantime = 3600Implement network-level security through firewall rules, intrusion detection systems, and network segmentation. Regular security assessments and penetration testing validate security configurations and identify potential vulnerabilities.
Testing and Troubleshooting
Comprehensive Testing Procedures
Systematic testing validates FreeRADIUS functionality across different authentication scenarios and client types. Begin with local testing using radtest utility before progressing to network device testing. Create comprehensive test plans covering various user types, authentication methods, and network conditions.
Execute authentication tests from different network segments:
# Local testing
radtest testuser testpass localhost 0 testing123
# Remote testing from client network
radtest employee1 password123 192.168.1.100 0 sharedsecret
# EAP testing using eapol_test
eapol_test -c eap-test.conf -s sharedsecretLoad testing identifies performance bottlenecks and capacity limitations. Use tools like radclient to simulate multiple concurrent authentication requests:
echo "User-Name = testuser, User-Password = testpass" | \
radclient -c 100 -p 10 192.168.1.100:1812 auth testing123Monitor system resources during load testing and adjust thread pool configurations, database connection limits, and memory allocations as needed. Document performance baselines for capacity planning purposes.
Debug Mode Analysis
FreeRADIUS debug mode provides detailed insight into authentication flows, module processing, and error conditions. Start the server in debug mode and analyze output systematically:
sudo freeradius -X -l stdoutDebug output includes request parsing, module execution sequences, database queries, and response generation. Common issues manifest through specific error patterns:
- Authentication failures show in “Auth-Type” processing
- Database connectivity issues appear during SQL module initialization
- Certificate problems manifest in EAP-TLS negotiations
- Client configuration errors show as “unknown client” messages
Create log analysis procedures and automated monitoring for production environments. Implement alerting mechanisms for critical error conditions and authentication failure patterns.
Common Issue Resolution
Authentication failures require systematic diagnosis starting with basic connectivity and progressing through configuration validation. Verify shared secrets match between clients and server configurations. Check user account existence and password accuracy in authentication databases.
Database connectivity issues often result from incorrect credentials, network restrictions, or service availability problems. Verify database server status, connection parameters, and firewall rules affecting database communications.
Certificate-related errors in EAP-TLS scenarios require validation of certificate chains, expiration dates, and key file permissions. Use OpenSSL commands to verify certificate validity and chain completeness:
openssl x509 -in /etc/freeradius/certs/server.crt -text -noout
openssl verify -CAfile /etc/freeradius/certs/ca.crt /etc/freeradius/certs/server.crtPerformance issues may indicate insufficient system resources, database optimization requirements, or network latency problems. Monitor system metrics during authentication peaks and adjust configurations accordingly.
Maintenance and Monitoring
Regular Maintenance Procedures
Proactive maintenance ensures optimal FreeRADIUS performance and security posture. Implement regular system updates including operating system patches, FreeRADIUS updates, and security fixes. Schedule maintenance windows during low-usage periods to minimize service impact.
Database maintenance includes regular backup procedures, index optimization, and data archiving. Implement automated backup scripts with off-site storage:
#!/bin/bash
DATE=$(date +%Y%m%d_%H%M%S)
mysqldump -u radiususer -p radius > /backup/radius_${DATE}.sql
find /backup -name "radius_*.sql" -mtime +30 -deleteLog file management prevents disk space exhaustion and maintains system performance. Configure log rotation through logrotate:
/var/log/freeradius/*.log {
daily
missingok
rotate 30
compress
notifempty
create 640 freerad freerad
postrotate
/bin/kill -HUP `cat /var/run/freeradius/freeradius.pid 2> /dev/null` 2> /dev/null || true
endscript
}Certificate renewal procedures prevent authentication disruptions. Monitor certificate expiration dates and implement automated renewal for certificates from automated certificate authorities like Let’s Encrypt.
Performance Monitoring Implementation
Comprehensive monitoring identifies performance trends and potential issues before they impact users. Implement monitoring for authentication success rates, response times, concurrent sessions, and system resource utilization. Use tools like Nagios, Zabbix, or Prometheus for infrastructure monitoring.
Configure SNMP monitoring for network device integration and centralized management. FreeRADIUS includes SNMP support for monitoring server statistics and performance metrics:
# Enable SNMP in radiusd.conf
snmp {
smux_password = monitoring_secret
}Database performance monitoring tracks query execution times, connection pool utilization, and storage growth patterns. Implement slow query logging and regular performance analysis:
SET GLOBAL slow_query_log = 'ON';
SET GLOBAL long_query_time = 2;Create automated alerting for critical conditions including authentication failure spikes, database connectivity issues, certificate expiration warnings, and system resource exhaustion.
Documentation and Change Management
Maintain comprehensive documentation covering system architecture, configuration details, troubleshooting procedures, and administrative processes. Document all customizations, security configurations, and integration procedures for knowledge transfer and disaster recovery purposes.
Implement change management procedures for configuration modifications, software updates, and infrastructure changes. Use version control systems like Git for configuration file management:
cd /etc/freeradius
git init
git add .
git commit -m "Initial FreeRADIUS configuration"Regular security assessments validate configuration compliance and identify potential vulnerabilities. Conduct periodic reviews of user accounts, client configurations, certificate validity, and access control policies. Implement security scanning and vulnerability assessment procedures.
Advanced Features and Extensions
Web-Based Management Integration
Administrative web interfaces simplify FreeRADIUS management for non-technical users and provide centralized control panels. daloRADIUS represents a popular PHP-based management interface offering user account management, reporting capabilities, and administrative functions.
Install daloRADIUS dependencies and configure web server integration:
sudo apt install -y apache2 php php-mysql php-cli php-common php-curl php-mbstring
sudo systemctl enable apache2
sudo systemctl start apache2Download and configure daloRADIUS:
cd /tmp
wget https://github.com/lirantal/daloradius/archive/master.zip
unzip master.zip
sudo mv daloradius-master /var/www/html/daloradius
sudo chown -R www-data:www-data /var/www/html/daloradiusWeb interface integration provides graphical user management, reporting dashboards, and configuration tools. However, maintain command-line expertise for troubleshooting and advanced configurations not accessible through web interfaces.
High Availability and Clustering
Enterprise deployments require redundancy and failover capabilities to ensure authentication service availability. Implement FreeRADIUS clustering using database replication, load balancers, and coordinated configurations across multiple servers.
Configure master-slave database replication for user account synchronization:
-- On master server
CHANGE MASTER TO MASTER_HOST='192.168.1.101',
MASTER_USER='replication_user',
MASTER_PASSWORD='replication_password';
START SLAVE;Load balancer configuration distributes authentication requests across multiple FreeRADIUS servers while providing health checking and automatic failover. Configure network devices with multiple RADIUS server addresses for client-side redundancy.
Monitor cluster health through automated testing and alerting mechanisms. Implement synchronized configuration management to maintain consistency across cluster members.
Scalability and Performance Optimization
Large-scale deployments require performance tuning and scalability optimizations. Adjust thread pool configurations, database connection limits, and memory allocations based on authentication volumes and response time requirements.
Configure FreeRADIUS for high-performance scenarios:
thread pool {
start_servers = 10
max_servers = 64
min_spare_servers = 5
max_spare_servers = 15
max_requests_per_server = 0
}Database optimization includes connection pooling, query optimization, and storage engine selection. Implement read replicas for reporting queries and write separation for performance improvement.
Consider horizontal scaling through geographical distribution and regional RADIUS servers. Implement proxy configurations for request routing and load distribution across multiple authentication domains.
Congratulations! You have successfully installed FreeRADIUS. Thanks for using this tutorial for installing FreeRADIUS on the Debian 13 “Trixie” system. For additional help or useful information, we recommend you check the official FreeRADIUS website.
