- Spelling checked
[sip-router] / doc / ser_radius / ser_radius.sgml
1 <!-- $Id$ -->
2 <!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.2//EN" [
3
4 <!ENTITY ser "<acronym>SIP</acronym> Express Router">
5 <!ENTITY nat "<acronym>NAT</acronym>">
6 <!ENTITY ip "<acronym>IP</acronym>">
7 <!ENTITY rtp "<acronym>RTP</acronym>">
8 <!ENTITY stun "<acronym>STUN</acronym>">
9 <!ENTITY fokus "FhG FOKUS">
10 <!ENTITY sip "<acronym>SIP</acronym>">
11 <!ENTITY rad "RADIUS">
12 <!ENTITY pstn "<acronym>PSTN</acronym>">
13
14 ]>
15
16 <book>
17     <bookinfo>
18         <title>&ser &rad; HOWTO</title>
19         <authorgroup>
20             <author>
21                 <firstname>Jan</firstname>
22                 <surname>Janak</surname>
23                 <email>jan@iptel.org</email>
24             </author>
25         </authorgroup>
26         <copyright>
27             <year>2003</year>
28             <holder>&fokus;</holder>
29         </copyright>
30         <revhistory>
31             <revision>
32                 <revnumber>$Revision$</revnumber>
33                 <date>$Date$</date>
34             </revision>
35         </revhistory>
36     </bookinfo>
37
38     <chapter>
39         <title>Introduction</title>
40         <simpara>
41             &ser can be configured to use &rad; server for authentication, accounting, and group
42             membership checking. Since configuration of &rad; seems to be a common source of
43             problems, we decided to put together this HOWTO.
44         </simpara>
45         <simpara>
46             The HOWTO covers installation and configuration of FreeRADIUS server only. There are
47             also other &rad; servers available and as long as they support digest authentication,
48             they should work too. Any volunteers willing to describe setup of other &rad; servers
49             are encouraged to contact the author.
50         </simpara>
51         <section>
52             <title>Prerequisites</title>
53             <simpara>
54                 To setup &rad; support in &ser; you will need the following:
55             </simpara>
56             <itemizedlist>
57                 <listitem>
58                     <simpara>
59                         FreeRADIUS server, you can get it from <ulink
60                             url="http://www.freeradius.org">FreeRADIUS website</ulink>. The HOWTO
61                             describes installation and setup of release 0.9.1.
62                     </simpara>
63                 </listitem>
64                 <listitem>
65                     <simpara>
66                         Radiusclient library. In version 0.8.14 we started to use the new version of
67                         radiusclient library developed by Maxim Sobolev called radiusclient-ng. The 
68                         homepage of the library is <ulink
69                             url="http://developer.berlios.de/projects/radiusclient-ng/">http://developer.berlios.de/projects/radiusclient-ng/</ulink>
70                     </simpara>
71                 </listitem>
72                 <listitem>
73                     <simpara>
74                         &ser;, get it from <ulink url="http://iptel.org/ser">http://iptel.org/ser</ulink>
75                     </simpara>
76                 </listitem>
77                 <listitem>
78                     <simpara>
79                         You should also have some experience in configuring &ser;. Before you enable
80                         &rad; authentication or accounting make sure that the basic server is
81                         running and that you know how to customize it to your taste.
82                     </simpara>
83                 </listitem>
84                 <listitem>
85                     <simpara>
86                         If you want to use &rad; accounting then you will have to compile &ser; from
87                         sources so you should know how to do it.
88                     </simpara>
89                 </listitem>
90             </itemizedlist>
91             <simpara>
92                 Various unix/linux distributions might include binary packages of the mentioned
93                 applications. In that case you can safely use the packages, there shouldn't be any
94                 problem. Location of some files may be different, though. We will describe
95                 how to install the software from sources only.
96             </simpara>
97             <warning>
98                 <simpara>
99                     Configuration of FreeRADIUS server described in the document is in no way
100                     exhaustive. This document is a sort of quick-start-guide, it shows how to get
101                     things running, but you should definitely read FreeRADIUS documentation
102                     and configure the server properly ! You have been warned.
103                 </simpara>
104             </warning>
105         </section>
106     </chapter>
107     <chapter>
108         <title>Radiusclient Library</title>
109         <simpara>
110             Untar the source tarball.
111         </simpara>
112         <screen format="linespecific">
113 root@localhost:/usr/local/src# tar xvfz radiusclient-0.4.3.tar.gz
114 </screen>
115             <simpara>
116                 Compile and install the library.
117             </simpara>
118             <screen format="linespecific">
119 root@localhost:/usr/local/src# cd radiusclient-0.3.2
120 root@localhost:/usr/local/src/radiusclient-0.3.2# ./configure
121 root@localhost:/usr/local/src/radiusclient-0.3.2# make
122 root@localhost:/usr/local/src/radiusclient-0.3.2# make install
123 </screen>
124         <simpara>
125             By default all the configuration files of the radiusclient library will be in
126             <filename moreinfo="none">/usr/local/etc/radiusclient</filename> directory.
127         </simpara>
128         <simpara>
129             If you use binary packages then the configuration files will be probably in <filename
130             moreinfo="none">/etc/radiusclient</filename>.
131         </simpara>
132         <section>
133             <title>File <filename moreinfo="none">radiusclient.conf</filename></title>
134             <simpara>
135                 The main configuration file of the library is <filename
136                     moreinfo="none">/usr/local/etc/radiusclient/radiusclient.conf</filename>, open
137                     the file in your favorite text editor and find lines containing the following:
138             </simpara>
139             <programlisting format="linespecific">
140 authserver      localhost
141 </programlisting>
142             <simpara>
143                 This is the hostname or &ip; address of the RADIUS server used for authentication. You
144                 will have to change this unless the server is running on the same host as your &sip;
145                 proxy.
146             </simpara>
147             <programlisting format="linespecific">
148 acctserver      localhost
149 </programlisting>
150             <simpara>
151                 This is the hostname or &ip; address of the RADIUS server used for accounting. You
152                 will have to change this unless the server is running on the same host as your &sip
153                 proxy.
154             </simpara>
155         </section>
156         <section>
157             <title>File <filename moreinfo="none">servers</filename></title>
158             <simpara>
159                 &rad; protocol uses simple access control mechanism based on shared secrets
160                 that allows &rad; servers to limit access from &rad; clients. A &rad; server is
161                 configured with a secret string and only &rad; clients that have the same
162                 secret will be accepted.
163             </simpara>
164             <simpara>
165                 You need to configure a shared secret for each server you have configured in
166                     <filename moreinfo="none">radiusclient.conf</filename> file in the previous
167                     step. The shared secrets are stored in <filename
168                     moreinfo="none">/usr/local/etc/radiusclient/servers</filename> file.
169             </simpara>
170             <simpara>
171                 Each line contains hostname of a &rad; server and shared secret used in
172                 communication with that server. The two values are separated by
173                 whitespaces. Configure shared secrets for every &rad; server you are going to use.
174             </simpara>
175             <warning>
176                 <simpara>
177                     &rad; servers and clients must be configured with the same shared secret,
178                     otherwise they will not accept RADIUS messages from each other and neither
179                     authentication nor accounting will work !
180                 </simpara>
181             </warning>
182         </section>
183         <section>
184             <title>File <filename moreinfo="none">dictionary</filename></title>
185             <simpara>
186                 Radiusclient library contains file called <filename
187                 moreinfo="none">dictionary.ser</filename>. That file includes all the attributes
188                 that are needed by &ser;. Include the file in the main <filename
189                 moreinfo="none">dictionary</filename> file. To include the file, put the following
190                 line at the end of <filename moreinfo="none">dictionary</filename> file:
191             </simpara>
192             <screen format="linespecific">
193 $INCLUDE /usr/local/etc/radiuclient/dictionary.ser
194 </screen>
195         </section>
196     </chapter>
197
198     <chapter>
199         <title>FreeRADIUS Server</title>
200         <simpara>
201             Untar, configure, build, and install the server:
202         </simpara>
203             <screen format="linespecific">
204 root@localhost:/usr/local/src# tar xvfz freeradius-0.9.1.tar.gz
205 root@localhost:/usr/local/src# cd freeradius-0.9.1
206 root@localhost"/usr/local/src/freeradius-0.9.1# ./configure
207 root@localhost"/usr/local/src/freeradius-0.9.1# make
208 root@localhost"/usr/local/src/freeradius-0.9.1# make install
209 </screen>
210         <simpara>
211             All the configuration files of FreeRADIUS server will be in <filename
212             moreinfo="none">/usr/local/etc/raddb</filename> directory. If you install a binary
213             package then you will probably find them in <filename moreinfo="none">/etc/raddb</filename>.
214         </simpara>
215         <simpara>
216             The following sections describe how to configure freeradius server. First we describe
217             the common configuration that must be done in any case. Configuration specific for
218             authentication, accounting, and group membership checking will be described in separate
219             sections.
220         </simpara>
221         
222         <section>
223             <title>Common configuration</title>
224             <section>
225                 <title>File <filename moreinfo="none">clients.conf</filename></title>
226                 <simpara>
227                     File <filename moreinfo="none">/usr/local/etc/raddb/clients.conf</filename>
228                     contains description of &rad; clients that are allowed to use the server. For
229                     each of the clients you need to specify it's hostname or &ip address and also a
230                     shared secret. The shared secret must be the same string you configured in
231                     radiusclient library.
232                 </simpara>
233                 <simpara>
234                     Suppose that your &sip; server is running on host proxy.foo.bar and
235                     radiusclient library on that machine has been configure with
236                     <quote>foobarsecret</quote> as the shared secret. You need to put the
237                     following section into the file:
238                 </simpara>
239                 <programlisting format="linespecific">
240 client proxy.foo.bar {
241     secret = foobarsecret
242     shortname = foo
243 }
244 </programlisting>
245                 <simpara>
246                     This fragment allows access from &rad; clients on proxy.foo.bar if they use
247                     <quote>foobarsecret</quote> as the shared secret.
248                 </simpara>
249                 <note>
250                     <simpara>
251                         The file already contains an entry for localhost (127.0.0.1), so if you are
252                         running the &rad; server on the same host as your &sip; server, then modify
253                         the existing entry instead. By default it contains shared secret
254                         <quote>testing123</quote>.
255                     </simpara>
256                 </note>
257             </section>
258             
259             <section>
260                 <title>File <filename moreinfo="none">dictionary</filename></title>
261                 <simpara>
262                     File <filename moreinfo="none">/usr/local/etc/raddb/dictionary</filename>
263                     contains the dictionary of FreeRADIUS server. You have to add the same
264                     dictionary file (<filename moreinfo="none">dictionary.ser</filename>), which you
265                     added to the dictionary of radiusclient library, also here. In this case you
266                     don't have to append the contents of the file, you can include it into the main
267                     file.  Add the following line at the end of <filename
268                     moreinfo="none">/usr/local/etc/raddb/dictionary</filename>:
269                 </simpara>
270                 <programlisting format="linespecific">
271 $INCLUDE /usr/local/etc/radiusclient/dictionary.ser
272 </programlisting>
273                 <simpara>
274                     That will include the same attribute definitions that are used in radiusclient
275                     library so the client and server will understand each other.
276                 </simpara>
277             </section>
278
279             <section>
280                 <title>File <filename moreinfo="none">radiusd.conf</filename></title>
281                 <simpara>
282                     Digest authentication is disabled by default and you must enable it in this
283                     file. There are two sections, <quote>authorize</quote> and
284                     <quote>authenticate</quote>. Both sections contain line containing word
285                     <quote>digest</quote>. Both of them are commented and you must un-comment them
286                     to enable digest authentication.
287                 </simpara>
288                 <note>
289                     <simpara>
290                         There is also another line containing word <quote>digest</quote> followed by
291                         curly braces and it is enabled by default. The section is supposed to
292                         contain digest module parameters but because digest module has no parameters,
293                         it is empty. This is not the line you are supposed to uncomment ! There are
294                         two more.
295                     </simpara>
296                 </note>
297             </section>
298             
299             <section>
300                 <title>File <filename moreinfo="none">users</filename></title>
301                 <simpara>
302                     This file contains authentication information for each user. For testing
303                     purposes we will create user <quote>test</quote>. Put the following into the file:
304                 </simpara>
305                     <programlisting format="linespecific">
306 test Auth-Type := Digest, User-Password == "test"
307      Reply-Message = "Hello, test with digest"
308 </programlisting>
309
310                 <simpara>
311                     The username and password is for testing only, you can safely remove the entry
312                     once your RADIUS server works and you are able to authenticate.
313                 </simpara>
314             </section>
315         </section>
316
317         <section>
318             <title>Test The Server</title>
319             <note>
320                 <simpara>
321                     This step is optional.
322                 </simpara>
323             </note>
324             <simpara>
325                 The basic configuration of FreeRADIUS server is done it now we are going to test if
326                 it really works. Start the server with parameter -X. That will cause the server to
327                 stay in the foreground (it will not turn into daemon) and produce a lot of debugging
328                 information on the standard output:
329             </simpara>
330             <screen format="linespecific">
331 root@/usr/local/src# radiusd -X
332 </screen>
333             <simpara>
334                 Create file <filename moreinfo="none">digest</filename> and put the following
335                 into the file:
336             </simpara>
337                 <programlisting format="linespecific">
338 User-Name = "test", Digest-Response = "631d6d73147add2f9e437f59bbc3aeb7", 
339 Digest-Realm = "testrealm", Digest-Nonce = "1234abcd" , 
340 Digest-Method = "INVITE", Digest-URI = "sip:5555551212@example.com", 
341 Digest-Algorithm = "MD5", Digest-User-Name = "test"
342 </programlisting>
343             <simpara>
344                 All the attributes must be on a single line.
345             </simpara>
346             <simpara>
347                 Run <command moreinfo="none">radclient</command> to test the server:
348             </simpara>
349             <screen format="linespecific">
350 root@/usr/local/src# radclient -f digest localhost auth &lt;shared_secret&gt;
351 </screen>
352             <note>
353                 <simpara>
354                     I suppose that you run the test utility directly on the &rad; server since
355                     it comes with the FreeRADIUS server package. That also means that you have
356                     to enable access from localhost in your <filename
357                     moreinfo="none">clients.conf</filename> file. Don't forget to
358                     replace &lt;shared_secret&gt; with the shared secret configured for locahost
359                     clients in <filename moreinfo="none">clients.conf</filename>.
360                 </simpara>
361             </note>
362             <simpara>
363                 If your server works properly then you should see the following response:
364             </simpara>
365             <screen format="linespecific">
366 Received response ID 224, code 2, length = 45
367         Reply-Message = "Hello, test with digest"
368 </screen>
369         </section>
370         
371         <section>
372             <title>Authentication Configuration</title>
373             <simpara>
374                 To create user <quote>joe</quote> in domain <quote>iptel.org</quote> with password
375                 <quote>heslo</quote> put the following into file <filename
376                 moreinfo="none">/usr/local/etc/raddb/users</filename>:
377             </simpara>
378             <programlisting format="linespecific">
379 joe@iptel.org Auth-Type := Digest, User-Password == "heslo"
380      Reply-Message = "Authenticated",
381      Sip-Rpid = "1234"
382 </programlisting>
383             <simpara>
384                 Attribute <quote>Sip-Rpid</quote> is optional. The attribute contains a phone number
385                 associated to the user. &ser; can be configured to put the phone number into
386                 Remote-Party-ID header field of the &sip; message. The header field can be then used
387                 by &pstn; gateways to display the number as the number of the caller on regular
388                 phones. You can omit the attribute if you don't need it.
389             </simpara>
390         </section>
391         
392         <section>
393             <title>Accounting Configuration</title>
394             <simpara>
395                 By default FreeRADIUS server will log all accounting requests into <filename
396                     moreinfo="none">/usr/local/var/log/radius/radacct</filename> directory in form
397                     of plain text files. The server will create one file for each hostname in the
398                     directory. The following example shows how the log files look like.
399             </simpara>
400             <example>
401                 <title>Example of Accounting Report</title>
402                 <programlisting format="linespecific">
403 Tue Jun 24 00:20:55 2003
404         Acct-Status-Type = Start
405         Service-Type = 15
406         Sip-Response-Code = 200
407         Sip-Method = 1
408         User-Name = "gh@192.168.2.16"
409         Calling-Station-Id = "sip:gh@192.168.2.16"
410         Called-Station-Id = "sip:jiri@192.168.2.16"
411         Sip-Translated-Request-URI = "sip:jiri@192.168.2.36"
412         Acct-Session-Id = "b9a2ffaa-0458-42e1-b5fd-59656b795d29@192.168.2.32"
413         Sip-To-Tag = "cb2cfe2e-3659-28c7-a8cc-ab0b8cbd3012"
414         Sip-From-Tag = "a783bd2f-bb8d-46fd-84a9-00a9833f189e"
415         Sip-CSeq = "1"
416         NAS-IP-Address = 192.168.2.16
417         NAS-Port = 5060
418         Acct-Delay-Time = 0
419         Client-IP-Address = 127.0.0.1
420         Acct-Unique-Session-Id = "9b323e6b2f5b0f33"
421         Timestamp = 1056406855
422
423 Tue Jun 24 00:20:56 2003
424         Acct-Status-Type = Stop
425         Service-Type = 15
426         Sip-Response-Code = 200
427         Sip-Method = 8
428         User-Name = "jiri@192.168.2.16"
429         Calling-Station-Id = "sip:jiri@192.168.2.16"
430         Called-Station-Id = "sip:gh@192.168.2.16"
431         Sip-Translated-Request-URI = "sip:192.168.2.32:9576"
432         Acct-Session-Id = "b9a2ffaa-0458-42e1-b5fd-59656b795d29@192.168.2.32"
433         Sip-To-Tag = "a783bd2f-bb8d-46fd-84a9-00a9833f189e"
434         Sip-From-Tag = "cb2cfe2e-3659-28c7-a8cc-ab0b8cbd3012"
435         Sip-CSeq = "4580"
436         NAS-IP-Address = 192.168.2.16
437         NAS-Port = 5060
438         Acct-Delay-Time = 0
439         Client-IP-Address = 127.0.0.1
440         Acct-Unique-Session-Id = "b2c2479a07b17c95"
441         Timestamp = 1056406856
442 </programlisting>
443             </example>
444         </section>
445         <section>
446             <title>Group Checking Configuration</title>
447             <simpara>
448                 If you want to make user <quote>joe</quote> in domain <quote>iptel.org</quote>
449                 member of group <quote>pstn</quote> then add the following to your <filename
450                 moreinfo="none">/usr/local/etc/raddb/users</filename> file:
451             </simpara>
452             <programlisting format="linespecific">
453 joe@iptel.org Sip-Group == "pstn", Auth-Type := Accept
454         Reply-Message = "Authorized"
455 </programlisting>
456         </section>
457     </chapter>
458     <chapter>
459         <title>&ser; Configuration</title>
460         <simpara>
461             We will describe installation from sources here. If you use binary packages then there
462             is an additional package containing &rad; related modules. You will need to install the
463             package.
464         </simpara>
465         <warning>
466             <simpara>
467                 Due to a mistake the binary packages for &rad; do not include &rad;-enabled
468                 version of acc (accounting) module. The packages contain modules for &rad;
469                 authentication and group membership checking only.
470             </simpara>
471             <simpara>
472                 If you need accounting over &rad; then you will have to compile &rad;-enabled
473                 version of acc module from the sources. This will be fixed in one of future
474                 releases, we apologize for any inconvenience.
475             </simpara>
476         </warning>
477         <simpara>
478             &rad;-related modules are not compiled by default. To compile them, edit <filename
479                 moreinfo="none">Makefile</filename>, find variable
480             <varname>exclude_modules</varname> and you should see <quote>auth_radius</quote>,
481             <quote>group_radius</quote>, and <quote>uri_radius</quote> among excluded
482             modules. Simply remove the three modules from the list.
483         </simpara>
484         <simpara>
485             If you need &rad; accounting then edit also sip_router/modules/acc/Makefile and
486             uncomment lines containing:
487         </simpara>
488             <programlisting format="linespecific">
489 DEFS+=-DRAD_ACC
490 LIBS=-L$(LOCALBASE)/lib -lradiusclient
491 </programlisting>
492         <simpara>
493             Then recompile and re-install &ser:
494         </simpara>
495             <screen format="linespecific">
496 root@localhost:/usr/local/src/sip_router# make proper
497 root@localhost:/usr/local/src/sip_router# make all
498 root@localhost:/usr/local/src/sip_router# make install
499 </screen>
500         <section>
501             <title>Authentication Configuration</title>
502             <simpara>
503                 Edit configuration file of &ser; and instead of <filename
504                     moreinfo="none">auth_db.so</filename> load <filename
505                     moreinfo="none">auth_radius.so</filename> and also replace <function
506                     moreinfo="none">www_authorize</function> with <function
507                     moreinfo="none">radius_www_authorize</function>.
508             </simpara>
509             <note>
510                 <simpara>
511                     <function moreinfo="none">radius_www_authorize</function> takes just one
512                     parameter (as opposed to <function moreinfo="none">www_authorize</function>
513                     which takes 2).
514                 </simpara>
515             </note>
516         </section>
517         <section>
518             <title>Accounting Configuration</title>
519             <simpara>
520                 To enable &rad; accounting simply use <varname>radius_log_flag</varname> and
521                 <varname>radius_log_missed_flag</varname> parameters instead of <varname>log_flag</varname>
522                 and <varname>log_missed_flag</varname>. Mark transactions that should be logged with
523                 flags configured in the parameters.
524             </simpara>
525         </section>
526         <section>
527             <title>Group Membership Checking</title>
528             <simpara>
529                 Instead of <filename moreinfo="none">group.so</filename> load <filename
530                     moreinfo="none">group_radius.so</filename>. The module exports the same
531                     functions as <filename moreinfo="none">group.so</filename>, the only difference
532                     is that all the function names exported by <filename
533                     moreinfo="none">group_radius.so</filename> have <quote>radius_</quote> prefix.
534             </simpara>
535         </section>
536     </chapter>
537
538     <chapter>
539         <title>Frequently Asked Questions</title>
540         <qandaset>
541             <qandaentry>
542                 <question>
543                     <simpara>
544                         I compiled &ser; &rad; modules and installed radiusclient library, but when I
545                         try to start ser I get the following error message:
546                     </simpara>
547                     <programlisting format="linespecific">
548 libradiusclient.so.0: cannot open shared object file: No such file or directory
549 </programlisting>
550                 </question>
551                 <answer>
552                     <simpara>
553                         Make sure that the directory which contains the library (usually <filename
554                             moreinfo="none">/usr/local/lib</filename>) is listed in <filename
555                             moreinfo="none">/etc/ld.so.conf</filename> and run <command
556                             moreinfo="none">ldconfig -v</command> (as root).
557                     </simpara>
558                 </answer>
559             </qandaentry>
560             <qandaentry>
561                 <question>
562                     <simpara>
563                         I configured everything as described in this HOWTO, but I get the following
564                         message from radiusclient library <quote> check_radius_reply: received
565                         invalid reply digest from RADIUS server</quote>. What does that mean ?
566                     </simpara>
567                 </question>
568                 <answer>
569                     <simpara>
570                         That means that radiusclient library was unable to verify digest of the
571                         RADIUS message (it is not related to &sip; digest) because shared secret of
572                         the client and server do not match.
573                     </simpara>
574                     <note>
575                         <simpara>
576                             FreeRADIUS server has two files that can contain definitions of clients
577                             and corresponding shared secrets--<filename
578                                 moreinfo="none">clients</filename> and <filename
579                             moreinfo="none">clients.conf</filename>.
580                         </simpara>
581                         <simpara>
582                             If you have proper shared secret in one file and you still get the
583                             mentioned error message then check also the other file. This can easily
584                             happen to clients running on the same host (127.0.0.1 or localhost),
585                             because <filename moreinfo="none">clients.conf</filename> contains
586                             definition for localhost by default with secret <quote>testing123</quote>.
587                         </simpara>
588                     </note>
589                 </answer>
590             </qandaentry>
591         </qandaset>
592     </chapter>
593 </book>