FreeRADIUS is a popular open-source RADIUS server solution. Typically, WHMCS users use FreeRADIUS to offer dialup internet and broadband services.

The module will provision a new account to a specific group, but it cannot provision an account with specific resources. You must define the resources for each account on the FreeRADIUS system itself.

This module does not ship with WHMCS by default. Instead, you must purchase and install it (see below).

Supported Features

Change PackageChange PasswordUsage UpdatesClient Area Link
This module also supports upgrades and downgrades between FreeRADIUS groups.

Adding this Module

You must purchase and upload this module before configuring it in the Admin Area.

To do this:

  1. Purchase the module from WHMCS. You will receive an email with a download link.
  2. Download the files.
  3. In your WHMCS installation, create the /modules/servers/freeradius/ directory.
  4. Upload the module files to the directory.
  5. Go to Configuration () > System Settings > Servers.
  6. Create a server for the FreeRADIUS accounts using the following details:
    • Name — A name for the server.
    • IP Address — The SQL hostname.
    • Server Type — The server type. Select Freeradius.
    • Username — The SQL username.
    • Password — The SQL password.
    • Access Hash — The SQL database name.
  7. Click Save Changes.

Database Requirements

This module requires MySQL® and will not function using PostgreSQL®. However, you can modify the module source code to use PostgreSQL instead.

You may also see the following database errors:

FreeRADIUS Database Query Error: Access denied for user 'vivieqsg_whmcs'@'localhost' to database 'radius'The MySQL user does not have permissions to access the FreeRADIUS database.If you’re hosting WHMCS and FreeRADIUS on different servers, ensure that the MySQL user and the host have permissions to access the database.
ERROR 2003 (HY000): Can't connect to MySQL server on 'ip.add.res.s' (110)MySQL cannot listen to outside connections or a firewall is blocking them.Make certain that the IP address from which the module is connecting is whitelisted in your firewall and that MySQL allows external connections.
FreeRADIUS Database Query Error: Table 'radius.usergroup' doesn't existThe module cannot find a table that it is trying to access a table in the FreeRADIUS MySQL database. The table may not exist, or it may use a different name.Get a list of the tables in your FreeRADIUS database and compare it with the error message. You may need to review and adjust your module’s code to ensure that it uses the correct database table names.

Creating a FreeRADIUS Product

You can create a product that provisions accounts on your FreeRADIUS server at Configuration () > System Settings > Products/Services.

When you do this:

  • In the Module Settings tab, select Freeradius.
  • Enter the appropriate group name from FreeRADIUS.


The module provisions accounts and sets up usernames using the client’s email address. It will attempt to use the full email address as the username.

If that username is already in use, it will append additional characters to the email address to ensure that each username is unique.

Usage Statistic Display

Usage statistics for the current billing cycle will display in the WHMCS Client Area. This provides statistics on their upload and download usage, number of logins, and total login time.

  • To view usage statistics as an admin, click Log in as Owner in the Summary tab in the desired client’s profile.
  • You can customize the output, styling, and content using the module’s freeradius_ClientArea function.

Sync Client Information with FreeRADIUS

You can sync information between WHMCS and FreeRADIUS by locating and uncommenting the following code in the freeradius.php file:

* For the name and contact details of the client in WHMCS to sync over to the users FreeRADIUS account,
* use the following code snippet:

  'username' => $username,
  'name' => $params["clientsdetails"]["firstname"] . ' ' . $params["clientsdetails"]["lastname"],
  'mail' => $email,
  'department' => '',
  'homephone' => $params["clientsdetails"]["phonenumber"],
  'workphone' => '',
  'mobile' => '',


Specify Additional Parameters for New Accounts

To apply additional FreeRADIUS parameters to new accounts, uncomment the following code in the freeradius.php file and adjust the attribute, value, and op values in the MySQL query:

* To apply additional radius parameters to new accounts, use the following code snippet
* for each additional parameter:

  'username' => $username,
  'attribute' => '<attribute-name>',
  'value' => '<attribute-value>',
  'op' => ':=',


Last modified: June 11, 2024