# &ser &rad; HOWTO

Jan
Janak
jan@iptel.org
2003
&fokus;
$Revision: 1.7 $
$Date: 2004/08/24 08:45:12 $

## Introduction

&ser can be configured to use &rad; server for authentication, accounting, and group membership checking. Since configuration of &rad; seems to be a common source of problems, we decided to put together this HOWTO.

The HOWTO covers installation and configuration of FreeRADIUS server only. There are also other &rad; servers available and as long as they support digest authentication, they should work too. Any volunteers willing to describe setup of other &rad; servers are encouraged to contact the author.

### Prerequisites

To setup &rad; support in &ser; 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/

- &ser;, get it from http://iptel.org/ser

- You should also have some experience in configuring &ser;. Before you enable &rad; 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 &rad; accounting then you will have to compile &ser; 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.

## Radiusclient Library

Untar the source tarball.

    root@localhost:/usr/local/src# tar xvfz radiusclient-0.4.3.tar.gz

Compile and install the library.

    root@localhost:/usr/local/src# cd radiusclient-0.3.2
    root@localhost:/usr/local/src/radiusclient-0.3.2# ./configure
    root@localhost:/usr/local/src/radiusclient-0.3.2# make
    root@localhost:/usr/local/src/radiusclient-0.3.2# make install

By default all the configuration files of the radiusclient library will be in `/usr/local/etc/radiusclient` directory.

If you use binary packages then the configuration files will be probably in `/etc/radiusclient`.

### File `radiusclient.conf`

The main configuration file of the library is `/usr/local/etc/radiusclient/radiusclient.conf`, open the file in your favorite 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.

### File `servers`

&rad; protocol uses simple access control mechanism based on shared secrets that allows &rad; servers to limit access from &rad; clients. A &rad; server is configured with a secret string and only &rad; 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 &rad; server and shared secret used in communication with that server. The two values are separated by whitespaces. Configure shared secrets for every &rad; server you are going to use.

&rad; 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 !

### File `dictionary`

Radiusclient library contains file called `dictionary.ser`. That file includes all the attributes that are needed by &ser;. 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

## FreeRADIUS Server

Untar, configure, build, and install the server:

    root@localhost:/usr/local/src# tar xvfz freeradius-0.9.1.tar.gz
    root@localhost:/usr/local/src# cd freeradius-0.9.1
    root@localhost"/usr/local/src/freeradius-0.9.1# ./configure
    root@localhost"/usr/local/src/freeradius-0.9.1# make
    root@localhost"/usr/local/src/freeradius-0.9.1# make install

All the configuration files of FreeRADIUS server will be in `/usr/local/etc/raddb` directory. If you install a binary package then you will probably find them in `/etc/raddb`.

The following sections describe how to configure freeradius server. First we describe the common configuration that must be done in any case. Configuration specific for authentication, accounting, and group membership checking will be described in separate sections.

### Common configuration

#### File `clients.conf`

File `/usr/local/etc/raddb/clients.conf` contains description of &rad; 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 &rad; 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 &rad; server on the same host as your &sip; server, then modify the existing entry instead. By default it contains shared secret testing123.

#### File `dictionary`

File `/usr/local/etc/raddb/dictionary` contains the dictionary of FreeRADIUS server. You have to add the same dictionary file (`dictionary.ser`), which you added to the dictionary of radiusclient library, also here. In this case you don't have to append the contents of the file, you can include it into the main file. Add the following line at the end of `/usr/local/etc/raddb/dictionary`:

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

That will include the same attribute definitions that are used in radiusclient library so the client and server will understand each other.

#### 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.

#### File `users`

This file contains authentication information for each user. For testing purposes we will create user test. Put the following into the file:

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

The username and password is for testing only, you can safely remove the entry once your RADIUS server works and you are able to authenticate.

### 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 debugging 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 &rad; 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"

### 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. &ser; 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.

### 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.

#### Example of Accounting Report

    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

### 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"

## &ser; Configuration

We will describe installation from sources here. If you use binary packages then there is an additional package containing &rad; related modules. You will need to install the package.

Due to a mistake the binary packages for &rad; do not include &rad;-enabled version of acc (accounting) module. The packages contain modules for &rad; authentication and group membership checking only.

If you need accounting over &rad; then you will have to compile &rad;-enabled version of acc module from the sources. This will be fixed in one of future releases, we apologize for any inconvenience.

&rad;-related modules are not compiled by default. To compile them, edit `Makefile`, find variable `exclude_modules` and you should see auth_radius, group_radius, and uri_radius among excluded modules. Simply remove the three modules from the list.

If you need &rad; accounting then edit also sip_router/modules/acc/Makefile and uncomment lines containing:

    DEFS+=-DRAD_ACC
    LIBS=-L$(LOCALBASE)/lib -lradiusclient

Then recompile and re-install &ser:

    root@localhost:/usr/local/src/sip_router# make proper
    root@localhost:/usr/local/src/sip_router# make all
    root@localhost:/usr/local/src/sip_router# make install

### Authentication Configuration

Edit configuration file of &ser; 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).

### Accounting Configuration

To enable &rad; 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.

### 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.

## Frequently Asked Questions

I compiled &ser; &rad; modules and installed radiusclient library, but when I try to start ser I get the following error message:

    libradiusclient.so.0: cannot open shared object file: No such file or directory

Make sure that the directory which contains the library (usually `/usr/local/lib`) is listed in `/etc/ld.so.conf` and run `ldconfig -v` (as root).

I configured everything as described in this HOWTO, but I get the following message from radiusclient library check_radius_reply: received invalid reply digest from RADIUS server. What does that mean ?

That means that radiusclient library was unable to verify digest of the RADIUS message (it is not related to &sip; digest) because shared secret of the client and server do not match.

FreeRADIUS server has two files that can contain definitions of clients and corresponding shared secrets--`clients` and `clients.conf`.

If you have proper shared secret in one file and you still get the mentioned error message then check also the other file. This can easily happen to clients running on the same host (127.0.0.1 or localhost), because `clients.conf` contains definition for localhost by default with secret testing123.