1.1. Prerequisities

To setup RADIUS support in SIP Express Router you will need the following:

• FreeRADIUS server, you can get it from FreeRADIUS website. The howto describes installation and setup of release 0.9.1.

• Radiusclient library. In version 0.8.14 we started to use the new version of radiusclient library developed by Maxim Sobolev called radiusclient-ng. The homepage of the library is http://developer.berlios.de/projects/radiusclient-ng/

• SIP Express Router, get it from http://iptel.org/ser

• You should also have some experience in configuring SIP Express Router. Before you enable RADIUS authentication or accounting make sure that the basic server is running and that you know how to customize it to your taste.

• If you want to use RADIUS accounting then you will have to compile SIP Express Router from sources so you should know how to do it.

Various unix/linux distributions might include binary packages of the mentioned applications. In that case you can safely use the packages, there shouldn't be any problem. Location of some files may be different, though. We will describe how to install the software from sources only.

Configuration of FreeRADIUS server described in the document is in no way exhaustive. This document is a sort of quick-start-guide, it shows how to get things running, but you should definitely read FreeRADIUS documentation and configure the server properly ! You have been warned.

2.1. File radiusclient.conf

The main configuration file of the library is /usr/local/etc/radiusclient/radiusclient.conf, open the file in your favourite text editor and find lines containing the following:

authserver      localhost

This is the hostname or IP address of the RADIUS server used for authentication. You will have to change this unless the server is running on the same host as your SIP proxy.

acctserver      localhost

This is the hostname or IP address of the RADIUS server used for accounting. You will have to change this unless the server is running on the same host as your SIP proxy.

2.2. File servers

RADIUS protocol uses simple access control mechanism based on shared secrets that allows RADIUS servers to limit access from RADIUS clients. A RADIUS server is configured with a secret string and only RADIUS clients that have the same secret will be accepted.

You need to configure a shared secret for each server you have configured in radiusclient.conf file in the previous step. The shared secrets are stored in /usr/local/etc/radiusclient/servers file.

Each line contains hostname of a RADIUS server and shared secret used in communication with that server. The two values are separated by whitespaces. Configure shared secrets for every RADIUS server you are going to use.

RADIUS servers and clients must be configured with the same shared secret, otherwise they will not accept RADIUS messages from each other and neither authentication nor accounting will work !

2.3. File dictionary

Radiusclient library contains file called dictionary.ser. That file includes all the attributes that are needed by SIP Express Router. Include the file in the main dictionary file. To include the file, put the following line at the end of dictionary file:

$INCLUDE /usr/local/etc/radiuclient/dictionary.ser

3.1. Common configuration

3.1.1. File clients.conf

File /usr/local/etc/raddb/clients.conf contains description of RADIUS clients that are allowed to use the server. For each of the clients you need to specify it's hostname or IP address and also a shared secret. The shared secret must be the same string you configured in radiusclient library.

Suppose that your SIP server is running on host proxy.foo.bar and radiusclient library on that machine has been configure with "foobarsecret" as the shared secret. You need to put the following section into the file:

client proxy.foo.bar {
    secret = foobarsecret
    shortname = foo
}

This fragment allows access from RADIUS clients on proxy.foo.bar if they use "foobarsecret" as the shared secret.

The file already contains an entry for localhost (127.0.0.1), so if you are running the RADIUS server on the same host as your SIP server, then modify the existing entry instead. By default it contains shared secret "testing123".

$INCLUDE /usr/local/etc/radiusclient/dictionary.ser

---

3.1.3. File radiusd.conf

Digest authentication is disabled by default and you must enable it in this file. There are two sections, "authorize" and "authenticate". Both sections contain line containing word "digest". Both of them are commented and you must un-comment them to enable digest authentication.

There is also another line containing word "digest" followed by curly braces and it is enabled by default. The section is supposed to contain digest module parameters but because digest module has no parameters, it is empty. This is not the line you are supposed to uncomment ! There are two more.

test Auth-Type := Digest, User-Password == "test"
     Reply-Message = "Hello, test with digest"

3.2. Test The Server

This step is optional.

The basic configuration of FreeRADIUS server is done it now we are going to test if it really works. Start the server with parameter -X. That will cause the server to stay in the foreground (it will not turn into daemon) and produce a lot of debuging information on the standard output:

root@/usr/local/src# radiusd -X

Create file digest and put the following into the file:

User-Name = "test", Digest-Response = "631d6d73147add2f9e437f59bbc3aeb7", 
Digest-Realm = "testrealm", Digest-Nonce = "1234abcd" , 
Digest-Method = "INVITE", Digest-URI = "sip:5555551212@example.com", 
Digest-Algorithm = "MD5", Digest-User-Name = "test"

