- Spelling checked
[sip-router] / doc / seruser / operation.sgml
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://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                             Stateless forwarding with the
894                             <command moreinfo="none">forward(uri:host, uri:port)</command> action
895                             guarantees high scalability. It withstands high load and
896                             does not run out of memory. A perfect use of stateless forwarding
897                             is load distribution.
898                         </para>
899                         <para>
900                             Stateful forwarding using the <command moreinfo="none">t_relay()</command>
901                             action is known to scale worse. It can quickly run out of memory and
902                             consumes more CPU time. Nevertheless, there are scenarios which are
903                             not implementable without stateful processing. In particular:
904                             <itemizedlist>
905                                 <listitem>
906                                     <para>
907                                         <emphasis>Accounting</emphasis> requires stateful processing
908                                         to be able to collect transaction status and issue a single
909                                         report when a transaction completes.
910                                     </para>
911                                 </listitem>
912                                 <listitem>
913                                     <para>
914                                         <emphasis>Forking</emphasis> only works with stateful forwarding.
915                                         Stateless forwarding only forwards to the default URI out of the
916                                         whole destination set.
917                                     </para>
918                                 </listitem>
919                                 <listitem>
920                                     <para>
921                                         <emphasis>DNS resolution</emphasis>. DNS resolution may be
922                                         better served with stateful processing. If a request is forwarded
923                                         to a destination whose address takes long time to resolve,
924                                         a server process is blocked and unresponsive. Subsequent 
925                                         request retransmissions from client will cause other processes
926                                         to block too if requests are processed statelessly. As a result,
927                                         <application moreinfo="none">ser</application> will quickly
928                                         run out of available processes. With stateful forwarding,
929                                         retransmissions are absorbed and do not cause blocking of
930                                         another process.
931                                     </para>
932                                 </listitem>
933                                 <listitem>
934                                     <para>
935                                         <emphasis>Forwarding Services</emphasis>. All sort of services 
936                                         with the "forward_on_event" logic, which rely on 
937                                         <command moreinfo="none">t_on_failure</command> tm
938                                         action must be processed statefully.
939                                     </para>
940                                 </listitem>
941                         <listitem>
942                             <para>
943                                 <emphasis>
944                                     Fail-over.
945                                 </emphasis>
946                                 If you wish to try out another destination, after a primary destination
947                                 failed you need to use stateful processing. With stateless processing
948                                 you never know with what status a forwarded request completed downstream
949                                 because you immediately release all processing information after the 
950                                 request is sent out. 
951
952                                 <note>
953                                     <para>
954                                         Positive return value of stateless
955                                         <command moreinfo="none">forward</command> action only indicates that
956                                         a request was successfully sent out, and does not gain any knowledge
957                                         about whether it was successfully received or replied. Neither does
958                                         the return value of
959                                         the stateful <command moreinfo="none">t_relay</command> action family
960                                         gain you this knowledge. However, these actions store transactional
961                                         context with which includes original request and allows you to
962                                         take an action when a negative reply comes back or a timer strikes.
963                                         See <xref linkend="replyprocessingsection"> for an example script 
964                                         which launches another
965                                         branch if the first try fails.
966                                     </para>
967                                 </note>
968
969                             </para>
970                         </listitem>
971                             </itemizedlist>
972                         </para>
973             </section> <!-- stateful vs. stateless -->
974             <section>
975                 <title>Serving Multiple Domains</title>
976                         <para>
977                             <application moreinfo="none">ser</application> can be configured to
978                             serve multiple domains. To do so, you need to take the following steps:
979                             <orderedlist>
980                                 <listitem id="createtable">
981                                     <para>
982                                         Create separate subscriber and location database table
983                                         for each domain served and name them uniquely.
984                                     </para>
985                                 </listitem>
986                                 <listitem>
987                                     <para>
988                                         Configure your script to distinguish between multiple
989                                         served domains. Use regular expressions for domain
990                                         matching as described in <xref linkend="redomainmatching">.
991                                     </para>
992                                 </listitem>
993                                 <listitem>
994                                     <para>
995                                         Update table names in usrloc and auth actions to reflect
996                                         names you created in <xref linkend="createtable">.
997                                     </para>
998                                 </listitem>
999                                 
1000                             </orderedlist>
1001                         </para>
1002                         <para>
1003                                 The latest <application>SER</application> release includes automated
1004                                 multidomain management which greatly automates maintenance of multiple  
1005                                 domains. Ask our technical support for more help.
1006                         </para>
1007             </section> <!-- multiple domains -->
1008             <section id="missedcalls">
1009                 <title>Reporting Missed Calls</title>
1010                         <para>
1011                             <application moreinfo="none">ser</application> can report missed
1012                             calls via <application moreinfo="none">syslog</application> facility
1013                             or to mysql. Mysql reporting can be utilized by 
1014                             <application moreinfo="none">ser</application>'s 
1015                             complementary web-interface, <application moreinfo="none">serweb</application>.
1016                             (See more in <xref linkend="serweb">).
1017                         </para>
1018                         <para>
1019                             Reporting on missed calls is enabled by acc module.
1020                             There are two cases, on which you want to report. The first
1021                             case is when a callee is off-line. The other case is when
1022                             a user is on-line, but call establishment fails. There
1023                             may be many failure reasons (call cancellation, inactive phone,
1024                             busy phone, server timer, etc.), all of them leading to
1025                             a negative (>=300) reply sent to caller. The acc module
1026                             can be configured to issue a missed-call report whenever
1027                             a transaction completes with a negative status. Two following
1028                             script fragment deals with both cases.
1029                         </para>
1030                         <para>
1031                             First, it reports
1032                             on calls missed due to off-line callee status
1033                             using the <command moreinfo="none">acc_request</command>
1034                             action. The action is wrapped in transactional
1035                             processing (<command moreinfo="none">t_newtran</command>)
1036                             to guarantee that reports are not
1037                             duplicated on receipt of retransmissions.
1038                             </para>
1039                         <para>
1040                             Secondly, transactions to on-line users are marked
1041                             to be reported on failure. That is what the 
1042                             <command moreinfo="none">setflag(3)</command> action
1043                             is responsible for, along with the configuration option
1044                             "log_missed_flag". This option configures <application moreinfo="none">ser</application>
1045                             to report on all transactions, which were marked
1046                             with flag 3.                           
1047                             <programlisting format="linespecific">
1048 loadmodule("modules/tm/tm.so");
1049 loadmodule("modules/acc/acc.so");
1050 ....
1051 # if a call is labeled using setflag(3) and is missed, it will
1052 # be reported
1053 ...
1054 modparam("acc", "log_missed_flag", 3 );
1055 if (!lookup("location")) {
1056      # call invitations to off-line users are reported using the
1057      # acc_request action; to avoid duplicate reports on request
1058      # retransmissions, request is processed statefully (t_newtran,
1059      # t_reply)
1060      if ((method=="INVITE" || method=="ACK") && t_newtran() ) {
1061           t_reply("404", "Not Found");
1062           acc_request("404 Not Found");
1063           break;
1064      };
1065      # all other requests to off-line users are simply replied
1066      # statelessly and no reports are issued
1067     sl_send_reply("404", "Not Found");
1068     break;
1069 } else {
1070      # user on-line; report on failed transactions; mark the
1071      # transaction for reporting using the same number as 
1072      # configured above; if the call is really missed, a report
1073      # will be issued
1074      setflag(3);
1075      # forward to user's current destination
1076      t_relay();
1077      break;
1078 };
1079                             </programlisting>
1080                             
1081                         </para>
1082             </section> <!-- missed calls -->
1083             <section>
1084                 <title>NAT Traversal</title>
1085                 <para>
1086                     NATs are worst things that ever happened to SIP. These devices
1087                     are very popular because they help to conserve IP address space
1088                     and save money charged for IP addresses. Unfortunately, they
1089                     translate addresses in a way which is not compatible with SIP.
1090                     SIP advertises receiver addresses in its payload. The advertised
1091                     addresses are invalid out of NATed networks. As a result,
1092                     SIP communication does not work across NATs without extra
1093                     effort.
1094                 </para>
1095                 <para>
1096                     There are few methods that may be deployed to traverse NATs.
1097                     How proper their use is depends on the deployment scenario.
1098                     Unfortunately, all the methods have some limitations and
1099                     there is no straight-forward solution addressing all
1100                     scenarios. Note that none of these methods takes explicit
1101                     support in <application moreinfo="none">ser</application>.
1102                 </para>
1103                 <para>
1104                     The first issue is whether SIP users are in control of 
1105                     their NATs. If not (NATs are either operated by ISP or
1106                     they are sealed to prevent users setting them up), the
1107                     only method is use of a STUN-enabled phone. STUN is 
1108                     a very simple protocol used to fool NAT in such a way,
1109                     they permit SIP sessions. Currently, we are aware of
1110                     one softphone (kphone) and one hardphone (snom) with
1111                     STUN support, other vendors are working on STUN support
1112                     too. Unfortunately, STUN gives no NAT traversal
1113                     guarantee -- there are types of NATs, so called
1114                     symmetric NATs, over which STUN fails to work.
1115                     <note>
1116                         <para>
1117                             There is actually yet another method to address
1118                             SIP-unaware, user-uncontrolled NATs. It is based
1119                             on a proxy server, which relays all signaling and
1120                             media and mangles packets to make them more
1121                             NAT-friendly. The very serious problem with this
1122                             method is it does not scale.
1123                         </para>
1124                     </note>
1125                 </para>
1126                 <para>
1127                     If users are in control of their own NAT, as typically residential
1128                     users are, they can still use STUN. However, they may use other
1129                     alternatives too. One of them is to replace their NAT with
1130                     a SIP-aware NAT. Such NATs have built-in SIP awareness,
1131                     that patches problems caused by address translations. Prices
1132                     of such devices are getting low and there are available
1133                     implementations (Intertex, Cisco/PIX). No special support
1134                     in phones is needed.
1135                 </para>
1136                 <para>
1137                     Other emerging option is UPnP. UPnP is a protocol that allows
1138                     phones to negotiate with NAT boxes. You need UPnP support in
1139                     both, NAT and phones. As UPnP NATs are quite affordable,
1140                     costs are not an obstacle. Currently, we are aware of one
1141                     SIP phone (SNOM) with UPnP support.
1142                 </para>
1143                 <para>
1144                     Geeks not wishing to upgrade their firewall to a SIP-aware or
1145                     UPnP-enabled one may try to configure static address translation.
1146                     That takes phones with configuration ability to use fixed port
1147                     numbers and advertise outside address in signaling. Cisco phones
1148                     have this capability, for example. The NAT devices need to
1149                     be configured to translate outside port ranges to the 
1150                     ranges configured in phones.                    
1151                 </para>
1152             </section> <!-- NAT traversal -->
1153
1154                 <section>
1155                 <title>Using Only Latest User's Contact for Forwarding
1156                 </title>
1157                         <para>
1158                                 In some scenarios, it may be beneficial only to use only one
1159                                 registered contact per user. If that is the case, setting
1160                                 registrar module's parameter <varname>append_branches</varname>
1161                                 to 1 will eliminate forking and forward all requests only
1162                                 to a single contact. If there are multiple contacts, a contact
1163                                 with highest priority is chosen. This can be changed to
1164                                 the "freshest" contact by setting module parameter's
1165                                 <varname>desc_time_order</varname> to 1.
1166                         </para>
1167
1168                 </section>
1169
1170             <section>
1171                 <title>Authentication Policy: Prevention of Unauthorized Domain 
1172                     Name Use in From and More</title>
1173                 <para>
1174                     Malicious users can claim a name of domain, to which they do 
1175                     not administratively belong, in From header field. This
1176                     behavior cannot be generally prevented. The reason is
1177                     that requests with such a faked header field do not need
1178                     to visit servers of the domain in question. However, if they
1179                     do so, it is desirable to assure that users claiming
1180                     membership in a domain are actually associated with it.
1181                     Otherwise the faked requests would be relayed and appear
1182                     as coming from the domain, which would increase
1183                     credibility of the faked address and decrease credibility of
1184                     the proxy server.
1185                 </para>
1186                 <para>
1187                     Preventing unauthorized domain name use in relayed requests 
1188                     is not difficult.
1189                     One needs to authenticate each request with name of the
1190                     served domain in From header field. To do so, one can
1191                     search for such a header field using <command moreinfo="none">search</command>
1192                     action (textops module) and force authentication if the
1193                     search succeeds.
1194                     <note>
1195                         <para>
1196                             A straight-forward solution might be to authenticate
1197                             ALL requests. However, that only works in closed
1198                             networks in which all users have an account in the
1199                             server domain. In open networks, it is desirable to permit
1200                             incoming calls from callers from other domains without
1201                             any authentication. For example, a company may wish
1202                             to accept calls from unknown callers who are
1203                             new prospective customers.
1204                             
1205                         </para>
1206                     </note>
1207                     <programlisting format="linespecific">
1208 # does the user claim our domain "foo.bar" in From?
1209 if (search("^(f|From):.*foo.bar")) {
1210         # if so, verify credential
1211         if (!proxy_authorize("foo.bar", "subscriber")) { 
1212               # don't proceed if credentials broken; challenge
1213               proxy_challenge("foo.bar", "0");
1214               break;
1215         };
1216 };
1217                     </programlisting>
1218                 </para>
1219                 <para>
1220                     In general, the authentication policy may be very rich. You may not
1221                     forget each request deserves its own security and you need to 
1222                     decide whether it shall be authenticated or not. As mentioned
1223                     above, in closed networks, you may want to authenticate absolutely 
1224                     every request. That however prohibits traffic from users from
1225                     other domains. A pseudo-example of a reasonable policy is attached:
1226                     it looks whether a request is registration, it claims to originate
1227                     from our domain in From header field, or is a local request to
1228                     another domain.
1229                     <programlisting format="linespecific">
1230 # (example provided by Michael Graff on [serusers] mailing list
1231 if (to me):
1232     if register
1233           www_authorize or fail if not a valid register
1234           done
1235     if claiming to be "From" one of the domains I accept registrations for
1236           proxy_authorize
1237           done
1238     if not to me (I'm relaying for a local phone to an external address)
1239           proxy_authorize
1240           done
1241                     </programlisting>
1242                 </para>
1243                 <para>
1244                     You also may want to apply additional restriction to how
1245                     digest username relates to usernames claimed in From and
1246                     To header fields. For example, the <command moreinfo="none">check_to</command>
1247                     action enforces the digest id to be equal to username
1248                     in To header fields. That is good in preventing someone
1249                     with valid credentials to register as someone else
1250                     (e.g., sending a REGISTER with valid credentials of
1251                     "joe" and To belonging to "alice"). Similarly,
1252                     <command moreinfo="none">check_from</command> is used
1253                     to enforce username in  from to equal to digest id.
1254                     <note>
1255                         <para>
1256                             There may be a need for a more complex relationship
1257                             between From/To username and digest id. For example,
1258                             providers with an established user/password database
1259                             may wish to keep using it, whereas permitting users
1260                             to claim some telephone numbers in From. To address
1261                             such needs generally, there needs to be a 1:N mapping
1262                             between digest id and all usernames that are acceptable
1263                             for it. This is being addressed in a newly contributed
1264                             module "domain", which also addresses more generally
1265                             issues of domain matching for multidomain scenarios.
1266                         </para>
1267                     </note>
1268                 </para>
1269                 <para>
1270                     Other operational aspect affecting the authentication policy
1271                     is guarding PSTN gateways (see <xref linkend="acl">). There
1272                     may be destinations that are given away for free whereas
1273                     other destinations may require access control using
1274                     group membership, to which  authentication is a prerequisite.
1275                 </para>
1276
1277             </section> <!-- authentication policy, faked froms -->
1278             <section>
1279                 <title>Connecting to PBX Voicemail Using a Cisco Gateway</title>
1280                 <para>
1281                     In some networks, administrators may wish to utilize their
1282                     PBX voicemail systems behind PSTN gateways. There is a practical problem
1283                     in many network settings: it is not clear for whom a call to
1284                     voicemail is. If voicemail is identified by a single number,
1285                     which is then put in INVITE's URI, there is no easy way to
1286                     learn for whom a message should be recorded. PBX voicemails
1287                     utilize that PSTN protocols signal the number of originally
1288                     called party. If you wish to make the PBX voicemail work,
1289                     you need to convey the number in SIP and translate it in
1290                     PSTN gateways to its PSTN counterpart.
1291                 </para>
1292                 <para>
1293                     There may be many different ways to achieve this scenario. Here
1294                     we describe the proprietary mechanism Cisco gateways use and how to 
1295                     configure <application moreinfo="none">ser</application> to
1296                     make the gateways happy. Cisco gateways expect the number
1297                     of originally called party to be located in proprietary
1298                     <varname>CC-Diversion</varname> header field. When a SIP 
1299                     INVITE sent via a PSTN gateway to PBX voicemail has number
1300                     of originally called party in the header field, the voicemail
1301                     system knows for whom the incoming message is. That is at least
1302                     true for AS5300/2600 with Cisco IOS 12.2.(2)XB connected to
1303                     Nortel pbxs via PRI. (On the other hand, 12.2.(7b) is known
1304                     not to work in this scenario.)
1305                 </para>
1306                 <para>
1307                     <application moreinfo="none">ser</application> needs then to
1308                     be configured to append the <varname>CC-Diversion</varname>
1309                     header field name for INVITEs sent to PBX voicemail.
1310                     The following script shows that: when initial forwarding
1311                     fails (nobody replies, busy is received, etc.), a new branch
1312                     is initiated to the pbx's phone number. 
1313                     <command moreinfo="none">append_urihf</command> is used to
1314                     append the <varname>CC-Diversion</varname> header field. It
1315                     takes two parameters: prefix, which includes header name,
1316                     and suffix which takes header field separator. 
1317                     <command moreinfo="none">append_urihf</command> inserts
1318                     original URI between those two.
1319                     <example>
1320                         <title>Forwarding to PBX/Voicemail via Cisco Gateways</title>
1321                         <programlisting format="linespecific">
1322 &ccdiversion;
1323                         </programlisting>
1324                     </example>
1325                     
1326                 </para>
1327             </section>
1328         </section> <!-- howtos -->
1329
1330         <section>
1331             <title>Troubleshooting</title>
1332             <para>
1333                 This section gathers practices how to deal with errors
1334                 known to occur frequently. To understand how to watch
1335                 SIP messages, server logs, and in general how to
1336                 troubleshoot, read also <xref linkend="operationalpractices">. 
1337             </para>
1338             <qandaset>
1339                 <qandaentry>
1340                     <question>
1341                         <para>
1342                         SIP requests are replied by <application>ser</application> with
1343                         "483 Too Many Hops" or "513 Message Too Large"
1344                         </para>
1345                     </question>
1346
1347                     <answer>
1348                         <para>
1349                             In both cases, the reason is probably an error in
1350                             request routing script which caused an infinite loop.
1351                             You can easily verify whether this happens by
1352                             watching SIP traffic on loopback interface. A typical
1353                             reason for misrouting is a failure to match local
1354                             domain correctly. If a server fails to recognize
1355                             a request for itself, it will try to forward it
1356                             to current URI in believe it would forward them
1357                             to a foreign domain. Alas, it forwards the request
1358                             to itself again. This continues to happen until
1359                             value of max_forwards header field reaches zero
1360                             or the request grows too big. Solutions is easy:
1361                             make sure that domain matching is correctly
1362                             configured. See <xref linkend="domainmatching">
1363                             for more information how to get it right.
1364                         </para>
1365                     </answer>               
1366                 </qandaentry>
1367                 <qandaentry>
1368                         
1369                     <question>
1370                                 
1371                         <para>
1372                         
1373                             Windows Messenger authentication fails.
1374                         </para>
1375                     </question>
1376                     <answer>
1377                         <anchor id="msmbug">
1378                         <para>
1379                             The most likely reason for this problem is a bug
1380                             in Windows Messenger. WM only authenticates if
1381                             server name in request URI equals authentication
1382                             realm. After a challenge is sent by SIP server,
1383                             WM does not resubmit the challenged request at all
1384                             and pops up authentication window again.
1385                             If you want to authenticate WM, you need to
1386                             set up your realm value to equal server name.
1387                             If your server has no name, IP address can be used
1388                             as realm too. The realm value is configured in
1389                                 scripts as the first parameter of all
1390                                 <command>{www|proxy}_{authorize|challenge}</command>
1391                                 actions.
1392                         </para>
1393                     </answer>
1394                 </qandaentry>
1395                 <qandaentry>
1396                     <question>
1397                         <para>
1398                             On a multihomed host, forwarded messages carry other 
1399                             interface in Via than used for sending, or messages 
1400                             are not sent and an error log is issued "invalid 
1401                             sendtoparameters one possible reason is the server 
1402                             is bound to localhost".
1403                         </para>
1404                     </question>
1405                     <answer>
1406                         <anchor id="mhomed">
1407                         <para>
1408                             Set the configuration option <varname>mhomed</varname>
1409                             to "1". <application moreinfo="none">ser</application>
1410                             will then attempt to calculate the correct interface.
1411                             It's not done by default as it degrades performance
1412                             on single-homed hosts or multi-homed hosts that are
1413                             not set-up as routers.
1414                         </para>
1415                     </answer>
1416                 </qandaentry>
1417                 <qandaentry>
1418                     <question>
1419                         <para>
1420                             I receive "ERROR: t_newtran: transaction already in process" in my logs.
1421                         </para>
1422                     </question>
1423                     <answer>
1424                         <para>
1425                             That looks like an erroneous use of tm module in script.
1426                             tm can handle only one transaction per request. If you
1427                             attempt to instantiate a transaction multiple times,
1428                             <application moreinfo="none">ser</application> will complain.
1429                             Anytime any of <command moreinfo="none">t_newtran</command>,
1430                             <command moreinfo="none">t_relay</command> or 
1431                             <command moreinfo="none">t_relay_to_udp</command> actions is
1432                             encountered, tm attempts to instantiate a transaction.
1433                             Doing so twice fails. Make sure that any of this
1434                             commands is called only once during script execution.
1435                         </para>
1436                     </answer>
1437                 </qandaentry>
1438                 <qandaentry>
1439                     <question>
1440                         <para>
1441                             I try to add an alias but 
1442                             <command moreinfo="none">serctl</command>
1443                             complains that table does not exist.
1444                         </para>
1445                     </question>
1446                     <answer>
1447                         <para>
1448                             You need to run <application moreinfo="none">ser</application>
1449                             and use the command
1450                             <command moreinfo="none">lookup("aliases")</command>
1451                             in its routing script. That's because the table 
1452                             of aliases is
1453                             stored in cache memory for high speed. The cache
1454                             memory is only set up when the 
1455                             <application moreinfo="none">ser</application>
1456                             is running and configured to use it. If that is
1457                             not the case, 
1458                             <application moreinfo="none">serctl</application>
1459                             is not able to manipulate the aliases table.
1460                         </para>
1461                     </answer>
1462                 </qandaentry>
1463
1464             <qandaentry>
1465                 <question>
1466                     <para>I started <application>ser</application> with
1467                         <varname>children=4</varname> but many more processes
1468                         were started. What is wrong?
1469                         </para>
1470                     </question>
1471                 <answer>
1472                     <para>
1473                         That's ok. The <varname>children</varname> parameter defines
1474                         how many children should process each transport protocol in
1475                         parallel. Typically, the server listens to multiple protocols
1476                         and starts other supporting processes like timer or FIFO
1477                         server too. Call <application>serctl ps</application> to watch
1478                         running processes.
1479                         </para>
1480                     </answer>
1481                 </qandaentry>
1482             <qandaentry>
1483                 <question>
1484                     <para>
1485                         I decided to use a compiled version of <application>ser</application>
1486                         but it does not start any more.
1487                         </para>
1488                     </question>
1489                 <answer>
1490                     <para>
1491                         You probably kept the same configuration file, which tries to load modules
1492                         from the binary distribution you used previously. Make sure that modules
1493                         paths are valid and point to where you compiled <application>ser</application>.
1494                         Also, watch logs for error messages "ERROR: load_module: could not open 
1495                         module".
1496                         </para>
1497                     </answer>
1498                 </qandaentry>
1499             
1500             </qandaset>
1501         </section> <!-- troubleshooting -->
1502     </chapter> <!-- operation -->