Browse code

- Improved documentation system - documentation makefiles - XML-based dialect of docbook used

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