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