Operating System Debian

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 sudo rights.
  • 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

TablePurpose
radcheckPer-user check items, such as the password
radreplyPer-user attributes returned in the Access-Accept
radusergroupWhich user belongs to which group
radgroupcheck, radgroupreplyCheck and reply items for a whole group
radacctAccounting sessions
radpostauthLog of authentication attempts
nasRADIUS 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.

Share story:

Continue reading other guides on How VPS.