Browse code

modules: readme files regenerated - app_lua_sr ... [skip ci]

Kamailio Dev authored on 25/05/2020 09:21:05
Showing 30 changed files
... ...
@@ -10,7 +10,7 @@ Daniel-Constantin Mierla
10 10
 
11 11
    <miconda@gmail.com>
12 12
 
13
-   Copyright � 2010-2019 Daniel-Constantin Mierla (asipto.com)
13
+   Copyright © 2010-2019 Daniel-Constantin Mierla (asipto.com)
14 14
      __________________________________________________________________
15 15
 
16 16
    Table of Contents
... ...
@@ -138,7 +138,7 @@ Chapter 1. Admin Guide
138 138
    Note that 'sr', 'sr.hdr' and 'sr.pv' modules are always registered to
139 139
    Lua.
140 140
 
141
-   Default value is "null".
141
+   Default value is “null”.
142 142
 
143 143
    Example 1.2. Set register parameter
144 144
 ...
... ...
@@ -10,8 +10,6 @@ Daniel-Constantin Mierla
10 10
 
11 11
    <miconda@gmail.com>
12 12
 
13
-Edited by
14
-
15 13
 Alex Balashov
16 14
 
17 15
    <abalashov@evaristesys.com>
... ...
@@ -1650,45 +1650,45 @@ Chapter 4. Frequently Asked Questions
1650 1650
 
1651 1651
    4.1.
1652 1652
 
1653
-       Are there known bugs in the Perl module?
1654
-
1655
-       The Perl module does have a few shortcomings that may be regarded as
1656
-       bugs.
1657
-         * Missing module functions. Not all functions of other modules are
1658
-           available for Perl access. The reason for this is a design property
1659
-           of Kamailio. Making available more functions is work in progress.
1660
-         * Perl and threads. Perl itself is, when compiled with the correct
1661
-           parameters, thread safe; unfortunately, not all Perl modules are.
1662
-           The DBI modules, especially (but not restricted to) DBI::ODBC are
1663
-           known NOT to be thread safe.
1664
-           Using DBI::ODBC -- and possibly other non-thread-safe Perl
1665
-           extensions -- may result in erroneous behavior of Kamailio,
1666
-           including (but not restricted to) server crashes and wrong routing.
1653
+   Are there known bugs in the Perl module?
1654
+
1655
+   The Perl module does have a few shortcomings that may be regarded as
1656
+   bugs.
1657
+     * Missing module functions. Not all functions of other modules are
1658
+       available for Perl access. The reason for this is a design property
1659
+       of Kamailio. Making available more functions is work in progress.
1660
+     * Perl and threads. Perl itself is, when compiled with the correct
1661
+       parameters, thread safe; unfortunately, not all Perl modules are.
1662
+       The DBI modules, especially (but not restricted to) DBI::ODBC are
1663
+       known NOT to be thread safe.
1664
+       Using DBI::ODBC -- and possibly other non-thread-safe Perl
1665
+       extensions -- may result in erroneous behavior of Kamailio,
1666
+       including (but not restricted to) server crashes and wrong routing.
1667 1667
 
1668 1668
    4.2.
1669 1669
 
1670
-       Where can I find more about Kamailio?
1670
+   Where can I find more about Kamailio?
1671 1671
 
1672
-       Take a look at https://www.kamailio.org/.
1672
+   Take a look at https://www.kamailio.org/.
1673 1673
 
1674 1674
    4.3.
1675 1675
 
1676
-       Where can I post a question about this module?
1676
+   Where can I post a question about this module?
1677 1677
 
1678
-       First at all check if your question was already answered on one of our
1679
-       mailing lists:
1680
-         * User Mailing List -
1681
-           https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users
1682
-         * Developer Mailing List -
1683
-           https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev
1678
+   First at all check if your question was already answered on one of our
1679
+   mailing lists:
1680
+     * User Mailing List -
1681
+       https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users
1682
+     * Developer Mailing List -
1683
+       https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev
1684 1684
 
1685
-       E-mails regarding any stable Kamailio release should be sent to
1686
-       <sr-users@lists.kamailio.org> and e-mails regarding development
1687
-       versions should be sent to <sr-dev@lists.kamailio.org>.
1685
+   E-mails regarding any stable Kamailio release should be sent to
1686
+   <sr-users@lists.kamailio.org> and e-mails regarding development
1687
+   versions should be sent to <sr-dev@lists.kamailio.org>.
1688 1688
 
1689 1689
    4.4.
1690 1690
 
1691
-       How can I report a bug?
1691
+   How can I report a bug?
1692 1692
 
1693
-       Please follow the guidelines provided at:
1694
-       https://github.com/kamailio/kamailio/issues.
1693
+   Please follow the guidelines provided at:
1694
+   https://github.com/kamailio/kamailio/issues.
... ...
@@ -22,8 +22,6 @@ Jan Janak
22 22
 
23 23
    <jan@iptel.org>
24 24
 
25
-Edited by
26
-
27 25
 Phil Lavin
28 26
 
29 27
    <phil.lavin@synety.com>
... ...
@@ -8,8 +8,6 @@ Edited by
8 8
 
9 9
 Jason Penton
10 10
 
11
-Edited by
12
-
13 11
 Richard Good
14 12
 
15 13
    Copyright © 2006 FhG Fokus
... ...
@@ -1658,28 +1656,28 @@ Chapter 3. Frequently Asked Questions
1658 1656
 
1659 1657
    3.1.
1660 1658
 
1661
-       Where can I find more about Kamailio?
1659
+   Where can I find more about Kamailio?
1662 1660
 
1663
-       Take a look at https://www.kamailio.org/.
1661
+   Take a look at https://www.kamailio.org/.
1664 1662
 
1665 1663
    3.2.
1666 1664
 
1667
-       Where can I post a question about this module?
1665
+   Where can I post a question about this module?
1668 1666
 
1669
-       First at all check if your question was already answered on one of our
1670
-       mailing lists:
1671
-         * User Mailing List -
1672
-           https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users
1673
-         * Developer Mailing List -
1674
-           https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev
1667
+   First at all check if your question was already answered on one of our
1668
+   mailing lists:
1669
+     * User Mailing List -
1670
+       https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users
1671
+     * Developer Mailing List -
1672
+       https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev
1675 1673
 
1676
-       E-mails regarding any stable Kamailio release should be sent to
1677
-       <sr-users@lists.kamailio.org> and e-mails regarding development
1678
-       versions should be sent to <sr-dev@lists.kamailio.org>.
1674
+   E-mails regarding any stable Kamailio release should be sent to
1675
+   <sr-users@lists.kamailio.org> and e-mails regarding development
1676
+   versions should be sent to <sr-dev@lists.kamailio.org>.
1679 1677
 
1680 1678
    3.3.
1681 1679
 
1682
-       How can I report a bug?
1680
+   How can I report a bug?
1683 1681
 
