small changes...
[sip-router] / doc / seruser / seruser.sgml
1 <!-- $Id$ -->
2 <!-- DOCTYPE Book SYSTEM "/usr/share/sgml/docbook/dtd-4.2/docbook.dtd" [ -->
3 <!DOCTYPE Book PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ 
4
5
6 <!ENTITY execexample SYSTEM "../../examples/exec.cfg">
7 <!ENTITY redirectexample SYSTEM "../../examples/redirect.cfg">
8 <!ENTITY replyexample SYSTEM "../../examples/onr.cfg">
9 <!ENTITY statefuluaexample SYSTEM "../../examples/uas.cfg">
10 <!ENTITY gpllicense SYSTEM "../../COPYING">
11 <!ENTITY sendim SYSTEM "../../examples/web_im/send_im.php">
12 <!ENTITY gatewayacl SYSTEM "../../examples/pstn.cfg">
13 <!ENTITY accountingexample SYSTEM "../../examples/acc.cfg">
14 <!ENTITY replicateexample SYSTEM "../../examples/replicate.cfg">
15 <!ENTITY defscr SYSTEM "../../etc/ser.cfg">
16 <!ENTITY execstep2 SYSTEM "../../examples/exec_s2.cfg">
17 <!ENTITY execstep3 SYSTEM "../../examples/exec_s3.cfg">
18 <!ENTITY execstep4 SYSTEM "../../examples/exec_s4.cfg">
19 <!ENTITY execstep5 SYSTEM "../../examples/exec_s5.cfg">
20 <!ENTITY execstep5b SYSTEM "../../examples/exec_s5b.cfg">
21 <!ENTITY ccdiversion SYSTEM "../../examples/ccdiversion.cfg">
22 <!ENTITY logging SYSTEM "../../examples/logging.cfg">
23 <!ENTITY releasenotes SYSTEM "../../NEWS">
24 <!ENTITY install SYSTEM "../../INSTALL">
25 <!ENTITY voicemail SYSTEM "voicemail.sgml">
26 <!ENTITY voicemailcfg SYSTEM "../../modules/vm/etc/ser.cfg">
27
28
29
30 ]>
31
32
33 <book label="seruser" id="seruser" lang="EN">
34
35 <?dbhtml filename="index.html">
36
37    
38     <title>iptel.org SIP Express Router v0.9.0 -- Admin's Guide</title>
39     <bookinfo>
40         <authorgroup>
41             <author>
42                 <firstname>Jiri</firstname>
43                 <surname>Kuthan</surname>
44                 <email>jiri@iptel.org</email>
45             </author>
46             <author>
47                 <firstname>Jan</firstname>
48                 <surname>Janak</surname>
49                 <email>jan@iptel.org</email>
50             </author>
51             <author>
52                 <firstname>Yacine</firstname>
53                 <surname>Rebahi</surname>
54                 <email>rebahi@fokus.fhg.de</email>
55             </author>
56
57         </authorgroup>
58
59         <copyright>
60             <year>2001</year>
61             <year>2002</year>
62             <holder>FhG Fokus</holder>
63         </copyright>
64         <legalnotice>
65             <para>
66                 This documentation is free software; you can redistribute
67                 it and/or modify it under the terms of the GNU General Public
68                 License as published by the Free Software Foundation; either
69                 version 2 of the License, or (at your option) any later
70                 version.
71             </para>
72             
73             <para>
74                 This program is distributed in the hope that it will be
75                 useful, but WITHOUT ANY WARRANTY; without even the implied
76                 warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
77                 See the GNU General Public License for more details.
78             </para>
79             
80             <para>
81                 You should have received a copy of the GNU General Public
82                 License along with this program; if not, write to the Free
83                 Software Foundation, Inc., 59 Temple Place, Suite 330, Boston,
84                 MA 02111-1307 USA
85             </para>
86             
87             <para>
88                 For more details see the file COPYING in the source
89                 distribution of <acronym>SER</acronym>.
90             </para>         
91         </legalnotice>
92
93         <abstract>
94             <para>
95                 The document describes the <acronym>SIP</acronym> Express Router and its use in
96                 <acronym>SIP</acronym> networks. It is intended as an aid to server 
97                 administrators. 
98             </para>
99         </abstract>
100         <releaseinfo>
101             This documentation is continuously updated. For the latest  
102             version visit our site at 
103             <ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser</ulink>.
104             $Revision$.
105         </releaseinfo>
106     </bookinfo>
107
108     <toc></toc>
109     
110     <chapter id="general">
111         <title>General Information</title>
112         <section id="aboutser">
113             <title>About <acronym>SIP</acronym> Express Router (<acronym>SER</acronym>)</title>
114             <para>
115                 SIP Express Router (<acronym>SER</acronym>) is an industrial-strength, free VoIP 
116                 server based on the Session Initiation Protocol (<acronym>SIP</acronym>, RFC3261). 
117                 It is engineered to power <acronym>IP</acronym> telephony infrastructures up to large 
118                 scale. The server keeps track of users, sets up VoIP sessions, 
119                 relays instant messages and creates space for new plug-in applications. 
120                 Its proven interoperability guarantees seamless integration with 
121                 components from other vendors, eliminating the risk of a single-vendor 
122                 trap. It has successfully participated in various interoperability 
123                 tests in which it worked with the products of other leading <acronym>SIP</acronym> vendors.
124             </para>
125             <para>
126                 The <acronym>SIP</acronym> Express Router enables a flexible plug-in model for new 
127                 applications: Third parties can easily link their plug-ins with 
128                 the server code and provide thereby advanced and customized services. 
129                 In this way, plug-ins such as <acronym>SNMP</acronym> support, RADIUS accounting,
130                 or SMS gateway have already been developed and are provided as 
131                 advanced features. Other modules are underway: Presence server,
132                 firewall control, and more.
133             </para>
134             <para>
135                 Its performance and robustness allows it to serve millions of users 
136                 and accommodate needs of very large operators. With a $3000 dual-CPU PC, the 
137                 <acronym>SIP</acronym> Express Router is able to power <acronym>IP</acronym> telephony services in an area 
138                 as large as the Bay Area during peak hours. Even on an IPAQ <acronym>PDA</acronym>, the server 
139                 withstands 150 calls per second (<acronym>CPS</acronym>)! The server has been powering our 
140                 iptel.org free <acronym>SIP</acronym> site withstanding heavy daily load that is further 
141                 increasing with the popularity of Microsoft's Windows Messenger.  
142             </para>
143             <para>
144                 The <acronym>SIP</acronym> Express Router is extremely configurable to allow the creation of 
145                 various routing and admission policies as well as setting up new and 
146                 customized services. Its configurability allows it to serve many roles: 
147                 network security barrier, application server, or <acronym>PSTN</acronym> gateway guard for 
148                 example.
149             </para>
150             <para>
151                 <application moreinfo="none">ser</application> can be also
152                 used with contributed applications. Currently, 
153                 <application moreinfo="none">serweb</application>, a
154                 <application moreinfo="none">ser</application> web interface,
155                 and <application moreinfo="none">SIPSak</application>
156                 diagnostic tool are available. Visit our site, 
157                 <ulink url="http://www.iptel.org/">http://www.iptel.org/</ulink>, 
158                 for more information on contributed packages.
159             </para>
160         </section> 
161
162         <section id="aboutiptel">
163             <title>About iptel.org</title>
164             <para>
165                 iptel.org is a know-how company spun off from Germany's national 
166                 research company FhG Fokus. One of the first <acronym>SIP</acronym> implementations ever, 
167                 low-QoS enhancements, interoperability tests and VoIP-capable firewall 
168                 control concepts are examples of well-known FhG's work.
169             </para>
170             <para>
171                 iptel.org continues to keep this know-how leadership in <acronym>SIP</acronym>. 
172                 The access rate of the company's site, a well-known source of 
173                 technological information, is a best proof of interest. Thousands 
174                 of hits come every day from the whole Internet.
175             </para>
176             <para>
177                 The iptel.org site, powered by SER, offers SIP services on the public 
178                 Internet. Feel free to apply for a free SIP account at
179                 <ulink url="http://www.iptel.org/user/">http://www.iptel.org/user/
180                 </ulink>
181             </para>
182
183             
184         </section> <!-- iptel -->
185         <section id="serfeatures">
186             <title>Feature List</title>
187             <para>
188                 Based on the latest standards, the <acronym>SIP</acronym> Express Router (<acronym>SER</acronym>) includes 
189                 support for registrar, proxy and redirect mode. Further it acts as 
190                 an application server with support for instant messaging and 
191                 presence including a <acronym>2G/SMS</acronym> and Jabber gateway, a call control policy 
192                 language, call number translation, private dial plans and accounting, 
193                 authorization and authentication (<acronym>AAA</acronym>) services. <application>SER</application> runs on Sun/Solaris, 
194                 PC/Linux, PC/BSD, IPAQ/Linux platforms and supports  both <acronym>IPv4</acronym> and <acronym>IPv6</acronym>. 
195                 Hosting multiple domains and database redundancy is supported.
196             </para>
197             <para>
198                 Other extensions are underway: presence server, firewall control and more.
199             </para>
200             <para>
201                 <application>ser</application> has been carefully engineered with the following 
202                 design objectives in mind:
203                 <itemizedlist>
204                     <listitem>
205                         <para>
206                             <emphasis>Speed</emphasis> - With <application>ser</application>, 
207                             thousands of calls per seconds are achievable 
208                             even on low-cost platforms. This competitive capacity allows 
209                             setting up networks which are inexpensive and easy to manage 
210                             due to low number of devices required. The processing capacity 
211                             makes dealing with many stress factors easier. The stress
212                             factors may include but are not limited to broken configurations and implementations,
213                             boot avalanches on power-up, high-traffic applications such as presence, 
214                             redundancy replications and denial-of-service attacks.
215                         </para>
216                         <para> The speed has been achieved by extensive code optimization, use of customized code, 
217                             <acronym>ANSI C</acronym> combined with assembly instructions and leveraging latest 
218                             <acronym>SIP</acronym> improvements. When powered by a dual-CPU Linux PC, 
219                             <application>ser</application> is able to process thousands of calls per second,
220                             capacity needed to serve call signaling demands of Bay Area population.
221                            
222                         </para>
223                     </listitem>
224                     <listitem>
225                         <para>
226                             <emphasis>Flexibility</emphasis> - <application>SER</application> allows its users 
227                             to define its behavior. 
228                             Administrators may write textual scripts which determine <acronym>SIP</acronym> routing 
229                             decisions, the main job of a proxy server. They may use the script to 
230                             configure numerous parameters and introduce additional logic. For example, 
231                             the scripts can determine for which destinations record routing should be 
232                             performed, who will be authenticated, which transactions should be processed 
233                             statefully, which requests will be proxied or redirected, etc.
234                         </para>
235
236                     </listitem>
237                     <listitem>
238                         <para>
239                             <emphasis>Extensibility</emphasis> - <application>SER</application>'s extensibility allows linking of 
240                             new C code to ser to 
241                             redefine or extend its logic. The new code can be developed independently 
242                             on <application>SER</application> core and linked to it in run-time. The concept is similar to 
243                             the module concept known for example in Apache Web server. Even such essential parts such 
244                             as transaction management have been developed as modules to keep the <application>SER</application> core 
245                             compact and fast.
246                         </para>
247                     </listitem>
248                     <listitem>
249                         <para>
250                             <emphasis>
251                                 Portability.
252                             </emphasis>
253                             <application>ser</application> has been written in ANSI C. It has been extensively tested 
254                             on PC/Linux and Sun/Solaris. Ports to BSD and IPAQ/Linux exist.
255                         </para>
256                     </listitem>
257                     <listitem>
258                         <para>
259                             <emphasis>                     
260                                 Interoperability. 
261                         </emphasis>
262                         <application>ser</application> is based on the open <acronym>SIP</acronym> standard. 
263                             It has undergone extensive tests with products of other vendors both in iptel.org
264                             labs and in the SIP Interoperability Tests (SIPIT). <application>ser</application> 
265                             powers the public iptel.org site 24 hours a day, 356 days a year 
266                             serving numerous SIP implementations using this site.
267                         </para>
268                     </listitem>
269                     <listitem>
270                         <para>
271                             <emphasis>Small size.</emphasis>
272                             Footprint of the core is 300k, add-on modules take up to 630k.
273                         </para>
274                     </listitem>
275                 </itemizedlist>
276             </para>
277         </section> <!-- serfeatures -->
278
279         <section id="usecases">
280             <title>Use Cases</title>
281             <para>
282                 This section illustrates the most frequent uses of SIP. In all these scenarios, 
283                 the SIP Express Router (SER) can be easily deployed as the glue connecting all 
284                 SIP components together, be it soft-phones, hard-phones, PSTN gateways or any other 
285                 SIP-compliant devices.
286             </para>
287             <section>
288                 <title>Added-Value ISP Services</title>
289                 <para>
290                     To attract customers, ISPs frequently offer applications bundled with IP access. 
291                     With SIP, the providers can conveniently offer a variety of services running on top 
292                     of a single infrastructure. Particularly, deploying VoIP and instant messaging and 
293                     presence services is as easy as setting up a SIP server and guiding customers to use 
294                     Windows Messenger. Additionally, the ISPs may offer advanced services such as PSTN 
295                     termination, user-driven call handling or unified messaging all using the same infrastructure.
296                 </para>
297                 <para>
298                     SIP Express Router has been engineered to power large scale networks: its capacity can deal 
299                     with large number of customers under high load caused by modern applications. Premium 
300                     performance allows deploying a low number of boxes while keeping investments and operational 
301                     expenses extremely low. ISPs can offer SIP-based instant messaging services and interface
302                     them to other instant messaging systems (Jabber, SMS). VoIP can be easily integrated along
303                     with added-value services, such as voicemail.
304                 </para>
305             </section> <!-- Added-value ISP -->
306             <section>
307                 <title>PC2Phone</title>
308                 <para>
309                     Internet Telephony Service Providers (ITSPs) offer the service of interconnecting 
310                     Internet telephony users using PC softphone or appliances to PSTN. Particularly with 
311                     long-distance and international calls, competitive pricing can be achieved by 
312                     routing the calls over the Internet.
313                 </para>
314                 <para>
315                     SIP Express Router can be easily configured to serve pc2phone users, distribute
316                     calls to geographically appropriate PSTN gateway, act as a security barrier and keep 
317                     track of charging. 
318                 </para>
319             </section>
320             <section>
321                 <title>PBX Replacement</title>
322                 <para>
323                     Replacing a traditional PBX in an enterprise can achieve reasonable 
324                     savings. Enterprises can deploy a single infrastructure for both voice 
325                     and data and bridge distant locations over the Internet. Additionally, they can 
326                     benefit of integration of voice and data.
327                 </para>
328                 <para>
329                     The SIP Express Router scales from SOHOs to large, international enterprises. 
330                     Even a single installation on a common PC is able to serve VoIP signaling of any 
331                     world's enterprise. Its policy-based routing language makes implementation of numbering 
332                     plans of companies spread across the world very easy. ACL features allow for protection of 
333                     PSTN gateway from unauthorized callers.
334                 </para>
335                 <para>
336                     SIP Express Router's support for programmable routing and accounting efficiently allows for 
337                     implementation of such a scenario.
338                 </para>
339             </section>
340         </section> <!-- Use Cases -->
341         <section id="aboutsip">
342             <title>About SIP Technology</title>
343             <para>
344                 The SIP protocol family is the technology which integrates services. 
345                 With SIP, Internet users can easily contact each other; figure out 
346                 willingness to have a conversation and couple different applications such as VoIP, video 
347                 and instant messaging. Integration with added-value services is seamless and easy. Examples 
348                 include integration with web (click-to-dial), E-mail (voice2email, UMS), and PSTN-like 
349                 services (conditional forwarding).
350             </para>
351             <para>
352                 The core piece of the technology is the Session Initiation Protocol (SIP, RFC3261) standardized by IETF. 
353                 Its main function is to establish communication sessions between users connected to the public 
354                 Internet and identified by e-mail-like addresses. One of SIP's greatest features is its transparent 
355                 support for multiple applications: the same infrastructure may be used for voice, video, gaming 
356                 or instant messaging as well as any other communication application.
357             </para>
358             <para>
359                 There are numerous scenarios in which SIP is already deployed: PBX replacement allows for 
360                 deployment of single inexpensive infrastructure in enterprises; PC-2-phone long-distance 
361                 services (e.g., Deltathree) cut callers long-distance expenses; instant messaging offered 
362                 by public severs (e.g., iptel.org) combines voice and text services with presence information. 
363                 New deployment scenarios are underway: SIP is a part of UMTS networks and research publications 
364                 suggest the use of SIP for virtual home environments or distributed network games.
365             </para>
366         </section> <!-- about sip -->
367         <section id="serlimitations">
368             <title>Known SER Limitations</title>
369             <para>
370                 The following items are not part of current distribution and are planned for next releases:
371                 <itemizedlist>
372                     <listitem>
373                         <para>
374                             TCP transport
375                         </para>
376                     </listitem>
377                     <listitem>
378                         <para>
379                             Script processing of multiple branches on forking
380                         </para>
381
382                         <warning>
383                             <para>
384                                 <application>ser</application>'s request processing language allows 
385                                 to make request decisions based on current URI. 
386                                 When a request if forked to multiple destinations, only the first branch's URI is used as 
387                                 input for script processing. This might lead to unexpected results. Whenever a URI resolves 
388                                 to multiple different next-hop URIs, only the first is processed which may result in handling 
389                                 not appropriate for the other branch. For example, a URI might resolve to an IP phone SIP 
390                                 address and PSTN gateway SIP address. If the IP phone address is the first, then script 
391                                 execution ignores the second branch. If a script includes checking gateway address in
392                                 request URI, the checks never match. That might result in ignoring of 
393                                 gateway admission control rules or applying them unnecessarily to non-gateway 
394                                 destinations.
395                             </para>
396                         </warning>
397                     </listitem>
398                 </itemizedlist>
399             </para>
400             <para>
401                 List of known bugs is publicly available at
402                 <ulink url="http://developer.berlios.de/bugs/?group_id=480">
403                     http://developer.berlios.de/bugs/?group_id=480
404                 </ulink>.
405             </para>
406         </section> <!-- limitations -->
407         <section id="licensing">
408             <title>Licensing</title>
409             <para>
410                 <application>ser</application> is freely available under terms and
411                 conditions of the GNU General Public License.
412             </para>     
413             <!-- COPYING -->
414             <screen>
415                     &gpllicense;
416             </screen>
417             
418         </section>
419         <section id="support">
420             <title>Obtaining Technical Assistance</title>
421             <para>
422                 We offer best-effort free support for <application>ser</application>.
423                 "best-effort" means that we try to solve your problems via email
424                 as soon as we can, subject to available manpower. If you need
425                 commercial support, contact info@iptel.org.
426             </para>
427             <para>
428                 To receive feedback to your inquiries, we recommend you to subscribe
429                 to the <emphasis>serusers</emphasis> mailing list and post your
430                 queries there. This mailing list is set up for mutual help by
431                 the community of <application>ser</application> users and developers.
432             </para>
433             <itemizedlist>
434                 <title>Mailing List Instructions</title>
435                 <listitem>
436                     <para>
437                         Public archives and subscription form:
438                         <ulink url="http://mail.iptel.org/mailman/listinfo/serusers">
439                             http://mail.iptel.org/mailman/listinfo/serusers
440                         </ulink>                        
441                     </para>
442                 </listitem>
443                 <listitem>
444                     <para>
445                         To post, send an email to serusers@iptel.org
446                     </para>
447                 </listitem>
448                 <listitem>
449                     <para>
450                         If you think you encountered an error, please submit the
451                         following information to avoid unnecessary round-trip times:                    
452                         <itemizedlist>
453                             <listitem>
454                                 <para>
455                                     Name and version of your operating system --
456                                     you can obtain it by calling
457                                     <command>uname -a</command>
458                                 </para>
459                             </listitem>
460                             <listitem>
461                                 <para>
462                                     <application>ser</application> distribution: 
463                                     release number and package                              
464                                 </para>
465                             </listitem>
466                             <listitem>
467                                 <para>
468                                     <application>ser</application> build -- 
469                                     you can obtain it by calling 
470                                     <command moreinfo="none">ser -V</command>
471                                 </para>
472                             </listitem>
473                             <listitem>
474                                 <para>
475                                     Your <application>ser</application> configuration file
476                                 </para>
477                             </listitem>
478                             <listitem>
479                                 <para>
480                                     <application>ser</application> logs -- with default settings
481                                     few logs are printed to <command>syslog</command> facility which
482                                     typically dumps them to 
483                                     <filename moreinfo="none">/var/log/messages</filename>. To 
484                                     enable detailed logs dumped to <filename>stderr</filename>,
485                                     apply the following configuration options: <command moreinfo="none">
486                                     debug=8, log_stderror=yes, fork=no</command>.
487                                 </para>
488                             </listitem>
489                             <listitem>
490                                 <para>
491                                     Captured SIP messages -- you can obtain them 
492                                     using tools such as <application>ngrep</application>
493                                     or <application moreinfo="none">ethereal</application>.
494                                 </para>
495                             </listitem>
496                         </itemizedlist>
497                     </para>
498                     
499                 </listitem>
500             </itemizedlist>         
501         
502             <para>
503                 If you are concerned about your privacy and do not wish your
504                 queries to be posted and archived publicly, you may post to
505                 serhelp@iptel.org. E-mails to this address are only forwarded
506                 to iptel.org's <application>ser</application> development team.
507                 However, as the team is quite busy you should not be surprised
508                 to get replies with considerable delay.
509
510             </para>
511         </section>
512         
513         <section id="moreinfo">
514             <title>More Information</title>
515             <para>
516                 Most up-to-date information including latest and most complete version
517                 of this documentation is always available at our website,
518                 <ulink url="http://www.iptel.org/ser/">http://www.iptel.org/ser/</ulink>.
519                 The site includes links to other important information about
520                 <application moreinfo="none">ser</application>, such
521                 as installation guidelines (INSTALL), download links,
522                 development pages, programmer's manual, etc.
523             </para>
524             <para>
525                 A SIP tutorial (slide set) is available at 
526                 <ulink url="http://www.iptel.org/sip/">http://www.iptel.org/sip/</ulink> .
527             </para>
528         </section> <!-- info -->
529
530         <section>
531             <title>Release Notes</title>
532             <literallayout format="linespecific" class="normal">
533 &releasenotes;
534             </literallayout>
535         </section> <!-- release notes -->
536
537
538     </chapter> <!-- general -->
539
540     <chapter>
541         <title>Introduction to SER</title>
542
543         <section id="requestrouting">
544             <title>Request Routing and SER Scripts</title>
545             <para>
546                 The most important concept of every SIP server is that of
547                 request routing. The request routing logic determines the next
548                 hop of a request. It can be for example used to implement user 
549                 location service or enforce static routing to a gateway. Real-world
550                 deployments actually ask for quite complex routing logic, which
551                 needs to reflect static routes to PSTN gateways, dynamic routes
552                 to registered users, authentication policy, capabilities of
553                 SIP devices, etc.
554             </para>
555             <para>
556                 SER's answer to this need for routing flexibility is a routing
557                 language, which allows administrators to define the SIP request
558                 processing logic in a detailed manner. They can for example easily
559                 split SIP traffic by method or destination, perform user location, 
560                 trigger authentication, verify access permissions, and so on.
561             </para>
562             <para>
563                 The primary building block of the routing language are <emphasis>actions</emphasis>. 
564                 There are built-in actions (like <command>forward</command> for stateless forwarding
565                 or <command>strip</command> for stripping URIs) as 
566                 well as external actions imported from shared library modules. All actions can 
567                 be combined in compound actions by enclosing them in braces, 
568                 e.g. <command>{a1(); a2();}</command>. 
569                 Actions are aggregated in one or more <emphasis>route blocks</emphasis>.
570                 Initially, only the default routing block denoted by <command>route[0]</command>
571                 is called. Other routing blocks can be called by the action
572                 <command>route(blocknumber)</command>, recursion is permitted.
573                 The language includes <emphasis>conditional statements</emphasis>. 
574             </para>
575
576             <para>
577                 The routing script is executed for every received request in sequential order. 
578                 Actions may return positive/negative/zero value. 
579
580                 Positive values are considered success and evaluated as
581                 TRUE in conditional expressions. Negative values are considered FALSE. 
582
583                 Zero value means error and leaves execution of currently processed
584                 route block. The route block is left too, if <command>break</command> is explicitly
585                 called from it.
586
587             </para>
588             <para>
589                 The easiest and still very useful way for <application>ser</application>
590                 users to affect request routing logic is
591                 to determine next hop statically. An example is
592                 routing to a PSTN gateway whose static IP address is well known.
593                 To configure static routing, simply use the action
594                 <command>forward( IP_address, port_number)</command>.
595                 This action forwards an incoming request "as is" to the
596                 destination described in action's parameters.
597             </para>
598
599             <example>
600                 <title>Static Forwarding</title>
601                 <programlisting format="linespecific">
602 # if requests URI is numerical and starts with
603 # zero, forward statelessly to a static destination
604
605 if (uri=~"^sip:0[0-9]*@iptel.org) {
606     forward( 192.168.99.3, 5080 );
607
608                 </programlisting>
609             </example>
610
611             <para>
612                 However, static forwarding is not sufficient in many cases.
613                 Users desire mobility and change their location frequently.
614                 Lowering costs for termination of calls in PSTN requires
615                 locating a least-cost gateway. Which next-hop is taken may
616                 depend on user's preferences. These and many other scenarios
617                 need the routing logic to be more dynamic. We describe in
618                 <xref linkend="conditions"> how to make request processing
619                 subject to various conditions and in 
620                 <xref linkend="urirewriting"> how to determine next SIP hop.
621             </para>
622         </section>
623
624         <section id="conditions">
625             <title>Conditional Statements</title>
626             <para>
627                 A very useful feature is the ability to make routing
628                 logic depend on a condition. A script condition may for
629                 example distinguish between request processing for
630                 served and foreign domains, IP and PSTN routes,
631                 it may split traffic by method or username, it
632                 may determine whether a request should be authenticated
633                 or not, etc. <application moreinfo="none">ser</application>
634                 allows administrators to form conditions based on
635                 properties of processed request, such as method or uri,
636                 as well as on virtually any piece of data on the
637                 Internet.
638             </para>
639             <example>
640                 <title>Conditional Statement</title>
641                 <para>
642                     This example shows how a conditional statement is
643                     used to split incoming requests between a PSTN
644                     gateway and a user location server based on
645                     request URI.
646                 </para>
647                 <programlisting format="linespecific">
648 # if request URI is numerical, forward the request to PSTN gateway...
649 if (uri=~"^sip:[0-9]+@foo.bar") { # match using a regular expression
650     forward( gateway.foo.bar, 5060 );
651 } else { # ... forward the request to user location server otherwise
652     forward( userloc.foo.bar, 5060 );
653 };
654                 </programlisting>
655             </example>
656
657             <para>
658                 Conditional statements in <application>ser</application> scripts may depend
659                 on a variety of  expressions. The simplest expressions are 
660                 action calls. They return true if they completed successfully or false otherwise. 
661                 An example of an action frequently used in conditional statements is
662                 <command moreinfo="none">search</command> imported from textops module.
663                 <command moreinfo="none">search</command> action leverages textual
664                 nature of SIP and compares SIP requests against a regular expression.
665                 The action returns true if the expression matched, false otherwise.
666                 <example>
667                     <title>Use of <command>search</command> Action in Conditional Expression</title>
668                     <programlisting format="linespecific">
669 # prevent strangers from claiming to belong to our domain;
670 # if sender claims to be in our domain in From header field,
671 # better authenticate him 
672 if (search("(f|From): .*@mydomain.com)) {
673     if (!(proxy_authorize("mydomain.com" /* realm */,"subscriber" /* table name */ ))) {
674            proxy_challenge("mydomain.com /* ream */, "1" /* use qop */ );
675            break;
676     }
677 }
678                     </programlisting>
679                 </example>
680             </para>
681             <para>
682                 As modules may be created, which export new functions, there is virtually
683                 no limitation on what functionality <application moreinfo="none">ser</application>
684                 conditions are based on. Implementers may introduce new actions whose
685                 return status depends on request content or any external data as well. Such actions
686                 can query SQL, web, local file systems or any other place which can provide
687                 information wanted for request processing.
688             </para>
689             <para>
690                 Furthermore, many request properties may be examined using existing built-in operands
691                 and operators. Available left-hand-side operands and legal combination with
692                 operators and right-hand-side operands are described in <xref linkend="logicalexpr">.
693                 Expressions may be grouped together using logical operators:
694                 negation (<command>!</command>), AND (<command>&&</command>), OR (<command moreinfo="none">
695                 ||</command> and precedence parentheses (<command>()</command>).
696             </para>
697
698             <section id="operators">
699                 <title>Operators and Operands</title>
700                 <para>
701                     There is a set of predefined operators and operands
702                     in ser, which in addition to actions may be evaluated
703                     in conditional expressions. 
704                 </para>
705                 <para>
706                     Left hand-side operands, which <application>ser</application>
707                     understands are the following:
708                     <itemizedlist>
709                         <listitem>
710                             <para>
711                                 <emphasis>method</emphasis>, which refers to 
712                                 request method
713                                 such as REGISTER or INVITE
714                             </para>
715                         </listitem>
716                         <listitem>
717                             <para>
718                                 <emphasis>uri</emphasis>, which refers to current request URI,
719                                 such as 
720                                 "sip:john.doe@foo.bar"
721                                 <note>
722                                     <para>
723                                         Note that "uri" always refers to current
724                                         value of URI, which is subject to change
725                                         be uri-rewriting actions.
726                                     </para>
727                                 </note>
728                             </para>
729                         </listitem>
730                         <listitem>
731                             <para>
732                                 <emphasis>src_ip</emphasis>, which refers to IP address from 
733                                 which a request came.
734                             </para>
735                         </listitem>
736                         <listitem>
737                             <para>
738                                 <emphasis>dst_ip</emphasis> refers to server's IP address 
739                                 at which a request was received
740                             </para>
741                         </listitem>
742                         <listitem>
743                             <para>
744                                 <emphasis>src_port</emphasis> port number from which a SIP
745                                 request came
746                             </para>
747                         </listitem>
748                     </itemizedlist>
749                 </para>
750                 <para>
751                     ser understands the following operators:
752                     <itemizedlist>
753                         <listitem>
754                             <para>
755                                 == stands for equity
756                             </para>
757                             
758                         </listitem>
759                         <listitem>
760                             <para>
761                                 =~ stands for regular expression matching
762                             </para>
763                         </listitem>
764                         <listitem>
765                             <para>
766                                 logical operators: and, or, negation, parentheses
767                                 (C-notation for the operators may be used too)
768                             </para>
769                         </listitem>
770                     </itemizedlist>
771                 </para>
772
773             <table id="logicalexpr">
774                 <title>Valid Combinations of Operands and Operators in Expressions</title>
775                 <tgroup cols="4">
776                     <thead>
777                         <row>
778                             <entry>
779                                 left-hand-side operand
780                             </entry>                        
781                             <entry>
782                                 valid operators
783                             </entry>
784                             <entry>
785                                 valid right-hand side operators
786                             </entry>
787                             <entry>
788                                 examples/comments
789                             </entry>
790                         </row>
791
792                     </thead>
793                     <tbody>
794
795                         <row>
796                             <entry>
797                                 method
798                             </entry>                        
799                             <entry>
800                                 == (exact match), =~ (regular expression matching)
801                             </entry>
802                             <entry>
803                                 string
804                             </entry>
805                             <entry>
806                                 method=="INVITE" || method=="ACK" || method=="CANCEL"
807                             </entry>
808                         </row>                  
809
810                         <row>
811                             <entry>
812                                 uri
813                             </entry>                        
814                             <entry>
815                                 == (exact match), =~ (regular expression matching)
816                             </entry>
817                             <entry>
818                                 string
819                             </entry>
820                             <entry>
821                                 uri=="sip:foo@bar.com" matches only if exactly this uri
822                                 is in request URI
823
824                             </entry>
825                         </row>                          
826
827                         <row>
828                             <entry>
829                                 
830                             </entry>                        
831                             <entry>
832                                 == (exact match)
833                             </entry>
834                             <entry>
835                                 myself
836                             </entry>
837                             <entry>
838                                 
839                                 the expression uri==myself is true if the host part in 
840                                 request URI equals a server name or a server alias (set using
841                                 the alias option in configuration file)
842                                 
843                             </entry>
844                         </row>                          
845
846                         <row>
847                             <entry>
848                                 src_ip
849                             </entry>                        
850                             <entry>
851                                 == (match)
852                             </entry>
853                             <entry>
854                                 IP, IP/mask_length, IP/mask, hostname, myself
855                             </entry>
856                             <entry>
857                                 src_ip==192.168.0.0/16 matches requests coming from
858                                 a private network
859                             </entry>
860                         </row>
861
862                         <row>
863                             <entry>
864                                 dst_ip                          
865                             </entry>                        
866                             <entry>
867                                 == (match)
868                             </entry>
869                             <entry>
870                                 IP, IP/mask_length, IP/mask, hostname, myself
871                             </entry>
872                             <entry>
873                                 dst_ip==127.0.0.1 matches if a request was received
874                                 via loopback interface
875                             </entry>
876                         </row>
877
878                         <row>
879                             <entry>
880                                     src_port
881                             </entry>                        
882                             <entry>
883                                 == (match)
884                             </entry>
885                             <entry>
886                                 port number
887                             </entry>
888                             <entry>
889                                 port number from which a request was sent, e.g. src_port==5060
890                             </entry>
891                         </row>                      
892
893
894                     </tbody>
895                 </tgroup>
896             </table>
897             
898
899                 <example>
900                     <title>
901                         More examples of use of <application>ser</application> operators and operands in conditional
902                         statements
903                     </title>
904                     <programlisting format="linespecific">
905 # using an action as condition input; in this
906 # case, an actions 'search' looks for Contacts
907 # with private IP address in requests; the condition
908 # is processed if such a contact header field is
909 # found
910
911 if (search("^(Contact|m): .*@(192\.168\.|10\.|172\.16)")) {
912 # .... 
913
914 # this condition is true if request URI matches
915 # the regular expression "@bat\.iptel\.org"
916     if (uri=~"@bat\.iptel\.org") {
917 # ...
918
919 # and this condition is true if a request came
920 # from an IP address (useful for example for
921 # authentication by IP address if digest is not
922 # supported) AND the request method is INVITE
923
924 # if ( (src_ip==192.68.77.110 and method=="INVITE")
925 # ...
926 </programlisting>
927                 </example>
928             </section> <!-- operators and operands -->
929             <section>
930                 <title>URI Matching</title>
931                 <para>URI matching expressions have a broad use in a SIP server
932                     and deserve more explanation. Typical uses of
933                     URI matching include implementation of numbering plans,
934                     domain matching,
935                     binding external applications to specific URIs,
936                     etc. This section shows examples of typical applications
937                     of URI-matching.
938                 </para>
939                 <section id="domainmatching">
940                     <title>Domain Matching</title>
941                     <para>
942                         One of most important uses of URI matching is deciding
943                         whether a request is targeted to a served or outside domain.
944                         Typically, different request
945                         processing applies. Requests for outside domains
946                         are simply forwarded to them, whereas
947                         more complex logic applies to requests for a served domain.
948                         The logic may include saving user's contacts
949                         when REGISTER requests are received, forwarding requests
950                         to current user's location or a PSTN gateways, 
951                         interaction with external applications, etc.
952                     </para>
953                     <para>
954                         The easiest way to decide whether a request belongs
955                         a served domain is using the <command moreinfo="none">myself</command>
956                         operand. 
957                         The expression "uri==myself" returns true if domain name
958                         in request URI matches name of the host at which
959                         <application moreinfo="none">ser</application> is
960                         running. This may be insufficient in cases when
961                         server name is not equal to domain name for which the server
962                         is responsible. For example, the "uri==myself" condition
963                         does not match if a server "sipserver.foo.bar" 
964                         receives a request for "sip:john.doe@foo.bar". To
965                         match other names in URI than server's own,
966                         set up the <varname>alias</varname> configuration
967                         option. The option may be used multiple times,
968                         each its use adds a new item to a list of aliases.
969                         The myself condition returns then  true 
970                         also for any hostname on the list of aliases.
971                         <example>
972                             <title>Use of uri==myself Expression</title>
973                             <programlisting format="linespecific">
974 # ser powers a domain "foo.bar" and runs at host sipserver.foo.bar;
975 # Names of served domains need to be stated in the aliases
976 # option; myself would not match them otherwise and would only
977 # match requests with "sipserver.foo.bar" in request-URI
978 alias="foo.bar"
979 alias="sales.foo.bar"
980 route[0] {
981         if (uri==myself) {
982             # the request either has server name or some of the
983             # aliases in its URI
984             log(1,"request for served domain")
985             # some domain-specific logic follows here ....
986         } else {
987             # aha -- the server is not responsible for this
988             # requests; that happens for example with the following URIs
989             #  - sip:a@marketing.foo.bar
990             #  - sip:a@otherdomain.bar
991             log(1,"request for outbound domain");
992             # outbound forwarding                         
993             t_relay();
994         };
995 }                       </programlisting>
996                     </example>
997                 </para>
998                 <para>
999                     It is possible to recognize whether a request belongs to
1000                     a domain using regular expressions too. Care needs to
1001                     be paid to construction of regular expressions. URI
1002                     syntax is rich and an incorrect expression would result
1003                     in incorrect call processing. The following example shows
1004                     how an expression for domain matching can be formed.
1005                     <example id="redomainmatching">
1006                         <title>Domain Matching Using Regular Expressions</title>
1007                         <para>
1008                             In this example, server named "sip.foo.bar" with
1009                             IP address 192.168.0.10 is responsible for the
1010                             "foo.bar" domain. That means, requests with the
1011                             following hostnames in URI should be matched:
1012                             <itemizedlist>
1013                                 <listitem>
1014                                     <para>
1015                                         foo.bar, which is the name of server domain
1016                                     </para>
1017                                 </listitem>
1018                                 <listitem>
1019                                     <para>
1020                                         sip.foo.bar, since it is server's name and some
1021                                         devices put server's name in request URI
1022                                     </para>
1023                                 </listitem>
1024                                 <listitem>
1025                                     <para>
1026                                         192.168.0.10, since it is server's IP address and
1027                                         some devices put server's IP address in request URI
1028                                     </para>
1029                                 </listitem>
1030                             </itemizedlist>                     
1031                             Note how this regular expression is constructed. In particular:
1032                             <itemizedlist>
1033                                 <listitem>
1034                                     <para>
1035                                         User name is optional (it is for example never included
1036                                         in REGISTER requests) and there are no restrictions on
1037                                         what characters it contains. That is what 
1038                                         <emphasis>(.+@)?</emphasis> mandates. 
1039                                     </para>
1040                                 </listitem>
1041                                 <listitem>
1042                                     <para>
1043                                         Hostname must be followed by port number, parameters
1044                                         or headers -- that is what the delimiters 
1045                                         <emphasis>[:;\?]</emphasis> are good for. If none
1046                                         it these follows, the URI must be ended 
1047                                         (<emphasis>$</emphasis>). Otherwise, longer hostnames
1048                                         such as 192.168.0.101 or foo.bar.otherdomain.com would
1049                                         mistakenly match.
1050                                     </para>
1051                                 </listitem>
1052                                 <listitem>
1053                                     <para>
1054                                         Matches are case-insensitive. All hostnames "foo.bar", "FOO.BAR"
1055                                         and "FoO.bAr" match.
1056                                     </para>
1057                                 </listitem>
1058                             </itemizedlist>
1059                         </para>
1060                         <programlisting>
1061 if (uri=~"^sip:(.+@)?(192\.168\.0\.10|(sip\.)?foo\.bar)([:;\?].*)?$")
1062       log(1, "yes, it is a request for our domain");
1063       break;
1064  };
1065                         </programlisting>
1066                     </example>
1067                 </para>
1068                 </section> <!-- domain matching -->
1069                 <section id="numberingplans">
1070                     <title>Numbering Plans</title>
1071
1072                     <para>
1073                         Other use of URI matching is implementation of dialing
1074                         plans. A typical task when designing a dialing plan for SIP networks
1075                         is to distinguish between "pure-IP" and PSTN destinations.
1076                         IP users typically have either alphanumerical or numerical
1077                         usernames. The numerical usernames are convenient for PSTN
1078                         callers who can only
1079                         use numeric keypads. Next-hop destination of IP users is looked up dynamically
1080                         using user location database. On the other hand, PSTN destinations are 
1081                         always indicated by nummerical usernames. Requests to PSTN are statically 
1082                         forwarded to well-known PSTN gateways.
1083                     </para>
1084                     <example>
1085                         <title>A simple Numbering Plan</title>
1086                         <para>
1087                             This example shows a simple dialing plan which reserves
1088                             dialing prefix "8" for IP users, other numbers
1089                             are used for PSTN destinations and all other non-nummerical
1090                             usernames are used for IP users.
1091                         </para>
1092                         <programlisting format="linespecific">
1093 # is it a PSTN destination? (is username nummerical and does not begin with 8?)
1094 if (uri=~"^sip:[0-79][0-9]*@") { # ... forward to gateways then;
1095       # check first to which PSTN destination the requests goes;
1096       # if it is US (prefix "1"), use the gateway 192.168.0.1...
1097       if (uri=~"^sip:1") {
1098            # strip the leading "1"
1099            strip(1);
1100            forward(192.168.0.1, 5060);
1101       } else {
1102            # ... use the gateway 10.0.0.1 for all other destinations
1103            forward(10.0.0.1, 5060);
1104       }
1105       break;
1106 } else {
1107       # it is an IP destination -- try to lookup it up in user location DB
1108       if (!lookup("location")) {
1109           # bad luck ... user off-line
1110           sl_send_reply("404", "Not Found");
1111           break;
1112       }
1113       # user on-line...forward to his current destination
1114       forward(uri:host,uri:port);
1115 }
1116                         </programlisting>
1117                     </example>
1118                 </section> <!-- numbering plans -->
1119             </section>
1120         </section> <!-- conditional statements -->
1121         
1122         <section id="urirewriting">
1123             <title>Request URI Rewriting</title>
1124
1125             <para>
1126                 The ability to give users and services a unique name using URI
1127                 is a powerful tool. It allows users to advertise how to reach
1128                 them, to state to whom they wish to communicate and what services 
1129                 they wish to use.
1130                 Thus, the ability to change URIs is very important and is
1131                 used for implementation of many services. 
1132                 "Unconditional forwarding" from user "boss" to user
1133                 "secretary" is a typical example of application relying
1134                 on change of URI address.
1135             </para>
1136             <para>
1137                 <application moreinfo="none">ser</application> has the ability
1138                 to change request URI in many ways.
1139                 A script can use any of the following
1140                 built-in actions to change request URI or a part of it:
1141
1142                 <command>rewriteuri</command>, 
1143                 <command>rewritehost</command>, 
1144                 <command>rewritehostport</command>, 
1145                 <command>rewriteuser</command>, 
1146                 <command>rewriteuserpass</command> and 
1147                 <command>rewriteport</command>. 
1148                 When later in the script
1149                 a forwarding action is encountered, the action forwards
1150                 the request to address in the rewritten URI.
1151                 <example>
1152                     <title>Rewriting URIs</title>
1153                     <programlisting format="linespecific">
1154 if (uri=~"dan@foo.bar") {
1155     rewriteuri("sip:bla@somewherelse.com")
1156     # forward statelessly to the destination in current URI, i.e.,
1157     # to sip:bla@somewherelese.com:5060
1158     forward( uri:host, uri:port);
1159 }
1160                     </programlisting>
1161                 </example>
1162             </para>         
1163             <para>Two more built-in URI-rewriting commands are of special importance
1164                 for implementation of dialing plans and manipulation of dialing
1165                 prefixes. <command>prefix(s)
1166                 </command>, inserts 
1167                 a string "s" in front of SIP address and 
1168                 <command>strip(n)</command> takes
1169                 away the first "n" characters of a SIP address.
1170                 See <xref linkend="urirewritingexamples"> for examples of use of
1171                 built-in URI-rewriting actions.
1172             </para>
1173
1174             <para>
1175                 Commands exported by external modules can change URI too
1176                 and many do so.
1177                 The most important application is changing URI using the
1178                 user location database. The command 
1179                 <command>lookup(table)</command> looks up current
1180                 user's location and rewrites user's address with it.
1181                 If there is no registered contact, the  command returns a negative value.
1182
1183
1184                 <example id=rewriteuri>
1185                     <title>Rewriting URIs Using User Location Database</title>
1186                     <programlisting format="linespecific">
1187 # store user location if a REGISTER appears
1188 if (method=="REGISTER") {
1189    save("mydomain1");
1190 } else {
1191 # try to use the previously registered contacts to
1192 # determine next hop
1193    if(lookup("mydomain1")) {
1194      # if found, forward there...
1195      t_relay();
1196    } else {
1197      # ... if no contact on-line, tell it upstream
1198      sl_send_reply("404", "Not Found" );
1199    };
1200 };
1201                     </programlisting>
1202                 </example>
1203             </para>
1204             <para>
1205                 External applications can be used to rewrite URI too.
1206                 The "exec" module provides script actions, which start external programs
1207                 and read new URI value from their output. <command moreinfo="none">exec_uri</command>
1208                 and <command moreinfo="none">exec_user</command> both call an external program,
1209                 pass current URI or its user part to it respectively, wait until it completes,
1210                 and eventually rewrite current URI with its output.
1211             </para>
1212             <para>
1213                 It is important to realize that <application moreinfo="none">ser</application>
1214                 operates over <emphasis>current URI</emphasis> all the time. If an original
1215                 URI is rewritten by a new one, the original will will be forgotten and the new one will 
1216                 be used in any further processing. In particular, the uri matching operand
1217                 and the user location action <command moreinfo="none">lookup</command>
1218                 always take current URI as input, regardless what the original URI was.
1219             </para>
1220             <para>
1221                 <xref linkend="urirewritingexamples"> shows how URI-rewriting actions affect 
1222                 an example URI, sip:12345@foo.bar:6060.
1223                 <table id="urirewritingexamples">
1224                     <title>URI-rewriting Using Built-In Actions</title>
1225                     <tgroup cols="2">
1226                         <thead>
1227                             <row>
1228                                 <entry>
1229                                     Example Action
1230                                 </entry>                                
1231                                 <entry>
1232                                     Resulting URI
1233                                 </entry>
1234                             </row>
1235                         </thead>
1236                         <tbody>
1237                             <row>
1238                                 <entry>
1239                                     <command moreinfo="none">rewritehost("192.168.0.10")</command> rewrites
1240                                     the hostname in URI, other parts (including port number) remain unaffected.
1241                                 </entry>
1242                                 <entry>
1243                                     sip:12345@192.168.10:6060
1244                                 </entry>
1245                             </row>
1246                             <row>
1247                                 <entry>
1248                                     <command moreinfo="none">rewriteuri("sip:alice@foo.bar");</command> rewrites
1249                                     the whole URI completely.
1250                                 </entry>
1251                                 <entry>
1252                                     sip:alice@foo.bar
1253                                 </entry>
1254                             </row>
1255                             <row>
1256                                 <entry>
1257                                     <command moreinfo="none">rewritehostport("192.168.0.10:3040")</command>rewrites 
1258                                     both hostname and port number in URI.
1259                                 </entry>
1260                                 <entry>
1261                                     sip:12345@192.168.0.10:3040
1262                                 </entry>
1263                             </row>
1264                             <row>
1265                                 <entry>
1266                                     <command moreinfo="none">rewriteuser("alice")</command> rewrites user part of URI.
1267                                 </entry>
1268                                 <entry>
1269                                     sip:alice@foo.bar:6060
1270                                 </entry>
1271                             </row>
1272                             <row>
1273                                 <entry>
1274                                     <command moreinfo="none">rewriteuserpass("alice:pw")</command> replaces the pair
1275                                     user:password in URI with a new value.
1276                                 </entry>
1277                                 <entry>
1278                                     sip:alice:pw@foo.bar:6060
1279                                 </entry>
1280                             </row>
1281                             <row>
1282                                 <entry>
1283                                     <command moreinfo="none">rewriteport("1234")</command> replaces port number in URI
1284                                 </entry>
1285                                 <entry>
1286                                     sip:12345@foo.bar:1234
1287                                 </entry>
1288                             </row>
1289                             <row>
1290                                 <entry>
1291                                     <command moreinfo="none">prefix("9")</command> inserts a string ahead of user part of URI
1292                                 </entry>
1293                                 <entry>
1294                                     sip:912345@foo.bar:6060
1295                                 </entry>
1296                             </row>
1297                             <row>
1298                                 <entry>
1299                                     <command moreinfo="none">strip(2)</command> removes leading characters from user part of URI
1300                                 </entry>
1301                                 <entry>
1302                                     sip:345@foo.bar:6060
1303                                 </entry>
1304                             </row>
1305
1306
1307                         </tbody>
1308                     </tgroup>
1309                 </table>
1310             </para>         
1311             <para>
1312                 You can verify whether you understood URI processing by
1313                 looking at the following example. It rewrites URI
1314                 several times. The question is what is the final URI to which
1315                 the script fill forward any incoming request.
1316                 <example>
1317                     <title>URI-rewriting Exercise</title>
1318                     <programlisting format="linespecific">
1319 exec_uri("echo sip:2234@foo.bar; echo > /dev/null");
1320 strip(2);
1321 if (uri=~"^sip:2") {
1322     prefix("0");
1323 } else {
1324     prefix("1");
1325 };                      
1326 forward(uri:host, uri:port);
1327                     </programlisting>
1328                 </example>
1329             </para>
1330             <para>
1331                 The correct answer is the resulting URI will be
1332                 "sip:134@foo.bar". <command moreinfo="none">exec_uri</command>
1333                 rewrites original URI to "sip:2234@foo.bar", 
1334                 <command moreinfo="none">strip(2)</command> takes
1335                 two leading characters from username away resulting
1336                 in "34@iptel.org", the condition does not match
1337                 because URI does not begin with "2" any more,
1338                 so the prefix "1" is inserted.
1339             </para>
1340
1341
1342         </section> <!-- URI rewriting -->
1343
1344         <section>
1345             <title>Destination Set</title>
1346             <para>
1347                 Whereas needs of many scenarios can by accommodated by maintaining
1348                 a single request URI, some scenarios are better served by
1349                 multiple URIs. Consider for example a user with address
1350                 john.doe@iptel.org. The user wishes to be reachable at his 
1351                 home phone, office phone, cell phone, softphone, etc. 
1352                 However, he still wishes to maintain a single public address
1353                 on his business card.
1354             </para>
1355             <para>
1356                 To enable such scenarios, <application>ser</application>
1357                 allows translation of a single request URI into multiple
1358                 outgoing URIs. The ability to forward a request to multiple
1359                 destinations is known as <emphasis>forking</emphasis>
1360                 in SIP language. All outogoing URIs (in trivial case one of them)
1361                 are called <emphasis>destination set</emphasis>. The destination
1362                 set always includes one default URI, to which additional URIs
1363                 can be appended. Maximum size of a destination set is limited by 
1364                 a compile-time constant, MAX_BRANCHES,
1365                 in <filename moreinfo="none">config.h</filename>.
1366             </para>
1367             <para>
1368                 Some actions are designed for use with a single URI whereas
1369                 other actions work with the whole destination set.
1370             </para>
1371             <para>
1372                 Actions which are currently available for creating the destination
1373                 set are <command>lookup</command> from usrloc module and 
1374                 <command>exec_uri/exec_user</command> from exec module.
1375                 <command moreinfo="none">lookup</command> fills in the destination
1376                 set with user contact's registered previously with REGISTER
1377                 requests. The <command moreinfo="none">exec</command> actions
1378                 fill in the destination set with output of an external program.
1379                 In both cases, current destination set is completely rewritten.         
1380                 New URIs can be appended to destination set by a call to the built-in
1381                 action <command>append_branch(uri)</command>.
1382             </para>
1383             <para>              
1384                 Currently supported features which utilize destination sets
1385                 are <emphasis>forking</emphasis> and <emphasis>redirection</emphasis>. 
1386                 Action <command>t_relay</command> (TM module) for stateful
1387                 forwarding supports forking. If called with a non-trivial destination
1388                 set, <command moreinfo="none">t_relay</command> forks
1389                 incoming request to all URIs in current destination set.
1390                 See <xref linkend="rewriteuri">. If a user
1391                 previously registered from three locations, the destination set is filled with 
1392                 all of them by <command>lookup</command> and the <command>t_relay</command>
1393                 command forwards the incoming request to all these destinations.
1394                 Eventually, all user's phone will be ringing in parallel.
1395             </para>
1396             <para>
1397                 SIP redirection is another feature which leverages destination sets.
1398                 It is a very light-weighted method to establish communication
1399                 between two parties with minimum burden put on the server. In
1400                 <application>ser</application>, the action <command>sl_send_reply</command>
1401                 (SL module) is used for this purpose. This action 
1402                 allows to generate replies to SIP requests without keeping 
1403                 any state. If the status code passed to the action is 3xx, 
1404                 the current destination set is printed in reply's Contact header
1405                 fields. Such a reply instructs the originating client to 
1406                 retry at these addresses. (See <xref linkend="redirectexample">).
1407             </para>
1408             <para>
1409                 Most other  <application>ser</application> actions ignore destination
1410                 sets: they either do not relate to URI processing (<command moreinfo="none">
1411                 log</command>, for example) or they work only with the default URI.
1412                 All URI-rewriting functions such as
1413                 <command moreinfo="none">rewriteuri</command> belong in this
1414                 category. URI-comparison operands only refers to the first URI
1415                 (see <xref linkend="operators">). Also, the built-in action
1416                 for stateless forwarding, <command>forward</command> works only
1417                 with the default URI and ignores rest of the destination set. The reason 
1418                 is a proxy server willing to fork must guarantee that the burden
1419                 of processing multiple replies is not put unexpectedly on upstream
1420                 client. This is only achievable with stateful processing.  
1421                 Forking cannot be used along with stateless <command>forward</command>,
1422                 which thus only processes one URI out of the whole destination set.
1423                 Also, the uri comparison operand (see <xref linkend="operators">)
1424                 refers only to current URI and ignores the rest of destination
1425                 set.
1426             </para> 
1427
1428         </section> <!-- Destination Set -->
1429
1430         <section>
1431             <title>User Location</title>
1432             <para>
1433                 Mobility is a key feature of SIP. Users are able to use one
1434                 one or more SIP devices and be reachable at them. Incoming requests 
1435                 for users are forwarded to all user's devices in use. The key
1436                 concept is that of soft-state registration. Users can
1437                 -- if in possession of valid credentials -- link SIP
1438                 devices to their e-mail like address of record. Their SIP devices
1439                 do so using a REGISTER request, as in <xref linkend="register">.
1440                 The request creates a binding between the public address of
1441                 record (To header field) and SIP device's current address
1442                 (Contact header field). 
1443                 <example id="register">
1444                     <title>REGISTER Request</title>
1445                     <programlisting format="linespecific">
1446 REGISTER sip:192.168.2.16 SIP/2.0
1447 Via: SIP/2.0/UDP 192.168.2.16;branch=z9hG4bKd5e5.5a9947e4.0
1448 Via: SIP/2.0/UDP 192.168.2.33:5060
1449 From: sip:123312@192.168.2.16
1450 To: sip:123312@192.168.2.16
1451 Call-ID: 00036bb9-0fd30217-491b6aa6-0a7092e9@192.168.2.33
1452 Date: Wed, 29 Jan 2003 18:13:15 GMT
1453 CSeq: 101 REGISTER
1454 User-Agent: CSCO/4
1455 Contact: sip:123312@192.168.2.33:5060
1456 Content-Length: 0
1457 Expires: 600
1458                     </programlisting>
1459                 </example>
1460                 Similar requests can be used to query all user's current contacts or to
1461                 delete them. All Contacts have certain time to live, when the time expires,
1462                 contact is removed and no longer used for processing of incoming requests.
1463             </para>
1464             <para>
1465                 <application moreinfo="none">ser</application> is built to do both: update
1466                 user location database from received REGISTER requests and look-up these
1467                 contacts when inbound requests for a user arrive. To achieve high performance,
1468                 the user location table is stored in memory. In regular intervals
1469                 (usrloc module's parameter <varname>timer_interval</varname> determines
1470                 their length), all changes to the in-memory table are backed up in
1471                 <application moreinfo="none">mysql</application> database to achieve
1472                 peristence accross server reboots. Administrators or application writers
1473                 can lookup list of current user's contacts stored in memory using the
1474                 <application moreinfo="none">serctl</application> tool (see <xref linkend="serctl">).
1475                 <example>
1476                     <title>Use of <application>serctl</application> Tool to Query User Location</title>
1477                     <screen format="linespecific">
1478 <![CDATA[
1479 [jiri@fox jiri]$ sc ul show jiri
1480 <sip:jiri@212.202.172.134>;q=0.00;expires=456
1481 <sip:7271@gateway.foo.bar>;q=0.00;expires=36000
1482 ]]>
1483                     </screen>
1484                 </example>
1485             </para>
1486             <para>
1487                 Building user location in <application moreinfo="none">ser</application> scripts is
1488                 quite easy. One first needs to determine whether a request is for served domain,
1489                 as described in <xref linkend="domainmatching">. If that is the case, the script
1490                 needs to distinguish between REGISTER requests, that update user location table,
1491                 and all other requests for which next hop is determined from the table. The
1492                 <command moreinfo="none">save</command> action is used to update user location
1493                 (i.e., it writes to it). The <command moreinfo="none">lookup</command> actions
1494                 reads from the user location table and fills in destination set with current
1495                 user's contacts.
1496                 <example>
1497                     <title>Use of User Location Actions</title>
1498                     <programlisting format="linespecific">
1499 # is the request for my domain ?
1500 if (uri==myself) {
1501     if (method=="REGISTER") { # REGISTERs are used to update
1502          save("location");
1503          break; # that's it, we saved the contacts, exit now
1504     } else {
1505          if (!lookup("location") { # no registered contact
1506             sl_send_reply("404", "Not Found");
1507             break;
1508          }
1509          # ok -- there are some contacts for the user; forward
1510          # the incoming request to all of them
1511          t_relay();
1512     };
1513 };
1514                     </programlisting>
1515                 </example>
1516             </para>
1517             <para>
1518                 Note that we used the action for stateful forwarding, 
1519                 <command moreinfo="none">t_relay</command>. That's is because
1520                 stateful forwarding allows to fork an incoming request to
1521                 multiple destinations. If we used stateful forwarding,
1522                 the request would be forwarded only to one uri out of
1523                 all user's contacts.
1524             </para>
1525         </section> <!-- User Location -->
1526         
1527         <section>
1528             <title>External Modules</title>
1529             <para>
1530                 <application moreinfo="none">ser</application> provides the ability to link the server with external
1531                 third-party shared libraries. Lot of functionality which is
1532                 included in the <application moreinfo="none">ser</application> distribution is actually located in
1533                 modules to keep the server "core" compact and clean.
1534                 Among others, there are modules for checking max_forwards
1535                 value in SIP requests (maxfwd), transactional processing (tm),
1536                 record routing (rr), accounting (acc), authentication (auth),
1537                 SMS gateway (sms), replying requests (sl), user location
1538                 (usrloc, registrar) and more.
1539             </para>
1540             <para>
1541                 In order to utilize new actions exported by a module, 
1542                 ser must first load it. To load a module, the directive
1543                 <command moreinfo="none">loadmodule "filename"</command>
1544                 must be included in beginning of
1545                 a <application>ser</application> script file.
1546             </para>
1547
1548             <example>
1549                 <title>Using Modules</title>
1550                 <para>
1551                     This example shows how a script instructs 
1552                     <application moreinfo="none">ser</application> to
1553                     load a module and use actions exported by it.
1554                     Particularly, the sl module exports an action
1555                     <command>sl_send_reply</command> which makes 
1556                     <application>ser</application> act as a stateless
1557                     user agent and reply all incoming requests with 404.
1558                 </para>
1559                 <programlisting format="linespecific">
1560 # first of all, load the module!
1561 loadmodule "/usr/lib/ser/modules/sl.so
1562 route{
1563     # reply all requests with 404
1564     sl_send_reply("404", "I am so sorry -- user not found");
1565 }
1566 </programlisting>
1567             </example>
1568             <note>
1569                 <para>Note that unlike with core commands, all actions
1570                     exported by modules must have parameters enclosed
1571                     in quotation marks in current version of 
1572                     <application moreinfo="none">ser</application>.
1573                     In the following example, the built-in action
1574                     <command moreinfo="none">forward</command> for
1575                     stateless forwarding takes
1576                     IP address and port numbers as parameters without
1577                     quotation marks whereas a module action 
1578                     <command moreinfo="none">t_relay</command> for
1579                     stateful forwarding takes parameters enclosed in
1580                     quotation marks.
1581                     <example>
1582                         <title>Parameters in built-in and exported
1583                         actions</title>
1584                         <programlisting format="linespecific">
1585 # built-in action doesn't enclose IP addresses and port numbers
1586 # in quotation marks
1587 forward(192.168.99.100, 5060);
1588 # module-exported functions enclose all parameters in quotation
1589 # marks
1590 t_relay_to("192.168.99.100", "5060");
1591                         </programlisting>
1592                     </example>
1593                 </para>
1594             </note>
1595             <para>
1596                 Many modules also allow users to change the way how they
1597                 work using predefined parameters. For example, the
1598                 authentication module needs to know location of MySQL
1599                 database which contains users' security credentials.
1600                 How module parameters
1601                 are set using the <command moreinfo="none">modparam</command>
1602                 directive is shown in <xref linkend="moduleparameters">. 
1603                 <command moreinfo="none">modparam</command>
1604                 always contains identification of module, parameter
1605                 name and parameter value. Description of parameters
1606                 available in modules is available in module documentation.
1607             </para>
1608             <para>
1609                 Yet another thing to notice in this example is module
1610                 dependency. Modules may depend on each other. For example,
1611                 the authentication modules leverages the mysql module
1612                 for accessing mysql databases and sl module for generating
1613                 authentication challenges. We recommend that modules are
1614                 loaded in dependency order to avoid ambiguous server
1615                 behaviour.
1616             </para>         
1617             <para>
1618                 <example id="moduleparameters">
1619                     <title>Module Parameters</title>
1620                     <programlisting format="linespecific">
1621 # ------------------ module loading ----------------------------------
1622
1623 # load first modules on which 'auth' module depends;
1624 # sl is used for sending challenges, mysql for storage
1625 # of user credentials
1626 loadmodule "modules/sl/sl.so"
1627 loadmodule "modules/mysql/mysql.so"
1628 loadmodule "modules/auth/auth.so"
1629
1630 # ------------------ module parameters -------------------------------
1631 # tell the auth module the access data for SQL database:
1632 # username, password, hostname and database name
1633 modparam("auth", "db_url","sql://ser:secret@dbhost/ser")
1634
1635
1636 # -------------------------  request routing logic -------------------
1637
1638 # authenticate all requests prior to forwarding them
1639
1640 route{
1641
1642         if (!proxy_authorize("foo.bar" /* realm */,
1643                         "subscriber" /* table name */ )) {
1644                 proxy_challenge("foo.bar", "0");
1645                 break;
1646         };
1647         forward(192.168.0.10,5060);
1648 }
1649
1650                     </programlisting>
1651                 </example>
1652             </para>
1653         </section>
1654
1655         <section>
1656             <title>Writing Scripts</title>
1657             <para>
1658                 This section demonstrates simple examples
1659                 how to configure server's behaviour using the
1660                 <application moreinfo="none">ser</application>
1661                 request routing language. All scripts follow the 
1662                 <application moreinfo="none">ser</application> language 
1663                 syntax, which dictates the following block ordering:
1664                 <itemizedlist>
1665                     <listitem>
1666                         <para>
1667                             <emphasis>global configuration parameters</emphasis> --
1668                             these value affect behaviour of the server such as port
1669                             number at which it listens, number of spawned children
1670                             processes, and log-level. See <xref linkend="coreoptions">
1671                             for a list of available options.
1672                         </para>
1673                     </listitem>
1674
1675                     <listitem>
1676                         <para>
1677                             <emphasis>module loading</emphasis> -- these statements
1678                             link external modules, such as transaction management
1679                             (tm) or stateless UA server (sl)  dynamically. See
1680                             <xref linkend="modulereference"> for a list of modules
1681                             included in <application moreinfo="none">ser</application>
1682                             distribution.
1683                         </para>
1684                         <note>
1685                                 <para>
1686                                         If modules depend on each other, than the depending
1687                                         modules must be loaded after modules on which they
1688                                         depend. We recommend to load first modules
1689                                         <command>tm</command> and <command>sl</command>
1690                                         because many other modules (authentication, user
1691                                         location, accounting, etc.) depend on these.
1692                                 </para>
1693                         </note>
1694                     </listitem>
1695                     <listitem>
1696                         <para>
1697                             <emphasis>module-specific parameters</emphasis> -- determine
1698                             how modules behave; for example, it is possible to configure
1699                             database to be used by authentication module.
1700                         </para>
1701                     </listitem>
1702                     <listitem>
1703                         <para>
1704                             one or more <emphasis>route blocks</emphasis> containing the
1705                             request processing logic, which includes built-in actions
1706                             as well as actions exported by modules. See <xref linkend="builtinref">
1707                             for a list of built-in actions.
1708                         </para>
1709                     </listitem>
1710                     <listitem>
1711                         <para>
1712                             optionally, if modules supporting reply
1713                             processing (currently only TM) are loaded,
1714                             one or more <emphasis>reply_route blocks</emphasis> containing
1715                             logic triggered by received replies. Restrictions on use of
1716                             actions within <command moreinfo="none">reply_route</command>
1717                             blocks apply -- see <xref linkend="builtinref"> for more
1718                             information.
1719                         </para>
1720                     </listitem>
1721                 </itemizedlist>
1722             </para>
1723
1724             <para>
1725                 For more complex examples, see the etc directory in
1726                 <application>ser</application> source distribution.
1727                 It contains the 
1728                 <filename moreinfo="none">iptel.cfg</filename> script which is
1729                 in production use at iptel.org's public SIP site and exploits most of 
1730                 <application>ser</application> features.
1731             </para>
1732
1733             <section id="defaultscript">
1734                 <title>Default Configuration Script</title>             
1735                 <para>
1736                     The configuration script, <filename moreinfo="none">ser.cfg</filename>,
1737                     is a part of every <application moreinfo="none">ser</application>
1738                     distribution and defines default behaviour. It allows users
1739                     to register with the server and have requests proxied to each
1740                     other.
1741                 </para>
1742                 <para>
1743                     After performing
1744                     routine checks, the script looks whether incoming request is for
1745                     served domain. If so and the request is "REGISTER", <application moreinfo="none">ser</application>
1746                     acts as SIP registrar and updates database of user's contacts.
1747                     Optionally, it verifies user's identity first to avoid
1748                     unauthorized contact manipulation.
1749                 </para>
1750                 <para>
1751                     Non-REGISTER request for served domains are then processed using
1752                     user location database. If a contact is found for requested URI,
1753                     script execution proceeds to stateful forwarding, a negative 404
1754                     reply is generated otherwise. Requests outside served domain
1755                     are always statefully forwarded.
1756                 </para>
1757                 <para>
1758                     Note that this simple script features several limitations:
1759                     <itemizedlist>
1760                         <listitem>                          
1761                             <para>
1762                                 By default, authentication is turned off to avoid
1763                                 dependency on mysql. Unless it it turned on, anyone
1764                                 can register using any name and "steal" someone else's
1765                                 calls.
1766                             </para>
1767                         </listitem>
1768                         <listitem>
1769                             <para>
1770                                 Even it authentication is turned on, there is no relationship
1771                                 between authentication username and address of record. That
1772                                 means that for example a user authenticating himself correctly
1773                                 with "john.doe" id may register contacts for "gw.bush".
1774                                 Site policy may wish to mandate authentication id to be equal
1775                                 to username claimed in To header field. <action moreinfo="none">check_to</action>
1776                                 action from auth module can be used to enforce such a policy.
1777                             </para>
1778                         </listitem>
1779                         <listitem>
1780                             <para>
1781                                 There is no dialing plan implemented. All users are supposed to
1782                                 be reachable via user location database. See <xref linkend="numberingplans">
1783                                 for more information.
1784                             </para>
1785                         </listitem>
1786                         <listitem>
1787                             <para>
1788                                 The script assumes users will be using server's name as a part of
1789                                 their address of record. If users wish to use another name (domain
1790                                 name for example), this must be set using the <varname>alias</varname>
1791                                 options. See <xref linkend="domainmatching"> for more information.
1792                             </para>
1793                         </listitem>
1794                         <listitem>
1795                             <para>
1796                                 If authentication is turned on by uncommenting related configuration
1797                                 options, clear-text user passwords will by assumed in back-end database.
1798                             </para>
1799                         </listitem>
1800                     </itemizedlist>
1801                 </para>
1802                 <example>
1803                     <title>Default Configuration Script</title>
1804                     <programlisting format="linespecific">
1805 &defscr;                        
1806                     </programlisting>
1807                 </example>
1808             </section>
1809
1810             <section id="statefulua">
1811                 <title>Stateful User Agent Server</title>
1812                 <para>
1813                     This examples shows how to make ser act as a stateful user
1814                     agent (UA). Ability to act as as a stateful UA is essential
1815                     to many applications which terminate a SIP path. These
1816                     applications wish to focus on their added value. They
1817                     do not wish to be involved in all SIP gory details, such
1818                     as request and reply retransmission, reply formatting, etc.
1819                     For example, we use the UA functionality to shield 
1820                     SMS gateway and instant message store from SIP transactional
1821                     processing.
1822                     The simple example bellow issues a log report on receipt
1823                     of a new transaction. 
1824                     If we did not use a stateful UA, every single request retransmission
1825                     would cause the application to be re-executed which would result in
1826                     duplicated SMS messages, instant message in message store or 
1827                     log reports.
1828                 </para>
1829                 <para>
1830                     The most important actions are <command moreinfo="none">
1831                         t_newtran</command> and <command moreinfo="none">
1832                         t_reply</command>. <command moreinfo="none">
1833                         
1834                     t_newtran</command> shields subsequent code from retransmissions.
1835                     It returns success and continues when a new request arrived.
1836                     It exits current route block immediately on receipt of
1837                     a retransmissions. It only returns a negative value when
1838                     a serious error, such as lack of memory, occurs.
1839                 </para>
1840                 <para>
1841                     <command moreinfo="none">t_reply</command> generates
1842                     a reply for a request. It generates the reply statefully,
1843                     i.e., it is kept for future retransmissions in memory.
1844                 </para>
1845                 <note>
1846                         <para>
1847                                 Applications that do not need stateful processing
1848                                 may act as stateless UA Server too. They just use
1849                                 the <command>sl_send_reply</command> action to
1850                                 send replies to requests without keeping any
1851                                 state. The benefit is memory cannot run out,
1852                                 the drawback is that each retransmission needs to
1853                                 be processed as a new request. An example of use
1854                                 of a stateless server is shown in
1855                         <xref linkend="redirectserver"> and
1856                         <xref linkend="executingscript">.
1857                         </para>
1858                 </note>
1859                 <example>
1860                     <title>Stateful UA Server</title>
1861                     <programlisting format="linespecific">
1862                         <!-- ../../examples/uas.cfg -->
1863                         &statefuluaexample;
1864                     </programlisting>
1865                 </example>
1866             </section> <!-- Stateful UAS -->
1867
1868             <section id="redirectserver">
1869                 <title>Redirect Server</title>
1870                 <para>
1871                     The redirect example shows how to redirect a request
1872                     to multiple destination using 3xx reply. Redirecting
1873                     requests as opposed to proxying them is essential to
1874                     various scalability scenarios. Once a message is
1875                     redirected, <application moreinfo="none">ser</application>
1876                     discards all related state and is no more involved
1877                     in subsequent SIP transactions (unless the redirection
1878                     addresses point to the same server again).
1879                 </para>
1880                 <para>
1881                     The key <application>ser</application> actions in this example 
1882                     are <command moreinfo="none">append_branch</command> and 
1883                     <command moreinfo="none">sl_send_reply</command> (sl module).
1884                 </para>
1885                 <para>
1886                     <command moreinfo="none">append_branch</command> adds
1887                     a new item to the destination set. The destinations set always
1888                     includes the current URI and may be enhanced up to
1889                     <constant>MAX_BRANCHES</constant> items.
1890                     <command moreinfo="none">sl_send_reply</command> command, 
1891                     if passed SIP reply code 3xx, takes all values in current 
1892                     destination set and adds them to Contact header field in 
1893                     the reply being  sent.
1894                 </para>
1895                 <example id="redirectexample">
1896                     <title>Redirect Server</title>
1897                     <programlisting format="linespecific">
1898                         <!-- ../../examples/redirect.cfg -->
1899                         &redirectexample;
1900                     </programlisting>
1901                 </example>
1902             </section> <!-- redirect server-->
1903             
1904             <section id="executingscript">
1905                 <title>Executing External Script</title>
1906                 <para>
1907                     Like in the previous example, we show how to
1908                     make ser act as a redirect server. The difference is 
1909                     that we do not use redirection addresses hardwired in
1910                     <application moreinfo="none">ser</application> script but
1911                     get them from external shell commands. We also use
1912                     ser's ability to execute shell commands to log
1913                     source IP address of incoming SIP requests.
1914                 </para>
1915                 <para>
1916                     The new commands introduced in this example are
1917                     <command moreinfo="none">exec_msg</command> and
1918                     <command moreinfo="none">exec_uri</command>.
1919                     <command moreinfo="none">exec_msg</command> takes
1920                     current requests, starts an external command, and
1921                     passes the requests to the command's standard input.
1922                     It also passes request's source IP address in
1923                     environment variable named <constant>SRC_IP</constant>.
1924                 </para>
1925                 <para>
1926                     <command moreinfo="none">exec_uri</command> serves
1927                     for URI rewriting by external applications.  The
1928                     <command moreinfo="none">exec_uri</command> action
1929                     passes current URI to the called external program as
1930                     command-line parameter, and rewrites current destination
1931                     set with the program's output. An example use would
1932                     be an implementation of a Least-Cost-Router, software which
1933                     returns URI of the cheapest PSTN provider for a given
1934                     destination based on some pricing tables. <xref linkend="execscript">
1935                     is much easier: it prints fixed URIs on its output using
1936                     shell script <command moreinfo="none">echo</command> command.
1937                 </para>
1938                 <note>
1939                         <para>
1940                                 This script works statelessly -- it uses this action for
1941                                 stateless replying, <command>sl_send_reply</command>.
1942                                 No transaction is kept in memory and each request retransmission
1943                                 is processed as a brand-new request. That may be a particular
1944                                 concern if the server logic (<command>exec</command> actions
1945                                 in this example) is too expensive. See 
1946                         <xref linkend="statefulua"> for instructions on how
1947                                 to make server logic stateful, so that retransmissions
1948                                 are absorbed and do not cause re-execution of the logic.
1949                         
1950                         </para>
1951                 </note>
1952                 <example id="execscript">
1953                     <title>Executing External Script</title>
1954                     <programlisting format="linespecific">
1955                         <!-- ../../examples/exec.cfg -->
1956                         &execexample;
1957                     </programlisting>
1958                 </example>
1959             </section> <!-- exec example -->
1960             
1961             <section id="replyprocessingsection">
1962                 <title>On-Reply Processing (Forward on Unavailable)</title>
1963                 <para>
1964                     Many services depend on status of messages relayed
1965                     downstream: <emphasis>forward on busy</emphasis> and 
1966                     <emphasis>forward on no reply</emphasis> to name the
1967                     most well-known ones. To support implementation of
1968                     such services, <application moreinfo="none">ser</application>
1969                     allows to return to request processing when request
1970                     forwarding failed. When a request is reprocessed,
1971                     new request branches may be initiated or the transaction
1972                     can be completed at discretion of script writer.
1973                 </para>
1974                 <para>
1975                     The primitives used are <command moreinfo="none">t_on_negative(r)</command>
1976                     and <command moreinfo="none">reply_route[r]{}.</command> If
1977                     <command>t_on_negative</command> is called before
1978                     a request is statefuly forwarded and a forwarding failure occurs, 
1979                     <application moreinfo="none">ser</application>
1980                     will return to request processing in a <command moreinfo="none">reply_route</command>
1981                     block. Failures include receipt of a SIP error
1982                     (status code >= 300 ) from upstream or not receiving
1983                     any final reply within final response period.
1984                 </para>
1985                 <para>
1986                     The length of the timer is governed by parameters of the
1987                     tm module. <varname>fr_timer</varname> is the length of
1988                     timer set for non-INVITE transactions and INVITE transactions
1989                     for which no provisional response is received. If a timer
1990                     hits, it indicates that a downstream server is unresponsive.
1991                     <varname>fr_inv_timer</varname> governs time to wait for 
1992                     a final reply for an INVITE. It is typically longer than
1993                     <varname>fr_timer</varname> because final reply may take
1994                     long time until callee (finds a mobile phone in a pocket and)
1995                     answers the call.
1996                 </para>
1997                 <para>
1998                     In <xref linkend="replyprocessing">, <command moreinfo="none">reply_route[1]</command>
1999                     is set to be entered on error using the <command moreinfo="none">t_on_negative(1)</command>
2000                     action. Within this reply block, <application moreinfo="none">ser</application>
2001                     is instructed to initiate a new branch and try to reach called party
2002                     at another destination (sip:nonsense@iptel.org). To deal with the case when neither the alternate
2003                     destination succeeds, <application moreinfo="none">t_on_negative</application>
2004                     is set again. If the case really occurs, <command moreinfo="none">reply_route[2]</command>
2005                     is entered and a last resort destination (sip:foo@iptel.org) is tried.
2006                 </para>
2007                 <example id="replyprocessing">
2008                     <title>On-Reply Processing</title>
2009                     <programlisting format="linespecific">
2010                         <!-- ../../examples/onr.cfg -->
2011                         &replyexample;
2012                     </programlisting>
2013
2014                 </example>
2015             </section> <!-- reply processing -->
2016         </section> <!-- examples -->
2017     </chapter>
2018
2019
2020     <chapter>
2021         <title>Server Operation</title>
2022         <section id="operationalpractices">
2023             <title>Recommended Operational Practices</title>
2024
2025             <para>
2026                 Operation of a SIP server is not always easy task.
2027                 Server administrators are challenged by broken or
2028                 misconfigured user agents, network and host failures,
2029                 hostile attacks and other stress-makers. All such
2030                 situations may lead to an operational failure. It is sometimes
2031                 very difficult to figure out the root reason of
2032                 a failure, particularly in a distributed environment
2033                 with many SIP components involved.              
2034                 In this section,
2035                 we share some of our practices and refer to tools
2036                 which have proven to
2037                 make life of administrators easier
2038             </para>
2039
2040         <qandaset>
2041             <qandaentry>
2042                 <question>
2043                     <para>
2044                         Keeping track of messages is good
2045                     </para>
2046                 </question>
2047                 <answer>
2048                         <para>
2049                             Frequently, operational errors are discovered or reported
2050                             with a delay.
2051                             Users frustrated by an error
2052                             frequently approach administrators
2053                             and scream "even though my SIP requests were absolutely ok
2054                             yesterday, they were mistakenly denied by your server".
2055                             If administrators do not record all SIP traffic at
2056                             their site, they will be no more able to identify
2057                             the problem reason.
2058                             We thus recommend that site
2059                             operators record all messages passing their site and keep them
2060                             stored for some period of time.
2061                         They may use utilities such as 
2062                         <application>ngrep 
2063                         </application> or 
2064                         <application>tcpdump
2065                         </application>.
2066                         There is also a utility <application moreinfo="none">
2067                             scripts/harv_ser.sh</application> in <application moreinfo="none">
2068                         ser</application> distribution for post-processing
2069                         of captured messages. It summarizes messages captured
2070                         by reply status and user-agent header field.
2071                     </para>
2072                 </answer>
2073             </qandaentry>
2074             <qandaentry>
2075                 <question>
2076                     <para>
2077                         Real-time Traffic Watching
2078                     </para>
2079                 </question>
2080                 <answer>
2081                         <para>
2082                     Looking at SIP messages in real-time may help to gain
2083                     understanding of problems. Though there are commercial
2084                     tools available, using a simple, text-oriented tool
2085                     such as <application>ngrep</application> makes the job very well thanks to SIP's textual nature.
2086                         </para>
2087                     <example id="usingngrep">
2088                         <title>Using <application>ngrep</application>
2089                         </title>
2090                         <para>In this example, all messages at port 5060
2091                         which include the string "bkraegelin" are captured
2092                         and displayed</para>
2093                         <programlisting format="linespecific">
2094 [jiri@fox s]$ ngrep bkraegelin@ port 5060
2095 interface: eth0 (195.37.77.96/255.255.255.240)
2096 filter: ip and ( port 5060 )
2097 match: bkraegelin@
2098 #
2099 U +0.000000 153.96.14.162:50240 -> 195.37.77.101:5060
2100 REGISTER sip:iptel.org SIP/2.0.
2101 Via: SIP/2.0/UDP 153.96.14.162:5060.
2102 From: sip:bkraegelin@iptel.org.
2103 To: sip:bkraegelin@iptel.org.
2104 Call-ID: 0009b7aa-1249b554-6407d246-72d2450a@153.96.14.162.
2105 Date: Thu, 26 Sep 2002 22:03:55 GMT.
2106 CSeq: 101 REGISTER.
2107 Expires: 10.
2108 Content-Length: 0.
2109 .
2110
2111 #
2112 U +0.000406 195.37.77.101:5060 -> 153.96.14.162:5060
2113 SIP/2.0 401 Unauthorized.
2114 Via: SIP/2.0/UDP 153.96.14.162:5060.
2115 From: sip:bkraegelin@iptel.org.
2116 To: sip:bkraegelin@iptel.org.
2117 Call-ID: 0009b7aa-1249b554-6407d246-72d2450a@153.96.14.162.
2118 CSeq: 101 REGISTER.
2119 WWW-Authenticate: Digest realm="iptel.org", nonce="3d9385170000000043acbf6ba9c9741790e0c57adee73812", algorithm=MD5.
2120 Server: Sip EXpress router(0.8.8 (i386/linux)).
2121 Content-Length: 0.
2122 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".
2123
2124                         </programlisting>
2125                     </example>
2126                 </answer>
2127             </qandaentry>
2128             <qandaentry>
2129                 <question>
2130                     <para>
2131                         Tracing Errors in Server Chains
2132                     </para>
2133                 </question>
2134                 <answer>
2135                         <para>
2136                             A request may pass any number of proxy servers on
2137                             its path to its destination. If an error occurs
2138                             in the chain, it is difficult for upstream troubleshooters
2139                             and/or users complaining to administrators to learn 
2140                             more about error circumstances. 
2141                             <application moreinfo="none">ser
2142                             </application> does its best and displays extensive
2143                             diagnostics information in SIP replies. It allows 
2144                             troubleshooters and/or users who report to troubleshooters
2145                             to gain additional knowledge about request processing
2146                             status. 
2147                             This extended debugging information is part of the warning 
2148                             header field. See <xref linkend="usingngrep"> for an illustration
2149                             of a reply that includes such a warning header field. The header
2150                             field contains the following pieces of information:
2151                         <itemizedlist>
2152                             <listitem>
2153                                 <para>
2154                                 Server's IP Address -- good to identify
2155                                 from which server in a chain the reply
2156                                 came.
2157                                     </para>
2158                             </listitem>
2159                             <listitem>
2160                                     <para>
2161                                         Incoming and outgoing URIs -- good to
2162                                         learn for which URI the reply was
2163                                         generated, as it may be rewritten
2164                                         many times in the path. Particularly
2165                                         useful for debugging of numbering plans.
2166                                     </para>
2167                             </listitem>
2168                             <listitem>
2169                                 <para>
2170                                         Number of Via header fields in replied
2171                                         request -- that helps in assessment of
2172                                         request path length. Upstream clients would
2173                                         not know otherwise, how far away in terms
2174                                         of SIP hops their requests were replied.
2175                                 </para>
2176                             </listitem>
2177                                 <listitem>
2178                                     <para>
2179                                         Server's process id. That is useful for
2180                                         debugging to discover situations when
2181                                         mutliple servers listen at the same
2182                                         address.
2183                                     </para>
2184                                 </listitem>
2185                                 <listitem>
2186                                     <para>
2187                                         IP address of previous SIP hop as seen by
2188                                         the SIP server.
2189                                     </para>
2190                                 </listitem>
2191                         </itemizedlist>
2192                     </para>
2193                         <para>
2194                             If server administrator is not comfortable with
2195                             disclosing all this information, he can turn them
2196                             off using the <varname>sip_warning</varname> configuration
2197                             option.
2198                         </para>
2199                     <para>
2200                         A nice utility for debugging server chains is
2201                         <application moreinfo="none">sipsak</application>,
2202                         Swiss Army Knife, traceroute-like tool for SIP
2203                         developed at iptel.org. It allows you to send
2204                         OPTIONS request with low, increasing Max-Forwards 
2205                         header-fields and follow how it propagates in
2206                         SIP network. See its webpage at
2207                         <ulink url="http://sipsak.berlios.de/">
2208                             http://sipsak.berlios.de/
2209                         </ulink>.
2210                     </para>
2211                     <example>
2212                         <title>Use of SIPSak for Learning SIP Path</title>
2213                         <programlisting format="linespecific">
2214 [jiri@bat sipsak]$ ./sipsak -T -s sip:7271@iptel.org
2215 warning: IP extract from warning activated to be more informational
2216 0: 127.0.0.1 (0.456 ms) SIP/2.0 483 Too Many Hops
2217 1: ?? (31.657 ms) SIP/2.0 200 OK
2218         without Contact header
2219
2220                         </programlisting>
2221                         <para>
2222                             Note that in this example, the second hop
2223                             server does not issue any warning header fields
2224                             in replies and it is thus impossible to display 
2225                             its IP address in <application moreinfo="none">
2226                             SIPsak</application>'s output.
2227                         </para>
2228                     </example>
2229                 </answer>
2230             </qandaentry>
2231             <qandaentry>
2232                 <question>
2233                     <para>
2234                         Watching Server Health
2235                     </para>
2236                 </question>
2237                 <answer>
2238                     <para>
2239                         Watching Server's operation status in real-time may
2240                         also be a great aid for trouble-shooting. 
2241                         <application>ser</application> has an excellent 
2242                         facility, a FIFO server, which allows UNIX
2243                         tools to access server's internals. (It is 
2244                         similar to how Linux tool access Linux kernel
2245                         via the proc file system.) The FIFO server
2246                         accepts commands via a FIFO (named pipe) and
2247                         returns data asked for. Administrators do not
2248                         need to learn details of the FIFO communication
2249                         and can serve themselves using a front-end
2250                         utility <application moreinfo="none">serctl</application>.
2251                         Of particular interest for 
2252                         monitoring server's operation are 
2253                         <application moreinfo="none">serctl</application>
2254                         commands
2255                         <command moreinfo="none">ps</command> and
2256                         <command moreinfo="none">moni</command>.
2257                         The former displays running 
2258                         <application moreinfo="none">ser</application>
2259                         processes, whereas the latter shows statistics.
2260                     </para>
2261                     <example>
2262                         <title>serctl ps command</title>
2263                         <para>
2264                             This example shows 10 processes running at a host.
2265                             The process 0, "attendant" watches child processes
2266                             and terminates all of them if a failure occurs in
2267                             any of them. Processes 1-4 listen at local
2268                             interface and processes 5-8 listen at Ethernet
2269                             interface at port number 5060. Process number
2270                             9 runs FIFO server, and process number 10
2271                             processes all server timeouts.
2272                         </para>
2273                         <programlisting format="linespecific">
2274 [jiri@fox jiri]$ serctl ps
2275 0       31590   attendant
2276 1       31592   receiver child=0 sock=0 @ 127.0.0.1::5060
2277 2       31595   receiver child=1 sock=0 @ 127.0.0.1::5060
2278 3       31596   receiver child=2 sock=0 @ 127.0.0.1::5060
2279 4       31597   receiver child=3 sock=0 @ 127.0.0.1::5060
2280 5       31604   receiver child=0 sock=1 @ 195.37.77.101::5060
2281 6       31605   receiver child=1 sock=1 @ 195.37.77.101::5060
2282 7       31606   receiver child=2 sock=1 @ 195.37.77.101::5060
2283 8       31610   receiver child=3 sock=1 @ 195.37.77.101::5060
2284 9       31611   fifo server
2285 10      31627   timer
2286                           
2287                         </programlisting>
2288                     </example>
2289                 </answer>
2290             </qandaentry>
2291             <qandaentry>
2292                 <question>
2293                     <para>
2294                         Is Server Alive
2295                     </para>
2296                 </question>
2297                 <answer>
2298                     <para>
2299                         It is essential for solid operation to know
2300                         continuously that server is alive. We've been
2301                         using two tools for this purpose. 
2302                         <application moreinfo="none">sipsak</application>
2303                         does a great job of "pinging" a server, which
2304                         may be used for alerting on unresponsive servers.
2305                     </para>
2306                     <para>
2307                         <application moreinfo="none">monit</application> is
2308                         a server watching utility which alerts when
2309                         a server dies.
2310                     </para>
2311                 </answer>
2312             </qandaentry>
2313             <qandaentry>
2314                 <question>
2315                     <para>
2316                         Dealing with DNS
2317                     </para>
2318                 </question>
2319                 <answer>
2320                     <para>
2321                         SIP standard leverages DNS. Administrators of
2322                         <application moreinfo="none">ser</application> should
2323                         be aware of impact of DNS on server's operation.
2324                         Server's attempt to resolve an unresolvable address
2325                         may block a server process in terms of seconds. To be
2326                         safer that the server doesn't stop responding
2327                         due to being blocked by DNS resolving, we recommend
2328                         the following practices:
2329                         <itemizedlist>
2330                             <listitem>
2331                                 <para>
2332                                     Start a sufficient number of children processes.
2333                                     If one is blocked, the other children will
2334                                     keep serving.
2335                                 </para>
2336                             </listitem>
2337                             <listitem>
2338                                 <para>
2339                                     Use DNS caching. For example, in Linux,
2340                                     there is an <application moreinfo="none">
2341                                     nscd</application> daemon available for
2342                                     this purpose.
2343                                 </para>
2344                             </listitem>
2345                             <listitem>
2346                                 <para>
2347                                     Process transactions statefully if memory
2348                                     allows. That helps to absorb retransmissions
2349                                     without having to resolve DNS for each of
2350                                     them.
2351                                 </para>
2352                             </listitem>
2353                         </itemizedlist>
2354                     </para>
2355                 </answer>
2356             </qandaentry>
2357                 <qandaentry>
2358                         <question>
2359                                 <para>
2360                                         Logging
2361                                 </para>
2362                         </question>
2363                         <answer>
2364                         <anchor id="logging">
2365                         <para>
2366                             <application>ser</application> by default logs
2367                             to <application>syslog</application> facility.
2368                             It is very useful to watch log messages for
2369                             abnormal behaviour. Log messages, subject to
2370                             <application>syslog</application> configuration
2371                             may be stored at different files, or even at remote
2372                             systems. A typical location of the log file is
2373                             <filename>/var/log/messages</filename>.
2374                         </para>
2375                         <note>
2376                             <para>
2377                                 One can also use other <application>syslogd</application>
2378                                 implementation. <application>metalog</application>
2379                                 (<ulink url="http://http://metalog.sourceforge.net//">
2380                                     http://metalog.sourceforge.net/
2381                                 </ulink>)
2382                                 features regular expression matching that enables
2383                                 to filter and group log messages.
2384                             </para>
2385                         </note>
2386                         <para>
2387                             For the purpose of debugging configuration scripts, one may
2388                             want to redirect log messages to console not to pollute
2389                             syslog files. To do so configure <application moreinfo="none">ser</application>
2390                             in the following way:
2391                             <itemizedlist>
2392                                 <listitem>
2393                                     <para>
2394                                         Attach ser to console by setting <varname>fork=no</varname>.
2395                                     </para>
2396                                 </listitem>
2397                                 <listitem>
2398                                     <para>
2399                                         Set explicitely at which address 
2400                                         <application moreinfo="none">ser</application>
2401                                         should be listening, e.g., <varname>listen=192.168.2.16</varname>.
2402                                     </para>
2403                                 </listitem>
2404                                 <listitem>
2405                                     <para>
2406                                         Redirect log messages to standard error by setting
2407                                         <varname>log_stderror=yes</varname>
2408                                     </para>
2409                                 </listitem>
2410                                 <listitem>
2411                                     <para>
2412                                         Set appropriately high log level. (Be sure that you redirected logging
2413                                         to standard output. Flooding system logs with many detailed messages
2414                                         would make the logs difficult to read and use.) You can set the global
2415                                         logging threshold value with the option <varname>debug=nr</varname>,
2416                                         where the higher <varname>nr</varname> the more detailed output.
2417                                         If you wish to set log level only for some script events, include
2418                                         the desired log level as the first parameter of the
2419                                         <command moreinfo="none">log</command> action in your script.
2420                                         The messages will be then printed if <command moreinfo="none">log</command>'s
2421                                         level is lower than the global threshold, i.e., the lower the more
2422                                         noisy output you get.
2423                                         <example>
2424                                             <title>Logging Script</title>
2425                                             <programlisting format="linespecific">
2426 &logging;
2427                                             </programlisting>
2428                                             <para>
2429                                                 The following SIP message causes then logging output as shown
2430                                                 bellow.
2431                                             </para>
2432                                             <programlisting format="linespecific">
2433 REGISTER sip:192.168.2.16 SIP/2.0
2434 Via: SIP/2.0/UDP 192.168.2.33:5060
2435 From: sip:113311@192.168.2.16
2436 To: sip:113311@192.168.2.16
2437 Call-ID: 00036bb9-0fd305e2-7daec266-212e5ec9@192.168.2.33
2438 Date: Thu, 27 Feb 2003 15:10:52 GMT
2439 CSeq: 101 REGISTER
2440 User-Agent: CSCO/4
2441 Contact: sip:113311@192.168.2.33:5060
2442 Content-Length: 0
2443 Expires: 600                                 
2444                                             </programlisting>
2445                                             <programlisting format="linespecific">
2446 [jiri@cat sip_router]$ ./ser -f examples/logging.cfg 
2447 Listening on 
2448               192.168.2.16 [192.168.2.16]::5060
2449 Aliases: cat.iptel.org:5060 cat:5060 
2450 WARNING: no fork mode 
2451  0(0) INFO: udp_init: SO_RCVBUF is initially 65535
2452  0(0) INFO: udp_init: SO_RCVBUF is finally 131070
2453  0(17379) REGISTER received
2454  0(17379) request for other domain received                                     
2455                                             </programlisting>
2456                                         </example>
2457                                     </para>
2458                                 </listitem>
2459                             </itemizedlist>
2460                         </para>
2461                         </answer>
2462                 </qandaentry>
2463             <qandaentry>
2464                 <question>
2465                     <para>
2466                         Labeling Outbound Requests
2467                     </para>
2468                 </question>
2469                 <answer>
2470                     <para>
2471                     Without knowing, which pieces of script code a relayed
2472                     request visited, trouble-shooting would be difficult.
2473                     Scripts typically apply different processing to
2474                     different routes such as to IP phones and PSTN
2475                     gateways. We thus recommend to label outgoing
2476                     requests with a label describing the type of processing
2477                     applied to the request.
2478                         </para>
2479                     <para>
2480                         Attaching "routing-history" hints to relayed
2481                         requests is as easy as using the 
2482                         <command moreinfo="none">append_hf</command>
2483                         action exported by textops module. The following
2484                         example shows how different labels are attached
2485                         to requests to which different routing logic
2486                         was applied.
2487                         <example>
2488                             <title>"Routing-history" labels</title>
2489                             <programlisting format="linespecific">
2490 # is the request for our domain?
2491 # if so, process it using UsrLoc and label it so.
2492 if (uri=~[@:\.]domain.foo") {
2493    if (!lookup("location")) {
2494     sl_send_reply("404", "Not Found");
2495     break;
2496    };
2497    # user found -- forward to him and label the request
2498    append_hf("P-hint: USRLOC\r\n");
2499 } else {
2500 # it is an outbound request to some other domain --
2501 # indicate it in the routing-history label
2502    append_hf("P-hint: OUTBOUND\r\n");
2503 };
2504 t_relay();
2505                             </programlisting>
2506                             <para>
2507                                 This is how such a labeled requests looks
2508                                 like. The last header field includes
2509                                 a label indicating the script processed
2510                                 the request as outbound.
2511                             </para>
2512                             <programlisting format="linespecific">
2513 #
2514 U 2002/09/26 02:03:09.807288 195.37.77.101:5060 -> 203.122.14.122:5060
2515 SUBSCRIBE sip:rajesh@203.122.14.122 SIP/2.0.
2516 Max-Forwards: 10.
2517 Via: SIP/2.0/UDP 195.37.77.101;branch=53.b44e9693.0.
2518 Via: SIP/2.0/UDP 203.122.14.115:16819.
2519 From: sip:rajeshacl@iptel.org;tag=5c7cecb3-cfa2-491d-a0eb-72195d4054c4.
2520 To: sip:rajesh@203.122.14.122.
2521 Call-ID: bd6c45b7-2777-4e7a-b1ae-11c9ac2c6a58@203.122.14.115.
2522 CSeq: 2 SUBSCRIBE.
2523 Contact: sip:203.122.14.115:16819.
2524 User-Agent: Windows RTC/1.0.
2525 Proxy-Authorization: Digest username="rajeshacl", realm="iptel.org", algorithm="MD5", uri="sip:rajesh@203.122.14.122", nonce="3d924fe900000000fd6227db9e565b73c465225d94b2a938", response="a855233f61d409a791f077cbe184d3e3".
2526 Expires: 1800.
2527 Content-Length: 0.
2528 P-hint: OUTBOUND.                           </programlisting>
2529                         </example>
2530                 </para>
2531                 </answer>
2532             </qandaentry>
2533         </qandaset>
2534         </section> <!-- operational practises -->
2535
2536         <section>
2537             <title>HOWTOs</title>
2538             <para>
2539                 This section is a "cookbook" for dealing with common tasks,
2540                 such as user management or controlling access
2541                 to PSTN gateways.
2542             </para>
2543             <section>
2544                 <title>User Management</title>
2545
2546                         <para>
2547                             There are two tasks related to management of SIP users:
2548                             maintaining user accounts and maintaining user contacts.
2549                             Both these jobs can be done using the 
2550                             <application moreinfo="none">serctl</application>
2551                             command-line tool. Also, the complimentary web
2552                             interface, <application moreinfo="none">serweb</application>,
2553                             can be used for this purpose as well.
2554                         </para>
2555                         <para>
2556                             If user authentication is turned on, which is a highly
2557                             advisable practice, user account must be created before
2558                             a user can log in. To create a new user account, call the
2559                             <command moreinfo="none">serctl add</command> utility
2560                             with username, password and email as parameters. It
2561                             is important that the environment <varname>SIP_DOMAIN</varname>
2562                             is set to your realm and matches realm values used in
2563                             your script. The realm value is used for calculation
2564                             of credentials stored in subscriber database, which are
2565                             bound permanently to this value.
2566                             <screen format="linespecific">
2567 [jiri@cat gen_ha1]$ export SIP_DOMAIN=foo.bar
2568 [jiri@cat gen_ha1]$ serctl add newuser secret newuser@foo.bar
2569 MySql Password: 
2570 new user added
2571                             </screen>
2572                         </para>
2573                         <para><application moreinfo="none">serctl</application> can
2574                             also change user's password or remove existing accounts
2575                             from system permanently.
2576                             <screen format="linespecific">
2577 [jiri@cat gen_ha1]$ serctl passwd newuser newpassword
2578 MySql Password: 
2579 password change succeeded
2580 [jiri@cat gen_ha1]$ serctl rm newuser                
2581 MySql Password: 
2582 user removed
2583                             </screen>
2584                         </para>
2585                         <para>
2586                             User contacts are typically automatically uploaded by SIP phones
2587                             to server during registration process and administrators do not
2588                             need to worry about them. However, users
2589                             may wish to append permanent contacts to PSTN gateways
2590                             or to locations in other administrative domains. 
2591                             To manipulate the contacts in such cases, use
2592                             <application moreinfo="none">serctl ul</application>
2593                             tool. Note that this is the only correct way
2594                             to update contacts -- direct changes to back-end
2595                             MySql database do not affect server's memory. Also note,
2596                             that if persistence is turned off (usrloc "db_mode"
2597                             parameter set to "0"), all contacts are gone on server
2598                             reboot. Make sure that persistence is enabled if you
2599                             add permanent contacts.
2600                         </para>
2601                         <para>
2602                             To add a new permanent contact for a user, call 
2603                             <application moreinfo="none">serctl ul add &lt;username&gt
2604                             &lt;contact&gt;</application>. To delete 
2605                             all user's contacts, call 
2606                             <application>serctl ul rm &lt;username&gt;</application>.
2607                             <application moreinfo="none">serctl ul show &lt;username&gt;</application>
2608                             prints all current user's contacts.
2609                             <screen format="linespecific">
2610 [jiri@cat gen_ha1]$ serctl ul add newuser sip:666@gateway.foo.bar
2611 sip:666@gateway.foo.bar
2612 200 Added to table
2613 ('newuser','sip:666@gateway.foo.bar') to 'location'
2614 [jiri@cat gen_ha1]$ serctl ul show newuser
2615 &lt;sip:666@gateway.foo.bar&gt;;q=1.00;expires=1073741812
2616 [jiri@cat gen_ha1]$ serctl ul rm newuser  
2617 200 user (location, newuser) deleted
2618 [jiri@cat gen_ha1]$ serctl ul show newuser
2619 404 Username newuser in table location not found
2620                             </screen>
2621                         </para>
2622             </section> <!-- user management -->
2623             <section>
2624                 <title>User Aliases</title>
2625
2626                         <para>
2627                             Frequently, it is desirable for a user to have multiple
2628                             addresses in a domain. For example, a user with username "john.doe" wants to be
2629                             reachable at a shorter address "john" or at a nummerical address
2630                             "12335", so that PSTN callers with digits-only key-pad can reach
2631    &nbs