- Initial versio of SER RADIUS Howto

doc/ser_radius/ser_radius.sgml

@@ -0,0 +1,573 @@
+<!-- $Id$ -->
+<!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
+
+<!ENTITY ser "<acronym>SIP</acronym> Express Router">
+<!ENTITY nat "<acronym>NAT</acronym>">
+<!ENTITY ip "<acronym>IP</acronym>">
+<!ENTITY rtp "<acronym>RTP</acronym>">
+<!ENTITY stun "<acronym>STUN</acronym>">
+<!ENTITY fokus "FhG FOKUS">
+<!ENTITY sip "<acronym>SIP</acronym>">
+<!ENTITY rad "RADIUS">
+<!ENTITY pstn "<acronym>PSTN</acronym>">
+
+]>
+
+<book>
+    <bookinfo>
+	<title>&ser &rad; HOWTO</title>
+	<authorgroup>
+	    <author>
+		<firstname>Jan</firstname>
+		<surname>Janak</surname>
+		<email>[email protected]</email>
+	    </author>
+	</authorgroup>
+	<copyright>
+	    <year>2003</year>
+	    <holder>&fokus;</holder>
+	</copyright>
+	<revhistory>
+	    <revision>
+		<revnumber>$Revision$</revnumber>
+		<date>$Date$</date>
+	    </revision>
+	</revhistory>
+    </bookinfo>
+
+    <chapter>
+	<title>Introduction</title>
+	<simpara>
+	    &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.
+	</simpara>
+	<simpara>
+	    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.
+	</simpara>
+	<section>
+	    <title>Prerequisities</title>
+	    <simpara>
+		To setup &rad; support in &ser; you will need the following:
+	    </simpara>
+	    <itemizedlist>
+		<listitem>
+		    <simpara>
+			FreeRADIUS server, you can get it from <ulink
+			    url="http://www.freeradius.org">FreeRADIUS website</ulink>. The howto
+			    describes installation and setup of release 0.9.1.
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			Radiusclient library, you can get it from <ulink
+			    url="http://www.mcs.de/~lf/radius">http://www.mcs.de/~lf/radius</ulink>.
+			    The howto describes installation and setup of version 0.3.2.
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			&ser;, get it from <ulink url="http://iptel.org/ser">http://iptel.org/ser</ulink>
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			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.
+		    </simpara>
+		</listitem>
+		<listitem>
+		    <simpara>
+			If you want to use &rad; accounting then you will have to compile &ser; from
+			sources so you should know how to do it.
+		    </simpara>
+		</listitem>
+	    </itemizedlist>
+	    <simpara>
+		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.
+	    </simpara>
+	    <warning>
+		<simpara>
+		    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.
+		</simpara>
+	    </warning>
+	</section>
+    </chapter>
+    <chapter>
+	<title>Radiusclient Library</title>
+	<simpara>
+	    Untar the source tarball.
+	</simpara>
+	<screen format="linespecific">
+root@localhost:/usr/local/src# tar xvfz radiusclient-0.3.2.tar.gz
+</screen>
+	    <simpara>
+		Compile and install the library.
+	    </simpara>
+	    <screen format="linespecific">
+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
+</screen>
+	<simpara>
+	    By default all the configuration files of the radiusclient library will be in
+	    <filename moreinfo="none">/usr/local/etc/radiusclient</filename> directory.
+	</simpara>
+	<simpara>
+	    If you use binary packages then the configuration files will be probably in <filename
+	    moreinfo="none">/etc/radiusclient</filename>.
+	</simpara>
+	<section>
+	    <title>File <filename moreinfo="none">radiusclient.conf</filename></title>
+	    <simpara>
+		The main configuration file of the library is <filename
+		    moreinfo="none">/usr/local/etc/radiusclient/radiusclient.conf</filename>, open
+		    the file in your favourite text editor and find lines containing the following:
+	    </simpara>
+	    <programlisting format="linespecific">
+authserver      localhost
+</programlisting>
+	    <simpara>
+		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.
+	    </simpara>
+	    <programlisting format="linespecific">
+acctserver      localhost
+</programlisting>
+	    <simpara>
+		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.
+	    </simpara>
+	</section>
+	<section>
+	    <title>File <filename moreinfo="none">servers</filename></title>
+	    <simpara>
+		&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.
+	    </simpara>
+	    <simpara>
+		You need to configure a shared secret for each server you have configured in
+		    <filename moreinfo="none">radiusclient.conf</filename> file in the previous
+		    step. The shared secrets are stored in <filename
+		    moreinfo="none">/usr/local/etc/radiusclient/servers</filename> file.
+	    </simpara>
+	    <simpara>
+		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.
+	    </simpara>
+	    <warning>
+		<simpara>
+		    &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 !
+		</simpara>
+	    </warning>
+	</section>
+	<section>
+	    <title>File <filename moreinfo="none">dictionary</filename></title>
+	    <simpara>
+		&ser; uses some attributes that are not included in the dictionary of radiusclient
+		library, therefore it is necesarry to add them. Unfortunatelly the dictionary file
+		used by &ser is not included in the source tarball of &ser;, so far it is in
+		unstable branch of the <ulink url="http://iptel.org/ser/cvs">CVS</ulink> only, but
+		it will be included in one of future releases. Meanwhile you can get it from <ulink
+		url="http://cvs.berlios.de/cgi-bin/viewcvs.cgi/ser/sip_router/etc/dictionary.ser?rev=HEAD">the
+		CVS</ulink>.
+	    </simpara>
+	    <simpara>
+		Download the file and put it into <filename
+		moreinfo="none">/usr/local/etc/radiusclient</filename> directory and then append it
+		to the main dictionary file:
+	    </simpara>
+	    <screen format="linespecific">
+root@localhost:/usr/local/etc/radiusclient# cat dictionary.ser &gt;&gt; dictionary
+</screen>
+	    <simpara>
+		That will append contents of <filename moreinfo="none">dictionary.ser</filename>
+		file to <filename moreinfo="none">dictionary</filename> file which contains the
+		main dictionary for the radiusclient library.
+	    </simpara>
+	</section>
+    </chapter>
+
+    <chapter>
+	<title>FreeRADIUS Server</title>
+	<simpara>
+	    Untar, configure, build, and install the server:
+	</simpara>
+	    <screen format="linespecific">
+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
+</screen>
+	<simpara>
+	    All the configuration files of FreeRADIUS server will be in <filename
+	    moreinfo="none">/usr/local/etc/raddb</filename> directory. If you install a binary
+	    package then you will probably find them in <filename moreinfo="none">/etc/raddb</filename>.
+	</simpara>
+	<simpara>
+	    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.
+	</simpara>
+	
+	<section>
+	    <title>Common configuration</title>
+	    <section>
+		<title>File <filename moreinfo="none">clients.conf</filename></title>
+		<simpara>
+		    File <filename moreinfo="none">/usr/local/etc/raddb/clients.conf</filename>
+		    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.
+		</simpara>
+		<simpara>
+		    Suppose that your &sip; server is running on host proxy.foo.bar and
+		    radiusclient library on that machine has been configure with
+		    <quote>foobarsecret</quote> as the shared secret. You need to put the
+		    following section into the file:
+		</simpara>
+		<programlisting format="linespecific">
+client proxy.foo.bar {
+    secret = foobarsecret
+    shortname = foo
+}
+</programlisting>
+		<simpara>
+		    This fragment allows access from &rad; clients on proxy.foo.bar if they use
+		    <quote>foobarsecret</quote> as the shared secret.
+		</simpara>
+		<note>
+		    <simpara>
+			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
+			<quote>testing123</quote>.
+		    </simpara>
+		</note>
+	    </section>
+	    
+	    <section>
+		<title>File <filename moreinfo="none">dictionary</filename></title>
+		<simpara>
+		    File <filename moreinfo="none">/usr/local/etc/raddb/dictionary</filename>
+		    contains the dictionary of FreeRADIUS server. You have to add the same
+		    dictionary file (<filename moreinfo="none">dictionary.ser</filename>), 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 <filename
+		    moreinfo="none">/usr/local/etc/raddb/dictionary</filename>:
+		</simpara>
+		<programlisting format="linespecific">
+$INCLUDE ../radiusclient/dictionary.ser
+</programlisting>
+		<simpara>
+		    That will include the same attribute definitions that are used in radiusclient
+		    library so the client and server will understand each other.
+		</simpara>
+	    </section>
+
+	    <section>
+		<title>File <filename moreinfo="none">radiusd.conf</filename></title>
+		<simpara>
+		    Digest authentication is disabled by default and you must enable it in this
+		    file. There are two sections, <quote>authorize</quote> and
+		    <quote>authenticate</quote>. Both sections contain line containing word
+		    <quote>digest</quote>. Both of them are commented and you must un-comment them
+		    to enable digest authentication.
+		</simpara>
+		<note>
+		    <simpara>
+			There is also another line containing word <quote>digest</quote> 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.
+		    </simpara>
+		</note>
+	    </section>
+	    
+	    <section>
+		<title>File <filename moreinfo="none">users</filename></title>
+		<simpara>
+		    This file contains authentication information for each user. For testing
+		    purposes we will create user <quote>test</quote>. Put the following into the file:
+		</simpara>
+		    <programlisting format="linespecific">
+test Auth-Type := Digest, User-Password == "test"
+     Reply-Message = "Hello, test with digest"
+</programlisting>
+
+		<simpara>
+		    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.
+		</simpara>
+	    </section>
+	</section>
+
+	<section>
+	    <title>Test The Server</title>
+	    <note>
+		<simpara>
+		    This step is optional.
+		</simpara>
+	    </note>
+	    <simpara>
+		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:
+	    </simpara>
+	    <screen format="linespecific">
+root@/usr/local/src# radiusd -X
+</screen>
+	    <simpara>
+		Create file <filename moreinfo="none">digest</filename> and put the following
+		into the file:
+	    </simpara>
+		<programlisting format="linespecific">
+User-Name = "test", Digest-Response = "631d6d73147add2f9e437f59bbc3aeb7", 
+Digest-Realm = "testrealm", Digest-Nonce = "1234abcd" , 
+Digest-Method = "INVITE", Digest-URI = "sip:[email protected]", 
+Digest-Algorithm = "MD5", Digest-User-Name = "test"
+</programlisting>
+	    <simpara>
+		All the attributes must be on a single line.
+	    </simpara>
+	    <simpara>
+		Run <command moreinfo="none">radclient</command> to test the server:
+	    </simpara>
+	    <screen format="linespecific">
+root@/usr/local/src# radclient -f digest localhost auth &lt;shared_secret&gt;
+</screen>
+	    <note>
+		<simpara>
+		    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 <filename
+		    moreinfo="none">clients.conf</filename> file. Don't forget to
+		    replace &lt;shared_secret&gt; with the shared secret configured for locahost
+		    clients in <filename moreinfo="none">clients.conf</filename>.
+		</simpara>
+	    </note>
+	    <simpara>
+		If your server works properly then you should see the following response:
+	    </simpara>
+	    <screen format="linespecific">
+Received response ID 224, code 2, length = 45
+        Reply-Message = "Hello, test with digest"
+</screen>
+	</section>
+	
+	<section>
+	    <title>Authentication Configuration</title>
+	    <simpara>
+		To create user <quote>joe</quote> in domain <quote>iptel.org</quote> with password
+		<quote>heslo</quote> put the following into file <filename
+		moreinfo="none">/usr/local/etc/raddb/users</filename>:
+	    </simpara>
+	    <programlisting format="linespecific">
[email protected] Auth-Type := Digest, User-Password == "heslo"
+     Reply-Message = "Authenticated",
+     Sip-Rpid = "1234"
+</programlisting>
+	    <simpara>
+		Attribute <quote>Sip-Rpid</quote> 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.
+	    </simpara>
+	</section>
+	
+	<section>
+	    <title>Accounting Configuration</title>
+	    <simpara>
+		By default FreeRADIUS server will log all accounting requests into <filename
+		    moreinfo="none">/usr/local/var/log/radius/radacct</filename> 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.
+	    </simpara>
+	    <example>
+		<title>Example of Accounting Report</title>
+		<programlisting format="linespecific">
+Tue Jun 24 00:20:55 2003
+        Acct-Status-Type = Start
+        Service-Type = 15
+        Sip-Response-Code = 200
+        Sip-Method = 1
+        User-Name = "[email protected]"
+        Calling-Station-Id = "sip:[email protected]"
+        Called-Station-Id = "sip:[email protected]"
+        Sip-Translated-Request-URI = "sip:[email protected]"
+        Acct-Session-Id = "[email protected]"
+        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 = "[email protected]"
+        Calling-Station-Id = "sip:[email protected]"
+        Called-Station-Id = "sip:[email protected]"
+        Sip-Translated-Request-URI = "sip:192.168.2.32:9576"
+        Acct-Session-Id = "[email protected]"
+        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
+</programlisting>
+	    </example>
+	</section>
+	<section>
+	    <title>Group Checking Configuration</title>
+	    <simpara>
+		If you want to make user <quote>joe</quote> in domain <quote>iptel.org</quote>
+		member of group <quote>pstn</quote> then add the following to your <filename
+		moreinfo="none">/usr/local/etc/raddb/users</filename> file:
+	    </simpara>
+	    <programlisting format="linespecific">
[email protected] Sip-Group == "pstn", Auth-Type := Accept
+        Reply-Message = "Authorized"
+</programlisting>
+	</section>
+    </chapter>
+    <chapter>
+	<title>&ser; Configuration</title>
+	<simpara>
+	    We will describe installation from sources here. If you use binary packages then there
+	    is an additional package containg &rad; related modules. You will need to install the
+	    package.
+	</simpara>
+	<warning>
+	    <simpara>
+		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.
+	    </simpara>
+	    <simpara>
+		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 incovenience.
+	    </simpara>
+	</warning>
+	<simpara>
+	    &rad;-related modules are not compiled by default. To compile them, edit <filename
+		moreinfo="none">Makefile</filename>, find variable
+	    <varname>exclude_modules</varname> and you should see <quote>auth_radius</quote>,
+	    <quote>group_radius</quote>, and <quote>uri_radius</quote> among excluded
+	    modules. Simply remove the three modules from the list.
+	</simpara>
+	<simpara>
+	    If you need &rad; accounting then edit also sip_router/modules/acc/Makefile and
+	    uncomment lines containing:
+	</simpara>
+	    <programlisting format="linespecific">
+DEFS+=-DRAD_ACC
+LIBS=-L$(LOCALBASE)/lib -lradiusclient
+</programlisting>
+	<simpara>
+	    Then recompile and re-install &ser:
+	</simpara>
+	    <screen format="linespecific">
+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
+</screen>
+	<section>
+	    <title>Authentication Configuration</title>
+	    <simpara>
+		Edit configuration file of &ser; and instead of <filename
+		    moreinfo="none">auth_db.so</filename> load <filename
+		    moreinfo="none">auth_radius.so</filename> and also replace <function
+		    moreinfo="none">www_authorize</function> with <function
+		    moreinfo="none">radius_www_authorize</function>.
+	    </simpara>
+	    <note>
+		<simpara>
+		    <function moreinfo="none">radius_www_authorize</function> takes just one
+		    parameter (as opposed to <function moreinfo="none">www_authorize</function>
+		    which takes 2).
+		</simpara>
+	    </note>
+	</section>
+	<section>
+	    <title>Accounting Configuration</title>
+	    <simpara>
+		To enable &rad; accounting simply use <varname>radius_log_flag</varname> and
+		<varname>radius_log_missed_flag</varname> parameters instead of <varname>log_flag</varname>
+		and <varname>log_missed_flag</varname>. Mark transactions that should be logged with
+		flags configured in the parameters.
+	    </simpara>
+	</section>
+	<section>
+	    <title>Group Membership Checking</title>
+	    <simpara>
+		Instead of <filename moreinfo="none">group.so</filename> load <filename
+		    moreinfo="none">group_radius.so</filename>. The module exports the same
+		    functions as <filename moreinfo="none">group.so</filename>, the only difference
+		    is that all the function names exported by <filename
+		    moreinfo="none">group_radius.so</filename> have <quote>radius_</quote> prefix.
+	    </simpara>
+	</section>
+    </chapter>
+
+    <chapter>
+	<title>Frequently Asked Questions</title>
+	<qandaset>
+	    <qandaentry>
+		<question>
+		    <simpara>
+			I compiled &ser; &rad; modules and installed radiusclient library, but when I
+			try to start ser I get the following error message:
+		    </simpara>
+		    <programlisting format="linespecific">
+libradiusclient.so.0: cannot open shared object file: No such file or directory
+</programlisting>
+		</question>
+		<answer>
+		    <simpara>
+			Make sure that the directory which contains the library (usually <filename
+			    moreinfo="none">/usr/local/lib</filename>) is listed in <filename
+			    moreinfo="none">/etc/ld.so.conf</filename> and run <command
+			    moreinfo="none">ldconfig -v</command> (as root).
+		    </simpara>
+		</answer>
+	    </qandaentry>
+	</qandaset>
+    </chapter>
+</book>