How to Install FreeRADIUS with MariaDB on Debian 13
Install FreeRADIUS 3.2 on Debian 13 with MariaDB as the user and accounting database, then verify it with a test user and radtest.
This guide installs FreeRADIUS 3.2 on Debian 13 (trixie) and connects it to a MariaDB database, so that users, their attributes and accounting records live in SQL tables instead of flat files. At the end you will have a server that answers a test authentication request for a user stored in the database. The same steps apply to Debian 12 (bookworm), which also ships FreeRADIUS 3.2. Debian 7 has been unsupported for years, and the FreeRADIUS 2 layout it used (sql.conf and $INCLUDE lines in radiusd.conf) no longer exists.
Requirements
- A Debian 13 or Debian 12 server and a user with
sudorights. - UDP ports 1812 (authentication) and 1813 (accounting) reachable from your network devices.
- The IP address of each device that will send RADIUS requests (access point, VPN gateway, switch).
Step 1: Install FreeRADIUS and MariaDB
sudo apt update
sudo apt install -y freeradius freeradius-mysql freeradius-utils mariadb-server
freeradius-mysql provides the SQL driver, which also works with MariaDB, and freeradius-utils provides test tools such as radtest. On Debian the configuration lives in /etc/freeradius/3.0/, the service is called freeradius and it runs as the user freerad.
Step 2: Create the database and load the schema
Create an empty database. On Debian, root connects to MariaDB through the local socket without a password:
sudo mariadb -e "CREATE DATABASE radius;"
FreeRADIUS ships the table definitions. Import them:
sudo sh -c 'mariadb radius < /etc/freeradius/3.0/mods-config/sql/main/mysql/schema.sql'
The same directory contains setup.sql, which creates a database user named radius with only the privileges the server needs: read access to the user tables and write access to accounting. The file contains the well-known default password radpass. Replace it with your own before importing. Avoid /, & and quote characters in the password so the command works unchanged:
sudo sed -i "s/radpass/CHANGE_THIS_PASSWORD/" /etc/freeradius/3.0/mods-config/sql/main/mysql/setup.sql
sudo sh -c 'mariadb radius < /etc/freeradius/3.0/mods-config/sql/main/mysql/setup.sql'
Check the tables:
sudo mariadb -e "SHOW TABLES;" radius
The list includes radcheck, radreply, radgroupcheck, radgroupreply, radusergroup, radacct, radpostauth and nas.
Step 3: Configure the SQL module
Open the module configuration:
sudo nano /etc/freeradius/3.0/mods-available/sql
Change the dialect and the driver. The defaults are sqlite and rlm_sql_null:
dialect = "mysql"
driver = "rlm_sql_${dialect}"
Further down, uncomment the connection settings and enter your password:
server = "localhost"
port = 3306
login = "radius"
password = "CHANGE_THIS_PASSWORD"
radius_db = "radius"
Inside the mysql { ... } block of the same file there is a tls { ... } sub-section that points to example certificate files and sets tls_required = yes. Those files do not exist on your server. For a database on the same host, comment out every line of that sub-section, from tls { to its closing brace.
If you want to keep your RADIUS clients in the nas table instead of clients.conf, also uncomment read_clients = yes. Clients are read from the table only when the server starts.
Enable the module by linking it into mods-enabled:
sudo ln -s ../mods-available/sql /etc/freeradius/3.0/mods-enabled/sql
You do not need to edit the virtual servers for basic use. In FreeRADIUS 3.2 the default and inner-tunnel sites already list -sql in their authorize, accounting and post-auth sections; the leading dash means the module is used whenever it is enabled. Only the session section has sql commented out. Uncomment it there if you want Simultaneous-Use checks.
Step 4: Add a client
Every device that talks to the server needs an entry with a shared secret. Add a block to /etc/freeradius/3.0/clients.conf:
client office-ap {
ipaddr = 198.51.100.20
secret = USE_A_LONG_RANDOM_SECRET
}
The file already contains a localhost client with the secret testing123, which the test below uses. Change that secret once testing is finished, because it is public knowledge.
Step 5: Create a test user and verify
Insert a user into radcheck:
sudo mariadb radius -e "INSERT INTO radcheck (username, attribute, op, value) VALUES ('alice', 'Cleartext-Password', ':=', 'test-password');"
Stop the service and run the server in the foreground in debug mode. This is the standard way to test any FreeRADIUS change, because it prints every step:
sudo systemctl stop freeradius
sudo freeradius -X
Wait for Ready to process requests. If the server exits instead, the last lines name the file and line that is wrong. In a second terminal send a request:
radtest alice test-password 127.0.0.1 0 testing123
A working setup answers with Received Access-Accept, and the debug output shows the query against radcheck. Press Ctrl+C in the first terminal and start the service normally:
sudo systemctl enable --now freeradius
sudo systemctl status freeradius
Step 6: Open the firewall
If you use UFW, allow RADIUS only from your network devices:
sudo ufw allow from 198.51.100.20 to any port 1812,1813 proto udp
With nftables or another firewall, allow UDP 1812 and 1813 from the same addresses.
Working with the tables
| Table | Purpose |
|---|---|
radcheck | Per-user check items, such as the password |
radreply | Per-user attributes returned in the Access-Accept |
radusergroup | Which user belongs to which group |
radgroupcheck, radgroupreply | Check and reply items for a whole group |
radacct | Accounting sessions |
radpostauth | Log of authentication attempts |
nas | RADIUS clients, when read_clients = yes |
The database user created by setup.sql can only read the user tables, so add and change users as the MariaDB root user or through a separate administrative account.
Frequently asked questions
The service fails to start after I enabled the SQL module. Where do I look?
Run sudo freeradius -X and read the last lines. Typical causes are a wrong password in mods-available/sql, the tls sub-section still being active, the freeradius-mysql package missing, or the driver still set to rlm_sql_null.
Do passwords have to be stored in clear text?
No. radcheck also accepts hashed attributes such as SHA2-Password or Crypt-Password, but hashed passwords only work with PAP-style authentication. CHAP needs the clear-text password, and MS-CHAPv2 needs either the clear-text password or the NT-Password hash.
Can the database run on another host?
Yes. Set server to that host, create the radius database user for the RADIUS server's address instead of localhost, and configure the tls sub-section with real certificate files rather than disabling it.
Is a web interface such as phpMyAdmin required?
No. FreeRADIUS needs only the database. A web front end for editing the tables is optional and adds another service you have to keep secure.