FreeRADIUS Commands

FreeRADIUS is the authentication server that handles all PPPoE/Hotspot subscriber connections. These commands help you manage the RADIUS service.

🔴 HIGH RISK - CRITICAL SERVICE

FreeRADIUS is the core authentication service. Stopping or restarting it will:

• Disconnect ALL active subscribers immediately
• Prevent new connections until service is restored
• Cause billing/session tracking issues

Only restart during scheduled maintenance windows (e.g., 2-4 AM)

---

Table of Contents

1. Service Management
2. Debug Mode
3. Testing Authentication
4. Log Management
5. Configuration
6. Troubleshooting

---

Service Management

Check FreeRADIUS Status

sudo systemctl status freeradius

Purpose: Shows if FreeRADIUS is running and recent activity.

---

Start FreeRADIUS

sudo systemctl start freeradius

Purpose: Starts the FreeRADIUS service.

---

Stop FreeRADIUS

🔴 COMPLETE SERVICE OUTAGE

Stopping FreeRADIUS will immediately disconnect ALL subscribers and prevent any new connections.

sudo systemctl stop freeradius

Purpose: Completely stops the RADIUS service.

When to use:

• Emergency troubleshooting
• Major configuration changes
• Server migration

---

Restart FreeRADIUS

🔴 SUBSCRIBER DISCONNECTION

Restarting will briefly disconnect all active sessions. New sessions will reconnect automatically.

sudo systemctl restart freeradius

Purpose: Stops and starts FreeRADIUS. Required after configuration changes.

Best Practice:

• Schedule during low-usage hours (2-4 AM)
• Notify subscribers in advance if possible
• Have support ready for reconnection issues

---

Reload FreeRADIUS

sudo systemctl reload freeradius

Purpose: Attempts graceful reload. Note: Not all config changes support reload.

---

Enable FreeRADIUS on Boot

sudo systemctl enable freeradius

---

Debug Mode

Run FreeRADIUS in Debug Mode

🟠 STOP SERVICE FIRST

Debug mode requires stopping the main service. This will disconnect subscribers.

# Stop the service first
sudo systemctl stop freeradius

# Run in debug mode (foreground)
sudo freeradius -X

Purpose: Shows detailed authentication process. Essential for troubleshooting.

Press Ctrl+C to stop debug mode, then restart the service:

sudo systemctl start freeradius

---

Debug with Specific Config

sudo freeradius -X -d /etc/freeradius/3.0/

---

Testing Authentication

Test User Authentication (radtest)

radtest username password localhost 0 testing123

Parameters:

• username - Subscriber username
• password - Subscriber password
• localhost - RADIUS server (use actual IP for remote)
• 0 - NAS port (usually 0)
• testing123 - RADIUS secret (check your config)

Example:

radtest testuser testpass 127.0.0.1 0 your_radius_secret

Success Response:

Received Access-Accept Id 123 from 127.0.0.1:1812 to 127.0.0.1:12345 length 20

Failure Response:

Received Access-Reject Id 123 from 127.0.0.1:1812 to 127.0.0.1:12345 length 20

---

Test with Attributes

echo "User-Name=testuser,User-Password=testpass" | radclient -x localhost auth testing123

---

Test Accounting

echo "User-Name=testuser,Acct-Status-Type=Start" | radclient -x localhost acct testing123

---

Log Management

View RADIUS Logs (Real-time)

sudo tail -f /var/log/freeradius/radius.log

---

View Detail Logs (Accounting)

sudo tail -f /var/log/freeradius/radacct/*/detail-*

---

Search for Specific User

sudo grep "username" /var/log/freeradius/radius.log

---

Check Log File Sizes

sudo du -sh /var/log/freeradius/*

---

Clear Old Logs

🟠 CAUTION

This removes log history. Back up if needed for auditing.

# Clear main log
sudo truncate -s 0 /var/log/freeradius/radius.log

# Remove old detail files (older than 30 days)
sudo find /var/log/freeradius/radacct -name "detail-*" -mtime +30 -delete

---

Configuration

Configuration Directory

ls -la /etc/freeradius/3.0/

Main Configuration Files

# Main config
sudo nano /etc/freeradius/3.0/radiusd.conf

# SQL module (database connection)
sudo nano /etc/freeradius/3.0/mods-available/sql

# Clients (NAS devices)
sudo nano /etc/freeradius/3.0/clients.conf

# Default site (authentication flow)
sudo nano /etc/freeradius/3.0/sites-available/default

Check SQL Module is Enabled

ls -la /etc/freeradius/3.0/mods-enabled/ | grep sql

Enable SQL Module

sudo ln -s /etc/freeradius/3.0/mods-available/sql /etc/freeradius/3.0/mods-enabled/

---

Troubleshooting

Common Issues

Authentication Failing

# Run in debug mode to see exact error
sudo systemctl stop freeradius
sudo freeradius -X
# Try to authenticate, watch output

Database Connection Issues

# Test MySQL connection
mysql -u radius -p radius -e "SELECT 1"

# Check SQL config
sudo grep -A5 "server = " /etc/freeradius/3.0/mods-available/sql

NAS Not Connecting

# Check clients.conf has correct NAS IP and secret
sudo grep -A5 "client" /etc/freeradius/3.0/clients.conf

# Check if NAS IP can reach RADIUS
sudo tcpdump -i any port 1812 or port 1813

Port Already in Use

# Check what's using RADIUS ports
sudo netstat -tlnp | grep -E "1812|1813"
sudo lsof -i :1812

---

Check RADIUS Ports

# Authentication port: 1812
# Accounting port: 1813
# CoA port: 3799
sudo netstat -tlnp | grep -E "1812|1813|3799"

---

Test Database Connectivity

# From RADIUS server
mysql -u radius -p -h localhost radius -e "SELECT COUNT(*) FROM radcheck;"

---

Quick Reference Card

Action	Command
Check status	sudo systemctl status freeradius
Start	sudo systemctl start freeradius
Stop	sudo systemctl stop freeradius
Restart	sudo systemctl restart freeradius
Debug mode	sudo freeradius -X
Test auth	radtest user pass localhost 0 secret
View logs	sudo tail -f /var/log/freeradius/radius.log
Config dir	/etc/freeradius/3.0/