Part 2: How to set up Prepaid Billing System with BSDRadius

In the first document named "HOWTO: BSDRadius and Gnugk" we discussed basic concepts of setting up BSDRadius with GnuGK gatekeeper. We covered installation of BSDRadius, configuration of BSDRadius and GnuGK to perform simple authentication by username and password and CDR logging into database. Of course, this is far from more or less usable billing system as it cannot do important thing - cannot decrease users balance as calls are being made. One way to do it is by using triggers in database. However, this will not allow to make system really prepaid, as we need to tell GnuGK for how long the user is allowed to speak because there is no way to return database query results back to radius client. Therefore the only way is to write our own module (obviously we will use Python) which would take care of this.

For impatient or non-interested in code internals, there is list of configuration files and mysql schema file at the end of this document. If you copy them to etc/bsdradius/ directory of BSDRadius and create MySQL schema, it should start to work immediately. If not, please read on to see what went wrong.

Contents of this document:

  1. What we want to achieve
  2. Database schema
  3. Simplebill module for BSDRadius
  4. Configuring BSDRadius
  5. Testing
  6. List of files

1. What we want to achieve

Here is list of requirements we set up for our simple prepaid billing system:

Notes:

2. Database schema

Attached database schema is tested on MySQL 4.1.x, however it should work on MySQL 5.x as well. To be backwards compatible we will not use triggers. To take advantage of foreign keys we will use InnoDB storage engine though. To import database schema into MySQL: 

# mysql
Welcome to the MySQL monitor.  Commands end with ; or \g.
Your MySQL connection id is 882 to server version: 4.1.18

Type 'help;' or '\h' for help. Type '\c' to clear the buffer.

mysql> create database bsdradius;
Query OK, 1 row affected (0.02 sec)

mysql> exit
Bye
# mysql bsdradius < /path/to/bsdradius/sql/simplebill.mysql.sql

Here is the list of tables in our billing database and description of most important tables:

3. Simplebill module for BSDRadius

As mentioned above, we will create our own module for BSDRadius. We will call it Simplebill and it should be placed in etc/bsdradius/user_modules directory. We will also need configuration file for this module which will hold database driver and access information. The file is etc/bsdradius/simplebill.conf and its contents are fairly simple and obvious: 

# contains settings for connecting to database
[DATABASE]

# database type
# Suppored RDMS': postgresql, mysql
type = mysql

# db host
host = localhost

# db user
user = bsdradius

# db user password
pass = somepass

# db name
name = bsdradius

Module is written in Python and will be located in etc/bsdradius/user_modules/simplebill.py. It will contain several functions as required by Radius server:

These functions should be referenced in Radius server user modules configuration file

4. Configuring BSDRadius

Once module is made and uploaded we have to tell BSDRadius how to use it. First, we have to make sure it can find users module directory and user modules configuration file (it is set by default, but double check will not harm). Entries in etc/bsdradius/bsdradiusd.conf looks like: 

# path to directory that may contain user's custom modules
user_module_dir = %(conf_dir)s/user_modules

# path to custom (3rd party, user-made) BSD Radius modules
# configuration file.
user_modules_file = %(conf_dir)s/user_modules.conf

Next, we have tio configure users module behaviour. This is done in etc/bsdradius/user_modules.conf: 

[simplebill]
configfile = simplebill.conf
startup_module = simplebill
startup_function = simplebill_funct_startup
authorization_module = simplebill
authorization_function = simplebill_funct_authz
authentication_module = simplebill
authentication_function = simplebill_funct_authc
accounting_module = simplebill
accounting_function = simplebill_funct_acct
shutdown_module = simplebill
shutdown_function = simplebill_funct_shutdown

This is basically it. Server now knows where to find functions in case it needs it and if module file simplebill.py and its config file simplebill.conf is in place, it should be ready to operate.

5. Testing

Testing of BSDRadius is fairly simple and is described in previous document "HOWTO: BSDRadius and Gnugk". As usually, start BSDRadius in debug mode: 

# cd /whatever/path/to/bsdradius/
# ./bin/bsdradius -sf

It will tell you if it was able to find and load all necessary modules at start time, and also if any error occured in run time. It will log onscreeen all radius requests received and also responses sent to GnuGK.

Once you are done with testing, you can start BSDRadius normally to run in background: 

# cd /whatever/path/to/bsdradius/
# ./bin/bsdradius

6. List of files

Here is the list of configuration files which are used in this document. They should work if directly copied into appropriate directory. It is recommended to change default passwords though.

For BSDRadius:

MySQL schema

Questions and comments welcome: aivis (at) bsdradius.org