SIP-router can be configured to use RADIUS server for authentication, accounting, and group membership checking. Since configuration of RADIUS 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 other RADIUS servers available and as long as they support digest authentication, they should work too. Any volunteers willing to describe setup of other RADIUS servers are encouraged to contact the author.
To setup RADIUS support in SIP-router you will need the following:
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.
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.
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.
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 !
Radiusclient library contains file called
dictionary.ser. That file includes all the
attributes that are needed by SIP-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
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.
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".
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.
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.
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.
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
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 localhost 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"
To create user "joe" in domain "sip-router.org" with password
"heslo" put the following into file
/usr/local/etc/raddb/users:
joe@sip-router.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-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.
By default the 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 1. 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
We will describe installation from sources here. If you use binary packages then there is an additional package containing RADIUS related modules. You will need to install the package.
RADIUS-related modules are not compiled by default. To compile
them, edit Makefile, find variable
exclude_modules and you should see
"auth_radius", "acc_radius", and "misc_radius" among excluded
modules. Simply remove the three modules from the list.
If you need RADIUS 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 SIP-router:
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
Edit configuration file of SIP-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).
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.