AAA RADIUS MODULE


Table of Contents

1. Admin Guide
1.1. Overview
1.2. Dependencies
1.2.1. OpenSIPS Modules
1.2.2. External Libraries or Applications
1.3. Exported Parameters
1.3.1. sets (string)
1.3.2. radius_config (string)
1.3.3. syslog_name (string)
1.3.4. fetch_all_values (integer)
1.4. Exported Functions
1.4.1. radius_send_auth(input_set_name, output_set_name)
1.4.2. radius_send_acct(input_set_name)
1.5. Exported Async Functions
1.5.1. radius_send_auth(input_set_name, output_set_name)
1.5.2. radius_send_acct(input_set_name)
2. Using radius async
2.1. Downloading radius-client library
2.2. Applying the patch
3. Contributors
3.1. By Commit Statistics
3.2. By Commit Activity
4. Documentation
4.1. Contributors

List of Tables

3.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)
3.2. Most recently active contributors(1) to this module

List of Examples

1.1. Set sets parameter
1.2. Set radius_config parameter
1.3. Set syslog_name parameter
1.4. Set fetch_all_values parameter
1.5. radius_send_auth usage
1.6. radius_send_acct usage
1.7. radius_send_auth usage
1.8. radius_send_acct usage
2.1. downloading the library
2.2. How to apply the patch

Chapter 1. Admin Guide

1.1. Overview

This module provides a Radius implementation for the AAA API from the core.

It also provides two functions to be used from the script for generating custom Radius acct and auth requests. Detection and handling of SIP-AVPs from Radius replies is automatically and transparently done by the module.

Since version 2.2, aaa_radius module supports asynchronous operations. But in order to use them, one must apply the patch contained by the modules/aaa_radius folder, called radius_async_support.patch.In order to do this, you must have freeradius-client sources. In order to do this you can follow the tutorial in the end of the documentation.

Any module that wishes to use it has to do the following:

  • include aaa.h

  • make a bind call with a proper radius specific url

1.2. Dependencies

1.2.1. OpenSIPS Modules

None.

1.2.2. External Libraries or Applications

One of the following libraries must be installed before running OpenSIPS with this module loaded:

By default, radiusclient-ng is used. To change at compile time to freeradius, uncomment the FREERADIUS=1 line in main Makefile.

1.3. Exported Parameters

1.3.1. sets (string)

Sets of Radius AVPs to be used when building custom RADIUS requests (set of input RADIUS AVPs) or when fetching data from the RADIUS reply (set of output RADIUS AVPs).

The format for a set definition is the following:

  • " set_name = ( attribute_name1 = var1 [, attribute_name2 = var2 ]* ) "

The left-hand side of the assignment must be an attribute name known by the RADIUS dictionary.

The right-hand side of the assignment must be a script pseudo variable or a script AVP. For more information about them see CookBooks - Scripting Variables.

Example 1.1. Set sets parameter


...
modparam("aaa_radius","sets","set4  =  (  Sip-User-ID  =   $avp(10)
			,   Sip-From-Tag=$si,Sip-To-Tag=$tt      )      ")
...

...
modparam("aaa_radius","sets","set1 = (User-Name=$var(usr), Sip-Group = $var(grp),
			Service-Type = $var(type)) ")
...

...
modparam("aaa_radius","sets","set2 = (Sip-Group = $var(sipgrup)) ")
...


1.3.2. radius_config (string)

Radiusclient configuration file.

This parameter is optional. It must be set only if the radius_send_acct and radius_send_auth functions are used.

Example 1.2. Set radius_config parameter


...
modparam("aaa_radius", "radius_config", "/etc/radiusclient-ng/radiusclient.conf")
...


1.3.3. syslog_name (string)

Enable logging of the client library to syslog, using the given log name.

This parameter is optional. Radius client libraries will try to use syslog to report errors (such as problems with dictionaries) with the given ident string .If this parameter is set, then these errors are visible in syslog. Otherwise errors are hidden.