1684
-       Please follow the guidelines provided at:
1685
-       https://github.com/kamailio/kamailio/issues.
1682
+   Please follow the guidelines provided at:
1683
+   https://github.com/kamailio/kamailio/issues.
... ...
@@ -1,2 +1,2119 @@
1
+DISPATCHER Module
1 2
 
3
+Daniel-Constantin Mierla
2 4
 
5
+   <miconda@gmail.com>
6
+
7
+Edited by
8
+
9
+Daniel-Constantin Mierla
10
+
11
+   <miconda@gmail.com>
12
+
13
+Carsten Bock
14
+
15
+   ng-voice GmbH
16
+
17
+Olle E. Johansson
18
+
19
+   Edvina AB
20
+
21
+Alessandro Arrichiello
22
+
23
+   Hewlett Packard
24
+
25
+Luis Martin
26
+
27
+Julien Chavanton
28
+
29
+   <jchavanton@gmail.com>
30
+
31
+Federico Cabiddu
32
+
33
+   <federico.cabiddu@gmail.com>
34
+
35
+   Copyright © 2004 FhG FOKUS
36
+
37
+   Copyright © 2005 Voice Sistem
38
+
39
+   Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
40
+
41
+   Copyright © 2014 Olle E. Johansson, Edvina AB
42
+
43
+   Copyright © 2015 Alessandro Arrichiello, Hewlett Packard
44
+
45
+   Copyright © 2017, 2018 Julien chavanton, Flowroute
46
+
47
+   Copyright © 2020 Federico Cabiddu, Libon
48
+     __________________________________________________________________
49
+
50
+   Table of Contents
51
+
52
+   1. Admin Guide
53
+
54
+        1. Overview
55
+        2. Dependencies
56
+
57
+              2.1. Kamailio modules
58
+              2.2. External libraries or applications
59
+
60
+        3. Parameters
61
+
62
+              3.1. list_file (string)
63
+              3.2. db_url (string)
64
+              3.3. table_name (string)
65
+              3.4. setid_col (string)
66
+              3.5. destination_col (string)
67
+              3.6. flags_col (string)
68
+              3.7. priority_col (string)
69
+              3.8. attrs_col (string)
70
+              3.9. force_dst (int)
71
+              3.10. flags (int)
72
+              3.11. use_default (int)
73
+              3.12. xavp_dst (str)
74
+              3.13. xavp_dst_mode (int)
75
+              3.14. xavp_ctx (str)
76
+              3.15. xavp_ctx_mode (int)
77
+              3.16. hash_pvar (str)
78
+              3.17. setid_pvname (str)
79
+              3.18. attrs_pvname (str)
80
+              3.19. ds_ping_method (string)
81
+              3.20. ds_ping_from (string)
82
+              3.21. ds_ping_interval (int)
83
+              3.22. ds_probing_threshold (int)
84
+              3.23. ds_inactive_threshold (int)
85
+              3.24. ds_ping_reply_codes (string)
86
+              3.25. ds_probing_mode (int)
87
+              3.26. ds_ping_latency_stats (int)
88
+              3.27. ds_latency_estimator_alpha (int)
89
+              3.28. ds_hash_size (int)
90
+              3.29. ds_hash_expire (int)
91
+              3.30. ds_hash_initexpire (int)
92
+              3.31. ds_hash_check_interval (int)
93
+              3.32. outbound_proxy (str)
94
+              3.33. ds_default_socket (str)
95
+              3.34. ds_default_sockname (str)
96
+              3.35. ds_timer_mode (int)
97
+              3.36. event_callback (str)
98
+              3.37. ds_attrs_none (int)
99
+              3.38. ds_db_extra_attrs (str)
100
+              3.39. ds_load_mode (int)
101
+              3.40. reload_delta (int)
102
+
103
+        4. Functions
104
+
105
+              4.1. ds_select_dst(set, alg[, limit])
106
+              4.2. ds_select_domain(set, alg[, limit])
107
+              4.3. ds_select(set, alg [, limit])
108
+              4.4. ds_select_routes(rules, mode [, limit])
109
+              4.5. ds_next_dst()
110
+              4.6. ds_next_domain()
111
+              4.7. ds_set_dst()
112
+              4.8. ds_set_domain()
113
+              4.9. ds_mark_dst([state])
114
+              4.10. ds_list_exists(groupid)
115
+              4.11. ds_is_from_list([groupid [, mode [, uri] ] ])
116
+              4.12. ds_load_update()
117
+              4.13. ds_load_unset()
118
+              4.14. ds_reload()
119
+
120
+        5. RPC Commands
121
+
122
+              5.1. dispatcher.set_state
123
+              5.2. dispatcher.set_duid_state
124
+              5.3. dispatcher.list
125
+              5.4. dispatcher.reload
126
+              5.5. dispatcher.ping_active
127
+              5.6. dispatcher.add
128
+              5.7. dispatcher.remove
129
+              5.8. dispatcher.hash
130
+
131
+        6. Installation and Running
132
+
133
+              6.1. Destination List File
134
+
135
+                    6.1.1. Special Attributes
136
+                    6.1.2. File Format
137
+
138
+              6.2. Kamailio config file
139
+
140
+        7. Event routes
141
+
142
+              7.1. dispatcher:dst-down
143
+              7.2. dispatcher:dst-up
144
+
145
+   2. Frequently Asked Questions
146
+
147
+   List of Examples
148
+
149
+   1.1. Set the “list_file” parameter
150
+   1.2. Set “db_url” parameter
151
+   1.3. Set “table_name” parameter
152
+   1.4. Set “setid_col” parameter
153
+   1.5. Set “destination_col” parameter
154
+   1.6. Set “flags_col” parameter
155
+   1.7. Set “priority_col” parameter
156
+   1.8. Set “attrs_col” parameter
157
+   1.9. Set the “force_dst” parameter
158
+   1.10. Set the “flags” parameter
159
+   1.11. Set the “use_default” parameter
160
+   1.12. Set the “xavp_dst” parameter
161
+   1.13. Set the “xavp_dst_mode” parameter
162
+   1.14. Set the “xavp_ctx” parameter
163
+   1.15. Set the “xavp_ctx_mode” parameter
164
+   1.16. Use $avp(hash) for hashing:
165
+   1.17. Use combination of PVs for hashing:
166
+   1.18. Set the “setid_pvname” parameter
167
+   1.19. Set the “attrs_pvname” parameter
168
+   1.20. Set the “ds_ping_method” parameter
169
+   1.21. Set the “ds_ping_from” parameter
170
+   1.22. Set the “ds_ping_interval” parameter
171
+   1.23. Set the “ds_probing_threshold” parameter
172
+   1.24. Set the “ds_inactive_threshold” parameter
173
+   1.25. Set the “ds_ping_reply_codes” parameter
174
+   1.26. Set the “ds_probing_mode” parameter
175
+   1.27. accessing the metrics
176
+   1.28. Set the “ds_ping_latency_stats” parameter
177
+   1.29. Set the “ds_hash_size” parameter
178
+   1.30. Set the “ds_hash_size” parameter
179
+   1.31. Set the “ds_hash_expire” parameter
180
+   1.32. Set the “ds_hash_initexpire” parameter
181
+   1.33. Set the “ds_hash_check_interval” parameter
182
+   1.34. Set the “outbound_proxy” parameter
183
+   1.35. Set the “ds_default_socket” parameter
184
+   1.36. Set the “ds_default_sockname” parameter
185
+   1.37. Set the “ds_timer_mode” parameter
186
+   1.38. Set event_callback parameter
187
+   1.39. Set the “ds_attrs_none” parameter
188
+   1.40. Set the “ds_db_extra_attrs” parameter
189
+   1.41. Set the “ds_load_mode” parameter
190
+   1.42. Set reload_delta parameter
191
+   1.43. ds_select_dst usage
192
+   1.44. configuring load balancing with congestion detection
193
+   1.45. ds_select_domain usage
194
+   1.46. ds_select usage
195
+   1.47. ds_select_routes usage
196
+   1.48. ds_mark_dst usage
197
+   1.49. ds_list_exists usage
198
+   1.50. ds_is_from_list usage
199
+   1.51. ds_load_unset usage
200
+   1.52. dispatcher list file
201
+   1.53. Kamailio config script - sample dispatcher usage
202
+
203
+Chapter 1. Admin Guide
204
+
205
+   Table of Contents
206
+
207
+   1. Overview
208
+   2. Dependencies
209
+
210
+        2.1. Kamailio modules
211
+        2.2. External libraries or applications
212
+
213
+   3. Parameters
214
+
215
+        3.1. list_file (string)
216
+        3.2. db_url (string)
217
+        3.3. table_name (string)
218
+        3.4. setid_col (string)
219
+        3.5. destination_col (string)
220
+        3.6. flags_col (string)
221
+        3.7. priority_col (string)
222
+        3.8. attrs_col (string)
223
+        3.9. force_dst (int)
224
+        3.10. flags (int)
225
+        3.11. use_default (int)
226
+        3.12. xavp_dst (str)
227
+        3.13. xavp_dst_mode (int)
228
+        3.14. xavp_ctx (str)
229
+        3.15. xavp_ctx_mode (int)
230
+        3.16. hash_pvar (str)
231
+        3.17. setid_pvname (str)
232
+        3.18. attrs_pvname (str)
233
+        3.19. ds_ping_method (string)
234
+        3.20. ds_ping_from (string)
235
+        3.21. ds_ping_interval (int)
236
+        3.22. ds_probing_threshold (int)
237
+        3.23. ds_inactive_threshold (int)
238
+        3.24. ds_ping_reply_codes (string)
239
+        3.25. ds_probing_mode (int)
240
+        3.26. ds_ping_latency_stats (int)
241
+        3.27. ds_latency_estimator_alpha (int)
242
+        3.28. ds_hash_size (int)
243
+        3.29. ds_hash_expire (int)
244
+        3.30. ds_hash_initexpire (int)
245
+        3.31. ds_hash_check_interval (int)
246
+        3.32. outbound_proxy (str)
247
+        3.33. ds_default_socket (str)
248
+        3.34. ds_default_sockname (str)
249
+        3.35. ds_timer_mode (int)
250
+        3.36. event_callback (str)
251
+        3.37. ds_attrs_none (int)
252
+        3.38. ds_db_extra_attrs (str)
253
+        3.39. ds_load_mode (int)
254
+        3.40. reload_delta (int)
255
+
256
+   4. Functions
257
+
258
+        4.1. ds_select_dst(set, alg[, limit])
259
+        4.2. ds_select_domain(set, alg[, limit])
260
+        4.3. ds_select(set, alg [, limit])
261
+        4.4. ds_select_routes(rules, mode [, limit])
262
+        4.5. ds_next_dst()
263
+        4.6. ds_next_domain()
264
+        4.7. ds_set_dst()
265
+        4.8. ds_set_domain()
266
+        4.9. ds_mark_dst([state])
267
+        4.10. ds_list_exists(groupid)
268
+        4.11. ds_is_from_list([groupid [, mode [, uri] ] ])
269
+        4.12. ds_load_update()
270
+        4.13. ds_load_unset()
271
+        4.14. ds_reload()
272
+
273
+   5. RPC Commands
274
+
275
+        5.1. dispatcher.set_state
276
+        5.2. dispatcher.set_duid_state
277
+        5.3. dispatcher.list
278
+        5.4. dispatcher.reload
279
+        5.5. dispatcher.ping_active
280
+        5.6. dispatcher.add
281
+        5.7. dispatcher.remove
282
+        5.8. dispatcher.hash
283
+
284
+   6. Installation and Running
285
+
286
+        6.1. Destination List File
287
+
288
+              6.1.1. Special Attributes
289
+              6.1.2. File Format
290
+
291
+        6.2. Kamailio config file
292
+
293
+   7. Event routes
294
+
295
+        7.1. dispatcher:dst-down
296
+        7.2. dispatcher:dst-up
297
+
298
+1. Overview
299
+
300
+   This module offers SIP load balancer functionality and it can be used
301
+   as SIP traffic dispatcher. There are many load balancing and traffic
302
+   dispatching algorithms that you can choose from, for example:
303
+   round-robin, weight based load balancing, call load distribution, and
304
+   hashing over SIP message attributes.
305
+
306
+   The module can be used as a stateless load balancer; it does not depend
307
+   on any call state tracking module. It requires the TM module if you
308
+   enable auto-discovery of active/inactive gateways.
309
+
310
+   It is very lightweight, therefore suitable for handling heavy SIP
311
+   traffic. As the module has a small footprint and the ability to load
312
+   balancing rules from a plain text file, it is suitable for embedded
313
+   systems.
314
+
315
+2. Dependencies
316
+
317
+   2.1. Kamailio modules
318
+   2.2. External libraries or applications
319
+
320
+2.1. Kamailio modules
321
+
322
+   The following modules must be loaded before this module:
323
+     * TM - only if active recovery of failed hosts is required.
324
+     * database engine - only if you want to load balancing routes from
325
+       database instead of plain text file. .
326
+
327
+2.2. External libraries or applications
328
+
329
+   The following libraries or applications must be installed before
330
+   running Kamailio with this module:
331
+     * none.
332
+
333
+3. Parameters
334
+
335
+   3.1. list_file (string)
336
+   3.2. db_url (string)
337
+   3.3. table_name (string)
338
+   3.4. setid_col (string)
339
+   3.5. destination_col (string)
340
+   3.6. flags_col (string)
341
+   3.7. priority_col (string)
342
+   3.8. attrs_col (string)
343
+   3.9. force_dst (int)
344
+   3.10. flags (int)
345
+   3.11. use_default (int)
346
+   3.12. xavp_dst (str)
347
+   3.13. xavp_dst_mode (int)
348
+   3.14. xavp_ctx (str)
349
+   3.15. xavp_ctx_mode (int)
350
+   3.16. hash_pvar (str)
351
+   3.17. setid_pvname (str)
352
+   3.18. attrs_pvname (str)
353
+   3.19. ds_ping_method (string)
354
+   3.20. ds_ping_from (string)
355
+   3.21. ds_ping_interval (int)
356
+   3.22. ds_probing_threshold (int)
357
+   3.23. ds_inactive_threshold (int)
358
+   3.24. ds_ping_reply_codes (string)
359
+   3.25. ds_probing_mode (int)
360
+   3.26. ds_ping_latency_stats (int)
361
+   3.27. ds_latency_estimator_alpha (int)
362
+   3.28. ds_hash_size (int)
363
+   3.29. ds_hash_expire (int)
364
+   3.30. ds_hash_initexpire (int)
365
+   3.31. ds_hash_check_interval (int)
366
+   3.32. outbound_proxy (str)
367
+   3.33. ds_default_socket (str)
368
+   3.34. ds_default_sockname (str)
369
+   3.35. ds_timer_mode (int)
370
+   3.36. event_callback (str)
371
+   3.37. ds_attrs_none (int)
372
+   3.38. ds_db_extra_attrs (str)
373
+   3.39. ds_load_mode (int)
374
+   3.40. reload_delta (int)
375
+
376
+3.1. list_file (string)
377
+
378
+   Path to the file with destination sets (destination groups).
379
+
380
+   Default value is “/etc/kamailio/dispatcher.list” or
381
+   “/usr/local/etc/kamailio/dispatcher.list”.
382
+
383
+   Example 1.1. Set the “list_file” parameter
384
+...
385
+modparam("dispatcher", "list_file", "/run/kamailio/dispatcher.list")
386
+...
387
+
388
+3.2. db_url (string)
389
+
390
+   If you want to load the list of gateways from the database you must set
391
+   this parameter.
392
+
393
+   Default value is “NULL” (disable DB support).
394
+
395
+   Example 1.2. Set “db_url” parameter
396
+...
397
+modparam("dispatcher", "db_url", "mysql://user:passwd@localhost/database")
398
+...
399
+
400
+3.3. table_name (string)
401
+
402
+   If you want to load the list of gateways from the database you must set
403
+   this parameter as the database name.
404
+
405
+   Default value is “dispatcher”.
406
+
407
+   Example 1.3. Set “table_name” parameter
408
+...
409
+modparam("dispatcher", "table_name", "my_dispatcher")
410
+...
411
+
412
+3.4. setid_col (string)
413
+
414
+   The column's name in the database storing the gateway's set (group) id.
415
+
416
+   Default value is “setid”.
417
+
418
+   Example 1.4. Set “setid_col” parameter
419
+...
420
+modparam("dispatcher", "setid_col", "groupid")
421
+...
422
+
423
+3.5. destination_col (string)
424
+
425
+   The column's name in the database storing the destination sip URI.
426
+
427
+   Default value is “destination”.
428
+
429
+   Example 1.5. Set “destination_col” parameter
430
+...
431
+modparam("dispatcher", "destination_col", "uri")
432
+...
433
+
434
+3.6. flags_col (string)
435
+
436
+   The column's name in the database storing the flags for the destination
437
+   URI.
438
+
439
+   Default value is “flags”.
440
+
441
+   Example 1.6. Set “flags_col” parameter
442
+...
443
+modparam("dispatcher", "flags_col", "dstflags")
444
+...
445
+
446
+3.7. priority_col (string)
447
+
448
+   The column's name in the database storing the priority for destination
449
+   URI.
450
+
451
+   Default value is “priority”.
452
+
453
+   Example 1.7. Set “priority_col” parameter
454
+...
455
+modparam("dispatcher", "priority_col", "dstpriority")
456
+...
457
+
458
+3.8. attrs_col (string)
459
+
460
+   The column's name in the database storing the attributes for
461
+   destination URI.
462
+
463
+   Default value is “attrs”.
464
+
465
+   Example 1.8. Set “attrs_col” parameter
466
+...
467
+modparam("dispatcher", "attrs_col", "dstattrs")
468
+...
469
+
470
+3.9. force_dst (int)
471
+
472
+   If set to 1, force overwriting of destination address (outbound proxy)
473
+   when that is already set. If set to 0, will return error when the
474
+   destination address is already set.
475
+
476
+   Default value is “1”.
477
+
478
+   Example 1.9. Set the “force_dst” parameter
479
+...
480
+modparam("dispatcher", "force_dst", 1)
481
+...
482
+
483
+3.10. flags (int)
484
+
485
+   Various flags that affect dispatcher's behaviour. The flags are defined
486
+   as a bitmask on an integer value. If flag 1 is set only the username
487
+   part of the URI will be used when computing an URI based hash. If no
488
+   flags are set the username, hostname and port will be used. The port is
489
+   used only if different from 5060 (normal sip URI) or 5061 (in the sips:
490
+   case).
491
+
492
+   If flag 2 is set, then failover support is enabled. The functions
493
+   exported by the module will store the rest of addresses from the
494
+   destination set in XAPVs, and use these XAVPs to try next address if
495
+   the current-tried destination fails.
496
+
497
+   Default value is “0”.
498
+
499
+   Example 1.10. Set the “flags” parameter
500
+ ...
501
+ modparam("dispatcher", "flags", 3)
502
+ ...
503
+
504
+3.11. use_default (int)
505
+
506
+   If the parameter is set to 1, the last address in destination set is
507
+   used as a final option to send the request to. For example, it is
508
+   useful when wanting to send the call to an announcement server saying:
509
+   "the gateways are full, try later".
510
+
511
+   Default value is “0”.
512
+
513
+   Example 1.11. Set the “use_default” parameter
514
+ ...
515
+ modparam("dispatcher", "use_default", 1)
516
+ ...
517
+
518
+3.12. xavp_dst (str)
519
+
520
+   The name of the XAVP which will hold the list with addresses and
521
+   associated properties, in the order they have been selected by the
522
+   chosen algorithm. If use_default is 1, the values of last XAVP
523
+   correspond to the last address in destination set. In case of using
524
+   dispatcher.list file, you have to set the priority field for each
525
+   destination to ensure a particular order there. The first XAVP is the
526
+   current selected destination. All the other addresses from the
527
+   destination set will be added in the XAVP list to be able to implement
528
+   serial forking.
529
+
530
+Note
531
+
532
+   You must set this parameter if you want to do load balancing fail over.
533
+
534
+   Default value is “_dsdst_”.
535
+
536
+   Example 1.12. Set the “xavp_dst” parameter
537
+ ...
538
+ modparam("dispatcher", "xavp_dst", "_dsdst_")
539
+ ...
540
+
541
+3.13. xavp_dst_mode (int)
542
+
543
+   Control what fields are added to the XAVP specified by xavp_dst
544
+   parameter.
545
+
546
+   The addeded fields are:
547
+     * grp - the set id (group id).
548
+     * uri - the URI address.
549
+     * sock - the socket pointer.
550
+     * socket - the socket string - it is added only if xavp_dst_mode has
551
+       bit 2 set (value 2).
552
+     * sockname - the sockname string - it is added only if xavp_dst_mode
553
+       has bit 3 set (value 3).
554
+     * dstid - the destination unique id (in case of call load
555
+       distribution algorithm).
556
+     * attrs - the attributes - they are added if xavp_dst_mode does not
557
+       have the bit 1 set (value 1).
558
+
559
+   Default value is “0” (add all fields).
560
+
561
+   Example 1.13. Set the “xavp_dst_mode” parameter
562
+...
563
+    modparam("dispatcher", "xavp_dst_mode", 1)
564
+...
565
+    modparam("dispatcher", "xavp_dst_mode", 2)
566
+...
567
+
568
+3.14. xavp_ctx (str)
569
+
570
+   The name of the XAVP which will hold some attributes specific to
571
+   dispatcher routing context. The XAVP can hold the next fields: cnt -
572
+   the number of addresses selected for routing.
573
+
574
+   Default value is “_dsctx_”.
575
+
576
+   Example 1.14. Set the “xavp_ctx” parameter
577
+ ...
578
+ modparam("dispatcher", "xavp_ctx", "_dsctx_")
579
+ ...
580
+
581
+3.15. xavp_ctx_mode (int)
582
+
583
+   Control what fields are added to the XAVP specified by xavp_ctx
584
+   parameter. The cnt field is added if xavp_cnt_mode does not have the
585
+   bit 1 set.
586
+
587
+   Default value is “0” (add all fields).
588
+
589
+   Example 1.15. Set the “xavp_ctx_mode” parameter
590
+ ...
591
+ modparam("dispatcher", "xavp_ctx_mode", 1)
592
+ ...
593
+
594
+3.16. hash_pvar (str)
595
+
596
+   String with PVs used for the hashing algorithm 7.
597
+
598
+Note
599
+
600
+   You must set this parameter if you want do hashing over custom message
601
+   parts.
602
+
603
+   Default value is “null” - disabled.
604
+
605
+   Example 1.16. Use $avp(hash) for hashing:
606
+ ...
607
+ modparam("dispatcher", "hash_pvar", "$avp(hash)")
608
+ ...
609
+
610
+   Example 1.17. Use combination of PVs for hashing:
611
+ ...
612
+ modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
613
+ ...
614
+
615
+3.17. setid_pvname (str)
616
+
617
+   The name of the PV where to store the set ID (group ID) when calling
618
+   ds_is_from_list() with no parameter.
619
+
620
+   Default value is “null” - don't set PV.
621
+
622
+   Example 1.18. Set the “setid_pvname” parameter
623
+ ...
624
+ modparam("dispatcher", "setid_pvname", "$var(setid)")
625
+ ...
626
+
627
+3.18. attrs_pvname (str)
628
+
629
+   The name of the PV where to store the attributes of matching address
630
+   when calling ds_is_from_list().
631
+
632
+   Default value is “null” - don't set PV.
633
+
634
+   Example 1.19. Set the “attrs_pvname” parameter
635
+ ...
636
+ modparam("dispatcher", "attrs_pvname", "$var(attrs)")
637
+ ...
638
+
639
+3.19. ds_ping_method (string)
640
+
641
+   With this method you can define, with which method you want to probe
642
+   the gateways. Pinging gateways feature depends on ds_ping_interval
643
+   parameter.
644
+
645
+   Default value is “OPTIONS”.
646
+
647
+   Example 1.20. Set the “ds_ping_method” parameter
648
+ ...
649
+ modparam("dispatcher", "ds_ping_method", "INFO")
650
+ ...
651
+
652
+3.20. ds_ping_from (string)
653
+
654
+   With this Method you can define the "From:"-Line for the request, sent
655
+   to the failed gateways. This method is only available, if compiled with
656
+   the probing of failed gateways enabled.
657
+
658
+   Default value is “sip:dispatcher@localhost”.
659
+
660
+   Example 1.21. Set the “ds_ping_from” parameter
661
+ ...
662
+ modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
663
+ ...
664
+
665
+3.21. ds_ping_interval (int)
666
+
667
+   With this parameter you can define the interval for sending a request
668
+   to a gateway marked as inactive upon a failed request routing to it.
669
+   This parameter is only used, when the TM-Module is loaded. If set to
670
+   “0”, the pinging of inactive gateway is disabled.
671
+
672
+   Default value is “0”.
673
+
674
+   Example 1.22. Set the “ds_ping_interval” parameter
675
+ ...
676
+ modparam("dispatcher", "ds_ping_interval", 30)
677
+ ...
678
+
679
+3.22. ds_probing_threshold (int)
680
+
681
+   If you want to set a gateway into inactive mode, there can be a
682
+   specific number of failed requests until it will change from "active"
683
+   to "inactive". It is using the state "trying", that allows selection of
684
+   gateway but indicates there was a failure previously with the gateway.
685
+   The number of attempts can be set with this parameter. This parameter
686
+   can be modified via ser config framework.
687
+
688
+   Default value is “1” (set inactive with first failure).
689
+
690
+   Example 1.23. Set the “ds_probing_threshold” parameter
691
+ ...
692
+ modparam("dispatcher", "ds_probing_threshold", 10)
693
+ ...
694
+
695
+3.23. ds_inactive_threshold (int)
696
+
697
+   If you want to set a gateway into active mode (after being inactive),
698
+   there can be a specific number of successful requests until it will
699
+   change from "inactive" to "active". The number of attempts can be set
700
+   with this parameter. This parameter can be modified via ser config
701
+   framework.
702
+
703
+   Default value is “1” (set active with first success).
704
+
705
+   Example 1.24. Set the “ds_inactive_threshold” parameter
706
+ ...
707
+ modparam("dispatcher", "ds_inactive_threshold", 10)
708
+ ...
709
+
710
+3.24. ds_ping_reply_codes (string)
711
+
712
+   This parameter defines the valid response codes, which are accepted as
713
+   a valid reply to the PING-Method. It is a list separated by colons,
714
+   where you may define either a single code (e.g. "code=202" would accept
715
+   202 as an additional, valid response) or a class of responses, you want
716
+   to accept (e.g. "class=2" would accept everything from 200 to 299 as
717
+   valid response). This parameter can be modified via config framework.
718
+
719
+   Please note that the response codes the module accepts as valid reply
720
+   to the PING-Method are not only the ones generated from the remote
721
+   servers, but also those that are generated locally. E.g.: setting
722
+   code=408 or class=400 will never set a backend down even if it is,
723
+   because internally the Kamailio transaction layer generates a 408 in
724
+   the case of no response from the remote server, and this internal code
725
+   408 is accepted as valid value.
726
+
727
+   Default value is “” (only 200 OK is accepted).
728
+
729
+   Example 1.25. Set the “ds_ping_reply_codes” parameter
730
+ ...
731
+ modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=
732
+3")
733
+ ...
734
+
735
+3.25. ds_probing_mode (int)
736
+
737
+   Controls what gateways are tested to see if they are reachable.
738
+     * Value 0: If set to 0, only the gateways with state PROBING are
739
+       tested. After a gateway is probed, the PROBING state is cleared in
740
+       this mode. This means that no probing will be executed at all only
741
+       if flag in config file is set to 8/PROBING (please check
742
+       destination list file syntaxis for more details), it will probe
743
+       only one time at startup or after dispatcher reload.
744
+     * Value 1: If set to 1, all gateways are tested. If set to 1 and
745
+       there is a failure of keepalive to an active gateway, then it is
746
+       set to TRYING state. This means that probing will be executed all
747
+       the time, but you can skip some servers with flag 4 in destination
748
+       list file, for example.
749
+     * Value 2: if set to 2, only gateways in INACTIVE state with PROBING
750
+       mode set are tested.
751
+     * Value 3: If set to 3, any gateway with state PROBING is continually
752
+       probed without modifying/removing the PROBING state. This allows
753
+       selected gateways to be probed continually, regardless of state
754
+       changes.
755
+
756
+   Default value is “0”.
757
+
758
+   Example 1.26. Set the “ds_probing_mode” parameter
759
+ ...
760
+ modparam("dispatcher", "ds_probing_mode", 1)
761
+ ...
762
+
763
+3.26. ds_ping_latency_stats (int)
764
+
765
+   Enable latency measurement when pinging nodes
766
+     * If set to 0, disable latency measurement.
767
+     * If set to 1, enable latency measurement.
768
+
769
+   Default value is “0”.
770
+
771
+   Example 1.27. accessing the metrics
772
+# using the command :
773
+kamcmd dispatcher.list
774
+ ...
775
+DEST: {
776
+        URI: sip:1.2.3.4
777
+        FLAGS: AX
778
+        PRIORITY: 9
779
+        LATENCY: {
780
+                AVG: 24.250000 # weighted moving average for the last few weeks
781
+                STD: 1.035000  # standard deviation of AVG
782
+                EST: 25.000000 # short term estimate, see parameter: ds_latency_
783
+estimator_alpha
784
+                MAX: 26        # maximum value seen
785
+                TIMEOUT: 0     # count of ping timeouts
786
+        }
787
+}
788
+ ...
789
+
790
+   Example 1.28. Set the “ds_ping_latency_stats” parameter
791
+ ...
792
+ modparam("dispatcher", "ds_ping_latency_stats", 1)
793
+ ...
794
+
795
+3.27. ds_latency_estimator_alpha (int)
796
+
797
+   The value to be used to control the memory of the estimator EWMA
798
+   "exponential weighted moving average" or "the speed at which the older
799
+   samples are dampened" a good explanation can be found here :
800
+   http://www.itl.nist.gov/div898/handbook/pmc/section3/pmc324.htm Because
801
+   Kamailio doesn't support float parameter types, the value in the
802
+   parameter is divided by 1000 and stored as float. For example, if you
803
+   want to set the alpha to be 0.75, use value 750 here.
804
+
805
+   Default value is “900 => 0.9”.
806
+
807
+   Example 1.29. Set the “ds_hash_size” parameter
808
+ ...
809
+ modparam("dispatcher", "ds_latency_estimator_alpha", 900)
810
+ ...
811
+
812
+3.28. ds_hash_size (int)
813
+
814
+   The value to be used as power of two to set the number of slots to hash
815
+   table storing data for call load dispatching (e.g., value 8 will create
816
+   a hash table with 256 slots). It must be greater than 0 to enable call
817
+   load dispatching feature (alg 10).
818
+
819
+   Default value is “0”.
820
+
821
+   Example 1.30. Set the “ds_hash_size” parameter
822
+ ...
823
+ modparam("dispatcher", "ds_hash_size", 9)
824
+ ...
825
+
826
+3.29. ds_hash_expire (int)
827
+
828
+   Expiration time in seconds to remove the load on a destination if no
829
+   BYE was received meanwhile.
830
+
831
+   Default value is “7200”.
832
+
833
+   Example 1.31. Set the “ds_hash_expire” parameter
834
+ ...
835
+ modparam("dispatcher", "ds_hash_expire", 3600)
836
+ ...
837
+
838
+3.30. ds_hash_initexpire (int)
839
+
840
+   Expiration time in seconds to remove the load on a destination if no
841
+   200 for INVITE was received meanwhile and state updated with
842
+   ds_load_update().
843
+
844
+   Default value is “7200”.
845
+
846
+   Example 1.32. Set the “ds_hash_initexpire” parameter
847
+ ...
848
+ modparam("dispatcher", "ds_hash_initexpire", 60)
849
+ ...
850
+
851
+3.31. ds_hash_check_interval (int)
852
+
853
+   Time interval in seconds to scan internal hash table with call load
854
+   dispatching data for expired items.
855
+
856
+   Default value is “30”.
857
+
858
+   Example 1.33. Set the “ds_hash_check_interval” parameter
859
+ ...
860
+ modparam("dispatcher", "ds_hash_check_interval", 60)
861
+ ...
862
+
863
+3.32. outbound_proxy (str)
864
+
865
+   SIP URI of outbound proxy to be used when sending pings.
866
+
867
+   By default no outbound proxy is defined.
868
+
869
+   Example 1.34. Set the “outbound_proxy” parameter
870
+ ...
871
+ modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
872
+ ...
873
+
874
+3.33. ds_default_socket (str)
875
+
876
+   Default socket to be used for sending pings and dispatching requests
877
+   when a gateway has no send socket configured.
878
+
879
+   By default no default socket is defined, the first configuration script
880
+   listen directive is used.
881
+
882
+   If parameter "ds_default_sockname" is set, then this parameter is
883
+   ignored.
884
+
885
+   Example 1.35. Set the “ds_default_socket” parameter
886
+ ...
887
+ modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
888
+ ...
889
+
890
+3.34. ds_default_sockname (str)
891
+
892
+   Default socket name to be used for sending pings and dispatching
893
+   requests when a gateway has no send socket configured.
894
+
895
+   By default no default socket is defined, the first configuration script
896
+   listen directive is used.
897
+
898
+   This parameter is used even if "ds_default_socket" parameter is set
899
+   (this parameter has higher priority).
900
+
901
+   Example 1.36. Set the “ds_default_sockname” parameter
902
+ ...
903
+ listen=udp:1.2.3.4:5060 name "sock1"
904
+ ...
905
+ modparam("dispatcher", "ds_default_sockname", "sock1")
906
+ ...
907
+
908
+3.35. ds_timer_mode (int)
909
+
910
+   Specify the timer process to be used by the module for keepalives and
911
+   active dialogs tracking.
912
+
913
+   It can be set to:
914
+     * 0 - use main timer process.
915
+     * 1 - use secondary timer process.
916
+
917
+   On a server with a lot of traffic, using secondary timer can help with
918
+   performances, because the main timer can be overloaded by taking care
919
+   of transactions retransmissions and expirations of items in memory.
920
+
921
+   Default value is “0”.
922
+
923
+   Example 1.37. Set the “ds_timer_mode” parameter
924
+ ...
925
+ modparam("dispatcher", "ds_timer_mode", 1)
926
+ ...
927
+
928
+3.36. event_callback (str)
929
+
930
+   The name of the function in the kemi configuration file (embedded
931
+   scripting language such as Lua, Python, ...) to be executed instead of
932
+   event_route[...] blocks.
933
+
934
+   The function receives a string parameter with the name of the event,
935
+   the values are: 'dispatcher:dst-down', 'dispatcher:dst-up'.
936
+
937
+   Default value is 'empty' (no function is executed for events).
938
+
939
+   Example 1.38. Set event_callback parameter
940
+...
941
+modparam("dispatcher", "event_callback", "ksr_dispatcher_event")
942
+...
943
+-- event callback function implemented in Lua
944
+function ksr_dispatcher_event(evname)
945
+        KSR.info("===== dispatcher module triggered event: " .. evname .. "\n");
946
+        return 1;
947
+end
948
+...
949
+
950
+3.37. ds_attrs_none (int)
951
+
952
+   If set to 1, "none=yes" is set in the attrs for those records that have
953
+   no attrs value, to ensure that corresponding XAVP fields for records do
954
+   not get mixed up.
955
+
956
+   Default value is “0”.
957
+
958
+   Example 1.39. Set the “ds_attrs_none” parameter
959
+ ...
960
+ modparam("dispatcher", "ds_attrs_none", 1)
961
+ ...
962
+
963
+3.38. ds_db_extra_attrs (str)
964
+
965
+   Set a list of column names to be loaded from database dispatcher table
966
+   and be concatenated to 'attrs' field. The format is:
967
+   'aname1=cname1;aname2=cname2;...;anameN=cnameN'.
968
+
969
+   The 'anameX' is the attribute name and 'cnameX' is column name. The
970
+   additional columns must be added to database dispatcher table and their
971
+   type must be VARCHAR (string).
972
+
973
+   Default value is “empty”.
974
+
975
+   Example 1.40. Set the “ds_db_extra_attrs” parameter
976
+...
977
+modparam("dispatcher", "ds_db_extra_attrs", "socket=socket;pref=prefix")
978
+...
979
+
980
+3.39. ds_load_mode (int)
981
+
982
+   If set to 1, the module throws error when failing to add a destination
983
+   address (e.g., invalid URI). If set to 0, it skips the failing address
984
+   and continues with the next ones.
985
+
986
+   Default value is “0”.
987
+
988
+   Example 1.41. Set the “ds_load_mode” parameter
989
+ ...
990
+ modparam("dispatcher", "ds_load_mode", 1)
991
+ ...
992
+
993
+3.40. reload_delta (int)
994
+
995
+   The number of seconds that have to be waited before executing a new
996
+   reload of dispatcher records. By default there is a rate limiting of
997
+   maximum one reload in five seconds.
998
+
999
+   If set to 0, no rate limit is configured. Note carefully: use this
1000
+   configuration only in tests environments because executing many RPC
1001
+   reload commands at the same time can cause unexpected behavior.
1002
+
1003
+   Default value is “5”.
1004
+
1005
+   Example 1.42. Set reload_delta parameter
1006
+...
1007
+modparam("dispatcher", "reload_delta", 1)
1008
+...
1009
+
1010
+4. Functions
1011
+
1012
+   4.1. ds_select_dst(set, alg[, limit])
1013
+   4.2. ds_select_domain(set, alg[, limit])
1014
+   4.3. ds_select(set, alg [, limit])
1015
+   4.4. ds_select_routes(rules, mode [, limit])
1016
+   4.5. ds_next_dst()
1017
+   4.6. ds_next_domain()
1018
+   4.7. ds_set_dst()
1019
+   4.8. ds_set_domain()
1020
+   4.9. ds_mark_dst([state])
1021
+   4.10. ds_list_exists(groupid)
1022
+   4.11. ds_is_from_list([groupid [, mode [, uri] ] ])
1023
+   4.12. ds_load_update()
1024
+   4.13. ds_load_unset()
1025
+   4.14. ds_reload()
1026
+
1027
+4.1.  ds_select_dst(set, alg[, limit])
1028
+
1029
+   The method selects a destination from addresses set. It returns true if
1030
+   a new destination is set. The selected address is set to dst_uri field
1031
+   (aka the outbound proxy address or the $du variable), not being visible
1032
+   in the SIP request.
1033
+
1034
+   If the bit 2 in 'flags' parameter is set, the rest of the addresses
1035
+   from the destination set are stored in XAVP list (limited with an
1036
+   optional 'limit' parameter). You can use 'ds_next_dst()' to use next
1037
+   address in order to achieve serial forking to all possible
1038
+   destinations.
1039
+
1040
+   Meaning of the parameters is as follows:
1041
+     * set - the id of the set from where to pick up destination address.
1042
+       It is the first column in destination list file. The parameter can
1043
+       be an integer or a variable holding an integer.
1044
+     * alg - the algorithm used to select the destination address. The
1045
+       parameter can be an integer or a variable holding an integer.
1046
+          + “0” - hash over callid
1047
+          + “1” - hash over from URI.
1048
+          + “2” - hash over to URI.
1049
+          + “3” - hash over request-URI.
1050
+          + “4” - round-robin (next destination).
1051
+          + “5” - hash over authorization-username (Proxy-Authorization or
1052
+            "normal" authorization). If no username is found, round robin
1053
+            is used.
1054
+          + “6” - random destination (using rand()).
1055
+          + “7” - hash over the content of PVs string. Note: This works
1056
+            only when the parameter hash_pvar is set.
1057
+          + “8” - select destination sorted by priority attribute value
1058
+            (serial forking ordered by priority).
1059
+          + “9” - use weight based load distribution. You have to set the
1060
+            attribute 'weight' for each address (gateway) in destination
1061
+            set. For more see the description of the 'weight' attribute in
1062
+            the 'Special Attributes' section.
1063
+          + “10” - use call load distribution. You have to set the
1064
+            attribute 'duid' (as an unique string id) per each address in
1065
+            destination set. Also, you must set the parameter
1066
+            'ds_hash_size'.
1067
+            The algorithm can be used even with stateless proxy mode,
1068
+            there is no SIP dialog tracking depending on other modules,
1069
+            just an internal lightweight call tracking by Call-Id, thus is
1070
+            fast and suitable even for embedded systems.
1071
+            The first destination selected by this algorithm is the one
1072
+            that has the least number of calls associated. The rest of the
1073
+            destination list is taken in order of the entries in set -
1074
+            anyhow, until a re-route to next destination happens, the load
1075
+            on each address can change.
1076
+            This algorithm can be used only for dispatching INVITE
1077
+            requests as it is the only SIP method creating a SIP call.
1078
+          + “11” - use relative weight based load distribution. You have
1079
+            to set the attribute 'rweight' per each address in destination
1080
+            set. Active host usage probability is rweight/(SUM of all
1081
+            active host rweights in destination group).
1082
+            The major difference from the weight distribution is the
1083
+            probability recalculation according to rweight value in case
1084
+            of host enabling/disabling
1085
+            For example, 100 calls in 3-hosts group with rweight params
1086
+            1/2/1 will be distributed as 25/50/25. After third host
1087
+            failing distribution will be changed to 33/67/0.
1088
+            Using this algorithm, you can also enable congestion control
1089
+            by setting the attibute 'cc=1', when 'cc' is enabled the
1090
+            'rweight' attribute will also be used to control congestion
1091
+            tolerance. When facing congestion the weight of a gateway is
1092
+            lowered by 1 for every ms of estimated congestion, a 'rweight'
1093
+            value of 50 is recommended. See the example "configuring load
1094
+            balancing with congestion detection" below.
1095
+            The congestion estimation is done using an EWMA (see
1096
+            ds_latency_estimator_alpha). If all the gateways in a set are
1097
+            above their congestion threshold(weight), the load
1098
+            distribution is instead done using the ratio of estimated
1099
+            congestion ms.
1100
+          + “12” - dispatch to all destination in setid at once (parallel
1101
+            forking). Note that the XAVPs are no longer set with the
1102
+            values of the destination records, no re-routing making sense
1103
+            in this case.
1104
+          + “X” - if the algorithm is not implemented, the first entry in
1105
+            set is chosen.
1106
+     * limit - the maximum number of items to be stored in XAVP list for
1107
+       further fail-overs (the first selected destination and default
1108
+       destination are the first to be put in the list)
1109
+
1110
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1111
+
1112
+   Example 1.43. ds_select_dst usage
1113
+...
1114
+ds_select_dst("1", "0");
1115
+...
1116
+$var(a) = 4;
1117
+ds_select_dst("1", "$var(a)");
1118
+...
1119
+ds_select_dst("1", "4", "3");
1120
+...
1121
+
1122
+   Example 1.44. configuring load balancing with congestion detection
1123
+...
1124
+# sample of SQL provisionning statements
1125
+INSERT INTO "dispatcher"
1126
+VALUES(1,1,'sip:192.168.0.1:5060',0,12,'rweight=50;weight=50;cc=1;','');
1127
+INSERT INTO "dispatcher"
1128
+VALUES(2,1,'sip:192.168.0.2:5060',0,12,'rweight=50;weight=50;cc=1;','');
1129
+...
1130
+modparam("dispatcher", "ds_ping_interval", 1) # ping gateways once/second
1131
+modparam("dispatcher", "ds_ping_latency_stats", 1) # update congestion metrics
1132
+# configure the latency estimator
1133
+modparam("dispatcher", "ds_latency_estimator_alpha", 900)
1134
+...
1135
+if (!ds_select_dst("1", "11")) { # use relative weight based load distribution
1136
+...
1137
+# sample of output from 'kamcmd dispatcher.list'
1138
+DEST: {
1139
+        URI: sip:192.168.0.1:5060
1140
+        FLAGS: AP
1141
+        PRIORITY: 12
1142
+        ATTRS: {
1143
+                BODY: rweight=50;weight=50;cc=1 # configuration values
1144
+                DUID:
1145
+                MAXLOAD: 0
1146
+                WEIGHT: 50
1147
+                RWEIGHT: 50
1148
+                SOCKET:
1149
+                SOCKNAME:
1150
+                OBPROXY:
1151
+        }
1152
+        LATENCY: {
1153
+                AVG: 20.104000
1154
+                STD: 1.273000
1155
+                # estimated congestion is currently 25ms = 45ms(EST) -20ms(AVG)
1156
+                EST: 45.005000
1157
+                MAX: 132
1158
+                TIMEOUT: 3
1159
+        }
1160
+}
1161
+...
1162
+
1163
+4.2.  ds_select_domain(set, alg[, limit])
1164
+
1165
+   The method selects a destination from addresses set and rewrites the
1166
+   host and port from R-URI. The parameters have same meaning as for
1167
+   ds_select_dst().
1168
+
1169
+   If the bit 2 in 'flags' is set, the rest of the addresses from the
1170
+   destination set are stored in XAVP list (limited with an optional
1171
+   'limit' parameter). You can use 'ds_next_domain()' to use next address
1172
+   to achieve serial forking to all possible destinations.
1173
+
1174
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1175
+
1176
+   Example 1.45. ds_select_domain usage
1177
+...
1178
+$var(a) = 4;
1179
+if(ds_select_domain("1", "$var(a)")) {
1180
+    t_relay();
1181
+    exit;
1182
+}
1183
+...
1184
+
1185
+4.3.  ds_select(set, alg [, limit])
1186
+
1187
+   The method selects a destination from addresses set and adds it in the
1188
+   XAVP specified for this module. It is not updating R-URI nor the
1189
+   destination URI. The parameters have same meaning as for
1190
+   ds_select_dst().
1191
+
1192
+   If the bit 2 in 'flags' is set, the rest of the addresses from the
1193
+   destination set are stored in XAVP list (limited with an optional
1194
+   'limit' parameter). You can execute 'ds_next_domain()' or
1195
+   'ds_next_dst()' to use next address to achieve serial forking to all
1196
+   possible destinations.
1197
+
1198
+   This function can be used from ANY_ROUTE.
1199
+
1200
+   Example 1.46. ds_select usage
1201
+...
1202
+$var(a) = 4;
1203
+if(ds_select("1", "$var(a)")) {
1204
+    ds_next_domain();
1205
+    t_relay();
1206
+    exit;
1207
+}
1208
+...
1209
+
1210
+4.4.  ds_select_routes(rules, mode [, limit])
1211
+
1212
+   The method selects destinations following the rules combining groups
1213
+   add algorithms, controlling where the first destination address is
1214
+   pushed, and optionally setting a limit of selected addresses.
1215
+
1216
+   Parameters:
1217
+     * rules - a string in the format "grp1=alg1;grp2=alg2;...grpN=algN",
1218
+       where grpX is an integer number identifying a dispatcher set id and
1219
+       algN is a dispatcher algorithm identifier. No white spaces should
1220
+       be given in the parameter value. The parameter can contain
1221
+       pseudo-variables.
1222
+     * mode - control where to push the first selected target address.
1223
+       Valid values are: '0', 'd' or 'D' to push the address in
1224
+       destination URI; '1', 'r' or 'R' to push the address in R-URI; '2',
1225
+       'x' or 'X' to push the address only in the XAVP when failure
1226
+       rerouting is enabled. Note that only first character of the
1227
+       parameter matters, therefore one can use a more meaningful value
1228
+       such as 'ruri' instead of 'r'. The parameter can contain pseudo
1229
+       variables.
1230
+     * limit - a positive integer value to restrict the number of selected
1231 </