Browse code

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

Jan Janak authored on 23/07/2005 22:48:53
Showing 1 changed files
1 1
deleted file mode 100644
... ...
@@ -1,1502 +0,0 @@
1
-    <chapter>
2
-	<title>Server Operation</title>
3
-	<section id="operationalpractices">
4
-	    <title>Recommended Operational Practices</title>
5
-
6
-	    <para>
7
-		Operation of a SIP server is not always easy task.
8
-		Server administrators are challenged by broken or
9
-		misconfigured user agents, network and host failures,
10
-		hostile attacks and other stress-makers. All such
11
-		situations may lead to an operational failure. It is sometimes
12
-		very difficult to figure out the root reason of
13
-		a failure, particularly in a distributed environment
14
-		with many SIP components involved.		
15
-		In this section,
16
-		we share some of our practices and refer to tools
17
-		which have proven to
18
-		make life of administrators easier
19
-	    </para>
20
-
21
-	<qandaset>
22
-	    <qandaentry>
23
-		<question>
24
-		    <para>
25
-			Keeping track of messages is good
26
-		    </para>
27
-		</question>
28
-		<answer>
29
-			<para>
30
-			    Frequently, operational errors are discovered or reported
31
-			    with a delay.
32
-			    Users frustrated by an error
33
-			    frequently approach administrators
34
-			    and scream "even though my SIP requests were absolutely ok
35
-			    yesterday, they were mistakenly denied by your server".
36
-			    If administrators do not record all SIP traffic at
37
-			    their site, they will be no more able to identify
38
-			    the problem reason.
39
-			    We thus recommend that site
40
-			    operators record all messages passing their site and keep them
41
-			    stored for some period of time.
42
-			They may use utilities such as 
43
-			<application>ngrep 
44
-			</application> or 
45
-			<application>tcpdump
46
-			</application>.
47
-			There is also a utility <application moreinfo="none">
48
-			    scripts/harv_ser.sh</application> in <application moreinfo="none">
49
-			ser</application> distribution for post-processing
50
-			of captured messages. It summarizes messages captured
51
-			by reply status and user-agent header field.
52
-		    </para>
53
-		</answer>
54
-	    </qandaentry>
55
-	    <qandaentry>
56
-		<question>
57
-		    <para>
58
-			Real-time Traffic Watching
59
-		    </para>
60
-		</question>
61
-		<answer>
62
-			<para>
63
-		    Looking at SIP messages in real-time may help to gain
64
-		    understanding of problems. Though there are commercial
65
-		    tools available, using a simple, text-oriented tool
66
-		    such as <application>ngrep</application> makes the job very well thanks to SIP's textual nature.
67
-			</para>
68
-		    <example id="usingngrep">
69
-			<title>Using <application>ngrep</application>
70
-			</title>
71
-			<para>In this example, all messages at port 5060
72
-			which include the string "bkraegelin" are captured
73
-			and displayed</para>
74
-			<programlisting format="linespecific">
75
-[jiri@fox s]$ ngrep bkraegelin@ port 5060
76
-interface: eth0 (195.37.77.96/255.255.255.240)
77
-filter: ip and ( port 5060 )
78
-match: bkraegelin@
79
-#
80
-U +0.000000 153.96.14.162:50240 -> 195.37.77.101:5060
81
-REGISTER sip:iptel.org SIP/2.0.
82
-Via: SIP/2.0/UDP 153.96.14.162:5060.
83
-From: sip:bkraegelin@iptel.org.
84
-To: sip:bkraegelin@iptel.org.
85
-Call-ID: 0009b7aa-1249b554-6407d246-72d2450a@153.96.14.162.
86
-Date: Thu, 26 Sep 2002 22:03:55 GMT.
87
-CSeq: 101 REGISTER.
88
-Expires: 10.
89
-Content-Length: 0.
90
-.
91
-
92
-#
93
-U +0.000406 195.37.77.101:5060 -> 153.96.14.162:5060
94
-SIP/2.0 401 Unauthorized.
95
-Via: SIP/2.0/UDP 153.96.14.162:5060.
96
-From: sip:bkraegelin@iptel.org.
97
-To: sip:bkraegelin@iptel.org.
98
-Call-ID: 0009b7aa-1249b554-6407d246-72d2450a@153.96.14.162.
99
-CSeq: 101 REGISTER.
100
-WWW-Authenticate: Digest realm="iptel.org", nonce="3d9385170000000043acbf6ba9c9741790e0c57adee73812", algorithm=MD5.
101
-Server: Sip EXpress router(0.8.8 (i386/linux)).
102
-Content-Length: 0.
103
-Warning: 392 127.0.0.1:5060 "Noisy feedback tells: pid=31604 req_src_ip=153.96.14.162 in_uri=sip:iptel.org out_uri=sip:iptel.org via_cnt==1".
104
-
105
-			</programlisting>
106
-		    </example>
107
-		</answer>
108
-	    </qandaentry>
109
-	    <qandaentry>
110
-		<question>
111
-		    <para>
112
-			Tracing Errors in Server Chains
113
-		    </para>
114
-		</question>
115
-		<answer>
116
-			<para>
117
-			    A request may pass any number of proxy servers on
118
-			    its path to its destination. If an error occurs
119
-			    in the chain, it is difficult for upstream troubleshooters
120
-			    and/or users complaining to administrators to learn 
121
-			    more about error circumstances. 
122
-			    <application moreinfo="none">ser
123
-			    </application> does its best and displays extensive
124
-			    diagnostics information in SIP replies. It allows 
125
-			    troubleshooters and/or users who report to troubleshooters
126
-			    to gain additional knowledge about request processing
127
-			    status. 
128
-			    This extended debugging information is part of the warning 
129
-			    header field. See <xref linkend="usingngrep"> for an illustration
130
-			    of a reply that includes such a warning header field. The header
131
-			    field contains the following pieces of information:
132
-			<itemizedlist>
133
-			    <listitem>
134
-				<para>
135
-				Server's IP Address -- good to identify
136
-				from which server in a chain the reply
137
-				came.
138
-				    </para>
139
-			    </listitem>
140
-			    <listitem>
141
-				    <para>
142
-					Incoming and outgoing URIs -- good to
143
-					learn for which URI the reply was
144
-					generated, as it may be rewritten
145
-					many times in the path. Particularly
146
-					useful for debugging of numbering plans.
147
-				    </para>
148
-			    </listitem>
149
-			    <listitem>
150
-				<para>
151
-					Number of Via header fields in replied
152
-					request -- that helps in assessment of
153
-					request path length. Upstream clients would
154
-					not know otherwise, how far away in terms
155
-					of SIP hops their requests were replied.
156
-				</para>
157
-			    </listitem>
158
-				<listitem>
159
-				    <para>
160
-					Server's process id. That is useful for
161
-					debugging to discover situations when
162
-					multiple servers listen at the same
163
-					address.
164
-				    </para>
165
-				</listitem>
166
-				<listitem>
167
-				    <para>
168
-					IP address of previous SIP hop as seen by
169
-					the SIP server.
170
-				    </para>
171
-				</listitem>
172
-			</itemizedlist>
173
-		    </para>
174
-			<para>
175
-			    If server administrator is not comfortable with
176
-			    disclosing all this information, he can turn them
177
-			    off using the <varname>sip_warning</varname> configuration
178
-			    option.
179
-			</para>
180
-		    <para>
181
-			A nice utility for debugging server chains is
182
-			<application moreinfo="none">sipsak</application>,
183
-			SIP Swiss Army Knife, traceroute-like tool for SIP
184
-			developed at iptel.org. It allows you to send
185
-			OPTIONS request with low, increasing Max-Forwards 
186
-			header-fields and follow how it propagates in
187
-			SIP network. See its webpage at
188
-			<ulink url="http://sipsak.berlios.de/">
189
-			    http://sipsak.berlios.de/
190
-			</ulink>.
191
-		    </para>
192
-		    <example>
193
-			<title>Use of SIPSak for Learning SIP Path</title>
194
-			<programlisting format="linespecific">
195
-[jiri@bat sipsak]$ ./sipsak -T -s sip:7271@iptel.org
196
-warning: IP extract from warning activated to be more informational
197
-0: 127.0.0.1 (0.456 ms) SIP/2.0 483 Too Many Hops
198
-1: ?? (31.657 ms) SIP/2.0 200 OK
199
-	without Contact header
200
-
201
-			</programlisting>
202
-			<para>
203
-			    Note that in this example, the second hop
204
-			    server does not issue any warning header fields
205
-			    in replies and it is thus impossible to display 
206
-			    its IP address in <application moreinfo="none">
207
-			    SIPsak</application>'s output.
208
-			</para>
209
-		    </example>
210
-		</answer>
211
-	    </qandaentry>
212
-	    <qandaentry>
213
-		<question>
214
-		    <para>
215
-			Watching Server Health
216
-		    </para>
217
-		</question>
218
-		<answer>
219
-		    <para>
220
-			Watching Server's operation status in real-time may
221
-			also be a great aid for trouble-shooting. 
222
-			<application>ser</application> has an excellent 
223
-			facility, a FIFO server, which allows UNIX
224
-			tools to access server's internals. (It is 
225
-			similar to how Linux tool access Linux kernel
226
-			via the proc file system.) The FIFO server
227
-			accepts commands via a FIFO (named pipe) and
228
-			returns data asked for. Administrators do not
229
-			need to learn details of the FIFO communication
230
-			and can serve themselves using a front-end
231
-			utility <application moreinfo="none">serctl</application>.
232
-			Of particular interest for 
233
-			monitoring server's operation are 
234
-			<application moreinfo="none">serctl</application>
235
-			commands
236
-			<command moreinfo="none">ps</command> and
237
-			<command moreinfo="none">moni</command>.
238
-			The former displays running 
239
-			<application moreinfo="none">ser</application>
240
-			processes, whereas the latter shows statistics.
241
-		    </para>
242
-		    <example>
243
-			<title>serctl ps command</title>
244
-			<para>
245
-			    This example shows 10 processes running at a host.
246
-			    The process 0, "attendant" watches child processes
247
-			    and terminates all of them if a failure occurs in
248
-			    any of them. Processes 1-4 listen at local
249
-			    interface and processes 5-8 listen at Ethernet
250
-			    interface at port number 5060. Process number
251
-			    9 runs FIFO server, and process number 10
252
-			    processes all server timeouts.
253
-			</para>
254
-			<programlisting format="linespecific">
255
-[jiri@fox jiri]$ serctl ps
256
-0	31590	attendant
257
-1	31592	receiver child=0 sock=0 @ 127.0.0.1::5060
258
-2	31595	receiver child=1 sock=0 @ 127.0.0.1::5060
259
-3	31596	receiver child=2 sock=0 @ 127.0.0.1::5060
260
-4	31597	receiver child=3 sock=0 @ 127.0.0.1::5060
261
-5	31604	receiver child=0 sock=1 @ 195.37.77.101::5060
262
-6	31605	receiver child=1 sock=1 @ 195.37.77.101::5060
263
-7	31606	receiver child=2 sock=1 @ 195.37.77.101::5060
264
-8	31610	receiver child=3 sock=1 @ 195.37.77.101::5060
265
-9	31611	fifo server
266
-10	31627	timer
267
-			  
268
-			</programlisting>
269
-		    </example>
270
-		</answer>
271
-	    </qandaentry>
272
-	    <qandaentry>
273
-		<question>
274
-		    <para>
275
-			Is Server Alive
276
-		    </para>
277
-		</question>
278
-		<answer>
279
-		    <para>
280
-			It is essential for solid operation to know
281
-			continuously that server is alive. We've been
282
-			using two tools for this purpose. 
283
-			<application moreinfo="none">sipsak</application>
284
-			does a great job of "pinging" a server, which
285
-			may be used for alerting on unresponsive servers.
286
-		    </para>
287
-		    <para>
288
-			<application moreinfo="none">monit</application> is
289
-			a server watching utility which alerts when
290
-			a server dies.
291
-		    </para>
292
-		</answer>
293
-	    </qandaentry>
294
-	    <qandaentry>
295
-		<question>
296
-		    <para>
297
-			Dealing with DNS
298
-		    </para>
299
-		</question>
300
-		<answer>
301
-		    <para>
302
-			SIP standard leverages DNS. Administrators of
303
-			<application moreinfo="none">ser</application> should
304
-			be aware of impact of DNS on server's operation.
305
-			Server's attempt to resolve an unresolvable address
306
-			may block a server process in terms of seconds. To be
307
-			safer that the server doesn't stop responding
308
-			due to being blocked by DNS resolving, we recommend
309
-			the following practices:
310
-			<itemizedlist>
311
-			    <listitem>
312
-				<para>
313
-				    Start a sufficient number of children processes.
314
-				    If one is blocked, the other children will
315
-				    keep serving.
316
-				</para>
317
-			    </listitem>
318
-			    <listitem>
319
-				<para>
320
-				    Use DNS caching. For example, in Linux,
321
-				    there is an <application moreinfo="none">
322
-				    nscd</application> daemon available for
323
-				    this purpose.
324
-				</para>
325
-			    </listitem>
326
-			    <listitem>
327
-				<para>
328
-				    Process transactions statefully if memory
329
-				    allows. That helps to absorb retransmissions
330
-				    without having to resolve DNS for each of
331
-				    them.
332
-				</para>
333
-			    </listitem>
334
-			</itemizedlist>
335
-		    </para>
336
-		</answer>
337
-	    </qandaentry>
338
-		<qandaentry>
339
-			<question>
340
-				<para>
341
-					Logging
342
-				</para>
343
-			</question>
344
-			<answer>
345
-			<anchor id="logging">
346
-			<para>
347
-			    <application>ser</application> by default logs
348
-			    to <application>syslog</application> facility.
349
-			    It is very useful to watch log messages for
350
-			    abnormal behavior. Log messages, subject to
351
-			    <application>syslog</application> configuration
352
-			    may be stored at different files, or even at remote
353
-			    systems. A typical location of the log file is
354
-			    <filename>/var/log/messages</filename>.
355
-			</para>
356
-			<note>
357
-			    <para>
358
-				One can also use other <application>syslogd</application>
359
-				implementation. <application>metalog</application>
360
-				(<ulink url="http://metalog.sourceforge.net/">
361
-				    http://metalog.sourceforge.net/
362
-				</ulink>)
363
-				features regular expression matching that enables
364
-				to filter and group log messages.
365
-			    </para>
366
-			</note>
367
-			<para>
368
-			    For the purpose of debugging configuration scripts, one may
369
-			    want to redirect log messages to console not to pollute
370
-			    syslog files. To do so configure <application moreinfo="none">ser</application>
371
-			    in the following way:
372
-			    <itemizedlist>
373
-				<listitem>
374
-				    <para>
375
-					Attach ser to console by setting <varname>fork=no</varname>.
376
-				    </para>
377
-				</listitem>
378
-				<listitem>
379
-				    <para>
380
-					Set explicitly at which address 
381
-					<application moreinfo="none">ser</application>
382
-					should be listening, e.g., <varname>listen=192.168.2.16</varname>.
383
-				    </para>
384
-				</listitem>
385
-				<listitem>
386
-				    <para>
387
-					Redirect log messages to standard error by setting
388
-					<varname>log_stderror=yes</varname>
389
-				    </para>
390
-				</listitem>
391
-				<listitem>
392
-				    <para>
393
-					Set appropriately high log level. (Be sure that you redirected logging
394
-					to standard output. Flooding system logs with many detailed messages
395
-					would make the logs difficult to read and use.) You can set the global
396
-					logging threshold value with the option <varname>debug=nr</varname>,
397
-					where the higher <varname>nr</varname> the more detailed output.
398
-					If you wish to set log level only for some script events, include
399
-					the desired log level as the first parameter of the
400
-					<command moreinfo="none">log</command> action in your script.
401
-					The messages will be then printed if <command moreinfo="none">log</command>'s
402
-					level is lower than the global threshold, i.e., the lower the more
403
-					noisy output you get.
404
-					<example>
405
-					    <title>Logging Script</title>
406
-					    <programlisting format="linespecific">
407
-&logging;
408
-					    </programlisting>
409
-					    <para>
410
-						The following SIP message causes then logging output as shown
411
-						bellow.
412
-					    </para>
413
-					    <programlisting format="linespecific">
414
-REGISTER sip:192.168.2.16 SIP/2.0
415
-Via: SIP/2.0/UDP 192.168.2.33:5060
416
-From: sip:113311@192.168.2.16
417
-To: sip:113311@192.168.2.16
418
-Call-ID: 00036bb9-0fd305e2-7daec266-212e5ec9@192.168.2.33
419
-Date: Thu, 27 Feb 2003 15:10:52 GMT
420
-CSeq: 101 REGISTER
421
-User-Agent: CSCO/4
422
-Contact: sip:113311@192.168.2.33:5060
423
-Content-Length: 0
424
-Expires: 600                                 
425
-					    </programlisting>
426
-					    <programlisting format="linespecific">
427
-[jiri@cat sip_router]$ ./ser -f examples/logging.cfg 
428
-Listening on 
429
-              192.168.2.16 [192.168.2.16]::5060
430
-Aliases: cat.iptel.org:5060 cat:5060 
431
-WARNING: no fork mode 
432
- 0(0) INFO: udp_init: SO_RCVBUF is initially 65535
433
- 0(0) INFO: udp_init: SO_RCVBUF is finally 131070
434
- 0(17379) REGISTER received
435
- 0(17379) request for other domain received					
436
-					    </programlisting>
437
-					</example>
438
-				    </para>
439
-				</listitem>
440
-			    </itemizedlist>
441
-			</para>
442
-			</answer>
443
-		</qandaentry>
444
-	    <qandaentry>
445
-		<question>
446
-		    <para>
447
-			Labeling Outbound Requests
448
-		    </para>
449
-		</question>
450
-		<answer>
451
-		    <para>
452
-		    Without knowing, which pieces of script code a relayed
453
-		    request visited, trouble-shooting would be difficult.
454
-		    Scripts typically apply different processing to
455
-		    different routes such as to IP phones and PSTN
456
-		    gateways. We thus recommend to label outgoing
457
-		    requests with a label describing the type of processing
458
-		    applied to the request.
459
-			</para>
460
-		    <para>
461
-			Attaching "routing-history" hints to relayed
462
-			requests is as easy as using the 
463
-			<command moreinfo="none">append_hf</command>
464
-			action exported by textops module. The following
465
-			example shows how different labels are attached
466
-			to requests to which different routing logic
467
-			was applied.
468
-			<example>
469
-			    <title>"Routing-history" labels</title>
470
-			    <programlisting format="linespecific">
471
-# is the request for our domain?
472
-# if so, process it using UsrLoc and label it so.
473
-if (uri=~[@:\.]domain.foo") {
474
-   if (!lookup("location")) {
475
-    sl_send_reply("404", "Not Found");
476
-    break;
477
-   };
478
-   # user found -- forward to him and label the request
479
-   append_hf("P-hint: USRLOC\r\n");
480
-} else {
481
-# it is an outbound request to some other domain --
482
-# indicate it in the routing-history label
483
-   append_hf("P-hint: OUTBOUND\r\n");
484
-};
485
-t_relay();
486
-			    </programlisting>
487
-			    <para>
488
-				This is how such a labeled requests looks
489
-				like. The last header field includes
490
-				a label indicating the script processed
491
-				the request as outbound.
492
-			    </para>
493
-			    <programlisting format="linespecific">
494
-#
495
-U 2002/09/26 02:03:09.807288 195.37.77.101:5060 -> 203.122.14.122:5060
496
-SUBSCRIBE sip:rajesh@203.122.14.122 SIP/2.0.
497
-Max-Forwards: 10.
498
-Via: SIP/2.0/UDP 195.37.77.101;branch=53.b44e9693.0.
499
-Via: SIP/2.0/UDP 203.122.14.115:16819.
500
-From: sip:rajeshacl@iptel.org;tag=5c7cecb3-cfa2-491d-a0eb-72195d4054c4.
501
-To: sip:rajesh@203.122.14.122.
502
-Call-ID: bd6c45b7-2777-4e7a-b1ae-11c9ac2c6a58@203.122.14.115.
503
-CSeq: 2 SUBSCRIBE.
504
-Contact: sip:203.122.14.115:16819.
505
-User-Agent: Windows RTC/1.0.
506
-Proxy-Authorization: Digest username="rajeshacl", realm="iptel.org", algorithm="MD5", uri="sip:rajesh@203.122.14.122", nonce="3d924fe900000000fd6227db9e565b73c465225d94b2a938", response="a855233f61d409a791f077cbe184d3e3".
507
-Expires: 1800.
508
-Content-Length: 0.
509
-P-hint: OUTBOUND.			    </programlisting>
510
-			</example>
511
-		</para>
512
-		</answer>
513
-	    </qandaentry>
514
-	</qandaset>
515
-	</section> <!-- operational practises -->
516
-
517
-	<section>
518
-	    <title>HOWTOs</title>
519
-	    <para>
520
-		This section is a "cookbook" for dealing with common tasks,
521
-		such as user management or controlling access
522
-		to PSTN gateways.
523
-	    </para>
524
-	    <section>
525
-		<title>User Management</title>
526
-
527
-			<para>
528
-			    There are two tasks related to management of SIP users:
529
-			    maintaining user accounts and maintaining user contacts.
530
-			    Both these jobs can be done using the 
531
-			    <application moreinfo="none">serctl</application>
532
-			    command-line tool. Also, the complimentary web
533
-			    interface, <application moreinfo="none">serweb</application>,
534
-			    can be used for this purpose as well.
535
-			</para>
536
-			<para>
537
-			    If user authentication is turned on, which is a highly
538
-			    advisable practice, user account must be created before
539
-			    a user can log in. To create a new user account, call the
540
-			    <command moreinfo="none">serctl add</command> utility
541
-			    with username, password and email as parameters. It
542
-			    is important that the environment <varname>SIP_DOMAIN</varname>
543
-			    is set to your realm and matches realm values used in
544
-			    your script. The realm value is used for calculation
545
-			    of credentials stored in subscriber database, which are
546
-			    bound permanently to this value.
547
-			    <screen format="linespecific">
548
-[jiri@cat gen_ha1]$ export SIP_DOMAIN=foo.bar
549
-[jiri@cat gen_ha1]$ serctl add newuser secret newuser@foo.bar
550
-MySql Password: 
551
-new user added
552
-			    </screen>
553
-			</para>
554
-			<para><application moreinfo="none">serctl</application> can
555
-			    also change user's password or remove existing accounts
556
-			    from system permanently.
557
-			    <screen format="linespecific">
558
-[jiri@cat gen_ha1]$ serctl passwd newuser newpassword
559
-MySql Password: 
560
-password change succeeded
561
-[jiri@cat gen_ha1]$ serctl rm newuser                
562
-MySql Password: 
563
-user removed
564
-			    </screen>
565
-			</para>
566
-			<para>
567
-			    User contacts are typically automatically uploaded by SIP phones
568
-			    to server during registration process and administrators do not
569
-			    need to worry about them. However, users
570
-			    may wish to append permanent contacts to PSTN gateways
571
-			    or to locations in other administrative domains. 
572
-			    To manipulate the contacts in such cases, use
573
-			    <application moreinfo="none">serctl ul</application>
574
-			    tool. Note that this is the only correct way
575
-			    to update contacts -- direct changes to back-end
576
-			    MySql database do not affect server's memory. Also note,
577
-			    that if persistence is turned off (usrloc "db_mode"
578
-			    parameter set to "0"), all contacts are gone on server
579
-			    reboot. Make sure that persistence is enabled if you
580
-			    add permanent contacts.
581
-			</para>
582
-			<para>
583
-			    To add a new permanent contact for a user, call 
584
-			    <application moreinfo="none">serctl ul add &lt;username&gt
585
-			    &lt;contact&gt;</application>. To delete 
586
-			    all user's contacts, call 
587
-			    <application>serctl ul rm &lt;username&gt;</application>.
588
-			    <application moreinfo="none">serctl ul show &lt;username&gt;</application>
589
-			    prints all current user's contacts.
590
-			    <screen format="linespecific">
591
-[jiri@cat gen_ha1]$ serctl ul add newuser sip:666@gateway.foo.bar
592
-sip:666@gateway.foo.bar
593
-200 Added to table
594
-('newuser','sip:666@gateway.foo.bar') to 'location'
595
-[jiri@cat gen_ha1]$ serctl ul show newuser
596
-&lt;sip:666@gateway.foo.bar&gt;;q=1.00;expires=1073741812
597
-[jiri@cat gen_ha1]$ serctl ul rm newuser  
598
-200 user (location, newuser) deleted
599
-[jiri@cat gen_ha1]$ serctl ul show newuser
600
-404 Username newuser in table location not found
601
-			    </screen>
602
-			</para>
603
-	    </section> <!-- user management -->
604
-	    <section>
605
-		<title>User Aliases</title>
606
-
607
-			<para>
608
-			    Frequently, it is desirable for a user to have multiple
609
-			    addresses in a domain. For example, a user with username "john.doe" wants to be
610
-			    reachable at a shorter address "john" or at a numerical address
611
-			    "12335", so that PSTN callers with digits-only key-pad can reach
612
-			    him too.
613
-			</para>
614
-			<para>
615
-			    With <application moreinfo="none">ser</application>, you can maintain
616
-			    a special user-location table and translate existing aliases to canonical
617
-			    usernames using the <command moreinfo="none">lookup</command>
618
-			    action from usrloc module. The following script fragment demonstrates
619
-			    use of <command moreinfo="none">lookup</command> for this purpose.
620
-			    <example>
621
-				<title>Configuration of Use of Aliases</title>
622
-				<programlisting format="linespecific">
623
-if (!uri==myself) { # request not for our domain...
624
-  route(1); # go somewhere else, where outbound requests are processed
625
-  break;
626
-};
627
-# the request is for our domain -- process registrations first
628
-if (method=="REGISTER") { route(3); break; };
629
-
630
-# look now, if there is an alias in the "aliases" table; don't care
631
-# about return value: whether there is some or not, move ahead then
632
-lookup("aliases");
633
-
634
-# there may be aliases which translate to other domain and for which
635
-# local processing is not appropriate; check again, if after the
636
-# alias translation, the request is still for us
637
-if (!uri==myself) { route(1); break; };
638
-
639
-# continue with processing for our domain...
640
-...
641
-  
642
-				</programlisting>
643
-			    </example>
644
-			</para>
645
-			<para>
646
-			    The table with aliases is updated using the
647
-			    <application moreinfo="none">serctl</application>
648
-			    tool. <application moreinfo="none">
649
-			    serctl alias add &lt;alias&gt; &lt;uri&gt;</application>
650
-			    adds a new alias, 
651
-			    <application moreinfo="none">serctl alias show &lt;user&gt;</application>
652
-			    prints an existing alias, and
653
-			    <application moreinfo="none">serctl alias rm &lt;user&gt;</application>
654
-			    removes it.
655
-			    <screen format="linespecific">
656
-[jiri@cat sip_router]$ serctl alias add 1234 sip:john.doe@foo.bar
657
-sip:john.doe@foo.bar
658
-200 Added to table
659
-('1234','sip:john.doe@foo.bar') to 'aliases'
660
-[jiri@cat sip_router]$ serctl alias add john sip:john.doe@foo.bar
661
-sip:john.doe@foo.bar
662
-200 Added to table
663
-('john','sip:john.doe@foo.bar') to 'aliases'
664
-[jiri@cat sip_router]$ serctl alias show john                    
665
-&lt;sip:john.doe@foo.bar&gt;;q=1.00;expires=1073741811
666
-[jiri@cat sip_router]$ serctl alias rm john  
667
-200 user (aliases, john) deleted				
668
-			    </screen>
669
-			</para>
670
-			<para>
671
-			    Note that persistence needs to be turned on in usrloc
672
-			    module. All changes to aliases will be otherwise lost
673
-			    on server reboot. To enable persistence, set the
674
-			    db_mode usrloc parameter to a non-zero value.
675
-			    <programlisting format="linespecific">
676
-# ....load module ...
677
-loadmodule "modules/usrloc/usrloc.so"
678
-# ... turn on persistence -- all changes to user tables are immediately
679
-# flushed to mysql
680
-modparam("usrloc", "db_mode",   1)
681
-# the SQL address:
682
-modparam("usrloc", "db_url","mysql://ser:secret@dbhost/ser")
683
-			    </programlisting>
684
-			</para>
685
-	    </section> <!-- user aliases -->
686
-	    <section id=acl>
687
-		<title>Access Control (PSTN Gateway)</title>
688
-			<para>
689
-			    It is sometimes important to exercise some sort of
690
-			    access control. A typical use case is when 
691
-			    <application moreinfo="none">ser</application> is used
692
-			    to guard a PSTN gateway. If a gateway was not well guarded,
693
-			    unauthorized users would be able to use it to terminate calls in PSTN,
694
-			    and cause high charges to its operator.
695
-			</para>
696
-			<para>
697
-			    There are few issues you need to understand when
698
-			    configuring <application moreinfo="none">ser</application>
699
-			    for this purpose. First, if a gateway is built or configured to
700
-			    accept calls from anywhere, callers may easily bypass your
701
-			    access control server and communicate with the gateway
702
-			    directly. You then need to enforce at transport layer
703
-			    that signaling is only accepted if coming via
704
-			    <application moreinfo="none">ser</application> and
705
-			    deny SIP packets coming from other hosts and port numbers.
706
-			    Your network must be configured not to allow forged
707
-			    IP addresses. Also, you need to turn on record-routing
708
-			    to assure that all session requests will travel via 
709
-			    <application moreinfo="none">ser</application>.			    
710
-			    Otherwise, caller's devices would send subsequent SIP requests 
711
-			    directly to your gateway, which would fail because of transport 
712
-			    filtering.
713
-			</para>
714
-			<para>
715
-			    Authorization (i.e., the process of determining who may call where)
716
-			    is facilitated in <application moreinfo="none">ser</application>
717
-			    using <emphasis>group membership</emphasis> concept. Scripts make 
718
-			    decisions on whether a caller is authorized to make a call to
719
-			    a specific destination based on user's membership in a group.
720
-			    For example a policy may be set up to allow calls to international
721
-			    destinations only to users, who are members of an "int" group.			    
722
-			    Before user's group membership is checked, his identity
723
-			    must be verified first. Without cryptographic verification of user's
724
-			    identity, it would be impossible to assert that a caller really
725
-			    is who he claims to be.
726
-			</para>
727
-			<para>
728
-			    The following script demonstrates, how to configure <application moreinfo="none">ser</application>
729
-			    as an access control server for a PSTN gateway. The script verifies user
730
-			    identity using digest authentication, checks user's privileges,
731
-			    and forces all requests to visit the server.
732
-			    <example>
733
-				<title>Script for Gateway Access Control</title>
734
-				<programlisting format="linespecific">
735
-&gatewayacl;
736
-				</programlisting>
737
-			    </example>
738
-			</para>
739
-			<para>
740
-			    Use the <application moreinfo="none">serctl</application> tool to
741
-			    maintain group membership. 
742
-			    <application moreinfo="none">serctl acl grant &lt;username&gt; &lt;group&gt;</application>
743
-			    makes a user member of a group, 
744
-			    <application>serctl acl show &lt;username&gt;</application> shows groups
745
-			    of which a user is member, and
746
-			    <application>serctl acl revoke &lt;username&gt; [&lt;group&gt;]</application>
747
-			    revokes user's membership in one or all groups.
748
-			    <screen format="linespecific">
749
-[jiri@cat sip_router]$ serctl acl grant john int
750
-MySql Password: 
751
-+------+-----+---------------------+
752
-| user | grp | last_modified       |
753
-+------+-----+---------------------+
754
-| john | int | 2002-12-08 02:09:20 |
755
-+------+-----+---------------------+
756
-			    </screen>
757
-			</para>
758
-	    </section> <!-- access control -->
759
-	    <section>
760
-		<title>Accounting</title>
761
-			<para>
762
-			    In some scenarios, like termination of calls in PSTN, SIP administrators
763
-			    may wish to keep track of placed calls. <application moreinfo="none">ser</application>
764
-			    can be configured to report on completed transactions. Reports are sent
765
-			    by default to <application moreinfo="none">syslog</application> facility.
766
-			    Support for RADIUS and mysql accounting exists as well.
767
-			</para>
768
-			<para>
769
-			    Note that <application moreinfo="none">ser</application> is no way 
770
-			    call-stateful. It reports on completed transactions, i.e., after 
771
-			    a successful call set up is reported, it drops any call-related 
772
-			    state. When a call is terminated, transactional state for BYE request
773
-			    is created and forgotten again after the transaction completes.
774
-			    This is a feature and not a bug -- keeping only transactional
775
-			    state allows for significantly higher scalability. It is then
776
-			    up to the accounting application to correlate call initiation
777
-			    and termination events.
778
-			</para>
779
-			<para>
780
-			    To enable call accounting, tm and acc modules need to be loaded,
781
-			    requests need to be processed statefully and labeled for
782
-			    accounting. That means, if you want a transaction to be reported,
783
-				the initial request must have taken the path 
784
-				"<command>setflag(X)</command>, <command>t_relay</command>"
785
-				in <application>ser</application> script. X must have the
786
-				value configured in <varname>acc_flag</varname>
787
-				configuration option.
788
-			</para>
789
-			<para>
790
-				Also note, that by default only transactions that initiate
791
-				a SIP dialog (typically INVITE) visit a proxy server.
792
-				Subsequent transactions are exchanged directly between
793
-				end-devices, do not visit proxy server and cannot be
794
-				reported. To be able to report on subsequent transactions,
795
-				you need to force them visit proxy server by turning 
796
-				record-routing on. 
797
-			</para>
798
-			<para>
799
-				
800
-			    <example>
801
-				<title>Configuration with Enabled Accounting</title>
802
-				<programlisting format="linespecific">
803
-&accountingexample;
804
-				</programlisting>
805
-			    </example>
806
-			</para>
807
-	    </section> <!-- accounting -->
808
-	    <section>
809
-		<title>Reliability</title>
810
-
811
-			<para>
812
-			    It is essential to guarantee continuous
813
-			    service operation even under erroneous conditions, 
814
-			    such as host or network failure. The major issue in such
815
-			    situations is transfer of operation to a backup
816
-			    infrastructure and making clients use it.
817
-			</para>
818
-			<para>
819
-			    The SIP standard's use of DNS SRV records has been
820
-			    explicitly constructed to handle with server failures.
821
-			    There may be multiple servers responsible for a domain
822
-			    and referred to by DNS. If it is impossible to communicate
823
-			    with a primary server, a client can proceed to another one.
824
-			    Backup servers may be located in a different geographic
825
-			    area to minimize risk caused by areal operational
826
-			    disasters: lack of power, flooding, earthquake, etc.
827
-			    <note>
828
-				<sidebar>
829
-				    <para>Unless there are redundant DNS
830
-				    servers, fail-over capability cannot be guaranteed.
831
-				    </para>
832
-				</sidebar>
833
-			    </note>
834
-			    Unfortunately, at the moment of writing this documentation
835
-			    (end of December 2002) only very few SIP products
836
-			    actually implement the DNS fail-over mechanism. Unless
837
-			    networks with SIP devices supporting this mechanism are
838
-			    built, alternative mechanisms must be used to force 
839
-			    clients to use backup servers. Such a mechanism is
840
-			    disconnecting primary server and replacing it with
841
-			    a backup server locally.
842
-			    It unfortunately precludes geographic dispersion and
843
-			    requires network multihoming to avoid dependency on
844
-			    single IP access. Another method is to update DNS
845
-			    when failure of the primary server is detected.
846
-			    The primary drawback of this method is its latency:
847
-			    it may take long time until all clients learn to use
848
-			    the new server.
849
-			</para>
850
-			<para>
851
-			    The easier part of the redundancy story is replication of 
852
-			    <application moreinfo="none">ser</application>
853
-			    data. <application moreinfo="none">ser</application>
854
-			    relies on replication capabilities of its back-end database.
855
-			    This works with one exception: user location database.
856
-			    User location database is a frequently accessed table,
857
-			    which is thus cached in server's memory to improve
858
-			    performance. Back-end replication does not affect
859
-			    in-memory tables, unless server reboots. To facilitate
860
-			    replication of user location database, 
861
-			    server's SIP replication feature must be enabled
862
-			    in parallel with back-end replication.
863
-			</para>
864
-			<para>
865
-			    The design idea of replication of user location database
866
-			    is easy: Replicate any successful REGISTER requests to
867
-			    a peer server. To assure that digest credentials can
868
-			    be properly verified, both servers need to use the same
869
-			    digest generation secret and maintain synchronized time.
870
-			    A known limitation of this method is it does not replicate
871
-			    user contacts entered in another way, for example using
872
-			    web interface through FIFO server.
873
-			    The following script example shows configuration of
874
-			    a server that replicates all REGISTERs.
875
-			    <example>
876
-				<title>Script for Replication of User Contacts</title>
877
-				<programlisting format="linespecific">
878
-&replicateexample;				    
879
-				</programlisting>
880
-			    </example>
881
-			</para>
882
-	    </section> <!-- reliability -->
883
-	    <section>
884
-		<title>Stateful versus Stateless Forwarding</title>
885
-		<para>
886
-		    <application moreinfo="none">ser</application> allows both stateless
887
-		    and stateful request processing. This memo explains what are pros and cons of
888
-		    using each method. The rule of thumb is "stateless for scalability,
889
-		    stateful for services". If you are unsure which you need, stateful
890
-		    is a safer choice which supports more usage scenarios.
891
-		</para>
892
-			<para>
893