By default this parameter is not set (no logging).

Example 1.3. Set syslog_name parameter

...
modparam("aaa_radius", "syslog_name", "aaa-radius")
...

1.3.4. fetch_all_values (integer)

For the output sets, this parameter controls if all the values (for the same RADIUS AVP) should be returned (otherwise only the first value will be returned). When enabling this options, be sure that the variable you use to get the RADIUS output can store multiple values (like the AVP variables).

By default this parameter is disabled (set to 0) for backward compatibility reasons.

Example 1.4. Set fetch_all_values parameter

...
modparam("aaa_radius", "fetch_all_values", 1)
...

1.4. Exported Functions

1.4.1.  radius_send_auth(input_set_name, output_set_name)

This function can be used from the script to make custom radius authentication request. The function takes two parameters.

The first parameter represents the name of the set that contains the list of attributes and pvars that will form the authentication request (see the sets module parameter).

The second parameter represents the name of the set that contains the list of attributes and pvars that will be extracted form the authentication reply (see the sets module parameter).

The sets must be defined using the sets exported parameter.

The function return TRUE (retcode 1) if authentication was successful, FALSE (retcode -1) if an error (any kind of error) occured during authentication processes or FALSE (retcode -2) if authentication was rejected or denied by RADIUS server.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, ERROR_ROUTE and LOCAL_ROUTE.

Example 1.5. radius_send_auth usage


...
radius_send_auth("set1","set2");
switch ($rc) {
	case 1:
		xlog("authentication ok \n");
		break;
	case -1:
		xlog("error during authentication\n");
		break;
	case -2:
		xlog("authentication denied \n");
		break;
}
...

		

1.4.2.  radius_send_acct(input_set_name)

This function can be used from the script to make custom radius authentication request. The function takes only one parameter that represents the name of the set that contains the list of attributes and pvars that will form the accounting request.

Only one set is needed as a parameter because no AVPs can be extracted from the accounting replies.

The set must be defined using the "sets" exported parameter.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, ERROR_ROUTE and LOCAL_ROUTE.

Example 1.6. radius_send_acct usage


...
radius_send_acct("set1");
...

		

1.5. Exported Async Functions

1.5.1.  radius_send_auth(input_set_name, output_set_name)

This function can be used from the script to make custom radius authentication request. The function takes two parameters.

The first parameter represents the name of the set that contains the list of attributes and pvars that will form the authentication request (see the sets module parameter).

The second parameter represents the name of the set that contains the list of attributes and pvars that will be extracted form the authentication reply (see the sets module parameter).

The sets must be defined using the sets exported parameter.

The function return TRUE (retcode 1) if authentication was successful, FALSE (retcode -1) if an error (any kind of error) occured during authentication processes or FALSE (retcode -2) if authentication was rejected or denied by RADIUS server.

Example 1.7. radius_send_auth usage


...
{
async( radius_send_auth("set1","set2"), resume);
}

