Table of Contents

FreeRADIUS 3: Build-Out & Integration

Jennifer Trower Updated by Jennifer Trower

Read Time: 08 mins

This guide is intended for users who wish to set up FreeRADIUS for use with Sonar. It leverages FreeRADIUS Genie, an installer that simplifies the configuration process, and is built for compatibility with Ubuntu 24.04 and FreeRADIUS 3.

Building the RADIUS Server

Getting Started

This installer is intended for use on Ubuntu 24.04 64bit with FreeRADIUS 3, but it should also work on other Ubuntu versions. First, install Ubuntu on the server where you plan to run FreeRADIUS. If you're hosting it online, Digital Ocean is a recommended option.

  1. Install Ubuntu 24.04 on your server.
  2. SSH into your server and run the following commands in preparation:
    1. sudo apt-get updates
    2. sudo apt-get upgrade
    3. sudo apt-get install php-cli php-mbstring php-mysql unzip git
      If you're on an older Ubuntu version, use this command instead to install the required PHP 5 packages and unzip:

      sudo apt-get install php5-cli php5-mbstring php5-mysql unzip git
  3. After running the initial commands, install MariaDB (a drop-in replacement for MySQL) and the FreeRADIUS server by using the following commands:
    1. sudo apt-get install mariadb-server mariadb-client
    2. sudo apt-get install freeradius freeradius-common freeradius-utils freeradius-mysql
  4. Download FreeRADIUS Genie:
    1.  git clonehttps://github.com/SonarSoftwareInc/freeradius_genie-v3.git
  5. Navigate into the FreeRADIUS Genie directory:
    1. cd freeradius_genie-v3

Hosting Considerations

If you're hosting your server online, it likely doesn't have swap memory set up. For servers with low RAM (1–2 GB), or even more, it's a good idea to add swap space to avoid out-of-memory errors. The swap file size should be at least equal to your server’s RAM and at most double the RAM. A simple rule is to match your swap size to your RAM and increase it to 2x only if needed. If you still get memory errors after doubling it, upgrade your server’s RAM instead of increasing swap further. You can also refer to the Ubuntu Swap FAQ for more guidance.

To set up swap, run these commands as root or use sudo:

  1. /usr/bin/fallocate -l 4G /swapfile where 4G is equal to the size of the swap file in gigabytes.
  2. /bin/chmod 600 /swapfile
  3. /sbin/mkswap /swapfile
  4. /sbin/swapon /swapfile
  5. echo "/swapfile none swap sw 0 0" >> /etc/fstab
  6. /sbin/sysctl vm.swappiness=10
  7. echo "vm.swappiness=10" >> /etc/sysctl.conf
  8. /sbin/sysctl vm.vfs_cache_pressure=50
  9. echo "vm.vfs_cache_pressure=50" >> /etc/sysctl.conf

Completing Preliminary Installation

With all required software installed, the next step is to secure and configure your SQL database. Run the following command:

sudo /usr/bin/mysql_secure_installation

Then answer the prompts like this:

  1. Enter current password for root (enter for none): Press Enter
  2. Set root password? [Y/n]: Type y
  3. New password: Enter a strong password and save it—you’ll need it soon
  4. Remove anonymous users? [Y/n]: Type y
  5. Disallow root login remotely? [Y/n]: Type y
  6. Remove test database and access to it? [Y/n]: Type y
  7. Reload privilege tables now? [Y/n]: Type y

After completing these steps, you’ll have a basic setup with FreeRADIUS and MySQL ready for initial configuration.

Configuration

To let the Sonar Genie tool finish the setup, you need to add your MySQL root password to a config file.

  1. Copy the example file and open it:
    1. cp .env.example .env
    2. nano .env
  2. Find the line that says MYSQL_PASSWORD=changeme, delete changeme, and replace it with the MySQL root password you set earlier.
  3. Press CTRL+X, then confirm to save and exit.

Be sure to save this password somewhere safe—you’ll need it again later.

Once that’s done, you’re ready to start using Genie!

Genie

Genie is a command‑line tool created to automate the setup and configuration of your FreeRADIUS server. You’ll use it to walk through the initial setup so you don’t need to edit configuration files or work directly in MySQL. Run: php genie

First Steps

Start by setting up the database:

  1. In the Genie menu, highlight Initial Configuration, press the space bar to select it, then press Enter.
  2. Select Setup initial database structure, press the space bar, then press Enter again. This will create the database structure.
    If you see a credentials error, double-check the MySQL root password in your .env file in the Configuration section.

Next, configure FreeRADIUS files:

  1. Select Perform initial FreeRADIUS configuration, press the space bar, then press Enter.
  2. This sets up FreeRADIUS to use the SQL server as a backend and restarts it.

Managing Your NAS

A NAS (Network Access Server) is the device that connects to your RADIUS server to manage client access—usually something like a PPPoE concentrator in ISP setups.

