modules/lcr: Fixed to/from_gw tests when proto parameter is 0 (ANY)
[sip-router] / modules / lcr / doc / lcr_admin.xml
1 <?xml version="1.0" encoding='ISO-8859-1'?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
3 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
4
5 <!-- Include general documentation entities -->
6 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
7 %docentities;
8
9 ]>
10 <!-- Module User's Guide -->
11
12 <chapter>
13         
14         <title>&adminguide;</title>
15         
16         <section>
17         <title>Overview</title>
18         <para>
19         The Least Cost Routing (LCR) module implements capability to
20         serially forward a request to one or more gateways so that the
21         order in which the gateways is tried is based on admin defined
22         "least cost" rules.
23         </para>
24         <para>
25         The LCR module supports many independent LCR instances (gateways and
26         least cost rules).  Each such instance has its own <emphasis>LCR
27         instance identifier</emphasis>.  Identifiers of normal LCR instances
28         are positive integers. Gateways may belong to special LCR instance
29         with identifier 0 meaning that such gateways belong to all normal
30         LCR instances.
31         </para>
32         <para>
33         For the purpose of facilitating least cost routing of requests,
34         each gateway of an LCR instance is associated with one or more 
35         &lt;prefix, from uri pattern, request uri pattern, priority, weight&gt;
36         tuples.  A gateway matches a request if user part of the Request-URI
37         matches a "prefix", the caller's URI matches a "From-URI" pattern and
38         the callee's URI matches a "Request-URI" pattern in a tuple that is
39         associated with the gateway.
40         </para>
41         <para>
42         When the function <emphasis>load_gws()</emphasis> is called,
43         matching gateways (that are not currently designated as defunct)
44         are ordered for forwarding purposes as follows:
45         </para>
46         <para>
47         <itemizedlist>
48             <listitem>
49                 <para>(1) according to longest Request-URI user part match
50                 </para>
51             </listitem>
52             <listitem>
53                 <para>(2) according to tuple's priority
54                 </para>
55             </listitem>
56             <listitem>
57                 <para>(3) according to tuple's randomized weight
58                 </para>
59             </listitem>
60         </itemizedlist>
61         </para>
62         <para>
63         A tuple can be marked as a "stopper" tuple.  If a "stopper"
64         tuple matches, then matching stops at it and all other tuples
65         with shorter prefixes are not considered.
66         </para>
67         <para>
68         Prefix is a string of characters or NULL.  From-URI
69         pattern and Request-URI pattern are regular expressions (see 'man 
70         pcresyntax' for syntax), an empty string, or NULL.  An empty or
71         NULL From-URI pattern, Request-URI pattern or prefix matches anything.
72         Smaller priority value means higher priority (highest priority
73         value being 0 and lowest being 255).
74         </para>
75         <para>
76         Weight is an integer value from 1 to 254.  Weight implementation is
77         fast, but unfair favoring larger weight values at the expense smaller
78         ones.  For example, if two gateways have weights 1 and 2, probability
79         that the gateway with weight 1 is tried first is 1/4, not 1/3.
80         Two scripts are provided in lcr/utils directory that can be used to
81         check the probabilities resulting from a given set of weight values.
82         Same can be done with command 'kamctl eval_weights'.
83         </para>
84         <para>
85         The function <emphasis>next_gw()</emphasis> can then be used to
86         select one gateway at a 
87         time for forwarding.  Upon each call, unless "dont_strip_or_tag_flag"
88         flag is set, user part of the original Request-URI is first  
89         stripped by the number of characters as specified by the
90         gateway's strip count and then prefixed by 
91         the gateway's prefix.  Upon each call, if a gateway's hostname is
92         NULL, Request-URI will be  
93         rewritten based on gateway's URI scheme, IP address, port,
94         parameters, and transport protocol.  If hostname is not NULL and
95         IP address is NULL, Request-URI will be rewritten based on the
96         gateway's URI scheme, 
97         hostname, port, parameters and transport protocol.  If both
98         hostname and IP address are not NULL, Request-URI will be
99         rewritten based on gateway's URI scheme, 
100         hostname, and parameters, and destination URI is set 
101         based on gateway's URI scheme, IP address, port, and transport
102         protocol.
103         </para>
104         <para>
105         Valid URI scheme values are NULL = sip, 1 = sip and 2
106         = sips.  Currently valid transport protocol values are NULL and 0 =
107         none, 1 = udp, 2 = tcp, 3 = tls, and 4 = sctp.
108         </para>
109         <para>
110         As a side effect of gateway selection, selected gateway's tag and flags
111         (that may contain information about the gateway and its capabilities)
112         are stored to tag_avp and flags_avp, respectively, if the corresponding
113         module parameter has been defined.
114         </para>
115         </section>
116
117         <section>
118         <title>Dependencies</title>
119         <section>
120         <title>&siprouter; modules</title>
121         <para>
122                 The following modules must be loaded before this module:
123                 <itemizedlist>
124                 <listitem>
125                 <para>
126                         <emphasis>A database module like mysql, postgres or 
127                         dbtext</emphasis>.
128                 </para>
129                 </listitem>
130                 </itemizedlist>
131         </para>
132         </section>
133         <section>
134         <title>External libraries or applications</title>
135         <para>
136                 The following libraries or applications must be installed before
137                 running &siprouter; with this module:
138                         <itemizedlist>
139                         <listitem>
140                         <para>
141                                 <emphasis>libpcre</emphasis>
142                         </para>
143                         </listitem>
144                         </itemizedlist>
145         </para>
146         </section>
147         </section>
148
149         <section>
150         <title>Parameters</title>
151         <section>
152                 <title><varname>db_url</varname> (string)</title>
153                 <para>
154                 &url; of the database table to be used.
155                 </para>
156                 <para>
157                 <emphasis>
158                         Default value is 
159                         <quote>&defaultrodb;</quote>.
160                 </emphasis>
161                 </para>
162                 <example>
163                 <title>Setting <varname>db_url</varname> module parameter</title>
164                 <programlisting format="linespecific">
165 ...
166 modparam("lcr","db_url","&exampledb;")
167 ...
168 </programlisting>
169                 </example>
170         </section>
171
172         <section>
173                 <title><varname>lcr_gw_table</varname> (string)</title>
174                 <para>
175                 Name of the table holding gateways definitions.
176                 </para>
177                 <para>
178                 <emphasis>
179                         Default value is <quote>lcr_gw</quote>.
180                 </emphasis>
181                 </para>
182                 <example>
183                 <title>Setting <varname>gw_table</varname> module parameter</title>
184                 <programlisting format="linespecific">
185 ...
186 modparam("lcr", "lcr_gw_table","gw")
187 ...
188 </programlisting>
189                 </example>
190         </section>
191
192         <section>
193                 <title><varname>id_column</varname> (string)</title>
194                 <para>
195                 Name of the auto-increment, primary key column.  Common
196                 to all lcr module tables.
197                 </para>
198                 <para>
199                 <emphasis>
200                         Default value is <quote>id</quote>.
201                 </emphasis>
202                 </para>
203                 <example>
204                 <title>Setting <varname>id_column</varname> module
205                 parameter</title> 
206                 <programlisting format="linespecific">
207 ...
208 modparam("lcr", "id_column", "row_id")
209 ...
210 </programlisting>
211                 </example>
212         </section>
213
214         <section>
215                 <title><varname>lcr_id_column</varname> (string)</title>
216                 <para>
217                 Name of the column holding the identifier of an LCR
218                 instance.  Common to all lcr module tables.  In lcr_rule and
219                 lcr_rule_target tables, value of the column is
220                 integer from 1 to lcr_count.  In lcr_gw table, value of the
221                 column is from 0 to lcr_count.
222                 </para>
223                 <para>
224                 <emphasis>
225                         Default value is <quote>lcr_id</quote>.
226                 </emphasis>
227                 </para>
228                 <example>
229                 <title>Setting <varname>lcr_id_column</varname> module
230                 parameter</title> 
231                 <programlisting format="linespecific">
232 ...
233 modparam("lcr", "lcr_id_column", "lcr_identifier")
234 ...
235 </programlisting>
236                 </example>
237         </section>
238
239         <section>
240                 <title><varname>gw_name_column</varname> (string)</title>
241                 <para>
242                 Name of the column holding gateway's name for
243                 documentation purpose.
244                 </para>
245                 <para>
246                 <emphasis>
247                         Default value is <quote>gw_name</quote>.
248                 </emphasis>
249                 </para>
250                 <example>
251                 <title>Setting <varname>gw_name_column</varname> module parameter</title>
252                 <programlisting format="linespecific">
253 ...
254 modparam("lcr", "gw_name_column", "name")
255 ...
256 </programlisting>
257                 </example>
258         </section>
259
260         <section>
261                 <title><varname>ip_addr_column</varname> (string)</title>
262                 <para>
263                 Name of the column holding the IPv4 or IPv6 address of
264                 the gateway.
265                 </para>
266                 <para>
267                 <emphasis>
268                         Default value is <quote>ip_addr</quote>.
269                 </emphasis>
270                 </para>
271                 <example>
272                 <title>Setting <varname>ip_addr_column</varname> module
273                 parameter</title> 
274                 <programlisting format="linespecific">
275 ...
276 modparam("lcr", "ip_addr_column", "ip")
277 ...
278 </programlisting>
279                 </example>
280         </section>
281
282         <section>
283                 <title><varname>hostname_column</varname> (string)</title>
284                 <para>
285                 Name of the column holding gateway's hostname that is
286                 used in Request-URI hostpart, when request is sent to the
287                 gateway.
288                 </para>
289                 <para>
290                 <emphasis>
291                         Default value is <quote>hostname</quote>.
292                 </emphasis>
293                 </para>
294                 <example>
295                 <title>Setting <varname>hostname_column</varname> module parameter</title>
296                 <programlisting format="linespecific">
297 ...
298 modparam("lcr", "hostname_column", "host")
299 ...
300 </programlisting>
301                 </example>
302         </section>
303
304         <section>
305                 <title><varname>port_column</varname> (string)</title>
306                 <para>
307                 Name of the column holding the port number of the gateway.
308                 </para>
309                 <para>
310                 <emphasis>
311                         Default value is <quote>port</quote>.
312                 </emphasis>
313                 </para>
314                 <example>
315                 <title>Setting <varname>port_column</varname> module parameter</title>
316                 <programlisting format="linespecific">
317 ...
318 modparam("lcr", "port_column", "port")
319 ...
320 </programlisting>
321                 </example>
322         </section>
323
324         <section>
325                 <title><varname>params_column</varname> (string)</title>
326                 <para>
327                 Name of the column holding gateway's parameters that is
328                 used in Request-URI, when request is sent to the
329                 gateway.
330                 </para>
331                 <para>
332                 <emphasis>
333                         Default value is <quote>params</quote>.
334                 </emphasis>
335                 </para>
336                 <example>
337                 <title>Setting <varname>params_column</varname> module parameter</title>
338                 <programlisting format="linespecific">
339 ...
340 modparam("lcr", "params_column", "parameters")
341 ...
342 </programlisting>
343                 </example>
344         </section>
345
346         <section>
347                 <title><varname>uri_scheme_column</varname> (string)</title>
348                 <para>
349                 Name of the column holding the uri scheme of the gateway.
350                 </para>
351                 <para>
352                 <emphasis>
353                         Default value is <quote>uri_scheme</quote>.
354                 </emphasis>
355                 </para>
356                 <example>
357                 <title>Setting <varname>uri_scheme_column</varname> module 
358                 parameter</title>
359                 <programlisting format="linespecific">
360 ...
361 modparam("lcr", "uri_scheme_column", "uri_scheme")
362 ...
363 </programlisting>
364                 </example>
365         </section>
366
367         <section>
368                 <title><varname>transport_column</varname> (string)</title>
369                 <para>
370                 Name of the column holding the transport protocol to be
371                 used for the gateway.
372                 </para>
373                 <para>
374                 <emphasis>
375                         Default value is <quote>transport</quote>.
376                 </emphasis>
377                 </para>
378                 <example>
379                 <title>Setting <varname>transport_column</varname> module 
380                 parameter</title>
381                 <programlisting format="linespecific">
382 ...
383 modparam("lcr", "transport_column", "trans")
384 ...
385 </programlisting>
386                 </example>
387         </section>
388
389         <section>
390                 <title><varname>strip_column</varname> (string)</title>
391                 <para>
392                 Name of the column holding the number of characters
393                 to be stripped from the front of Request-URI user part
394                 before inserting tag.
395                 </para>
396                 <para>
397                 <emphasis>
398                         Default value is <quote>strip</quote>.
399                 </emphasis>
400                 </para>
401                 <example>
402                 <title>Setting <varname>strip_column</varname> module 
403                 parameter</title>
404                 <programlisting format="linespecific">
405 ...
406 modparam("lcr", "strip_column", "strip_count")
407 ...
408 </programlisting>
409                 </example>
410         </section>
411
412         <section>
413                 <title><varname>tag_column</varname> (string)</title>
414                 <para>
415                 Name of the column holding gateway specific tag string
416                 that is added to Request URI userpart after stripping.
417                 </para>
418                 <para>
419                 <emphasis>
420                         Default value is <quote>tag</quote>.
421                 </emphasis>
422                 </para>
423                 <example>
424                 <title>Setting <varname>tag_column</varname> module parameter</title>
425                 <programlisting format="linespecific">
426 ...
427 modparam("lcr", "tag_column", "gw_tag")
428 ...
429 </programlisting>
430                 </example>
431         </section>
432
433         <section>
434                 <title><varname>flags_column</varname> (string)</title>
435                 <para>
436                 Name of the column holding gateway specific flag values.
437                 </para>
438                 <para>
439                 <emphasis>
440                         Default value is <quote>flags</quote>.
441                 </emphasis>
442                 </para>
443                 <example>
444                 <title>Setting <varname>flags_column</varname> module parameter</title>
445                 <programlisting format="linespecific">
446 ...
447 modparam("lcr", "flags_column", "gw_flags")
448 ...
449 </programlisting>
450                 </example>
451         </section>
452
453         <section>
454                 <title><varname>defunct_column</varname> (string)</title>
455                 <para>
456                 Name of the column holding UNIX timestamp telling the
457                 time until which the gw is considered as defunct.
458                 If timestamp value is 4294967295 (= max UNIX timestamp value)
459                 or greater, gw is considered currently unused and is not
460                 loaded into memory at all.
461                 </para>
462                 <para>
463                 <emphasis>
464                         Default value is <quote>defunct</quote>.
465                 </emphasis>
466                 </para>
467                 <example>
468                 <title>Setting <varname>defunct_column</varname> module parameter</title>
469                 <programlisting format="linespecific">
470 ...
471 modparam("lcr", "defunct_column", "defunct_until")
472 ...
473 </programlisting>
474                 </example>
475         </section>
476
477         <section>
478                 <title><varname>lcr_rule_table</varname> (string)</title>
479                 <para>
480                 Name of the table holding the LCR rules.
481                 </para>
482                 <para>
483                 <emphasis>
484                         Default value is <quote>lcr_rule</quote>.
485                 </emphasis>
486                 </para>
487                 <example>
488                 <title>Setting <varname>lcr_rule_table</varname> module parameter</title>
489                 <programlisting format="linespecific">
490 ...
491 modparam("lcr", "lcr_rule_table", "rules")
492 ...
493 </programlisting>
494                 </example>
495         </section>
496
497         <section>
498                 <title><varname>prefix_column</varname> (string)</title>
499                 <para>
500                 Name of the column holding prefix of Request-URI user
501                 part and prefix of gateway.
502                 </para>
503                 <para>
504                 <emphasis>
505                         Default value is <quote>prefix</quote>.
506                 </emphasis>
507                 </para>
508                 <example>
509                 <title>Setting <varname>prefix_column</varname> module
510                 parameter</title> 
511                 <programlisting format="linespecific">
512 ...
513 modparam("lcr", "prefix_column", "number_prefix")
514 ...
515 </programlisting>
516                 </example>
517         </section>
518
519         <section>
520                 <title><varname>from_uri_column</varname> (string)</title>
521                 <para>
522                 Name of the column holding the From (caller's) URI.
523                 </para>
524                 <para>
525                 <emphasis>
526                         Default value is <quote>from_uri</quote>.
527                 </emphasis>
528                 </para>
529                 <example>
530                 <title>Setting <varname>from_uri_column</varname> module parameter</title>
531                 <programlisting format="linespecific">
532 ...
533 modparam("lcr", "from_uri_column", "caller_uri")
534 ...
535 </programlisting>
536                 </example>
537         </section>
538
539         <section>
540                 <title><varname>request_uri_column</varname> (string)</title>
541                 <para>
542                 Name of the column holding the regular expression to match
543                 against the complete request URI (including the "sip:" prefix).
544                 </para>
545                 <para>
546                 <emphasis>
547                         Default value is <quote>request_uri</quote>.
548                 </emphasis>
549                 </para>
550                 <example>
551                 <title>Setting <varname>request_uri_column</varname> module parameter</title>
552                 <programlisting format="linespecific">
553 ...
554 modparam("lcr", "request_uri_column", "callee_uri")
555 ...
556 </programlisting>
557                 </example>
558         </section>
559
560         <section>
561                 <title><varname>stopper_column</varname> (string)</title>
562                 <para>
563                 Name of the column holding rule's stopper attribute.
564                 </para>
565                 <para>
566                 <emphasis>
567                         Default value is <quote>stopper</quote>.
568                 </emphasis>
569                 </para>
570                 <example>
571                 <title>Setting <varname>stopper_column</varname> module
572                 parameter 
573                         </title>
574                 <programlisting format="linespecific">
575 ...
576 modparam("lcr", "stopper_column", "stop")
577 ...
578 </programlisting>
579                 </example>
580         </section>
581
582         <section>
583                 <title><varname>enabled_column</varname> (string)</title>
584                 <para>
585                 Name of the column telling is the rule is currently
586                 enabled or disabled.
587                 </para>
588                 <para>
589                 <emphasis>
590                         Default value is <quote>enabled</quote>.
591                 </emphasis>
592                 </para>
593                 <example>
594                 <title>Setting <varname>enabled_column</varname> module
595                 parameter
596                 </title>
597                 <programlisting format="linespecific">
598 ...
599 modparam("lcr", "enabled_column", "in_use")
600 ...
601 </programlisting>
602                 </example>
603         </section>
604
605         <section>
606                 <title><varname>lcr_rule_target_table</varname> (string)</title>
607                 <para>
608                 Name of the table holding information about the LCR rule
609                 targets (gateways).
610                 </para>
611                 <para>
612                 <emphasis>
613                         Default value is <quote>lcr_rule_target</quote>.
614                 </emphasis>
615                 </para>
616                 <example>
617                 <title>Setting <varname>lcr_rule_target_table</varname>
618                 module parameter</title> 
619                 <programlisting format="linespecific">
620 ...
621 modparam("lcr", "lcr_rule_target_table", "rules")
622 ...
623 </programlisting>
624                 </example>
625         </section>
626
627         <section>
628                 <title><varname>rule_id_column</varname> (string)</title>
629                 <para>
630                 Name of lcr_rule_target_table column containing an id of
631                 lcr_rule table.
632                 </para>
633                 <para>
634                 <emphasis>
635                         Default value is <quote>rule_id</quote>.
636                 </emphasis>
637                 </para>
638                 <example>
639                 <title>Setting <varname>rule_id_column</varname> module
640                 parameter 
641                         </title>
642                 <programlisting format="linespecific">
643 ...
644 modparam("lcr", "rule_id_column", "rule")
645 ...
646 </programlisting>
647                 </example>
648         </section>
649
650         <section>
651                 <title><varname>gw_id_column</varname> (string)</title>
652                 <para>
653                 Name of lcr_rule_target_table column containing an id of
654                 lcr_gw table.
655                 </para>
656                 <para>
657                 <emphasis>
658                         Default value is <quote>gw_id</quote>.
659                 </emphasis>
660                 </para>
661                 <example>
662                 <title>Setting <varname>gw_id_column</varname> module
663                 parameter 
664                         </title>
665                 <programlisting format="linespecific">
666 ...
667 modparam("lcr", "gw_id_column", "gw")
668 ...
669 </programlisting>
670                 </example>
671         </section>
672
673         <section>
674                 <title><varname>priority_column</varname> (string)</title>
675                 <para>
676                 Name of the column holding the priority of the rule
677                 target.
678                 </para>
679                 <para>
680                 <emphasis>
681                         Default value is <quote>priority</quote>.
682                 </emphasis>
683                 </para>
684                 <example>
685                 <title>Setting <varname>priority_column</varname> module
686                 parameter</title>
687                 <programlisting format="linespecific">
688 ...
689 modparam("lcr", "priority_column", "priority")
690 ...
691 </programlisting>
692                 </example>
693         </section>
694
695         <section>
696                 <title><varname>weight_column</varname> (string)</title>
697                 <para>
698                 Name of the column holding weight of rule target.
699                 </para>
700                 <para>
701                 <emphasis>
702                         Default value is <quote>weight</quote>.
703                 </emphasis>
704                 </para>
705                 <example>
706                 <title>Setting <varname>weight_column</varname> module
707                 parameter</title> 
708                 <programlisting format="linespecific">
709 ...
710 modparam("lcr","weight_column", "target_weight")
711 ...
712 </programlisting>
713                 </example>
714         </section>
715
716         <section>
717                 <title><varname>lcr_count</varname> (integer)</title>
718                 <para>
719                 Number of LCR instances.
720                 </para>
721                 <para>
722                 <emphasis>
723                         Default value is 1.
724                 </emphasis>
725                 </para>
726                 <example>
727                 <title>
728                 Setting <varname>lcr_count</varname> module
729                 parameter
730                 </title>
731                 <programlisting format="linespecific">
732 ...
733 modparam("lcr", "lcr_count", 10)
734 ...
735 </programlisting>
736                 </example>
737         </section>
738
739         <section>
740                 <title><varname>gw_uri_avp</varname> (AVP string)</title>
741                 <para>
742                 Internal AVP that load_gws() function uses to store
743                 information of matching gateways.
744                 </para>
745                 <para>
746                 <emphasis>
747                         There is NO default value, thus this variable must
748                         be defined in &siprouterconfig;.
749                 </emphasis>
750                 </para>
751                 <example>
752                 <title>Setting <varname>gw_uri_avp</varname> module
753                 parameter</title> 
754                 <programlisting format="linespecific">
755 ...
756 modparam("lcr", "gw_uri_avp", "$avp(i:709)")
757 ...
758 </programlisting>
759                 </example>
760         </section>
761
762         <section>
763                 <title><varname>ruri_user_avp</varname> (AVP string)</title>
764                 <para>
765                 Internal AVP that next_gw function uses to store
766                 Request-URI user for subsequent next_gw calls.
767                 </para>
768                 <para>
769                 <emphasis>
770                         There is NO default value, thus this variable must
771                         be defined in &siprouterconfig;.
772                 </emphasis>
773                 </para>
774                 <example>
775                 <title>Setting <varname>ruri_user_avp</varname> module parameter</title>
776                 <programlisting format="linespecific">
777 ...
778 modparam("lcr", "ruri_user_avp", "$avp(i:500)")
779 ...
780 </programlisting>
781                 </example>
782         </section>
783
784         <section>
785                 <title><varname>tag_avp</varname> (AVP string)</title>
786                 <para>
787                 If defined, an AVP where successful next_gw and from_gw
788                 functions store gateway's tag.
789                 </para>
790                 <para>
791                 <emphasis>
792                         There is NO default value, i.e, if not defined,
793                         gateway's tag is not stored anywhere.
794                 </emphasis>
795                 </para>
796                 <example>
797                 <title>Setting <varname>tag_avp</varname> module parameter</title>
798                 <programlisting format="linespecific">
799 ...
800 modparam("lcr", "tag_avp", "$avp(lcr_tag)")
801 ...
802 </programlisting>
803                 </example>
804         </section>
805
806         <section>
807                 <title><varname>flags_avp</varname> (AVP string)</title>
808                 <para>
809                 If defined, an AVP where successful next_gw and from_gw
810                 functions store gateway's flags.
811                 </para>
812                 <para>
813                 <emphasis>
814                         There is NO default value, i.e, if not defined,
815                         gateway's flags are not stored anywhere.
816                 </emphasis>
817                 </para>
818                 <example>
819                 <title>Setting <varname>flags_avp</varname> module parameter</title>
820                 <programlisting format="linespecific">
821 ...
822 modparam("lcr", "flags_avp", "$avp(i:712)")
823 ...
824 </programlisting>
825                 </example>
826         </section>
827
828         <section>
829                 <title><varname>defunct_capability</varname> (integer)</title>
830                 <para>
831                 Tells if defunct capability of (non-responsive) gateways is
832                 supported.  Non-zero value turns on defunct capability.
833                 </para>
834                 <para>
835                 <emphasis>
836                         Default value is 0.
837                 </emphasis>
838                 </para>
839                 <example>
840                 <title>
841                 Setting <varname>defunct_capability</varname> module
842                 parameter
843                 </title>
844                 <programlisting format="linespecific">
845 ...
846 modparam("lcr", "defunct_capability", 1)
847 ...
848 </programlisting>
849                 </example>
850         </section>
851
852         <section>
853                 <title><varname>lcr_id_avp</varname> (AVP string)</title>
854                 <para>
855                 Internal AVP that load_gws() function uses to store
856                 LCR instance identifier of loaded gateways.  Only needed if
857                 gateway defunct capability has been activated.
858                 </para>
859                 <para>
860                 <emphasis>
861                         There is NO default value.
862                 </emphasis>
863                 </para>
864                 <example>
865                 <title>Setting <varname>lcr_id_avp</varname> module
866                 parameter</title> 
867                 <programlisting format="linespecific">
868 ...
869 modparam("lcr", "lcr_id_avp", "$avp(s:lcr_id_avp)")
870 ...
871 </programlisting>
872                 </example>
873         </section>
874
875         <section>
876                 <title><varname>defunct_gw_avp</varname> (AVP string)</title>
877                 <para>
878                 Internal AVP that next_gw() function uses to store
879                 internal index of the  
880                 selected gateway for later use by defunct_gw() function.
881                 Only needed if 
882                 gateway defunct capability has been activated.
883                 </para>
884                 <para>
885                 <emphasis>
886                         There is NO default value.
887                 </emphasis>
888                 </para>
889                 <example>
890                 <title>Setting <varname>defunct_gw_avp</varname> module
891                 parameter</title> 
892                 <programlisting format="linespecific">
893 ...
894 modparam("lcr", "defunct_gw_avp", "$avp(s:defunct_gw_avp)")
895 ...
896 </programlisting>
897                 </example>
898         </section>
899
900         <section>
901                 <title><varname>lcr_rule_hash_size</varname> (integer)</title>
902                 <para>
903                 Defines the size of hash table used to store LCR rules.
904                 Hashing is done based on rule's prefix.  Larger value means
905                 less collisions with other prefixes.  Hash size value
906                 should be a power of 2.
907                 </para>
908                 <para>
909                 <emphasis>
910                         Default value is 128.
911                 </emphasis>
912                 </para>
913                 <example>
914                 <title>
915                 Setting <varname>lcr_rule_hash_size</varname> module
916                 parameter
917                 </title>
918                 <programlisting format="linespecific">
919 ...
920 modparam("lcr", "lcr_rule_hash_size", 1024)
921 ...
922 </programlisting>
923                 </example>
924         </section>
925
926         <section>
927                 <title><varname>lcr_gw_count</varname> (integer)</title>
928                 <para>
929                 Defines the maximum number of gateways in lcr_gw table.
930                 </para>
931                 <para>
932                 <emphasis>
933                         Default value is 128.
934                 </emphasis>
935                 </para>
936                 <example>
937                 <title>
938                 Setting <varname>lcr_gw_count</varname> module parameter
939                 </title>
940                 <programlisting format="linespecific">
941 ...
942 modparam("lcr", "lcr_gw_count", 1024)
943 ...
944 </programlisting>
945                 </example>
946         </section>
947
948         <section>
949                 <title><varname>dont_strip_or_tag_flag</varname> (integer)</title>
950                 <para>
951                 Defines the flag number used to tell if stripping and
952                 tagging is done for the selected gateway.
953                 </para>
954                 <para>
955                 <emphasis>
956                         Default value is -1 meaning that the flag is not
957                 defined.
958                 </emphasis>
959                 </para>
960                 <example>
961                 <title>
962                 Setting <varname>dont_strip_or_tag_flag</varname> module
963                 parameter
964                 </title>
965                 <programlisting format="linespecific">
966 ...
967 modparam("lcr", "dont_strip_or_tag_flag", 10)
968 ...
969 </programlisting>
970                 </example>
971         </section>
972
973         <section>
974                 <title><varname>fetch_rows</varname> (integer)</title>
975                 <para>
976                 The number of the rows to be fetched at once from database
977                 when loading data from lcr_rule table. This value can be
978                 used to tune 
979                 the load time at startup.  For 1MB of private memory (default)
980                 it should be below 3750. In order for this parameter to
981                 have effect, the database driver must support fetch_result()
982                 capability.
983                 </para>
984                 <para>
985                 <emphasis>
986                         Default value is <quote>1024</quote>.
987                 </emphasis>
988                 </para>
989                 <example>
990                 <title>Set <varname>fetch_rows</varname> parameter</title>
991                 <programlisting format="linespecific">
992 ...
993 modparam("lcr", "fetch_rows", 3000)
994 ...
995 </programlisting>
996                 </example>
997         </section>
998
999         </section>
1000
1001         <section>
1002         <title>Functions</title>
1003         <section>
1004                 <title>
1005                 <function moreinfo="none">load_gws(lcr_id[, uri_user[, caller_uri]])
1006                 </function> 
1007                 </title>
1008                 <para>
1009                 Loads attributes of matching gateways to gw_uri_avp
1010                 (see Overview section).  Argument lcr_id specifies the used
1011                 LCR instance.  It can be a positive integer or a pseudo
1012                 variable containing an integer value.
1013                 If uri_user is given, it is used, instead of Request-URI user
1014                 part, to look for matching gateways.  Caller's URI may be given
1015                 by caller_uri argument. If caller_uri argument is
1016                 omitted, it defaults to empty string. Both uri_user and
1017                 caller_uri argument may be a string or a pseudo variable
1018                 containing a sting value.  
1019                 </para>
1020                 <para>
1021                 Returns 1 if at least one matching gateway was found, 2
1022                 if no matching gateways was found, and -1 on error.
1023                 </para>
1024                 <para>
1025                 Execution time of load_gws() function is O(N) * O(M),
1026                 where N is number of different prefix lengths and M
1027                 is number of collisions for matching prefix(es) in lcr
1028                 rules hash table of the LCR instance.
1029                 </para>
1030                 <para>
1031                 This function can be used from REQUEST_ROUTE.
1032                 </para>
1033                 <example>
1034                 <title><function>load_gws</function> usage</title>
1035                 <programlisting format="linespecific">
1036 ...
1037 if (!load_gws(1, $rU, $var(caller_uri))) {
1038         sl_send_reply("500", "Server Internal Error - Cannot load gateways");
1039         exit;
1040 };
1041 ...
1042 </programlisting>
1043                 </example>
1044         </section>
1045
1046         <section>
1047                 <title>
1048                 <function moreinfo="none">next_gw()</function>
1049                 </title>        
1050                 <para>
1051                 Upon first call, fetches attribute values stored in first
1052                 gw_uri_avp, destroys that AVP, and rewrites
1053                 Request-URI and possibly also destination URI as
1054                 described in the Overview section. Saves user part of
1055                 Request-URI into 
1056                 ruri_user_avp for use in subsequent next_gw() calls.
1057                 </para>
1058                 <para>
1059                 Upon subsequent calls, does the same as in above, but
1060                 takes user part of Request-URI from ruri_user_avp.
1061                 </para>
1062                 <para>
1063                 As a side effect, stores gateway's tag and flags to
1064                 tag_avp and flags_avp, respectively, if the corresponding
1065                 module parameter has been defined.
1066                 </para>
1067                 <para>
1068                 Returns 1 on success and -1 if there were no gateways
1069                 left or if an error occurred (see syslog).
1070                 </para>
1071                 <para>
1072                 Must be preceded by successful load_gws() call.
1073                 </para>
1074                 <para>
1075                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1076                 </para>
1077                 <example>
1078                 <title><function>next_gw</function> usage from a route block</title>
1079                 <programlisting format="linespecific">
1080 ...
1081 if (!next_gw()) {
1082         sl_send_reply("503", "Service not available - No gateways");
1083         exit;
1084 };
1085 ...
1086 </programlisting>
1087                 </example>
1088                 <example>
1089                 <title><function>next_gw</function> usage from a failure
1090                 route block 
1091                         </title>
1092                 <programlisting format="linespecific">
1093 ...
1094 if (!next_gw()) {
1095         t_reply("503", "Service not available - No more gateways");
1096         exit;
1097 };
1098 ...
1099 </programlisting>
1100                 </example>
1101         </section>
1102
1103         <section>
1104                 <title>
1105                 <function moreinfo="none">defunct_gw(period)</function>
1106                 </title>        
1107                 <para>
1108                 Defuncts gateway denoted by lcr_id_avp and defunct_gw_avp
1109                 (which were set by previuos next_gw() call)
1110                 for a period of seconds given as argument.  Argument 
1111                 must be a positive integer constant or a pseudo variable
1112                 with positive integer value.  Value of defunct column in
1113                 database is not updated.
1114                 </para>
1115                 <para>
1116                 Returns 1 on success and -1 in case of error (see syslog).
1117                 </para>
1118                 <para>
1119                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1120                 </para>
1121                 <example>
1122                 <title><function>defunct_gw</function> usage</title>
1123                 <programlisting format="linespecific">
1124 ...
1125 defunct_gw(60);
1126 ...
1127 </programlisting>
1128                 </example>
1129         </section>
1130
1131         <section>
1132                 <title>
1133                 <function moreinfo="none">from_gw(lcr_id[, ip_addr, proto])</function>
1134                 </title>
1135                 <para>
1136                 Checks if request comes from IP address and transport protocol
1137                 specified for a gateway in LCR instance lcr_id.
1138                 Fails if the LCR instance includes 
1139                 one or more gateways without IP address.
1140                 IP address and transport protocol to be checked are either
1141                 taken from source IP address of the request or
1142                 (if present) from ip_addr and proto arguments.
1143                 </para>
1144                 <para>
1145                 lcr_id can be an integer constant or a pseudo variable
1146                 holding an integer value.  ip_addr can be a string or a pseudo
1147                 variable holding a string value.  proto can be an integer
1148                 constant (0 = ANY, 1 = UDP, 2 = TCP,
1149                 3 = TLS, 4 = SCTP) or a pseudo variable holding such an
1150                 integer value.
1151                 </para>
1152                 <para>
1153                 If request comes from a gateway, gateway's tag and flags are
1154                 stored as a side effect to
1155                 tag_avp and flags_avp, respectively, if the corresponding
1156                 module parameter has been defined.
1157                 </para>
1158                 <para>
1159                 Returns 1 on success and -1 on failure or on error.
1160                 </para>
1161                 <para>
1162                 Execution time of from_gw() function is O(log N),
1163                 where N is number of gateways in the LCR instance.
1164                 </para>
1165                 <para>
1166                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
1167                 ONREPLY_ROUTE.
1168                 </para>
1169                 <example>
1170                 <title><function>from_gw</function> usage</title>
1171                 <programlisting format="linespecific">
1172 ...
1173 if (from_gw(1, $avp(s:real_source_addr), 2) {
1174         ...
1175 };
1176 ...
1177 </programlisting>
1178                 </example>
1179                 </section>
1180
1181         <section>
1182                 <title>
1183                 <function moreinfo="none">from_any_gw([ip_addr, proto])</function>
1184                 </title>
1185                 <para>
1186                 Checks if request comes from IP address and transport 
1187                 protocol specified for any gateway.  Only LCR instances,
1188                 where all gateways
1189                 have IP address, are included in the test.
1190                 IP address and transport protocol to be checked are either
1191                 taken from source IP address and transport protocol 
1192                 of the request or
1193                 (if present) from ip_addr and proto arguments.  See from_gw()
1194                 function for more info about the arguments.
1195                 </para>
1196                 <para>
1197                 If any gateway has the IP address and transport protocol,
1198                 function returns LCR
1199                 identifier of the gateway.  Returns -1 on error or if
1200                 the request does not come from a gateway. 
1201                 </para>
1202                 <para>
1203                 If request comes from a gateway, gateway's tag and flags are
1204                 stored as a side effect to
1205                 tag_avp and flags_avp, respectively, if the corresponding
1206                 module parameter has been defined.
1207                 </para>
1208                 <para>
1209                 Execution time of from_gw() function is M * O(log N),
1210                 where M is number of LCR instances and N is average number of
1211                 gateways in LCR instances.
1212                 </para>
1213                 <para>
1214                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
1215                 ONREPLY_ROUTE.
1216                 </para>
1217                 <example>
1218                 <title><function>from_gw</function> usage</title>
1219                 <programlisting format="linespecific">
1220 ...
1221 $var(lcr_id) = from_any_gw("192.168.1.1", 3);
1222 ...
1223 </programlisting>
1224                 </example>
1225                 </section>
1226
1227                 <section>
1228                 <title>
1229                 <function moreinfo="none">to_gw(lcr_id[, ip_addr, proto])</function>
1230                 </title>
1231                 <para>
1232                 Checks if in-dialog request goes to IP address and transport
1233                 protocol specified for a gateway in LCR instance lcr_id.
1234                 Fails if LCR
1235                 instance includes one or more gateways without IP
1236                 address.  IP address and transport protocol to be
1237                 checked are either taken from Request-URI or (if
1238                 present) from ip_addr and proto arguments.  See from_gw()
1239                 for more info regarding the arguments.
1240                 </para>
1241                 <para>
1242                 Returns 1 on success and -1 on failure and error.
1243                 </para>
1244                 <para>
1245                 Execution time of to_gw() function is O(log N),
1246                 where N is number of gateways in the LCR instance.
1247                 </para>
1248                 <para>
1249                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1250                 </para>
1251                 <example>
1252                 <title><function>to_gw</function> usage</title>
1253                 <programlisting format = "linespecific">
1254 ...
1255 if (to_gw("1")) {
1256         ...
1257         exit;
1258 };
1259 ...
1260 </programlisting>
1261                 </example>
1262         </section>
1263
1264         <section>
1265                 <title>
1266                 <function moreinfo="none">to_any_gw([ip_addr, proto])</function>
1267                 </title>
1268                 <para>
1269                 Checks if in-dialog request goes to IP address and transport
1270                 protocol of any gateway.
1271                 Only LCR instances, where all gateways 
1272                 have IP address, are included in the test. IP
1273                 address and transport protocol to be checked are
1274                 either taken from Request-URI or (if present)
1275                 from ip_addr and proto arguments.   See from_gw()
1276                 for more info regarding the arguments.
1277                 </para>
1278                 <para>
1279                 Execution time of to_any_gw() function is M * O(log N),
1280                 where M is number of LCR instances and N is average
1281                 number of gateways in LCR instances.
1282                 </para>
1283                 <para>
1284                 If any gateway has the IP address, returns LCR identifier
1285                 of the gateway.  Returns -1 if request does
1286                 not go to a gateway and on error.
1287                 </para>
1288                 <para>
1289                 This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1290                 </para>
1291                 <example>
1292                 <title><function>to_gw</function> usage</title>
1293                 <programlisting format = "linespecific">
1294 ...
1295 if (to_any_gw("192.55.66.2", 1)) {
1296         ...
1297         exit;
1298 };
1299 ...
1300 </programlisting>
1301                 </example>
1302         </section>
1303
1304         </section>
1305
1306         <section>
1307         <title>Exported RPC Commands</title>
1308                 <section>
1309                 <title><function>lcr.reload</function></title>
1310                 <para>
1311                         Causes lcr module to re-read the contents of
1312                         LCR tables into memory.
1313                 </para>
1314                 <para>
1315                 Name: <emphasis>lcr.reload</emphasis>
1316                 </para>
1317                 <para>Parameters: <emphasis>none</emphasis></para>
1318                 <example>
1319                 <title><function>lcr.reload</function> RPC example</title>
1320                 <programlisting  format="linespecific">
1321                 $ sercmd lcr.reload
1322                 </programlisting>
1323                 </example>
1324                 </section>
1325                 
1326                 <section>
1327                 <title><function>lcr.dump_gws</function></title>
1328                 <para>
1329                         Causes lcr module to dump the contents of its
1330                         in-memory gw table.
1331                 </para>
1332                 <para>Parameters: <emphasis>none</emphasis></para>
1333                 <example>
1334                 <title><function>lcr.dump_gws</function> RPC example</title>
1335                 <programlisting  format="linespecific">
1336                 $ sercmd lcr.dump_gws
1337                 </programlisting>
1338                 </example>
1339                 </section>
1340                 
1341                 <section>
1342                 <title><function>lcr.dump_rules</function></title>
1343                 <para>
1344                         Causes lcr module to dump the contents of its
1345                         in-memory lcr_rule and lcr_rule_target tables.
1346                 </para>
1347                 <para>Parameters: <emphasis>none</emphasis></para>
1348                 <example>
1349                 <title><function>lcr.dump_rules</function> RPC example</title>
1350         <programlisting  format="linespecific">
1351                 $ sercmd lcr.dump_rules
1352                 </programlisting>
1353                 </example>
1354                 </section>
1355
1356                 <section>
1357                 <title><function>lcr.defunct_gw</function></title>
1358                 <para>
1359                         Defuncts gateway loaded into memory for a period of
1360                         time (seconds) without a need to store gateway's
1361                         defunct value into database and reload the tables.
1362                 </para>
1363                 <para>
1364                 Name: <emphasis>lcr.defunct_gw</emphasis>
1365                 </para>
1366                 <para>Parameters: <emphasis>lcr_id gw_id period</emphasis></para>
1367                 <example>
1368                 <title><function>lcr.defunct_gw</function> RPC example</title>
1369                 <programlisting  format="linespecific">
1370                 $ sercmd lcr.defunct_gw 1 4 120
1371                 </programlisting>
1372                 </example>
1373                 </section>
1374         </section>
1375         <section>
1376         <title>Known Limitations</title>
1377         <para>
1378                 In-memory LCR rules and gw tables are switched
1379                 by two consecutive machine instructions. If lcr reload
1380                 process is interrupted after the first one, in-memory
1381                 gateway table does not match in-memory rule table until
1382                 execution of lcr reload process is resumed.
1383         </para>
1384         </section>
1385 </chapter>