FreeRadius Addon Module

From WHMCS Documentation

FreeRADIUS is the popular open source RADIUS server solution and is the most widely deployed RADIUS server in the world. It supports all common authentication protocols, and the server comes with a PHP-based web user administration tool, called dialupadmin. It is the basis for many commercial RADIUS products and services, like embedded systems, RADIUS appliances that support Network Access Control and WiMAX. Source: Wikipedia:FreeRADIUS

Typically we find users of WHMCS utilizing FreeRadius to offer Dial Up Internet & Broadband Services. We have created an addon module to integrate with FreeRadius that supports the following:

  • account creation
  • suspensions
  • unsuspension
  • terminations
  • password resets
  • upgrading/downgrading of accounts between FreeRADIUS groups

Usage statistics for the current billing cycle/period will be displayed to end users inside the WHMCS client area. This provides statistics on their upload and download usage, number of logins and total login time. The output, styling and content of this can be customized via the freeradius_ClientArea function within the module.

The module will provision a new account to a specific group, but is not capable of provisioning an account with specific resources. You must define the resources for a given account on the FreeRADIUS system itself.

Buying the Addon

The FreeRadius Addon Module is available for $150 and can be purchased via the link below.

Installing & Using FreeRadius within WHMCS

Once you've purchased the FreeRadius addon, you will receive an email once activated directing you where to download the addon from. Once downloaded, the freeradius module folder simply needs to be uploaded to the /modules/servers/freeradius/ folder of your WHMCS installation (you will need to create this).

This FreeRadius module interacts directly with the Radius database system and so once installed, you then need to go to Configuration () > System Settings > Servers or, prior to WHMCS 8.0, Setup > Products/Services > Servers. Create a server for the FreeRadius accounts entering the details as follows:

  • Name - Anything you choose
  • IP Address - SQL Hostname
  • Server Type - Freeradius
  • Username - SQL Username
  • Password - SQL Password
  • Access Hash - SQL Database Name

Next it's time to create a product, this is done under Configuration () > System Settings > Products/Services or, prior to WHMCS 8.0, Setup > Products/Services > Product/Services as with any product in WHMCS. From there select the Add New Product option, specify a name, description & pricing, etc... all as desired, and then on the Module Settings tab, select the Freeradius module option and enter the Group Name defined in Radius to control the permissions/limitations of the account this product should setup.

That's all there is to it. You can then begin using the module in WHMCS as with any module, either manually invoking via the Module Command buttons displayed on a clients instance of the product, using the automated setup options of instantly upon order, after first payment or after manual admin review, and with the automated actions of overdue suspension, reactivations, late terminations, etc...


  1. Does this module work with PostgreSQL?
    • At this time the module only works with MySQL. As the module is provided as plain source code, you may however modify the code so that it works with a PostgreSQL system instead.
  2. I can't see a users stats when logged into the admin area?
    • The stats are only shown on the client area side. You'll need to 'Login as...' to view the stats for a particular account.
  3. I keep getting this error - "FreeRadius Database Query Error: Access denied for user 'vivieqsg_whmcs'@'localhost' to database 'radius'".
    • The MySQL user does not have permissions to access your FreeRADIUS database. If you're hosting WHMCS and FreeRADIUS on different system (which isn't unusual), then you must make sure the MySQL user and host from which the MySQL user is connecting from, have permissions to access the database.
  4. I keep getting this error - "ERROR 2003 (HY000): Can't connect to MySQL server on 'ip.add.res.s' (110)".
    • This usually means MySQL is not set to listen to outside connections or there is a firewall blocking the connections. Please ensure the IP address from which the module is connecting from is whitelisted in your firewall or that MySQL is set to allow external connections to it.
  5. I get this error when trying to use the Module Commands - "FreeRadius Database Query Error: Table 'radius.usergroup' doesn't exist".
    • This means the module is trying to get or put data into your FreeRADIUS MySQL database, but the table either doesn't exist or is named something else. If this happens, you should get a list of the tables in your FreeRADIUS database and compare them with the error you've gotten. It may be necessary at this point to review and adjust the code of the module so that the module uses the names of tables in your database.
  6. How does the module configure usernames?
    • The module will provision accounts and setup usernames based on the email address of the client. It will attempt to use the full email address as the username though if the username is already in use it will use the email address plus some numbers so each username is unique.
  7. How can I sync the name and contact information between WHMCS and FreeRADIUS?
    • This information can be synced between WHMCS and FreeRADIUS by locating and uncommenting the following code in the freeradius.php file. This will allow the name and contact details of the client in WHMCS to sync over to the users FreeRADIUS account.
 * 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' => '',

  1. How do I specify additional radius configuration parameters for new accounts?
    • To apply additional radius parameters to new accounts, simply locate and uncomment the following code in the freeradius.php file, adjusting the values given for the attribute, value and op in the MySQL query on the first of those lines as required for your additional configuration parameter.
 * 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' => ':=',