Browse code

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

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