modules/lcr: Fixed to/from_gw tests when proto parameter is 0 (ANY)
[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-2010 Juha Heinanen
14      __________________________________________________________________
15
16    Table of Contents
17
18    1. Admin Guide
19
20         1. Overview
21         2. Dependencies
22
23               2.1. SIP Router modules
24               2.2. External libraries or applications
25
26         3. Parameters
27
28               3.1. db_url (string)
29               3.2. lcr_gw_table (string)
30               3.3. id_column (string)
31               3.4. lcr_id_column (string)
32               3.5. gw_name_column (string)
33               3.6. ip_addr_column (string)
34               3.7. hostname_column (string)
35               3.8. port_column (string)
36               3.9. params_column (string)
37               3.10. uri_scheme_column (string)
38               3.11. transport_column (string)
39               3.12. strip_column (string)
40               3.13. tag_column (string)
41               3.14. flags_column (string)
42               3.15. defunct_column (string)
43               3.16. lcr_rule_table (string)
44               3.17. prefix_column (string)
45               3.18. from_uri_column (string)
46               3.19. request_uri_column (string)
47               3.20. stopper_column (string)
48               3.21. enabled_column (string)
49               3.22. lcr_rule_target_table (string)
50               3.23. rule_id_column (string)
51               3.24. gw_id_column (string)
52               3.25. priority_column (string)
53               3.26. weight_column (string)
54               3.27. lcr_count (integer)
55               3.28. gw_uri_avp (AVP string)
56               3.29. ruri_user_avp (AVP string)
57               3.30. tag_avp (AVP string)
58               3.31. flags_avp (AVP string)
59               3.32. defunct_capability (integer)
60               3.33. lcr_id_avp (AVP string)
61               3.34. defunct_gw_avp (AVP string)
62               3.35. lcr_rule_hash_size (integer)
63               3.36. lcr_gw_count (integer)
64               3.37. dont_strip_or_tag_flag (integer)
65               3.38. fetch_rows (integer)
66
67         4. Functions
68
69               4.1. load_gws(lcr_id[, uri_user[, caller_uri]])
70               4.2. next_gw()
71               4.3. defunct_gw(period)
72               4.4. from_gw(lcr_id[, ip_addr, proto])
73               4.5. from_any_gw([ip_addr, proto])
74               4.6. to_gw(lcr_id[, ip_addr, proto])
75               4.7. to_any_gw([ip_addr, proto])
76
77         5. Exported RPC Commands
78
79               5.1. lcr.reload
80               5.2. lcr.dump_gws
81               5.3. lcr.dump_rules
82               5.4. lcr.defunct_gw
83
84         6. Known Limitations
85
86    List of Examples
87
88    1.1. Setting db_url module parameter
89    1.2. Setting gw_table module parameter
90    1.3. Setting id_column module parameter
91    1.4. Setting lcr_id_column module parameter
92    1.5. Setting gw_name_column module parameter
93    1.6. Setting ip_addr_column module parameter
94    1.7. Setting hostname_column module parameter
95    1.8. Setting port_column module parameter
96    1.9. Setting params_column module parameter
97    1.10. Setting uri_scheme_column module parameter
98    1.11. Setting transport_column module parameter
99    1.12. Setting strip_column module parameter
100    1.13. Setting tag_column module parameter
101    1.14. Setting flags_column module parameter
102    1.15. Setting defunct_column module parameter
103    1.16. Setting lcr_rule_table module parameter
104    1.17. Setting prefix_column module parameter
105    1.18. Setting from_uri_column module parameter
106    1.19. Setting request_uri_column module parameter
107    1.20. Setting stopper_column module parameter
108    1.21. Setting enabled_column module parameter
109    1.22. Setting lcr_rule_target_table module parameter
110    1.23. Setting rule_id_column module parameter
111    1.24. Setting gw_id_column module parameter
112    1.25. Setting priority_column module parameter
113    1.26. Setting weight_column module parameter
114    1.27. Setting lcr_count module parameter
115    1.28. Setting gw_uri_avp module parameter
116    1.29. Setting ruri_user_avp module parameter
117    1.30. Setting tag_avp module parameter
118    1.31. Setting flags_avp module parameter
119    1.32. Setting defunct_capability module parameter
120    1.33. Setting lcr_id_avp module parameter
121    1.34. Setting defunct_gw_avp module parameter
122    1.35. Setting lcr_rule_hash_size module parameter
123    1.36. Setting lcr_gw_count module parameter
124    1.37. Setting dont_strip_or_tag_flag module parameter
125    1.38. Set fetch_rows parameter
126    1.39. load_gws usage
127    1.40. next_gw usage from a route block
128    1.41. next_gw usage from a failure route block
129    1.42. defunct_gw usage
130    1.43. from_gw usage
131    1.44. from_gw usage
132    1.45. to_gw usage
133    1.46. to_gw usage
134    1.47. lcr.reload RPC example
135    1.48. lcr.dump_gws RPC example
136    1.49. lcr.dump_rules RPC example
137    1.50. lcr.defunct_gw RPC example
138
139 Chapter 1. Admin Guide
140
141    Table of Contents
142
143    1. Overview
144    2. Dependencies
145
146         2.1. SIP Router modules
147         2.2. External libraries or applications
148
149    3. Parameters
150
151         3.1. db_url (string)
152         3.2. lcr_gw_table (string)
153         3.3. id_column (string)
154         3.4. lcr_id_column (string)
155         3.5. gw_name_column (string)
156         3.6. ip_addr_column (string)
157         3.7. hostname_column (string)
158         3.8. port_column (string)
159         3.9. params_column (string)
160         3.10. uri_scheme_column (string)
161         3.11. transport_column (string)
162         3.12. strip_column (string)
163         3.13. tag_column (string)
164         3.14. flags_column (string)
165         3.15. defunct_column (string)
166         3.16. lcr_rule_table (string)
167         3.17. prefix_column (string)
168         3.18. from_uri_column (string)
169         3.19. request_uri_column (string)
170         3.20. stopper_column (string)
171         3.21. enabled_column (string)
172         3.22. lcr_rule_target_table (string)
173         3.23. rule_id_column (string)
174         3.24. gw_id_column (string)
175         3.25. priority_column (string)
176         3.26. weight_column (string)
177         3.27. lcr_count (integer)
178         3.28. gw_uri_avp (AVP string)
179         3.29. ruri_user_avp (AVP string)
180         3.30. tag_avp (AVP string)
181         3.31. flags_avp (AVP string)
182         3.32. defunct_capability (integer)
183         3.33. lcr_id_avp (AVP string)
184         3.34. defunct_gw_avp (AVP string)
185         3.35. lcr_rule_hash_size (integer)
186         3.36. lcr_gw_count (integer)
187         3.37. dont_strip_or_tag_flag (integer)
188         3.38. fetch_rows (integer)
189
190    4. Functions
191
192         4.1. load_gws(lcr_id[, uri_user[, caller_uri]])
193         4.2. next_gw()
194         4.3. defunct_gw(period)
195         4.4. from_gw(lcr_id[, ip_addr, proto])
196         4.5. from_any_gw([ip_addr, proto])
197         4.6. to_gw(lcr_id[, ip_addr, proto])
198         4.7. to_any_gw([ip_addr, proto])
199
200    5. Exported RPC Commands
201
202         5.1. lcr.reload
203         5.2. lcr.dump_gws
204         5.3. lcr.dump_rules
205         5.4. lcr.defunct_gw
206
207    6. Known Limitations
208
209 1. Overview
210
211    The Least Cost Routing (LCR) module implements capability to serially
212    forward a request to one or more gateways so that the order in which
213    the gateways is tried is based on admin defined "least cost" rules.
214
215    The LCR module supports many independent LCR instances (gateways and
216    least cost rules). Each such instance has its own LCR instance
217    identifier. Identifiers of normal LCR instances are positive integers.
218    Gateways may belong to special LCR instance with identifier 0 meaning
219    that such gateways belong to all normal LCR instances.
220
221    For the purpose of facilitating least cost routing of requests, each
222    gateway of an LCR instance is associated with one or more <prefix, from
223    uri pattern, request uri pattern, priority, weight> tuples. A gateway
224    matches a request if user part of the Request-URI matches a "prefix",
225    the caller's URI matches a "From-URI" pattern and the callee's URI
226    matches a "Request-URI" pattern in a tuple that is associated with the
227    gateway.
228
229    When the function load_gws() is called, matching gateways (that are not
230    currently designated as defunct) are ordered for forwarding purposes as
231    follows:
232
233      * (1) according to longest Request-URI user part match
234      * (2) according to tuple's priority
235      * (3) according to tuple's randomized weight
236
237    A tuple can be marked as a "stopper" tuple. If a "stopper" tuple
238    matches, then matching stops at it and all other tuples with shorter
239    prefixes are not considered.
240
241    Prefix is a string of characters or NULL. From-URI pattern and
242    Request-URI pattern are regular expressions (see 'man pcresyntax' for
243    syntax), an empty string, or NULL. An empty or NULL From-URI pattern,
244    Request-URI pattern or prefix matches anything. Smaller priority value
245    means higher priority (highest priority value being 0 and lowest being
246    255).
247
248    Weight is an integer value from 1 to 254. Weight implementation is
249    fast, but unfair favoring larger weight values at the expense smaller
250    ones. For example, if two gateways have weights 1 and 2, probability
251    that the gateway with weight 1 is tried first is 1/4, not 1/3. Two
252    scripts are provided in lcr/utils directory that can be used to check
253    the probabilities resulting from a given set of weight values. Same can
254    be done with command 'kamctl eval_weights'.
255
256    The function next_gw() can then be used to select one gateway at a time
257    for forwarding. Upon each call, unless "dont_strip_or_tag_flag" flag is
258    set, user part of the original Request-URI is first stripped by the
259    number of characters as specified by the gateway's strip count and then
260    prefixed by the gateway's prefix. Upon each call, if a gateway's
261    hostname is NULL, Request-URI will be rewritten based on gateway's URI
262    scheme, IP address, port, parameters, and transport protocol. If
263    hostname is not NULL and IP address is NULL, Request-URI will be
264    rewritten based on the gateway's URI scheme, hostname, port, parameters
265    and transport protocol. If both hostname and IP address are not NULL,
266    Request-URI will be rewritten based on gateway's URI scheme, hostname,
267    and parameters, and destination URI is set based on gateway's URI
268    scheme, IP address, port, and transport protocol.
269
270    Valid URI scheme values are NULL = sip, 1 = sip and 2 = sips. Currently
271    valid transport protocol values are NULL and 0 = none, 1 = udp, 2 =
272    tcp, 3 = tls, and 4 = sctp.
273
274    As a side effect of gateway selection, selected gateway's tag and flags
275    (that may contain information about the gateway and its capabilities)
276    are stored to tag_avp and flags_avp, respectively, if the corresponding
277    module parameter has been defined.
278
279 2. Dependencies
280
281    2.1. SIP Router modules
282    2.2. External libraries or applications
283
284 2.1. SIP Router modules
285
286    The following modules must be loaded before this module:
287      * A database module like mysql, postgres or dbtext.
288
289 2.2. External libraries or applications
290
291    The following libraries or applications must be installed before
292    running SIP Router with this module:
293      * libpcre
294
295 3. Parameters
296
297    3.1. db_url (string)
298    3.2. lcr_gw_table (string)
299    3.3. id_column (string)
300    3.4. lcr_id_column (string)
301    3.5. gw_name_column (string)
302    3.6. ip_addr_column (string)
303    3.7. hostname_column (string)
304    3.8. port_column (string)
305    3.9. params_column (string)
306    3.10. uri_scheme_column (string)
307    3.11. transport_column (string)
308    3.12. strip_column (string)
309    3.13. tag_column (string)
310    3.14. flags_column (string)
311    3.15. defunct_column (string)
312    3.16. lcr_rule_table (string)
313    3.17. prefix_column (string)
314    3.18. from_uri_column (string)
315    3.19. request_uri_column (string)
316    3.20. stopper_column (string)
317    3.21. enabled_column (string)
318    3.22. lcr_rule_target_table (string)
319    3.23. rule_id_column (string)
320    3.24. gw_id_column (string)
321    3.25. priority_column (string)
322    3.26. weight_column (string)
323    3.27. lcr_count (integer)
324    3.28. gw_uri_avp (AVP string)
325    3.29. ruri_user_avp (AVP string)
326    3.30. tag_avp (AVP string)
327    3.31. flags_avp (AVP string)
328    3.32. defunct_capability (integer)
329    3.33. lcr_id_avp (AVP string)
330    3.34. defunct_gw_avp (AVP string)
331    3.35. lcr_rule_hash_size (integer)
332    3.36. lcr_gw_count (integer)
333    3.37. dont_strip_or_tag_flag (integer)
334    3.38. fetch_rows (integer)
335
336 3.1. db_url (string)
337
338    URL of the database table to be used.
339
340    Default value is “mysql://openserro:openserro@localhost/openser”.
341
342    Example 1.1. Setting db_url module parameter
343 ...
344 modparam("lcr","db_url","dbdriver://username:password@dbhost/dbname")
345 ...
346
347 3.2. lcr_gw_table (string)
348
349    Name of the table holding gateways definitions.
350
351    Default value is “lcr_gw”.
352
353    Example 1.2. Setting gw_table module parameter
354 ...
355 modparam("lcr", "lcr_gw_table","gw")
356 ...
357
358 3.3. id_column (string)
359
360    Name of the auto-increment, primary key column. Common to all lcr
361    module tables.
362
363    Default value is “id”.
364
365    Example 1.3. Setting id_column module parameter
366 ...
367 modparam("lcr", "id_column", "row_id")
368 ...
369
370 3.4. lcr_id_column (string)
371
372    Name of the column holding the identifier of an LCR instance. Common to
373    all lcr module tables. In lcr_rule and lcr_rule_target tables, value of
374    the column is integer from 1 to lcr_count. In lcr_gw table, value of
375    the column is from 0 to lcr_count.
376
377    Default value is “lcr_id”.
378
379    Example 1.4. Setting lcr_id_column module parameter
380 ...
381 modparam("lcr", "lcr_id_column", "lcr_identifier")
382 ...
383
384 3.5. gw_name_column (string)
385
386    Name of the column holding gateway's name for documentation purpose.
387
388    Default value is “gw_name”.
389
390    Example 1.5. Setting gw_name_column module parameter
391 ...
392 modparam("lcr", "gw_name_column", "name")
393 ...
394
395 3.6. ip_addr_column (string)
396
397    Name of the column holding the IPv4 or IPv6 address of the gateway.
398
399    Default value is “ip_addr”.
400
401    Example 1.6. Setting ip_addr_column module parameter
402 ...
403 modparam("lcr", "ip_addr_column", "ip")
404 ...
405
406 3.7. hostname_column (string)
407
408    Name of the column holding gateway's hostname that is used in
409    Request-URI hostpart, when request is sent to the gateway.
410
411    Default value is “hostname”.
412
413    Example 1.7. Setting hostname_column module parameter
414 ...
415 modparam("lcr", "hostname_column", "host")
416 ...
417
418 3.8. port_column (string)
419
420    Name of the column holding the port number of the gateway.
421
422    Default value is “port”.
423
424    Example 1.8. Setting port_column module parameter
425 ...
426 modparam("lcr", "port_column", "port")
427 ...
428
429 3.9. params_column (string)
430
431    Name of the column holding gateway's parameters that is used in
432    Request-URI, when request is sent to the gateway.
433
434    Default value is “params”.
435
436    Example 1.9. Setting params_column module parameter
437 ...
438 modparam("lcr", "params_column", "parameters")
439 ...
440
441 3.10. uri_scheme_column (string)
442
443    Name of the column holding the uri scheme of the gateway.
444
445    Default value is “uri_scheme”.
446
447    Example 1.10. Setting uri_scheme_column module parameter
448 ...
449 modparam("lcr", "uri_scheme_column", "uri_scheme")
450 ...
451
452 3.11. transport_column (string)
453
454    Name of the column holding the transport protocol to be used for the
455    gateway.
456
457    Default value is “transport”.
458
459    Example 1.11. Setting transport_column module parameter
460 ...
461 modparam("lcr", "transport_column", "trans")
462 ...
463
464 3.12. strip_column (string)
465
466    Name of the column holding the number of characters to be stripped from
467    the front of Request-URI user part before inserting tag.
468
469    Default value is “strip”.
470
471    Example 1.12. Setting strip_column module parameter
472 ...
473 modparam("lcr", "strip_column", "strip_count")
474 ...
475
476 3.13. tag_column (string)
477
478    Name of the column holding gateway specific tag string that is added to
479    Request URI userpart after stripping.
480
481    Default value is “tag”.
482
483    Example 1.13. Setting tag_column module parameter
484 ...
485 modparam("lcr", "tag_column", "gw_tag")
486 ...
487
488 3.14. flags_column (string)
489
490    Name of the column holding gateway specific flag values.
491
492    Default value is “flags”.
493
494    Example 1.14. Setting flags_column module parameter
495 ...
496 modparam("lcr", "flags_column", "gw_flags")
497 ...
498
499 3.15. defunct_column (string)
500
501    Name of the column holding UNIX timestamp telling the time until which
502    the gw is considered as defunct. If timestamp value is 4294967295 (=
503    max UNIX timestamp value) or greater, gw is considered currently unused
504    and is not loaded into memory at all.
505
506    Default value is “defunct”.
507
508    Example 1.15. Setting defunct_column module parameter
509 ...
510 modparam("lcr", "defunct_column", "defunct_until")
511 ...
512
513 3.16. lcr_rule_table (string)
514
515    Name of the table holding the LCR rules.
516
517    Default value is “lcr_rule”.
518
519    Example 1.16. Setting lcr_rule_table module parameter
520 ...
521 modparam("lcr", "lcr_rule_table", "rules")
522 ...
523
524 3.17. prefix_column (string)
525
526    Name of the column holding prefix of Request-URI user part and prefix
527    of gateway.
528
529    Default value is “prefix”.
530
531    Example 1.17. Setting prefix_column module parameter
532 ...
533 modparam("lcr", "prefix_column", "number_prefix")
534 ...
535
536 3.18. from_uri_column (string)
537
538    Name of the column holding the From (caller's) URI.
539
540    Default value is “from_uri”.
541
542    Example 1.18. Setting from_uri_column module parameter
543 ...
544 modparam("lcr", "from_uri_column", "caller_uri")
545 ...
546
547 3.19. request_uri_column (string)
548
549    Name of the column holding the regular expression to match against the
550    complete request URI (including the "sip:" prefix).
551
552    Default value is “request_uri”.
553
554    Example 1.19. Setting request_uri_column module parameter
555 ...
556 modparam("lcr", "request_uri_column", "callee_uri")
557 ...
558
559 3.20. stopper_column (string)
560
561    Name of the column holding rule's stopper attribute.
562
563    Default value is “stopper”.
564
565    Example 1.20. Setting stopper_column module parameter
566 ...
567 modparam("lcr", "stopper_column", "stop")
568 ...
569
570 3.21. enabled_column (string)
571
572    Name of the column telling is the rule is currently enabled or
573    disabled.
574
575    Default value is “enabled”.
576
577    Example 1.21. Setting enabled_column module parameter
578 ...
579 modparam("lcr", "enabled_column", "in_use")
580 ...
581
582 3.22. lcr_rule_target_table (string)
583
584    Name of the table holding information about the LCR rule targets
585    (gateways).
586
587    Default value is “lcr_rule_target”.
588
589    Example 1.22. Setting lcr_rule_target_table module parameter
590 ...
591 modparam("lcr", "lcr_rule_target_table", "rules")
592 ...
593
594 3.23. rule_id_column (string)
595
596    Name of lcr_rule_target_table column containing an id of lcr_rule
597    table.
598
599    Default value is “rule_id”.
600
601    Example 1.23. Setting rule_id_column module parameter
602 ...
603 modparam("lcr", "rule_id_column", "rule")
604 ...
605
606 3.24. gw_id_column (string)
607
608    Name of lcr_rule_target_table column containing an id of lcr_gw table.
609
610    Default value is “gw_id”.
611
612    Example 1.24. Setting gw_id_column module parameter
613 ...
614 modparam("lcr", "gw_id_column", "gw")
615 ...
616
617 3.25. priority_column (string)
618
619    Name of the column holding the priority of the rule target.
620
621    Default value is “priority”.
622
623    Example 1.25. Setting priority_column module parameter
624 ...
625 modparam("lcr", "priority_column", "priority")
626 ...
627
628 3.26. weight_column (string)
629
630    Name of the column holding weight of rule target.
631
632    Default value is “weight”.
633
634    Example 1.26. Setting weight_column module parameter
635 ...
636 modparam("lcr","weight_column", "target_weight")
637 ...
638
639 3.27. lcr_count (integer)
640
641    Number of LCR instances.
642
643    Default value is 1.
644
645    Example 1.27.  Setting lcr_count module parameter
646 ...
647 modparam("lcr", "lcr_count", 10)
648 ...
649
650 3.28. gw_uri_avp (AVP string)
651
652    Internal AVP that load_gws() function uses to store information of
653    matching gateways.
654
655    There is NO default value, thus this variable must be defined in
656    sip-router.cfg.
657
658    Example 1.28. Setting gw_uri_avp module parameter
659 ...
660 modparam("lcr", "gw_uri_avp", "$avp(i:709)")
661 ...
662
663 3.29. ruri_user_avp (AVP string)
664
665    Internal AVP that next_gw function uses to store Request-URI user for
666    subsequent next_gw calls.
667
668    There is NO default value, thus this variable must be defined in
669    sip-router.cfg.
670
671    Example 1.29. Setting ruri_user_avp module parameter
672 ...
673 modparam("lcr", "ruri_user_avp", "$avp(i:500)")
674 ...
675
676 3.30. tag_avp (AVP string)
677
678    If defined, an AVP where successful next_gw and from_gw functions store
679    gateway's tag.
680
681    There is NO default value, i.e, if not defined, gateway's tag is not
682    stored anywhere.
683
684    Example 1.30. Setting tag_avp module parameter
685 ...
686 modparam("lcr", "tag_avp", "$avp(lcr_tag)")
687 ...
688
689 3.31. flags_avp (AVP string)
690
691    If defined, an AVP where successful next_gw and from_gw functions store
692    gateway's flags.
693
694    There is NO default value, i.e, if not defined, gateway's flags are not
695    stored anywhere.
696
697    Example 1.31. Setting flags_avp module parameter
698 ...
699 modparam("lcr", "flags_avp", "$avp(i:712)")
700 ...
701
702 3.32. defunct_capability (integer)
703
704    Tells if defunct capability of (non-responsive) gateways is supported.
705    Non-zero value turns on defunct capability.
706
707    Default value is 0.
708
709    Example 1.32.  Setting defunct_capability module parameter
710 ...
711 modparam("lcr", "defunct_capability", 1)
712 ...
713
714 3.33. lcr_id_avp (AVP string)
715
716    Internal AVP that load_gws() function uses to store LCR instance
717    identifier of loaded gateways. Only needed if gateway defunct
718    capability has been activated.
719
720    There is NO default value.
721
722    Example 1.33. Setting lcr_id_avp module parameter
723 ...
724 modparam("lcr", "lcr_id_avp", "$avp(s:lcr_id_avp)")
725 ...
726
727 3.34. defunct_gw_avp (AVP string)
728
729    Internal AVP that next_gw() function uses to store internal index of
730    the selected gateway for later use by defunct_gw() function. Only
731    needed if gateway defunct capability has been activated.
732
733    There is NO default value.
734
735    Example 1.34. Setting defunct_gw_avp module parameter
736 ...
737 modparam("lcr", "defunct_gw_avp", "$avp(s:defunct_gw_avp)")
738 ...
739
740 3.35. lcr_rule_hash_size (integer)
741
742    Defines the size of hash table used to store LCR rules. Hashing is done
743    based on rule's prefix. Larger value means less collisions with other
744    prefixes. Hash size value should be a power of 2.
745
746    Default value is 128.
747
748    Example 1.35.  Setting lcr_rule_hash_size module parameter
749 ...
750 modparam("lcr", "lcr_rule_hash_size", 1024)
751 ...
752
753 3.36. lcr_gw_count (integer)
754
755    Defines the maximum number of gateways in lcr_gw table.
756
757    Default value is 128.
758
759    Example 1.36.  Setting lcr_gw_count module parameter
760 ...
761 modparam("lcr", "lcr_gw_count", 1024)
762 ...
763
764 3.37. dont_strip_or_tag_flag (integer)
765
766    Defines the flag number used to tell if stripping and tagging is done
767    for the selected gateway.
768
769    Default value is -1 meaning that the flag is not defined.
770
771    Example 1.37.  Setting dont_strip_or_tag_flag module parameter
772 ...
773 modparam("lcr", "dont_strip_or_tag_flag", 10)
774 ...
775
776 3.38. fetch_rows (integer)
777
778    The number of the rows to be fetched at once from database when loading
779    data from lcr_rule table. This value can be used to tune the load time
780    at startup. For 1MB of private memory (default) it should be below
781    3750. In order for this parameter to have effect, the database driver
782    must support fetch_result() capability.
783
784    Default value is “1024”.
785
786    Example 1.38. Set fetch_rows parameter
787 ...
788 modparam("lcr", "fetch_rows", 3000)
789 ...
790
791 4. Functions
792
793    4.1. load_gws(lcr_id[, uri_user[, caller_uri]])
794    4.2. next_gw()
795    4.3. defunct_gw(period)
796    4.4. from_gw(lcr_id[, ip_addr, proto])
797    4.5. from_any_gw([ip_addr, proto])
798    4.6. to_gw(lcr_id[, ip_addr, proto])
799    4.7. to_any_gw([ip_addr, proto])
800
801 4.1.  load_gws(lcr_id[, uri_user[, caller_uri]])
802
803    Loads attributes of matching gateways to gw_uri_avp (see Overview
804    section). Argument lcr_id specifies the used LCR instance. It can be a
805    positive integer or a pseudo variable containing an integer value. If
806    uri_user is given, it is used, instead of Request-URI user part, to
807    look for matching gateways. Caller's URI may be given by caller_uri
808    argument. If caller_uri argument is omitted, it defaults to empty
809    string. Both uri_user and caller_uri argument may be a string or a
810    pseudo variable containing a sting value.
811
812    Returns 1 if at least one matching gateway was found, 2 if no matching
813    gateways was found, and -1 on error.
814
815    Execution time of load_gws() function is O(N) * O(M), where N is number
816    of different prefix lengths and M is number of collisions for matching
817    prefix(es) in lcr rules hash table of the LCR instance.
818
819    This function can be used from REQUEST_ROUTE.
820
821    Example 1.39. load_gws usage
822 ...
823 if (!load_gws(1, $rU, $var(caller_uri))) {
824         sl_send_reply("500", "Server Internal Error - Cannot load gateways");
825         exit;
826 };
827 ...
828
829 4.2.  next_gw()
830
831    Upon first call, fetches attribute values stored in first gw_uri_avp,
832    destroys that AVP, and rewrites Request-URI and possibly also
833    destination URI as described in the Overview section. Saves user part
834    of Request-URI into ruri_user_avp for use in subsequent next_gw()
835    calls.
836
837    Upon subsequent calls, does the same as in above, but takes user part
838    of Request-URI from ruri_user_avp.
839
840    As a side effect, stores gateway's tag and flags to tag_avp and
841    flags_avp, respectively, if the corresponding module parameter has been
842    defined.
843
844    Returns 1 on success and -1 if there were no gateways left or if an
845    error occurred (see syslog).
846
847    Must be preceded by successful load_gws() call.
848
849    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
850
851    Example 1.40. next_gw usage from a route block
852 ...
853 if (!next_gw()) {
854         sl_send_reply("503", "Service not available - No gateways");
855         exit;
856 };
857 ...
858
859    Example 1.41. next_gw usage from a failure route block
860 ...
861 if (!next_gw()) {
862         t_reply("503", "Service not available - No more gateways");
863         exit;
864 };
865 ...
866
867 4.3.  defunct_gw(period)
868
869    Defuncts gateway denoted by lcr_id_avp and defunct_gw_avp (which were
870    set by previuos next_gw() call) for a period of seconds given as
871    argument. Argument must be a positive integer constant or a pseudo
872    variable with positive integer value. Value of defunct column in
873    database is not updated.
874
875    Returns 1 on success and -1 in case of error (see syslog).
876
877    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
878
879    Example 1.42. defunct_gw usage
880 ...
881 defunct_gw(60);
882 ...
883
884 4.4.  from_gw(lcr_id[, ip_addr, proto])
885
886    Checks if request comes from IP address and transport protocol
887    specified for a gateway in LCR instance lcr_id. Fails if the LCR
888    instance includes one or more gateways without IP address. IP address
889    and transport protocol to be checked are either taken from source IP
890    address of the request or (if present) from ip_addr and proto
891    arguments.
892
893    lcr_id can be an integer constant or a pseudo variable holding an
894    integer value. ip_addr can be a string or a pseudo variable holding a
895    string value. proto can be an integer constant (0 = ANY, 1 = UDP, 2 =
896    TCP, 3 = TLS, 4 = SCTP) or a pseudo variable holding such an integer
897    value.
898
899    If request comes from a gateway, gateway's tag and flags are stored as
900    a side effect to tag_avp and flags_avp, respectively, if the
901    corresponding module parameter has been defined.
902
903    Returns 1 on success and -1 on failure or on error.
904
905    Execution time of from_gw() function is O(log N), where N is number of
906    gateways in the LCR instance.
907
908    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
909    ONREPLY_ROUTE.
910
911    Example 1.43. from_gw usage
912 ...
913 if (from_gw(1, $avp(s:real_source_addr), 2) {
914         ...
915 };
916 ...
917
918 4.5.  from_any_gw([ip_addr, proto])
919
920    Checks if request comes from IP address and transport protocol
921    specified for any gateway. Only LCR instances, where all gateways have
922    IP address, are included in the test. IP address and transport protocol
923    to be checked are either taken from source IP address and transport
924    protocol of the request or (if present) from ip_addr and proto
925    arguments. See from_gw() function for more info about the arguments.
926
927    If any gateway has the IP address and transport protocol, function
928    returns LCR identifier of the gateway. Returns -1 on error or if the
929    request does not come from a gateway.
930
931    If request comes from a gateway, gateway's tag and flags are stored as
932    a side effect to tag_avp and flags_avp, respectively, if the
933    corresponding module parameter has been defined.
934
935    Execution time of from_gw() function is M * O(log N), where M is number
936    of LCR instances and N is average number of gateways in LCR instances.
937
938    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
939    ONREPLY_ROUTE.
940
941    Example 1.44. from_gw usage
942 ...
943 $var(lcr_id) = from_any_gw("192.168.1.1", 3);
944 ...
945
946 4.6.  to_gw(lcr_id[, ip_addr, proto])
947
948    Checks if in-dialog request goes to IP address and transport protocol
949    specified for a gateway in LCR instance lcr_id. Fails if LCR instance
950    includes one or more gateways without IP address. IP address and
951    transport protocol to be checked are either taken from Request-URI or
952    (if present) from ip_addr and proto arguments. See from_gw() for more
953    info regarding the arguments.
954
955    Returns 1 on success and -1 on failure and error.
956
957    Execution time of to_gw() function is O(log N), where N is number of
958    gateways in the LCR instance.
959
960    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
961
962    Example 1.45. to_gw usage
963 ...
964 if (to_gw("1")) {
965         ...
966         exit;
967 };
968 ...
969
970 4.7.  to_any_gw([ip_addr, proto])
971
972    Checks if in-dialog request goes to IP address and transport protocol
973    of any gateway. Only LCR instances, where all gateways have IP address,
974    are included in the test. IP address and transport protocol to be
975    checked are either taken from Request-URI or (if present) from ip_addr
976    and proto arguments. See from_gw() for more info regarding the
977    arguments.
978
979    Execution time of to_any_gw() function is M * O(log N), where M is
980    number of LCR instances and N is average number of gateways in LCR
981    instances.
982
983    If any gateway has the IP address, returns LCR identifier of the
984    gateway. Returns -1 if request does not go to a gateway and on error.
985
986    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
987
988    Example 1.46. to_gw usage
989 ...
990 if (to_any_gw("192.55.66.2", 1)) {
991         ...
992         exit;
993 };
994 ...
995
996 5. Exported RPC Commands
997
998    5.1. lcr.reload
999    5.2. lcr.dump_gws
1000    5.3. lcr.dump_rules
1001    5.4. lcr.defunct_gw
1002
1003 5.1. lcr.reload
1004
1005    Causes lcr module to re-read the contents of LCR tables into memory.
1006
1007    Name: lcr.reload
1008
1009    Parameters: none
1010
1011    Example 1.47. lcr.reload RPC example
1012                 $ sercmd lcr.reload
1013
1014 5.2. lcr.dump_gws
1015
1016    Causes lcr module to dump the contents of its in-memory gw table.
1017
1018    Parameters: none
1019
1020    Example 1.48. lcr.dump_gws RPC example
1021                 $ sercmd lcr.dump_gws
1022
1023 5.3. lcr.dump_rules
1024
1025    Causes lcr module to dump the contents of its in-memory lcr_rule and
1026    lcr_rule_target tables.
1027
1028    Parameters: none
1029
1030    Example 1.49. lcr.dump_rules RPC example
1031                 $ sercmd lcr.dump_rules
1032
1033 5.4. lcr.defunct_gw
1034
1035    Defuncts gateway loaded into memory for a period of time (seconds)
1036    without a need to store gateway's defunct value into database and
1037    reload the tables.
1038
1039    Name: lcr.defunct_gw
1040
1041    Parameters: lcr_id gw_id period
1042
1043    Example 1.50. lcr.defunct_gw RPC example
1044                 $ sercmd lcr.defunct_gw 1 4 120
1045
1046 6. Known Limitations
1047
1048    In-memory LCR rules and gw tables are switched by two consecutive
1049    machine instructions. If lcr reload process is interrupted after the
1050    first one, in-memory gateway table does not match in-memory rule table
1051    until execution of lcr reload process is resumed.