route[resume] {
switch ($rc) {
	case 1:
		xlog("authentication ok \n");
		break;
	case -1:
		xlog("error during authentication\n");
		break;
	case -2:
		xlog("authentication denied \n");
		break;
}
...

		

1.5.2.  radius_send_acct(input_set_name)

This function can be used from the script to make custom radius authentication request. The function takes only one parameter that represents the name of the set that contains the list of attributes and pvars that will form the accounting request.

Only one set is needed as a parameter because no AVPs can be extracted from the accounting replies.

The set must be defined using the "sets" exported parameter.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE, BRANCH_ROUTE, ERROR_ROUTE and LOCAL_ROUTE.

Example 1.8. radius_send_acct usage


...
{
async( radius_send_acct("set1","set2"), resume);
}

route[resume] {
xlog(" accounting finished\n");
}

...

		

Chapter 2. Using radius async

2.1. Downloading radius-client library

You can download the last freeRADIUS Client Library sources from here . So the first step would be to download these sources in any folder you want. In this exaple we will consider this folder generically called freeRADIUS-client. After you download the sources, extract the contents of the archive.

Example 2.1.  downloading the library

........
mkdir freeRADIUS-client; cd freeRADIUS-client
wget ftp://ftp.freeradius.org/pub/freeradius/freeradius-client-1.1.7.tar.gz
tar -xzvf freeradius-client-1.1.7.tar.gz
........
		

2.2.  Applying the patch

After you extracted the contents of the archive, you can apply the patch called radius_async_support.patch that you can find in modules/aaa_radius/ inside OpenSIPS sources folder. You must apply this patch to the freeRADIUS-client library and after this you can install the radius library as usual using configure and make commands and free to use the library.

Example 2.2.  How to apply the patch

........
cd freeRADIUS-client/freeradius-client-1.1.7.tar.gz
patch -p1 < /path/to/opensips/modules/aaa_radius/radius_async_support.patch
./configure --any-options-you-want
make
sudo make install
........
		

Chapter 3. Contributors

3.1. By Commit Statistics

Table 3.1. Top contributors by DevScore(1), authored commits(2) and lines added/removed(3)

 NameDevScoreCommitsLines ++Lines --
1. Irina-Maria Stanescu2410143260
2. Bogdan-Andrei Iancu (@bogdan-iancu)14119170
3. Ionut Ionita (@ionutrazvanionita)144113512
4. Razvan Crainea (@razvancrainea)1194639
5. Liviu Chircu (@liviuchircu)64836
6. Boris Ratner42385
7. Anca Vamanu4253
8. Matt Lehner31323
9. Авдиенко Михаил31717
10. Alex Massover3161

All remaining contributors: Julián Moreno Patiño, Walter Doekes (@wdoekes).

(1) DevScore = author_commits + author_lines_added / (project_lines_added / project_commits) + author_lines_deleted / (project_lines_deleted / project_commits)

(2) including any documentation-related commits, excluding merge commits. Regarding imported patches/code, we do our best to count the work on behalf of the proper owner, as per the "fix_authors" and "mod_renames" arrays in opensips/doc/build-contrib.sh. If you identify any patches/commits which do not get properly attributed to you, please submit a pull request which extends "fix_authors" and/or "mod_renames".

(3) ignoring whitespace edits, renamed files and auto-generated files

3.2. By Commit Activity

Table 3.2. Most recently active contributors(1) to this module

 NameCommit Activity
1. Bogdan-Andrei Iancu (@bogdan-iancu)Aug 2009 - Jun 2018
2. Liviu Chircu (@liviuchircu)Mar 2014 - Jun 2018
3. Ionut Ionita (@ionutrazvanionita)Jun 2015 - Jan 2017
4. Razvan Crainea (@razvancrainea)Sep 2010 - Feb 2016
5. Julián Moreno PatiñoFeb 2016 - Feb 2016
6. Walter Doekes (@wdoekes)Jun 2014 - Jun 2014
7. Boris RatnerMar 2012 - Jan 2013
8. Matt LehnerAug 2010 - Aug 2010
9. Irina-Maria StanescuJul 2009 - Jul 2010
10. Авдиенко МихаилNov 2009 - Nov 2009

All remaining contributors: Alex Massover, Anca Vamanu.

(1) including any documentation-related commits, excluding merge commits

Chapter 4. Documentation

4.1. Contributors

Last edited by: Bogdan-Andrei Iancu (@bogdan-iancu), Liviu Chircu (@liviuchircu), Ionut Ionita (@ionutrazvanionita), Walter Doekes (@wdoekes), Boris Ratner, Razvan Crainea (@razvancrainea), Irina-Maria Stanescu.

doc copyrights:

Copyright © 2009 Irina-Maria Stanescu

Copyright © 2009 Voice Sistem SRL