Merge remote branch 'origin/sr_3.0'
[sip-router] / modules / lcr / README
1 LCR (Least Cost Routing) Module
2
3 Juha Heinanen
4
5    <jh@tutpro.com>
6
7 Edited by
8
9 Juha Heinanen
10
11    <jh@tutpro.com>
12
13    Copyright © 2005-2009 Juha Heinanen
14    Revision History
15    Revision $Revision$ $Date$
16      __________________________________________________________________
17
18    Table of Contents
19
20    1. Admin Guide
21
22         1. Overview
23         2. Dependencies
24
25               2.1. SIP Router modules
26               2.2. External libraries or applications
27
28         3. Exported Parameters
29
30               3.1. db_url (string)
31               3.2. gw_table (string)
32               3.3. lcr_id_column (string)
33               3.4. gw_name_column (string)
34               3.5. grp_id_column (string)
35               3.6. ip_addr_column (string)
36               3.7. hostname_column (string)
37               3.8. port_column (string)
38               3.9. uri_scheme_column (string)
39               3.10. transport_column (string)
40               3.11. strip_column (string)
41               3.12. tag_column (string)
42               3.13. weight_column (string)
43               3.14. flags_column (string)
44               3.15. defunct_column (string)
45               3.16. lcr_table (string)
46               3.17. prefix_column (string)
47               3.18. from_uri_column (string)
48               3.19. priority_column (string)
49               3.20. lcr_count (integer)
50               3.21. gw_uri_avp (AVP string)
51               3.22. ruri_user_avp (AVP string)
52               3.23. flags_avp (AVP string)
53               3.24. defunct_capability (integer)
54               3.25. lcr_id_avp (AVP string)
55               3.26. defunct_gw_avp (AVP string)
56               3.27. lcr_hash_size (integer)
57               3.28. fetch_rows (integer)
58
59         4. Exported Functions
60
61               4.1. load_gws(lcr_id, caller_uri)
62               4.2. next_gw()
63               4.3. defunct_gw(period)
64               4.4. from_gw(lcr_id [, ip_addr])
65               4.5. from_any_gw([ip_addr])
66               4.6. to_gw(lcr_id [, ip_addr])
67               4.7. to_any_gw([ip_addr])
68
69         5. Exported MI Commands
70
71               5.1. lcr_reload
72               5.2. lcr_gw_dump
73               5.3. lcr_lcr_dump
74
75         6. Exported RPC Commands
76
77               6.1. lcr.reload
78               6.2. lcr.dump_gws
79               6.3. lcr.dump_lcrs
80
81         7. Known Limitations
82
83    List of Examples
84
85    1.1. Setting db_url module parameter
86    1.2. Setting gw_table module parameter
87    1.3. Setting lcr_id_column module parameter
88    1.4. Setting gw_name_column module parameter
89    1.5. Setting grp_id_column module parameter
90    1.6. Setting ip_addr_column module parameter
91    1.7. Setting hostname_column module parameter
92    1.8. Setting port_column module parameter
93    1.9. Setting uri_scheme_column module parameter
94    1.10. Setting transport_column module parameter
95    1.11. Setting strip_column module parameter
96    1.12. Setting tag_column module parameter
97    1.13. Setting weight_column module parameter
98    1.14. Setting flags_column module parameter
99    1.15. Setting defunct_column module parameter
100    1.16. Setting lcr_table module parameter
101    1.17. Setting prefix_column module parameter
102    1.18. Setting from_uri_column module parameter
103    1.19. Setting priority_column module parameter
104    1.20. Setting lcr_count module parameter
105    1.21. Setting gw_uri_avp module parameter
106    1.22. Setting ruri_user_avp module parameter
107    1.23. Setting flags_avp module parameter
108    1.24. Setting defunct_capability module parameter
109    1.25. Setting lcr_id_avp module parameter
110    1.26. Setting defunct_gw_avp module parameter
111    1.27. Setting lcr_hash_size module parameter
112    1.28. Set fetch_rows parameter
113    1.29. load_gws usage
114    1.30. next_gw usage from a route block
115    1.31. next_gw usage from a failure route block
116    1.32. defunct_gw usage
117    1.33. from_gw usage
118    1.34. from_gw usage
119    1.35. to_gw usage
120    1.36. to_gw usage
121    1.37. lcr.reload RPC example
122    1.38. lcr.dump_gws RPC example
123    1.39. lcr.dump_lcr RPC example
124
125 Chapter 1. Admin Guide
126
127    Table of Contents
128
129    1. Overview
130    2. Dependencies
131
132         2.1. SIP Router modules
133         2.2. External libraries or applications
134
135    3. Exported Parameters
136
137         3.1. db_url (string)
138         3.2. gw_table (string)
139         3.3. lcr_id_column (string)
140         3.4. gw_name_column (string)
141         3.5. grp_id_column (string)
142         3.6. ip_addr_column (string)
143         3.7. hostname_column (string)
144         3.8. port_column (string)
145         3.9. uri_scheme_column (string)
146         3.10. transport_column (string)
147         3.11. strip_column (string)
148         3.12. tag_column (string)
149         3.13. weight_column (string)
150         3.14. flags_column (string)
151         3.15. defunct_column (string)
152         3.16. lcr_table (string)
153         3.17. prefix_column (string)
154         3.18. from_uri_column (string)
155         3.19. priority_column (string)
156         3.20. lcr_count (integer)
157         3.21. gw_uri_avp (AVP string)
158         3.22. ruri_user_avp (AVP string)
159         3.23. flags_avp (AVP string)
160         3.24. defunct_capability (integer)
161         3.25. lcr_id_avp (AVP string)
162         3.26. defunct_gw_avp (AVP string)
163         3.27. lcr_hash_size (integer)
164         3.28. fetch_rows (integer)
165
166    4. Exported Functions
167
168         4.1. load_gws(lcr_id, caller_uri)
169         4.2. next_gw()
170         4.3. defunct_gw(period)
171         4.4. from_gw(lcr_id [, ip_addr])
172         4.5. from_any_gw([ip_addr])
173         4.6. to_gw(lcr_id [, ip_addr])
174         4.7. to_any_gw([ip_addr])
175
176    5. Exported MI Commands
177
178         5.1. lcr_reload
179         5.2. lcr_gw_dump
180         5.3. lcr_lcr_dump
181
182    6. Exported RPC Commands
183
184         6.1. lcr.reload
185         6.2. lcr.dump_gws
186         6.3. lcr.dump_lcrs
187
188    7. Known Limitations
189
190 1. Overview
191
192    The Least Cost Routing (LCR) module implements capability to serially
193    forward a request to one or more gateways so that the order in which
194    the gateways is tried is based on admin defined "least cost" rules.
195
196    The LCR module supports many independent LCR instances (gateways and
197    least cost rules). Each such instance has its own LCR identifier.
198
199    For the purpose of facilitating least cost routing of requests, each
200    gateway of an LCR instance belongs to a gateway group and each gateway
201    group is associated with one or more <prefix, from pattern, priority>
202    tuples. A gateway matches a request if the user part of the Request URI
203    matches a "prefix" and the caller's URI matches a "from" pattern in a
204    tuple that belongs to the group of the gateway.
205
206    When the function load_gws() is called, matching gateways (that are not
207    currently designated as defunct) are ordered for forwarding purposes in
208    the following order:
209      * (1) according to longest user part match
210      * (2) according to tuple's priority
211      * (3) gateway's randomized weight within its group
212
213    Prefix is a string of characters or NULL. From pattern is a regular
214    expression (see 'man pcresyntax' for syntax), an empty string, or NULL.
215    An empty or NULL from pattern or prefix matches anything. Smaller
216    priority value means higher priority (highest priority value being 0).
217    Weight is an integer value from 1 to 254.
218
219    The function next_gw() can then be used to select one gateway at a time
220    for forwarding. Upon each call, the user part of the original request
221    URI is first stripped by the number of characters as specified by the
222    gateway's strip count and then prefixed by the gateway's tag. Upon
223    first call, if a gateway's hostname is NULL, the request URI will be
224    rewritten based on gateway's URI scheme, IP address, port, and
225    transport protocol. If hostname is not NULL, the request-URI is
226    rewritten based on the gateway's URI scheme and hostname, and
227    destination URI is set based on gateway's URI scheme, IP address, port,
228    and transport protocol. Upon subsequent calls, the same is done, but
229    instead of rewriting the Request URI, a new branch is added.
230
231    Valid URI scheme values are NULL = sip, 1 = sip and 2 = sips. Currently
232    valid transport protocol values are NULL = none, 1 = udp, 2 = tcp, 3 =
233    tls, and 4 = sctp.
234
235    As a side effect of the gateway selection, the gateway's flags (that
236    may contain information about capabilities of the gateway) are stored
237    into an AVP.
238
239 2. Dependencies
240
241    2.1. SIP Router modules
242    2.2. External libraries or applications
243
244 2.1. SIP Router modules
245
246    The following modules must be loaded before this module:
247      * TM module
248      * A database module like mysql, postgres or dbtext.
249
250 2.2. External libraries or applications
251
252    The following libraries or applications must be installed before
253    running SIP Router with this module:
254      * none.
255
256 3. Exported Parameters
257
258    3.1. db_url (string)
259    3.2. gw_table (string)
260    3.3. lcr_id_column (string)
261    3.4. gw_name_column (string)
262    3.5. grp_id_column (string)
263    3.6. ip_addr_column (string)
264    3.7. hostname_column (string)
265    3.8. port_column (string)
266    3.9. uri_scheme_column (string)
267    3.10. transport_column (string)
268    3.11. strip_column (string)
269    3.12. tag_column (string)
270    3.13. weight_column (string)
271    3.14. flags_column (string)
272    3.15. defunct_column (string)
273    3.16. lcr_table (string)
274    3.17. prefix_column (string)
275    3.18. from_uri_column (string)
276    3.19. priority_column (string)
277    3.20. lcr_count (integer)
278    3.21. gw_uri_avp (AVP string)
279    3.22. ruri_user_avp (AVP string)
280    3.23. flags_avp (AVP string)
281    3.24. defunct_capability (integer)
282    3.25. lcr_id_avp (AVP string)
283    3.26. defunct_gw_avp (AVP string)
284    3.27. lcr_hash_size (integer)
285    3.28. fetch_rows (integer)
286
287 3.1. db_url (string)
288
289    URL of the database table to be used.
290
291    Default value is "mysql://openserro:openserro@localhost/openser".
292
293    Example 1.1. Setting db_url module parameter
294 ...
295 modparam("lcr","db_url","dbdriver://username:password@dbhost/dbname")
296 ...
297
298 3.2. gw_table (string)
299
300    Name of the table holding gateways definitions.
301
302    Default value is "gw".
303
304    Example 1.2. Setting gw_table module parameter
305 ...
306 modparam("lcr","gw_table","gw")
307 ...
308
309 3.3. lcr_id_column (string)
310
311    Name of the column holding the identifier of an LCR instance. Common to
312    both gw and lcr tables.
313
314    Default value is "lcr_id".
315
316    Example 1.3. Setting lcr_id_column module parameter
317 ...
318 modparam("lcr", "lcr_id_column", "lcr_identifier")
319 ...
320
321 3.4. gw_name_column (string)
322
323    Name of the column holding the gateway name.
324
325    Default value is "gw_name".
326
327    Example 1.4. Setting gw_name_column module parameter
328 ...
329 modparam("lcr","gw_name_column","gw_name")
330 ...
331
332 3.5. grp_id_column (string)
333
334    Name of the column holding the group ID of gateway both in gw and lcr
335    tables.
336
337    Default value is "grp_id".
338
339    Example 1.5. Setting grp_id_column module parameter
340 ...
341 modparam("lcr","grp_id_column","grp_id")
342 ...
343
344 3.6. ip_addr_column (string)
345
346    Name of the column holding the IP address of the gateway.
347
348    Default value is "ip_addr".
349
350    Example 1.6. Setting ip_addr_column module parameter
351 ...
352 modparam("lcr","ip_addr_column","ip_addr")
353 ...
354
355 3.7. hostname_column (string)
356
357    Name of the column holding gateway's hostname that is used in
358    Request-URI, when request is sent to the gateway. Note that request is
359    not forwarded based on hostname, but based on gateway's IP address in
360    destination URI.
361
362    Default value is "hostname".
363
364    Example 1.7. Setting hostname_column module parameter
365 ...
366 modparam("lcr", "hostname_column","hostname")
367 ...
368
369 3.8. port_column (string)
370
371    Name of the column holding the port number of the gateway.
372
373    Default value is "port".
374
375    Example 1.8. Setting port_column module parameter
376 ...
377 modparam("lcr","port_column","port")
378 ...
379
380 3.9. uri_scheme_column (string)
381
382    Name of the column holding the uri scheme of the gateway.
383
384    Default value is "uri_scheme".
385
386    Example 1.9. Setting uri_scheme_column module parameter
387 ...
388 modparam("lcr","uri_scheme_column","uri_scheme")
389 ...
390
391 3.10. transport_column (string)
392
393    Name of the column holding the transport type to be used for the
394    gateway.
395
396    Default value is "transport".
397
398    Example 1.10. Setting transport_column module parameter
399 ...
400 modparam("lcr","transport_column","transport")
401 ...
402
403 3.11. strip_column (string)
404
405    Name of the column holding the number of characters to be stripped from
406    the front of Request URI user part before inserting tag.
407
408    Default value is "strip".
409
410    Example 1.11. Setting strip_column module parameter
411 ...
412 modparam("lcr","strip_column","strip_count")
413 ...
414
415 3.12. tag_column (string)
416
417    Name of the column holding gateway specific tag string.
418
419    Default value is "tag".
420
421    Example 1.12. Setting tag_column module parameter
422 ...
423 modparam("lcr","tag_column","gw_tag")
424 ...
425
426 3.13. weight_column (string)
427
428    Name of the column holding gateway's weight within its group.
429
430    Default value is "weight".
431
432    Example 1.13. Setting weight_column module parameter
433 ...
434 modparam("lcr","weight_column","gw_weight")
435 ...
436
437 3.14. flags_column (string)
438
439    Name of the column holding gateway specific flag values.
440
441    Default value is "flags".
442
443    Example 1.14. Setting flags_column module parameter
444 ...
445 modparam("lcr","flags_column","gw_flags")
446 ...
447
448 3.15. defunct_column (string)
449
450    Name of the column holding UNIX timestamp telling the time until which
451    the gw is considered as defunct.
452
453    Default value is "defunct".
454
455    Example 1.15. Setting defunct_column module parameter
456 ...
457 modparam("lcr","defunct_column","defunct_until")
458 ...
459
460 3.16. lcr_table (string)
461
462    Name of the table holding the LCR rules.
463
464    Default value is "lcr".
465
466    Example 1.16. Setting lcr_table module parameter
467 ...
468 modparam("lcr","lcr_table","lcr")
469 ...
470
471 3.17. prefix_column (string)
472
473    Name of the column holding prefix of Request URI user part.
474
475    Default value is "prefix".
476
477    Example 1.17. Setting prefix_column module parameter
478 ...
479 modparam("lcr","prefix_column","prefix")
480 ...
481
482 3.18. from_uri_column (string)
483
484    Name of the column holding the FROM (source) URI.
485
486    Default value is "from_uri".
487
488    Example 1.18. Setting from_uri_column module parameter
489 ...
490 modparam("lcr","from_uri_column","from_uri")
491 ...
492
493 3.19. priority_column (string)
494
495    Name of the column holding the priority of the rule.
496
497    Default value is "priority".
498
499    Example 1.19. Setting priority_column module parameter
500 ...
501 modparam("lcr","priority_column","priority")
502 ...
503
504 3.20. lcr_count (integer)
505
506    Number of LCR instances.
507
508    Default value is 1.
509
510    Example 1.20. Setting lcr_count module parameter
511 ...
512 modparam("lcr", "lcr_count", 10)
513 ...
514
515 3.21. gw_uri_avp (AVP string)
516
517    Internal AVP that load_gws() function uses to store information of
518    matching gateways.
519
520    There is NO default value, thus this variable must be defined in
521    sip-router.cfg.
522
523    Example 1.21. Setting gw_uri_avp module parameter
524 ...
525 modparam("lcr", "gw_uri_avp", "$avp(i:709)")
526 ...
527
528 3.22. ruri_user_avp (AVP string)
529
530    Internal AVP that next_gw function uses to store Request-URI user for
531    subsequent next_gw calls.
532
533    There is NO default value, thus this variable must be defined in
534    sip-router.cfg.
535
536    Example 1.22. Setting ruri_user_avp module parameter
537 ...
538 modparam("lcr", "ruri_user_avp", "$avp(i:500)")
539 ...
540
541 3.23. flags_avp (AVP string)
542
543    An AVP where successful next_gw and from_gw functions store gateway's
544    flags.
545
546    There is NO default value, thus this variable must be defined in
547    sip-router.cfg.
548
549    Example 1.23. Setting flags_avp module parameter
550 ...
551 modparam("lcr", "flags_avp", "$avp(i:712)")
552 ...
553
554 3.24. defunct_capability (integer)
555
556    Tells if defunct capability of (non-responsive) gateways is supported.
557    Non-zero value turns on defunct capability.
558
559    Default value is 0.
560
561    Example 1.24. Setting defunct_capability module parameter
562 ...
563 modparam("lcr", "defunct_capability", 1)
564 ...
565
566 3.25. lcr_id_avp (AVP string)
567
568    Internal AVP that load_gws() function uses to store LCR instance
569    identifier of loaded gateways. Only needed if gateway defunct
570    capability has been activated.
571
572    There is NO default value.
573
574    Example 1.25. Setting lcr_id_avp module parameter
575 ...
576 modparam("lcr", "lcr_id_avp", "$avp(s:lcr_id_avp)")
577 ...
578
579 3.26. defunct_gw_avp (AVP string)
580
581    Internal AVP that next_gw() function uses to store IP address of the
582    selected gateway for later use by defunct_gw() function. Only needed if
583    gateway defunct capability has been activated.
584
585    There is NO default value.
586
587    Example 1.26. Setting defunct_gw_avp module parameter
588 ...
589 modparam("lcr", "defunct_gw_avp", "$avp(s:defunct_gw_avp)")
590 ...
591
592 3.27. lcr_hash_size (integer)
593
594    Defines the size of hash table used to store <prefix, from_pattern,
595    priority> tuples. Hashing is done based on prefix. Larger value means
596    less collisions with other prefixes. Hash size value should be a power
597    of 2.
598
599    Default value is 128.
600
601    Example 1.27. Setting lcr_hash_size module parameter
602 ...
603 modparam("lcr", "lcr_hash_size", 1024)
604 ...
605
606 3.28. fetch_rows (integer)
607
608    The number of the rows to be fetched at once from database when loading
609    data from the lcr table. This value can be used to tune the load time
610    at startup. For 1MB of private memory (default) it should be below
611    3750. In order for this parameter to have effect, the database driver
612    must support fetch_result() capability.
613
614    Default value is "2000".
615
616    Example 1.28. Set fetch_rows parameter
617 ...
618 modparam("lcr", "fetch_rows", 3000)
619 ...
620
621 4. Exported Functions
622
623    4.1. load_gws(lcr_id, caller_uri)
624    4.2. next_gw()
625    4.3. defunct_gw(period)
626    4.4. from_gw(lcr_id [, ip_addr])
627    4.5. from_any_gw([ip_addr])
628    4.6. to_gw(lcr_id [, ip_addr])
629    4.7. to_any_gw([ip_addr])
630
631 4.1. load_gws(lcr_id, caller_uri)
632
633    Loads URI schemes, IP addresses, hostnames, ports, and transports of
634    matching gateways to gw_uri_avp (see Overview section). Argument lcr_id
635    specifies the used LCR instance. It can be an integer or a pseudo
636    variable containing an integer value. Caller's URI is given by
637    caller_uri argument, which must be a pseudo variable.
638
639    Returns 1 on success and -1 on error.
640
641    Execution time of load_gws() function is O(N) * O(M), where N is number
642    of different prefix lengths and M is number of collisions for matching
643    prefix(es) in lcr hash table of the LCR instance.
644
645    This function can be used from REQUEST_ROUTE.
646
647    Example 1.29. load_gws usage
648 ...
649 if (!load_gws("1", "$var(caller_uri)")) {
650         sl_send_reply("500", "Server Internal Error - Cannot load gateways");
651         exit;
652 };
653 ...
654
655 4.2. next_gw()
656
657    Upon first call, replaces URI scheme, host, port, and transport of
658    Request-URI by the values stored in first gw_uri_avp and destroys that
659    AVP (see Overview section). Saves user part of Request-URI into
660    ruri_user_avp for use in subsequent next_gw() calls.
661
662    Upon subsequent calls, appends a new branch URI to the request, where
663    URI scheme, host, port, and transport of are taken from values stored
664    in the first gw_uri_avp and destroys that AVP. URI user is taken from
665    ruri_user_avp.
666
667    As a side effect, stores gateway's flags to flags_avp.
668
669    Returns 1 on success and -1 if there were no gateways left or if an
670    error occurred (see syslog).
671
672    Must be preceded by successful load_gws() call.
673
674    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
675
676    Example 1.30. next_gw usage from a route block
677 ...
678 if (!next_gw()) {
679         sl_send_reply("503", "Service not available - No gateways");
680         exit;
681 };
682 ...
683
684    Example 1.31. next_gw usage from a failure route block
685 ...
686 if (!next_gw()) {
687         t_reply("503", "Service not available - No more gateways");
688         exit;
689 };
690 ...
691
692 4.3. defunct_gw(period)
693
694    Defuncts gateway selected by preceding next_gw() call for a period of
695    seconds given as argument. Argument must be a positive integer constant
696    or a pseudo variable with positive integer value. Value of defunct
697    column in database is not updated.
698
699    Returns 1 on success and -1 in case of error (see syslog).
700
701    Must be preceded by successful next_gw() call.
702
703    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
704
705    Example 1.32. defunct_gw usage
706 ...
707 defunct_gw("60");
708 ...
709
710 4.4. from_gw(lcr_id [, ip_addr])
711
712    Checks if request comes from IP address of a gateway in LCR instance
713    specified by lcr_id argument, which can be an integer constant or a
714    pseudo variable with integer value. IP address to be checked is either
715    taken from source IP address of the request or (if present) from
716    ip_addr pseudo variable argument.
717
718    If request comes from a gateway, gateway's flags are stored into
719    flags_avp as side effect.
720
721    Returns 1 on success and -1 on failure or on error.
722
723    Execution time of from_gw() function is O(log N), where N is number of
724    gateways in the LCR instance.
725
726    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
727    ONREPLY_ROUTE.
728
729    Example 1.33. from_gw usage
730 ...
731 if (from_gw("1", "$avp(s:real_source_addr)") {
732         ...
733 };
734 ...
735
736 4.5. from_any_gw([ip_addr])
737
738    Checks if request comes from IP address of any gateway. IP address to
739    be checked is either taken from source IP address of the request or (if
740    present) from ip_addr pseudo variable argument.
741
742    If any gateway has the IP address, function returns LCR identifier of
743    the gateway. Returns -1 on error or if the request does not come from a
744    gateway.
745
746    If request comes from a gateway, the gateway's flags are stored into
747    flags_avp as side effect.
748
749    Execution time of from_gw() function is M * O(log N), where M is number
750    of LCR instances and N is average number of gateways in LCR instances.
751
752    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
753    ONREPLY_ROUTE.
754
755    Example 1.34. from_gw usage
756 ...
757 $var(lcr_id) = from_any_gw();
758 ...
759
760 4.6. to_gw(lcr_id [, ip_addr])
761
762    Checks if in-dialog request goes to a gateway in LCR instance specified
763    by lcr_id argument. IP address to be checked is either taken from
764    Request-URI hostpart or (if present) from ip_addr pseudo variable
765    argument.
766
767    Returns 1 on success and -1 on failure and error.
768
769    Execution time of to_gw() function is O(log N), where N is number of
770    gateways in the LCR instance.
771
772    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
773
774    Example 1.35. to_gw usage
775 ...
776 if (to_gw("1")) {
777         ...
778         exit;
779 };
780 ...
781
782 4.7. to_any_gw([ip_addr])
783
784    Checks if in-dialog request goes to any gateway. IP address to be
785    checked is either taken from Request-URI hostpart or (if present) from
786    ip_addr pseudo variable argument.
787
788    Execution time of to_any_gw() function is M * O(log N), where M is
789    number of LCR instances and N is average number of gateways in LCR
790    instances.
791
792    If any gateway has the IP address, returns LCR identifier of the
793    gateway. Returns -1 if request does not go to a gateway and on error.
794
795    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
796
797    Example 1.36. to_gw usage
798 ...
799 if (to_any_gw()) {
800         ...
801         exit;
802 };
803 ...
804
805 5. Exported MI Commands
806
807    5.1. lcr_reload
808    5.2. lcr_gw_dump
809    5.3. lcr_lcr_dump
810
811 5.1. lcr_reload
812
813    Causes lcr module to re-read the contents of gw and lcr tables into
814    memory.
815
816    Reload fails if number of gateways is larger than value of constant
817    MAX_NO_OF_GWS in file lcr_mod.h, which defaults to 128. If you have
818    more than 128 gateways, you need to increase the value of this constant
819    and recompile lcr module.
820
821    Name: lcr_reload
822
823    Parameters: none
824
825    MI FIFO Command Format:
826                 :lcr_reload:_reply_fifo_file_
827                 _empty_line_
828
829 5.2. lcr_gw_dump
830
831    Causes lcr module to dump the contents of its in-memory gw table.
832
833    Name: lcr_gw_dump
834
835    Parameters: none
836
837    MI FIFO Command Format:
838                 :lcr_gw_dump:_reply_fifo_file_
839                 _empty_line_
840
841 5.3. lcr_lcr_dump
842
843    Causes lcr module to dump the contents of its in-memory lcr table.
844
845    Name: lcr_lcr_dump
846
847    Parameters: none
848
849    MI FIFO Command Format:
850                 :lcr_gw_dump:_reply_fifo_file_
851                 _empty_line_
852
853 6. Exported RPC Commands
854
855    6.1. lcr.reload
856    6.2. lcr.dump_gws
857    6.3. lcr.dump_lcrs
858
859 6.1. lcr.reload
860
861    Causes lcr module to re-read the contents of gw and lcr tables into
862    memory.
863
864    Name: lcr.reload
865
866    Parameters: none
867
868    Example 1.37. lcr.reload RPC example
869                 $ sercmd lcr.reload
870
871 6.2. lcr.dump_gws
872
873    Causes lcr module to dump the contents of its in-memory gw table.
874
875    Parameters: none
876
877    Example 1.38. lcr.dump_gws RPC example
878                 $ sercmd lcr.dump_gws
879
880 6.3. lcr.dump_lcrs
881
882    Causes lcr module to dump the contents of its in-memory lcr table.
883
884    Parameters: none
885
886    Example 1.39. lcr.dump_lcr RPC example
887                 $ sercmd lcr.dump_lcrs
888
889 7. Known Limitations
890
891    In-memory gateway and in-memory lcr table are switched by two
892    consecutive machine instructions. If lcr reload process is interrupted
893    after the first one, in-memory gateway table does not match in-memory
894    lcr table until execution of lcr reload process is resumed.