To add a NAS using Genie:

  1. Run php genie to open the tool.
  2. From the main menu, select NAS Configuration, then Add NAS.
  3. Enter the NAS’s IP address and a short name for it when prompted.

Genie will generate a random secret—make sure to copy it. You’ll need to enter it into your PPPoE concentrator (for example, a MikroTik router).

Connecting MikroTik to Your RADIUS Server

Now that your RADIUS server is set up, you can connect it to your MikroTik router to manage PPPoE sessions. These steps may vary depending on your NAS device, so check the manual if needed.

To configure RADIUS in MikroTik using WinBox:

  1. Go to RADIUS in the left menu.
  2. Click the + button to add a new RADIUS server.
  3. Fill out the form:
    1. Check the PPP checkbox.
    2. In Address, enter your RADIUS server’s IP.
    3. In Secret, enter the random secret Genie gave you.
    4. In Src. Address, enter the IP address you used when adding the NAS in Genie.

That’s it—your MikroTik is now using RADIUS for PPPoE!

You can view all NAS entries in Genie by selecting List NAS Entries, or remove one using Remove NAS.

Configuring MySQL for Remote Access

To let Sonar connect to your RADIUS server, you need to enable remote access in MySQL.

  1. In Genie, go to the MySQL Remote Access Configuration menu.
  2. Select Enable remote access — this allows MySQL to accept connections from outside the server, rather than just to localhost (127.0.0.1).

Next, create a remote access user:

  1. In the same menu, select Add a remote access user.
  2. Genie will ask for the remote server’s IP. Use the default for Sonar V2.
    If you're using Sonar V1 and don't know the IP, ping your Sonar instance to find it.

After you add the remote access user, Genie will give you a random username and password—be sure to copy and save them for later.

You can also use this menu anytime to add, view, or remove MySQL users.

Linking FreeRADIUS to Sonar

Now that setup is complete, you’ll connect your RADIUS server to Sonar.

  1. In your Sonar instance, go to Settings.
  2. Click on Networking, then select RADIUS Servers.
  3. Fill in the required details:
    • Database Name: radius
    • Database Port: 3306
  4. Click Validate Credentials. If everything is correct, the Current Server Status will show as Accessible.

Basic PPPoE Configuration

Once everything is set up, you can configure a basic PPPoE setup on your MikroTik router.

  1. Set Up IP Pools
    Go to IP > Pool in MikroTik. These pools should match the ones you've set up in Sonar’s IPAM (refer to Sonar docs for help).
    1. Define a start IP, end IP, and an optional “next pool” if the first is full.
    2. You can assign static IPs in Sonar by linking them to a user’s RADIUS account. If not, MikroTik will assign a dynamic IP from the pool, and Sonar will track it as a soft assignment.
  2. Create a PPP Profile
    Go to PPP > Profiles and click + to create a new profile.
    1. Set a name.
    2. Choose a Local Address (like the first IP in your subnet, but not one inside the pool).
    3. For Remote Address, pick your first IP pool.
    4. Add DNS servers to assign to users.
    5. Under the Limits tab, set a Session Timeout (for example, 24 hours). Leave it blank if you want sessions to stay connected indefinitely.
Enable RADIUS Accounting in MikroTik

After setting up your PPP profile:

  1. Go to the Secrets tab, then click PPP Authentication & Accounting.
  2. Check Use Radius and Accounting.
  3. Set a value for Interim Update (in minutes). This controls how often MikroTik sends usage data to the RADIUS server.
    For small networks (a few hundred users), 1–5 minutes is fine. For larger networks, start with 15 minutes or more to avoid overloading your server.
Set Up the PPPoE Server in MikroTik
  1. Go to the PPPoE Servers tab and click + to create a new server.
  2. Enter a name, choose the interface clients will connect through, and select the PPP profile you set up earlier.
  3. Check One Session Per Host to limit each device to one PPPoE session.
  4. Make sure all authentication options at the bottom are checked.

Your basic PPPoE server is now ready.

Testing the Connection
  1. In Sonar, go to a user account, then Network > RADIUS, and create a new RADIUS account. Note the username and password.
  2. In MikroTik, go to Active Connections and try connecting with a PPPoE client using the Sonar credentials.
  3. The client should get an IP from the pool, and the connection will appear in the list.
Assigning a Static IP

To assign a static IP:

  1. In Sonar, go to the user’s account > Network > IP Assignments.
  2. Assign an IP to the RADIUS account.
  3. Disconnect and reconnect the PPPoE client—it will now receive the static IP.

Scaling FreeRADIUS for Large Networks

To handle large networks, FreeRADIUS mainly needs plenty of RAM, CPU power, and fast storage. You’ll also want to adjust a few settings from the scalability guide. If you're managing a network with hundreds of thousands of users and need help, feel free to reach out.

How did we do?

Finding your OIDs

How Sonar Communicates - Egress IPs Explained

Contact