- Spelling checked
[sip-router] / doc / seruser / reference.sgml
1     <chapter>
2         <title>Reference</title>
3         <section id="coreoptions">
4             <title>Core Options</title>
5             <para>Core options are located in beginning of configuration file and
6             affect behavior of the server.</para>
7             <itemizedlist>
8                 <listitem>
9                     <para>
10                         <varname>debug</varname> - Set log level, this is number between 0 and 9. Default 
11                         is 0.
12                         
13                     </para>
14                 </listitem>
15                 <listitem>
16                     <para>
17                         <varname>fork</varname> - If set to yes, the server will spawn children. If set to no, the main
18                         process will be processing all messages. Default is yes.
19                         <note>
20                             <para>
21                                 Disabling child spawning is useful mainly for
22                                 debugging. When <varname>fork</varname> is turned off,
23                                 some features are unavailable: 
24                                 there is no attendant process, no pid file is generated,
25                                 and server listens only at one address. Make sure you
26                                 are debugging the same interface at which 
27                                 <application moreinfo="none">ser</application> listens.
28                                 The easiest way to do so is to set the interface using
29                                 <varname>listen</varname> option explicitly.
30                                 </para>
31                         </note>
32                     </para>
33                 </listitem>
34                 <listitem>
35                     <para>
36                         <varname>log_stderror</varname> - If set to yes, the server will print its debugging 
37                         information to standard error output. If set to no, <command moreinfo="none">syslog</command> 
38                         will be used. Default is no (printing to syslog).
39                     </para>
40                 </listitem>
41                 <listitem>
42                     <para>
43                         <varname>listen</varname> - list of all IP addresses or hostnames SER should listen on.
44                         <note>
45                                 <para>
46                                         This parameter may repeat several times, then SER will
47                                         listen on all addresses. For example, the following
48                                         command-line options (equivalent to "listen" config
49                                         option) may be used: 
50                                         <command>
51                                                 ser -l foo  -l bar -p 5061 -l x -l y 
52                                         </command>
53                                         will listen on foo:5060, bar:5061 & x:5061 & y:5061
54
55                                 </para>
56                         </note>
57                     </para>
58                 </listitem>
59                 <listitem>
60                     <para>
61                         <varname>alias</varname> - Add IP addresses or hostnames to list of name aliases.
62                         All requests with hostname matching an alias will satisfy the condition 
63                         "uri==myself".
64                     </para>
65                 </listitem>
66                 <listitem>
67                     <para>
68                         <varname>dns</varname> - Uses dns to check if it is necessary to add a "received=" field to a via.
69                         Default is no.
70                     </para>
71                 </listitem>
72                 <listitem>
73                     <para>
74                         <varname>rev_dns</varname> - Same as dns but use reverse DNS. Default is no.
75                     </para>
76                 </listitem>
77                 <listitem>
78                     <para>
79                         <varname>port</varname> - Listens on the specified port (default 5060). It applies to the last 
80                         address specified in listen and to all the following that do not have a corresponding "port" option.
81                     </para>
82                 </listitem>
83                 <listitem>
84                     <para>
85                         <varname>maxbuffer</varname> - Maximum receive buffer size which will not be exceeded by 
86                         the auto-probing procedure even if the OS allows. Default value is MAX_RECV_BUFFER_SIZE,
87                         which is 256k.
88                     </para>
89                 </listitem>
90                 <listitem>
91                     <para>
92                         <varname>children</varname> - Specifies how many processes should be started
93                         for each transport protocol. 
94                     Running multiple children allows a server to 
95                         server multiple requests in parallel when request processing block (e.g., on DNS
96                         lookup). Note that <application>ser</application> typically spawns additional
97                         processes, such as timer process or FIFO server. If FIFO server is turned on,
98                         you can watch running processes using the <application moreinfo="none">serctl</application>
99                         utility.
100
101
102                     </para>
103                 </listitem>
104                 <listitem>
105                     <para>
106                         <varname>check_via</varname> - Turn on or off Via host checking when forwarding replies.
107                         Default is no.
108                     </para>
109                 </listitem>
110                 <listitem>
111                     <para>
112                         <varname>syn_branch</varname> - Shall the server use stateful synonym branches? It is faster but not 
113                         reboot-safe. Default is yes.
114                     </para>
115                 </listitem>
116                 <listitem>
117                     <para>
118                         <varname>memlog</varname> - Debugging level for final memory statistics report. Default is L_DBG --
119                         memory statistics are dumped only if <varname>debug</varname> is set high.
120                     </para>
121                 </listitem>
122                 <listitem>
123                     <para>
124                         <varname>sip_warning</varname> - Should replies include extensive warnings? By default yes,
125                         it is good for trouble-shooting.
126                     </para>
127                 </listitem>
128                 <listitem>
129                     <para>
130                         <varname>fifo</varname> - FIFO special file pathname, for example "/tmp/ser_fifo". Default is
131                         no filename -- no FIFO server is started then. We recommend to set it so that
132                         accompanying applications such as <application moreinfo="none">serweb</application> or
133                         <application moreinfo="none">serctl</application> can communicate with
134                         <application moreinfo="none">ser</application>.
135                     </para>
136                 </listitem>
137                 <listitem>
138                     <para>
139                         <varname>fifo_mode</varname> - Permissions of the FIFO special file.
140                     </para>
141                 </listitem>
142                 <listitem>
143                     <para>
144                         <varname>server_signature</varname> - Should locally-generated messages include server's signature?
145                         By default yes, it is good for trouble-shooting.
146                     </para>
147                 </listitem>
148                 <listitem>
149                     <para>
150                         <varname>reply_to_via</varname> - A hint to reply modules
151                         whether they should send reply
152                         to IP advertised in Via.
153                         Turned off by default, which means that replies are
154                         sent to IP address from which requests came from. 
155                     </para>
156                 </listitem>
157                 <listitem>
158                     <para>
159                         <varname>user | uid</varname> - uid to be used by the server. 
160                     </para>
161                 </listitem>
162                 <listitem>
163                     <para>
164                         <varname>group | gid</varname> - gid to be used by the server.
165                     </para>
166                 </listitem>
167                 <listitem>
168                     <para>
169                         <varname>mhomed</varname> -- enable calculation of 
170                         outbound interface; useful on multihomed servers,
171                         ser <link linkend="mhomed"></link>.
172                     </para>
173                 </listitem>
174                 <listitem>
175                     <para>
176                         <varname>loadmodule</varname> - Specifies a module to be loaded (for example "/usr/lib/ser/modules/tm.so")
177                     </para>
178                 </listitem>
179                 <listitem>
180                     <para>
181                         <varname>modparam</varname> - Module parameter configuration. The commands takes three parameters:
182                         <itemizedlist>
183                             <listitem>
184                                 <para>
185                                     <emphasis>module</emphasis> - Module in which the parameter resides.
186                                 </para>
187                             </listitem>
188                             <listitem>
189                                 <para>
190                                     <emphasis>parameter</emphasis> - Name of the parameter to be configured.
191                                 </para>
192                             </listitem>
193                             <listitem>
194                                 <para>
195                                     <emphasis>value</emphasis> - New value of the parameter.
196                                 </para>
197                             </listitem>
198                         </itemizedlist>
199                     </para>
200                 </listitem>
201             </itemizedlist>
202         </section>
203         <section id="builtinref">
204             <title>Core Commands</title>
205
206
207             <itemizedlist id="routeblocks">
208                 <title>Route Blocks and Process Control</title>
209                 <!--<para>
210                     Route block and process control keywords determine
211                     the order in which SIP requests are processed.
212                 </para>-->
213                 <listitem>
214                     <para>
215                         <command>route[number]{...}</command> - This marks a "route block" in configuration files.
216                         route blocks are basic building blocks of <application>ser</application> scripts. 
217                         Each route block contains a sequence of 
218                         <application>SER</application> actions enclosed in braces. Multiple route blocks
219                         can be included in a configuration file.
220                         When script execution begins on request receipt, 
221                         route block number 0 is entered. Other route blocks serve as a kind of sub-routines and 
222                         may be entered by calling the action <command>route(n)</command>, 
223                         where n is number of the block. The action <command>break</command>
224                         exits currently executed route block. It stops script execution for
225                         route block number 0 or returns to calling route block otherwise.
226                     </para>
227                     <example>
228                         <title>route</title>
229                         <programlisting format="linespecific">
230 route[0] {
231         # call routing block number 2
232         route(2);
233 }
234
235 route[2] {
236     forward("host.foo.bar", 5060);
237 }
238 </programlisting>
239                     </example>
240                 </listitem>
241                 <listitem>
242                     <para>
243                         <command>failure_route</command> is used to restart request processing
244                         when a negative reply for a previously relayed request is received. It is only
245                         used along with tm module, which stores the original requests and
246                         can return to their processing later. To activate processing
247                         of a <command>failure_route</command> block, call the TM action
248                         <command>t_on_failure(route_number)</command> before calling
249                         <command moreinfo="none">t_relay</command>. When a negative reply
250                         comes back, the desired <command moreinfo="none">failure_route</command>
251                         will be entered and processing of the original request may
252                         continue. 
253                         </para>
254                     <para>
255                         The set of actions applicable from within
256                         <command moreinfo="none">failure_route</command> blocks is limited.
257                         Permitted actions are URI-manipulation actions, logging and
258                         sending stateful replies using <command moreinfo="none">t_reply</command>.
259                     </para>
260                     <example>
261                         <title>failure_route</title>
262                         <programlisting format="linespecific">
263 failure_route[1] {
264     # for some reason, the original forwarding attempt
265     # failed, try at another URI
266     append_branch("sip:nonsense@iptel.org");
267     # if this new attempt fails too, try another failure_route
268     t_on_failure("2");
269         t_relay();
270 }
271 </programlisting>
272                     </example>
273                 </listitem>
274
275                 <listitem>
276                     <para>
277                         The action <command>break</command> exits currently executed route block. 
278                         It stops script execution for route block number 0 or returns to calling 
279                         route block otherwise.
280                         <note>
281                             <para>
282                                 We recommend to use <command moreinfo="none">break</command>
283                                 after any request forwarding or replying. This practice
284                                 helps to avoid erroneous scripts that 
285                                 continue execution and mistakenly send another reply or
286                                 forward a request to another place, resulting in
287                                 protocol confusion.
288                             </para>
289                         </note>
290                     </para>
291                     <para>
292                         <emphasis>Example:</emphasis> break;
293                     </para>
294                 </listitem>
295
296                 <listitem>
297                     <para>
298                         <command>route(n)</command> - call routing block route[n]{...};
299                         when the routing block n finishes processing, control is passed
300                         back to current block and processing continues.
301                     </para>
302                 </listitem>
303
304                 <listitem>
305                     <para>
306                         <command>if (condition) statement</command> - Conditional statement.
307                     </para>
308                     <example>
309                         <title>Use of <command>if</command></title>
310                         <programlisting format="linespecific">
311 if (method=="REGISTER) {
312     log("register received\n");
313 };
314 </programlisting>
315                     </example>
316                 </listitem>
317                 <listitem>
318                     <para>
319                         <command>if - else</command> - If-Else Conditional statement.
320                     </para>
321                     <example>
322                         <title>Use of <command>if-else</command></title>
323                         <programlisting format="linespecific">
324 if (method=="REGISTER) {
325     log("register received\n");
326 } else {
327     log("non-register received\n");
328 };
329 </programlisting>
330                     </example>
331                 </listitem>
332
333             </itemizedlist>
334             <itemizedlist>
335                 <title>Flag Manipulation</title>
336                 <listitem>
337                     <para>
338                         <command>setflag</command> - Set flag in the message.
339                     </para>
340                     <para>
341                         <emphasis>Example:</emphasis> setflag(1);
342                     </para>
343                 </listitem>
344                 <listitem>
345                     <para>
346                         <command>resetflag</command> - Reset flag in the message.
347                     </para>
348                     <para>
349                         <emphasis>Example:</emphasis> resetflag(1);
350                     </para>
351                 </listitem>
352                 <listitem>
353                     <para>
354                         <command>isflagset</command> - Test whether a particular flag is set.
355                     </para>
356                     <example>
357                         <title>isflagset</title>
358                         <programlisting format="linespecific">
359 if (isflagset(1)) {
360     ....
361 };
362 </programlisting>
363                     </example>
364                 </listitem>
365             </itemizedlist>
366             <itemizedlist>
367                 <title>Manipulation of URI and Destination Set</title>
368                 <listitem>
369                     <para>
370                         <command>rewritehost | sethost | seth</command> - Rewrite host part of the Request URI.
371                     </para>
372                     <para>
373                         <emphasis>Example:</emphasis> sethost("foo.bar.com");
374                     </para>
375                 </listitem>
376                 <listitem>
377                     <para>
378                         <command>rewritehostport | sethostport | sethp</command> - Rewrite host and port part of the Request URI.
379                     </para>
380                     <para>
381                         <emphasis>Example:</emphasis> sethostport("foo.bar.com:5060");
382                     </para>
383                 </listitem>
384                 <listitem>
385                     <para>
386                         <command>rewriteuser | setuser | setu</command> - Rewrite or set username part of the Request URI.
387                     </para>
388                     <para>
389                         <emphasis>Example:</emphasis> setuser("joe");
390                     </para>
391                 </listitem>
392                 <listitem>
393                     <para>
394                         <command>rewriteuserpass | setuserpass | setup</command> - Rewrite or set username and password part
395                         of the Request URI.
396                     </para>
397                     <para>
398                         <emphasis>Example:</emphasis> setuserpass("joe:mypass");
399                     </para>
400                 </listitem>
401                 <listitem>
402                     <para>
403                         <command>rewriteport | setport | setp</command> - Rewrite or set port of the Request URI.
404                     </para>
405                     <para>
406                         <emphasis>Example:</emphasis> setport("5060");
407                     </para>
408                 </listitem>
409                 <listitem>
410                     <para>
411                         <command>rewriteuri | seturi</command> - Rewrite or set the whole Request URI.
412                     </para>
413                     <para>
414                         <emphasis>Example:</emphasis> seturi("sip:joe@foo.bar.com:5060");
415                     </para>
416                 </listitem>
417                 <listitem>
418                     <para>
419                         <command>revert_uri</command> - Revert changes made to the Request URI and use original Request URI.
420                     </para>
421                     <para>
422                         <emphasis>Example:</emphasis> revert_uri();
423                     </para>
424                 </listitem>
425                 <listitem>
426                     <para>
427                         <command>prefix</command> - Add prefix to username in Request URI.
428                     </para>
429                     <para>
430                         <emphasis>Example:</emphasis> prefix("123");
431                     </para>
432                 </listitem>
433                 <listitem>
434                     <para>
435                         <command>strip</command> - Remove first n characters of username in Request URI.
436                     </para>
437                     <para>
438                         <emphasis>Example:</emphasis> strip(3);
439                     </para>
440                 </listitem>
441                 <listitem>
442                     <para>
443                         <command>append_branch</command> - Append a new destination to destination set of the message.
444                     </para>
445                     <para>
446                         <example>
447                             <title>Use of <command>append_branch</command></title>
448                             <programlisting format="linespecific">
449 # redirect to these two destinations: a@foo.bar and b@foo.bar
450 # 1) rewrite the current URI
451 rewriteuri("sip:a@foo.bar");
452 # 2) append another entry to the destination ser
453 append_branch("sip:b@foo.bar");
454 # redirect now
455 sl_send_reply("300", "redirection");
456                             </programlisting>
457                         </example>
458                     </para>
459                 </listitem>
460             </itemizedlist>
461             <itemizedlist>
462                 <title>Message Forwarding</title>
463                 <listitem>
464                     <para>
465                         <command>forward(uri, port)</command> - Forward the request to given 
466                         destination statelessly.  The uri and port parameters may take special 
467                         values 'uri:host'
468                         and 'uri:port' respectively, in which case SER forwards to destination
469                         set in current URI. All other elements in a destination set are
470                         ignored by stateless forwarding.
471                     </para>
472                     <para>
473                         <emphasis>Example:</emphasis> forward("foo.bar.com"); # port defaults to 5060
474                     </para>
475                 </listitem>
476                 <listitem>
477                     <para>
478                         <command>send</command> - Send the message as is to a third party 
479                     </para>
480                     <para>
481                         <emphasis>Example:</emphasis> send("foo.bar.com");
482                     </para>
483                 </listitem>
484             </itemizedlist>
485             <itemizedlist>
486                 <title>Logging</title>
487                 
488
489                 <listitem>
490                     
491                     <para>
492                         <command>log([level], message)</command> - Log a message.
493                     </para>
494                     <para>
495                         <emphasis>Example:</emphasis> log(1, "This is a message with high log-level set to 1\n");
496                     </para>
497                     <para>
498                         Logging is very useful for troubleshooting or attracting administrator's
499                         attention to unusual situations. <application moreinfo="none">ser</application>
500                         reports log messages to <application moreinfo="none">syslog</application>
501                         facility unless it is configured to print them to <filename moreinfo="none">stderr</filename>
502                         with the <varname>log_stderr</varname> configuration option. Log messages
503                         are only issued if their log level exceeds threshold set with the
504                         <varname>debug</varname> configuration option. If log level is omitted,
505                         messages are issued at log level 4.
506                 </para>
507                 </listitem>
508
509             </itemizedlist>
510
511
512
513
514             <itemizedlist>
515                 <title>Miscellaneous</title>
516                 <listitem>
517                     <para>
518                         <command>len_gt</command> - If length of the message is greater than value given as parameter, the
519                         command will return 1 (indicating true). Otherwise -1 (indicating false) will be returned. It may 
520                         take 'max_len' as parameter, in which case message size is limited
521                         to internal buffer size BUF_SIZE (3040 by default).
522                     </para>
523                     <example>
524                         <title>Use of <command>len_gt</command></title>
525                         <programlisting format="linespecific">
526 # deny all requests larger in size than 1 kilobyte
527 if (len_gt(1024)) {
528     sl_send_reply("513", "Too big");
529     break;
530 };
531                         </programlisting>
532                     </example>
533                 </listitem>
534             </itemizedlist>
535         </section>
536         <section>
537             <title>Command Line Parameters</title>
538             <note>
539                 <para>
540                     Command-Line parameters may be overridden by configuration
541                     file options which take precedence over them.
542                 </para>
543             </note>
544             <itemizedlist>
545                 <listitem>
546                     <para>
547                         <emphasis>-h</emphasis> - Displays a short usage description, including all available options.
548                     </para>
549                 </listitem>
550                 <listitem>
551                     <para>
552                         <emphasis>-c</emphasis> - Performs loop checks and computes branches.
553                     </para>
554                 </listitem>
555                 <listitem>
556                     <para>
557                         <emphasis>-r</emphasis> - Uses dns to check if it is necessary to add a "received=" field to a via.
558                     </para>
559                 </listitem>
560                 <listitem>
561                     <para>
562                         <emphasis>-R</emphasis> - Same as -r but uses reverse dns.
563                     </para>
564                 </listitem>
565                 <listitem>
566                     <para>
567                         <emphasis>-v</emphasis> - Turns on via host checking when forwarding replies.
568                     </para>
569                 </listitem>
570                 <listitem>
571                     <para>
572                         <emphasis>-d</emphasis> - Turns on debugging, multiple -d increase debugging level.
573                     </para>
574                 </listitem>
575                 <listitem>
576                     <para>
577                         <emphasis>-D</emphasis> - Runs ser in the foreground (it doesn't fork into daemon mode).
578                     </para>
579                 </listitem>
580                 <listitem>
581                     <para>
582                         <emphasis>-E</emphasis> - Sends all the log messages to stderr.
583                     </para>
584                 </listitem>
585                 <listitem>
586                     <para>
587                         <emphasis>-V</emphasis> - Displays the version number.
588                     </para>
589                 </listitem>
590                 <listitem>
591                     <para>
592                         <emphasis>-f config-file</emphasis> - Reads the configuration from "config-file" (default ./ser.cfg).
593                     </para>
594                 </listitem>
595                 <listitem>
596                     <para>
597                         <emphasis>-l address</emphasis> - Listens on the specified address. Multiple -l mean listening 
598                         on multiple addresses. The default behavior is to listen on all the ipv4 interfaces.
599                     </para>
600                 </listitem>
601                 <listitem>
602                     <para>
603                         <emphasis>-p port</emphasis> - Listens on the specified port (default 5060). It applies to the last 
604                         address specified with -l and to all the following that do not have a corresponding -p.
605                     </para>
606                 </listitem>
607                 <listitem>
608                     <para>
609                         <emphasis>-n processes-no</emphasis> - Specifies the number of children processes forked per 
610                         interface (default 8).
611                     </para>
612                 </listitem>
613                 <listitem>
614                     <para>
615                         <emphasis>-b max_rcv_buf_size</emphasis> - Maximum receive buffer size which will not be exceeded by 
616                         the auto-probing procedure even if the OS allows.
617                     </para>
618                 </listitem>
619                 <listitem>
620                     <para>
621                         <emphasis>-m shared_mem_size</emphasis> - Size of the shared memory which will be allocated (in Megabytes).
622                     </para>
623                 </listitem>
624                 <listitem>
625                     <para>
626                         <emphasis>-w working-dir</emphasis> - Specifies the working directory. In the very improbable event 
627                         that will crash, the core file will be generated here.
628                     </para>
629                 </listitem>
630                 <listitem>
631                     <para>
632                         <emphasis>-t chroot-dir</emphasis> - Forces ser to chroot after reading the config file.
633                     </para>
634                 </listitem>
635                 <listitem>
636                     <para>
637                         <emphasis>-u uid</emphasis> - Changes the user id under which ser runs.
638                     </para>
639                 </listitem>
640                 <listitem>
641                     <para>
642                         <emphasis>-g gid</emphasis> - Changes the group id under which ser runs.
643                     </para>
644                 </listitem>
645                 <listitem>
646                     <para>
647                         <emphasis>-P pid-file</emphasis> - Creates a file containing the pid of the main ser process.
648                     </para>
649                 </listitem>
650                 <listitem>
651                     <para>
652                         <emphasis>-i fifo-path</emphasis> - Creates a fifo, useful for monitoring ser status.
653                     </para>
654                 </listitem>
655             </itemizedlist>
656         </section>
657
658
659
660
661         <section id="modulereference">
662             <title>Modules</title>
663             <para>
664                 Module description is currently located in READMEs of
665                 respective module directories. <filename moreinfo="none">README-MODULES</filename>
666                 lists all available modules, including their maturity status.
667                 In the current <application moreinfo="none">ser</application>
668                 distribution, there are the following modules:
669                 <itemizedlist>
670                     <listitem>
671                         <para>
672                             <emphasis>
673                                 acc
674                             </emphasis>
675                             -- call accounting using <application moreinfo="none">syslog</application> facility.
676                                 RADIUS and mysql support can be compiled in.
677                             Depends on tm.
678                         </para>
679                     </listitem>
680                     <listitem>
681                         <para>
682                             <emphasis>
683                                 auth, auth_db, auth_radius
684                             </emphasis>
685                             -- digest authentication. Depends on sl and mysql.
686                         </para>
687                     </listitem>
688
689                         <listitem>
690                                 <para>
691                                         <emphasis>domain</emphasis> -- checks URIs whether they belong
692                                         in a list of served domains or not.
693                                 </para>
694                         </listitem>
695
696
697
698                         <listitem>
699                                 <para>
700                                         <emphasis>ENUM</emphasis> -- E.164 phone number resolution using ENUM.
701                                 </para>
702                         </listitem>
703
704
705                     <listitem>
706                         <para>
707                             <emphasis>
708                                 exec
709                             </emphasis>
710                             -- execution of shell programs.
711                         </para>
712                     </listitem>
713
714                     <listitem>
715                         <para>
716                             <emphasis>
717                                 group, group_radius
718                             </emphasis>
719                             -- checks membership of users in groups
720                         </para>
721                     </listitem>
722
723                     <listitem>
724                         <para>
725                             <emphasis>
726                                 jabber
727                             </emphasis> -- gateway between SIMPLE and Jabber instant messaging. Depends
728                             on tm and mysql.
729                         </para>
730                     </listitem>
731                     <listitem>
732                         <para>
733                             <emphasis>
734                                 maxfwd
735                             </emphasis>
736                             -- checking max-forwards header field.
737                         </para>
738                     </listitem>
739                     <listitem>
740                         <para>
741                             <emphasis>msilo</emphasis>
742
743                         -- message silo. Store for undelivered instant messages. Depends on tm and mysql.
744                             </para>
745                     </listitem>
746
747                     <listitem>
748                         <para>
749                             <emphasis>
750                                 mysql
751                             </emphasis>
752                             -- mysql database back-end.
753                             </para>
754                     </listitem>
755
756                     <listitem>
757                         <para>
758                             <emphasis>
759                                         nathelper       
760                             </emphasis>
761                             -- facilitates NAT traversal for symmetric SIP phones such as ATA.
762                             </para>
763                     </listitem>
764
765                     <listitem>
766                         <para>
767                             <emphasis>
768                                         pa
769                             </emphasis>
770                             -- presence agent
771                             </para>
772                     </listitem>
773
774                     <listitem>
775                         <para>
776                             <emphasis>
777                                 registrar, usrloc
778                             </emphasis>
779                             -- User Location database. Works in in-memory mode or with mysql persistence
780                             support. Depends on sl, and on mysql if configured for use with mysql.
781                         </para>
782                     </listitem>
783                     <listitem>
784                         <para>
785                             <emphasis>
786                                 rr
787                             </emphasis>
788                             -- Record Routing (strict and loose)
789                         </para>
790                     </listitem>
791                     <listitem>
792                         <para>
793                             <emphasis>
794                                 sl
795                             </emphasis>
796                             -- stateless User Agent server.
797                         </para>
798                     </listitem>
799                     <listitem>
800                         <para>
801                             <emphasis>
802                                 sms
803                             </emphasis>
804                             -- SIMPLE/SMS gateway. Depends on tm. Takes special hardware.
805                         </para>
806                     </listitem>
807                         <listitem>
808                         <para>
809                                 <emphasis>textops</emphasis> -- textual database back-end.
810                         </para>
811                         </listitem>
812                                 
813                     <listitem>                  
814                         <para>
815                             <emphasis>
816                                 tm
817                             </emphasis>
818                             -- transaction manager (stateful processing).
819                         </para>
820                     </listitem>
821
822                     <listitem>                  
823                         <para>
824                             <emphasis>
825                                 uri, uri_radius
826                             </emphasis>
827                             -- checks digest identity against header URIs or a database list
828                         </para>
829                     </listitem>
830
831                 </itemizedlist>
832             </para>
833             <para>
834                 The most frequently used actions exported by modules are summarized
835                 in <xref linkend="moduleactions">. For a full explanation of 
836                 module actions, see documentation in respective module directories
837                 in source distribution of <application moreinfo="none">ser</application>.
838             </para>
839             <table id="moduleactions">
840                 <title>Frequently Used Module Actions</title>
841                 <tgroup cols="4">
842                     <thead>
843                         <row>                       
844                             <entry>
845                                 Command
846                             </entry>
847                             <entry>
848                                 Modules
849                             </entry>
850                             <entry>
851                                 Parameters
852                             </entry>
853                             <entry>
854                                 Comments
855                             </entry>
856                         </row>
857                     </thead>
858
859                     <tbody>
860
861                         <row>
862                             <entry>
863                                 append_hf
864                             </entry>
865                             <entry>
866                                 textops
867                                 </entry>
868                             <entry>
869                                 header field
870                                 </entry>
871                             <entry>
872                                 append a header field to the end of request's header
873                                 </entry>
874                             </row>
875                         <row>
876                             <entry>
877                                 check_from
878                             </entry>
879                             <entry>
880                                 uri
881                             </entry>
882                             <entry>
883                                 none
884                             </entry>
885                             <entry>
886                                 check if username in from header field matches authentication id
887                             </entry>
888                         </row>
889                         <row>
890                             <entry>
891                                 check_to
892                             </entry>
893                             <entry>
894                                 uri
895                             </entry>
896                             <entry>
897                                 none
898                             </entry>
899                             <entry>
900                                 check if username in To header field matched authentication id
901                             </entry>
902                         </row>
903                         <row>
904                             <entry>
905                                 exec_dset
906                             </entry>
907                             <entry>
908                                 exec
909                             </entry>
910                             <entry>
911                                 command name
912                             </entry>
913                             <entry>
914                                 execute an external command and replace destination set with
915                                 its output
916                             </entry>
917                         </row>
918                         <row>
919                             <entry>
920                                 exec_msg
921                             </entry>
922                             <entry>
923                                 exec
924                             </entry>
925                             <entry>
926                                 command name
927                             </entry>
928                             <entry>
929                                 execute an external command and pass received SIP request
930                                 to its input
931                             </entry>
932                         </row>
933                         <row>
934                             <entry>
935                                 is_user
936                             </entry>
937                             <entry>
938                                 uri
939                             </entry>
940                             <entry>
941                                 user id
942                             </entry>
943                             <entry>
944                                 returns true if request credentials belong to a user
945                             </entry>
946                         </row>
947                         <row>
948                             <entry>
949                                 is_user_in
950                             </entry>
951                             <entry>
952                                 auth
953                             </entry>
954                             <entry>
955                                 user, group
956                             </entry>
957                             <entry>
958                                 check if user is member of a group; user can be gained
959                                 from request URI ("Request-URI"), To header field ("To"),
960                                 From header field ("From") or digest credentials
961                                 ("Credentials")
962                             </entry>
963                         </row>
964                         <row>
965                             <entry>
966                                 lookup
967                             </entry>
968                             <entry>
969                                 usrloc
970                             </entry>
971                             <entry>
972                                 table name
973                             </entry>
974                             <entry>
975                                 attempt to translate request URI using user location database;
976                                 returns false if no contact for user found;
977                             </entry>
978                         </row>
979                         <row>
980                             <entry>
981                                 loose_route
982                             </entry>
983                             <entry>
984                                 rr
985                             </entry>
986                             <entry>
987                                 none
988                             </entry>
989                             <entry>
990                                 process loose routes in requests
991                             </entry>
992                         </row>
993                         <row>
994                             <entry>
995                                 mf_process_maxfwd_header
996                             </entry>
997                             <entry>
998                                 maxfwd
999                             </entry>
1000                             <entry>
1001                                 default max_forwards value
1002                             </entry>
1003                             <entry>
1004                                 return true, if request's max_forwards value has not
1005                                 reached zero yet; if none is included in the request,
1006                                 set it to value in parameter
1007                             </entry>
1008                         </row>
1009                         <row>
1010                             <entry>
1011                                 proxy_authorize
1012                             </entry>
1013                             <entry>
1014                                 auth
1015                             </entry>
1016                             <entry>
1017                                 realm, subscriber table
1018                             </entry>
1019                             <entry>
1020                                 returns true if requests contains proper credentials, false
1021                                 otherwise
1022                             </entry>
1023                         </row>
1024
1025
1026
1027
1028
1029
1030                         <row>
1031                             <entry>
1032                                 proxy_challenge
1033                             </entry>
1034                             <entry>
1035                                 auth
1036                             </entry>
1037                             <entry>
1038                                 realm, qop
1039                             </entry>
1040                             <entry>
1041                                 challenge user to submit digest credentials; qop may be turned
1042                                 off for backwards compatibility with elderly implementations
1043                             </entry>
1044                         </row>
1045                         <row>
1046                             <entry>
1047                                 record_route
1048                             </entry>
1049                             <entry>
1050                                 rr
1051                             </entry>
1052                             <entry>
1053                                 none
1054                             </entry>
1055                             <entry>
1056                                 record-route a request
1057                             </entry>
1058                         </row>
1059                         <row>
1060                             <entry>
1061                                 replace
1062                             </entry>
1063                             <entry>
1064                                 textops
1065                             </entry>
1066                             <entry>
1067                                 RegExp, Substitute
1068                             </entry>
1069                             <entry>
1070                                 find the first occurrence of a string matching the regular 
1071                                 expression in header or body and replace it with a substitute
1072                             </entry>
1073                         </row>
1074                         <row>
1075                             <entry>
1076                                 replace_all
1077                             </entry>
1078                             <entry>
1079                                 textops
1080                             </entry>
1081                             <entry>
1082                                 RegExp, Substitute
1083                             </entry>
1084                             <entry>
1085                                 find all occurrences of a string matching the regular 
1086                                 expression in header or body and replace it with a substitute
1087                             </entry>
1088                         </row>
1089                         <row>
1090                             <entry>
1091                                 save
1092                             </entry>
1093                             <entry>
1094                                 usrloc
1095                             </entry>
1096                             <entry>
1097                                 table name
1098                             </entry>
1099                             <entry>
1100                                 for use in registrar: save content of Contact header fields
1101                                 in user location database and reply with 200
1102                             </entry>
1103                         </row>
1104                         <row>
1105                             <entry>
1106                                 search
1107                             </entry>
1108                             <entry>
1109                                 textops
1110                             </entry>
1111                             <entry>
1112                                 regular expression
1113                             </entry>
1114                             <entry>
1115                                 search for a regular expression match in request header of body
1116                             </entry>
1117                         </row>
1118
1119                         <row>
1120                             <entry>
1121                                 sl_send_reply
1122                             </entry>
1123                             <entry>
1124                                 sl
1125                             </entry>
1126                             <entry>
1127                                 status code, reason phrase
1128                             </entry>
1129                             <entry>
1130                                 reply a request statelessly
1131                             </entry>
1132                         </row>
1133
1134                         <row>
1135                             <entry>
1136                                 t_relay
1137                             </entry>
1138                             <entry>
1139                                 tm
1140                             </entry>
1141                             <entry>
1142                                 none
1143                             </entry>
1144                             <entry>
1145                                 stateful forwarding to locations in current destination set
1146                             </entry>
1147                         </row>
1148
1149                         <row>
1150                             <entry>
1151                                 t_on_failure
1152                             </entry>
1153                             <entry>
1154                                 tm
1155                             </entry>
1156                             <entry>
1157                                 failure_route number
1158                             </entry>
1159                             <entry>
1160                                 set failure_route block which shall be entered if stateful
1161                                 forwarding fails
1162                             </entry>
1163                         </row>
1164
1165                         <row>
1166                             <entry>
1167                                 t_replicate
1168                             </entry>
1169                             <entry>
1170                                 tm
1171                             </entry>
1172                             <entry>
1173                                 host, port number
1174                             </entry>
1175                             <entry>
1176                                 replicate a request to a destination
1177                             </entry>
1178                         </row>
1179
1180
1181                     </tbody>
1182                 </tgroup>
1183             </table>
1184         </section> <!-- modules -->
1185         <section id="fiforeference">
1186             <title>FIFO Commands Reference</title>
1187             <para>
1188                 This section lists currently supported FIFO commands. Some of them are
1189                 built-in in <application moreinfo="none">ser</application> core, whereas
1190                 others are exported by modules. The most important exporters are now
1191                 tm and usrloc module. tm FIFO commands allow users to initiate transactions
1192                 without knowledge of underlying SIP stack. usrloc FIFO commands allow
1193                 users to access in-memory user-location database. Note that that is the
1194                 only way how to affect content of the data-base in real-time. Changes
1195                 to MySql database do not affect in-memory table unless <application moreinfo="none">ser</application>
1196                 is restarted.
1197             </para>
1198             <table>
1199                 
1200                 <title>FIFO Commands</title>
1201                 <tgroup cols="4">
1202                     <thead>
1203                         <row>
1204                             <entry>
1205                                 Command
1206                             </entry>
1207                             <entry>
1208                                 Module
1209                             </entry>
1210                             <entry>
1211                                 Parameters
1212                             </entry>                        
1213                             <entry>
1214                                 Comments
1215                             </entry>
1216                         </row>
1217                     </thead>
1218                     <tbody>
1219                         <row>
1220                             <entry>
1221                                 ps
1222                             </entry>
1223                             <entry>
1224                                 core
1225                             </entry>
1226                             <entry>
1227                                 none
1228                             </entry>
1229                             <entry>
1230                                 prints running <application moreinfo="none">ser</application> processes
1231                             </entry>
1232                         </row>
1233                         <row>
1234                             <entry>which</entry>
1235                             <entry>core</entry>
1236                             <entry>none</entry>
1237                             <entry>prints list of available FIFO commands</entry>
1238                         </row>
1239                         <row>
1240                             <entry>arg</entry>
1241                             <entry>core</entry>
1242                             <entry>none</entry>
1243                             <entry>prints list of command-line arguments with which 
1244                                 <application moreinfo="none">ser</application> was started</entry>
1245                         </row>
1246                         <row>
1247                             <entry>pwd</entry>
1248                             <entry>core</entry>
1249                             <entry>none</entry>
1250                             <entry>prints <application moreinfo="none">ser</application>'s working
1251                             directory</entry>
1252                         </row>
1253                         <row>
1254                             <entry>version</entry>
1255                             <entry>core</entry>
1256                             <entry>none</entry>
1257                             <entry>prints version of <application moreinfo="none">ser</application></entry>
1258                         </row>
1259                         <row>
1260                             <entry>uptime</entry>
1261                             <entry>core</entry>
1262                             <entry>none</entry>
1263                             <entry>prints <application moreinfo="none">ser</application>'s running time</entry>
1264                         </row>
1265                         <row>
1266                             <entry>sl_stats</entry>
1267                             <entry>sl</entry>
1268                             <entry>none</entry>
1269                             <entry>prints statistics for sl module</entry>
1270                         </row>
1271                         <row>
1272                             <entry>t_stats</entry>
1273                             <entry>tm</entry>
1274                             <entry>none</entry>
1275                             <entry>print statistics for tm module</entry>
1276                         </row>
1277                         <row>
1278                             <entry>t_hash</entry>
1279                             <entry>tm</entry>
1280                             <entry>none</entry>
1281                             <entry>print occupation of transaction table (mainly for debugging)</entry>
1282                         </row>
1283                         <row>
1284                             <entry>t_uac_dlg</entry>
1285                             <entry>tm</entry>
1286                             <entry>method, request URI, outbound URI (if none, empty line with a single dot),
1287                                         dot-line-terminated header fields, optionally dot-line terminated message
1288                                         body. 
1289                                 </entry>
1290                                         
1291                             <entry>initiate a transaction.
1292                                         From and To header fields must be present in header field list,
1293                                         so does Content-Type if body is present. If CSeq, CallId and From-tag
1294                                         are not present, ephemeral values are generated. Content_length is
1295                                         calculated automatically if body present.
1296                                 </entry>
1297                         </row>
1298                         <row>
1299                             <entry>ul_stats</entry>
1300                             <entry>usrloc</entry>
1301                             <entry>none</entry>
1302                             <entry>print usrloc statistics</entry>
1303                         </row>
1304                         <row>
1305                             <entry>ul_rm</entry>
1306                             <entry>usrloc</entry>
1307                             <entry>table name, user name</entry>
1308                             <entry>remove all user's contacts from user-location database</entry>
1309                         </row>
1310                         <row>
1311                             <entry>ul_rm_contact</entry>
1312                             <entry>usrloc</entry>
1313                             <entry>table name, user name, contact</entry>
1314                             <entry>remove a user's contact from user-location database</entry>
1315                         </row>
1316                         <row>
1317                             <entry>ul_dump</entry>
1318                             <entry>usrloc</entry>
1319                             <entry>none</entry>
1320                             <entry>print content of in-memory user-location database</entry>
1321                         </row>
1322                         <row>
1323                             <entry>ul_flush</entry>
1324                             <entry>usrloc</entry>
1325                             <entry>none</entry>
1326                             <entry>flush content of in-memory user-location cache in
1327                             persistent database (MySQL)</entry>
1328                         </row>
1329                         <row>
1330                             <entry>ul_add</entry>
1331                             <entry>usrloc</entry>
1332                             <entry>table name, user name, contact, expiration, priority (q)</entry>
1333                             <entry>insert a contact address in user-location database</entry>
1334                         </row>
1335                         <row>
1336                             <entry>ul_show_contact</entry>
1337                             <entry>usrloc</entry>
1338                             <entry>table, user name</entry>
1339                             <entry>show user's contact addresses in user-location database</entry>
1340                         </row>
1341                     </tbody>
1342                 </tgroup>
1343             </table>
1344         </section>
1345         <section>
1346             <title>Used Database Tables</title>
1347             <para>
1348                 <application moreinfo="none">ser</application> includes MySQL support
1349                 to guarantee data persistence across server reboots and storage
1350                 of users' web environment. The data stored in
1351                 the database include user profiles, access control lists, user location,
1352                 etc. Note that users are not supposed to alter the data directly, as it
1353                 could introduce inconsistency between data on persistence storage and
1354                 in server's memory.
1355                 The following list enumerates used tables and explains their purpose.
1356
1357                 <itemizedlist>
1358                     <listitem>
1359                         <para>
1360                             subscriber -- table of users. It includes user names and
1361                             security credentials, as well as additional user information.
1362                         </para>
1363                     </listitem>
1364                     <listitem>
1365                         <para>
1366                             reserved -- reserved user names. <application moreinfo="none">serweb</application>
1367                             does not permit creation of accounts with name on this list.
1368                         </para>
1369                     </listitem>
1370                     <listitem>
1371                         <para>
1372                             phonebook -- user's personal phonebooks. Accessible via
1373                             <application moreinfo="none">serweb</application>.
1374                         </para>
1375                     </listitem>
1376                     <listitem>
1377                         <para>
1378                             pending -- table of unconfirmed subscription requests. Used by
1379                             <application moreinfo="none">serweb</application>.
1380                         </para>
1381                     </listitem>
1382                     <listitem>
1383                         <para>
1384                             missed_calls -- table of missed calls. Can be fed by acc modules
1385                             if mysql support is turned on. Displayed by <application moreinfo="none">serweb</application>.
1386                         </para>
1387                     </listitem>
1388                     <listitem>
1389                         <para>
1390                             location -- user contacts. Typically updated through
1391                             <application moreinfo="none">ser</application>'r registrar
1392                             functionality.
1393                         </para>
1394                     </listitem>
1395                     <listitem>
1396                         <para>
1397                             grp -- group membership. Used by auth module to determine
1398                             whether a user belongs to a group.
1399                         </para>
1400                     </listitem>
1401                     <listitem>
1402                         <para>
1403                             event -- allows users to subscribe to additional services.
1404                             Currently unused.
1405                         </para>
1406                     </listitem>
1407                     <listitem>
1408                         <para>
1409                             aliases -- keeps track of alternative user names.
1410                         </para>
1411                     </listitem>
1412                     <listitem>
1413                         <para>
1414                             active_sessions -- keeps track of currently active web sessions.
1415                             For use by <application moreinfo="none">serweb</application>.
1416                         </para>
1417                     </listitem>
1418                     <listitem>
1419                         <para>
1420                             acc -- keeps track of accounted calls.  Can be fed by acc module
1421                             if mysql support is turned on. Displayed by <application moreinfo="none">serweb</application>.
1422                         </para>
1423                     </listitem>
1424                     <listitem>
1425                         <para>
1426                             config -- maintains attribute-value pairs for keeping various information.
1427                             Currently not used.
1428                         </para>
1429                     </listitem>
1430                     <listitem>
1431                         <para>
1432                             silo -- message store for instant messages which could not have been
1433                             delivered.
1434                         </para>
1435                     </listitem>
1436
1437                     <listitem>
1438                         <para>
1439                             version -- keeps version number of each table definition.
1440                         </para>
1441                     </listitem>
1442
1443                     <listitem>
1444                         <para>
1445                             domain -- maintains list of served domains.
1446                         </para>
1447                     </listitem>
1448
1449                     <listitem>
1450                         <para>
1451                             server_monitoring-* -- reserved for persistent monitoring of 
1452                                 server's operation
1453                         </para>
1454                     </listitem>
1455
1456                     <listitem>
1457                         <para>
1458                             uri -- used to keep lists of URIs "owned" by a user
1459                                 (as identified by digest identity); good for some
1460                                 PSTN interworking scenarios
1461                         </para>
1462                     </listitem>
1463
1464
1465                 </itemizedlist>
1466                 
1467             </para>
1468         </section>
1469     </chapter> <!-- reference -->