All the attributes must be on a single line.

Run radclient to test the server:

root@/usr/local/src# radclient -f digest localhost auth <shared_secret>

I suppose that you run the test utility directly on the RADIUS server since it comes with the FreeRADIUS server package. That also means that you have to enable access from localhost in your clients.conf file. Don't forget to replace <shared_secret> with the shared secret configured for locahost clients in clients.conf.

If your server works properly then you should see the following response:

Received response ID 224, code 2, length = 45
        Reply-Message = "Hello, test with digest"

3.3. Authentication Configuration

To create user "joe" in domain "iptel.org" with password "heslo" put the following into file /usr/local/etc/raddb/users:

joe@iptel.org Auth-Type := Digest, User-Password == "heslo"
     Reply-Message = "Authenticated",
     Sip-Rpid = "1234"

Attribute "Sip-Rpid" is optional. The attribute contains a phone number associated to the user. SIP Express Router can be configured to put the phone number into Remote-Party-ID header field of the SIP message. The header field can be then used by PSTN gateways to display the number as the number of the caller on regular phones. You can omit the attribute if you don't need it.

3.4. Accounting Configuration

By default FreeRADIUS server will log all accounting requests into /usr/local/var/log/radius/radacct directory in form of plain text files. The server will create one file for each hostname in the directory. The following example shows how the log files look like.

Tue Jun 24 00:20:55 2003
        Acct-Status-Type = Start
        Service-Type = 15
        Sip-Response-Code = 200
        Sip-Method = 1
        User-Name = "gh@192.168.2.16"
        Calling-Station-Id = "sip:gh@192.168.2.16"
        Called-Station-Id = "sip:jiri@192.168.2.16"
        Sip-Translated-Request-URI = "sip:jiri@192.168.2.36"
        Acct-Session-Id = "b9a2ffaa-0458-42e1-b5fd-59656b795d29@192.168.2.32"
        Sip-To-Tag = "cb2cfe2e-3659-28c7-a8cc-ab0b8cbd3012"
        Sip-From-Tag = "a783bd2f-bb8d-46fd-84a9-00a9833f189e"
        Sip-CSeq = "1"
        NAS-IP-Address = 192.168.2.16
        NAS-Port = 5060
        Acct-Delay-Time = 0
        Client-IP-Address = 127.0.0.1
        Acct-Unique-Session-Id = "9b323e6b2f5b0f33"
        Timestamp = 1056406855

Tue Jun 24 00:20:56 2003
        Acct-Status-Type = Stop
        Service-Type = 15
        Sip-Response-Code = 200
        Sip-Method = 8
        User-Name = "jiri@192.168.2.16"
        Calling-Station-Id = "sip:jiri@192.168.2.16"
        Called-Station-Id = "sip:gh@192.168.2.16"
        Sip-Translated-Request-URI = "sip:192.168.2.32:9576"
        Acct-Session-Id = "b9a2ffaa-0458-42e1-b5fd-59656b795d29@192.168.2.32"
        Sip-To-Tag = "a783bd2f-bb8d-46fd-84a9-00a9833f189e"
        Sip-From-Tag = "cb2cfe2e-3659-28c7-a8cc-ab0b8cbd3012"
        Sip-CSeq = "4580"
        NAS-IP-Address = 192.168.2.16
        NAS-Port = 5060
        Acct-Delay-Time = 0
        Client-IP-Address = 127.0.0.1
        Acct-Unique-Session-Id = "b2c2479a07b17c95"
        Timestamp = 1056406856

3.5. Group Checking Configuration

If you want to make user "joe" in domain "iptel.org" member of group "pstn" then add the following to your /usr/local/etc/raddb/users file:

joe@iptel.org Sip-Group == "pstn", Auth-Type := Accept
        Reply-Message = "Authorized"

4.1. Authentication Configuration

Edit configuration file of SIP Express Router and instead of auth_db.so load auth_radius.so and also replace www_authorize with radius_www_authorize.

radius_www_authorize takes just one parameter (as opposed to www_authorize which takes 2).

4.2. Accounting Configuration

To enable RADIUS accounting simply use radius_log_flag and radius_log_missed_flag parameters instead of log_flag and log_missed_flag. Mark transactions that should be logged with flags configured in the parameters.

4.3. Group Membership Checking

Instead of group.so load group_radius.so. The module exports the same functions as group.so, the only difference is that all the function names exported by group_radius.so have "radius_" prefix.