modules: readme files regenerated - dispatcher ...
[sip-router] / modules / dispatcher / README
1 DISPATCHER Module
2
3 Daniel-Constantin Mierla
4
5    <miconda@gmail.com>
6
7 Edited by
8
9 Daniel-Constantin Mierla
10
11    <miconda@gmail.com>
12
13 Edited by
14
15 Carsten Bock
16
17    ng-voice GmbH
18
19 Edited by
20
21 Olle E. Johansson
22
23    Edvina AB
24
25 Edited by
26
27 Alessandro Arrichiello
28
29    Hewlett Packard
30
31 Edited by
32
33 Luis Martin
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
46    Table of Contents
47
48    1. Admin Guide
49
50         1. Overview
51         2. Dependencies
52
53               2.1. Kamailio modules
54               2.2. External libraries or applications
55
56         3. Parameters
57
58               3.1. list_file (string)
59               3.2. db_url (string)
60               3.3. table_name (string)
61               3.4. setid_col (string)
62               3.5. destination_col (string)
63               3.6. flags_col (string)
64               3.7. priority_col (string)
65               3.8. force_dst (int)
66               3.9. flags (int)
67               3.10. use_default (int)
68               3.11. dst_avp (str)
69               3.12. grp_avp (str)
70               3.13. cnt_avp (str)
71               3.14. dstid_avp (str)
72               3.15. attrs_avp (str)
73               3.16. sock_avp (str)
74               3.17. hash_pvar (str)
75               3.18. setid_pvname (str)
76               3.19. attrs_pvname (str)
77               3.20. ds_ping_method (string)
78               3.21. ds_ping_from (string)
79               3.22. ds_ping_interval (int)
80               3.23. ds_probing_threshold (int)
81               3.24. ds_inactive_threshold (int)
82               3.25. ds_ping_reply_codes (string)
83               3.26. ds_probing_mode (int)
84               3.27. ds_hash_size (int)
85               3.28. ds_hash_expire (int)
86               3.29. ds_hash_initexpire (int)
87               3.30. ds_hash_check_interval (int)
88               3.31. outbound_proxy (str)
89               3.32. ds_default_socket (str)
90               3.33. ds_timer_mode (int)
91
92         4. Functions
93
94               4.1. ds_select_dst(set, alg[, limit])
95               4.2. ds_select_domain(set, alg[, limit])
96               4.3. ds_select(set, alg [, limit])
97               4.4. ds_next_dst()
98               4.5. ds_next_domain()
99               4.6. ds_mark_dst([state])
100               4.7. ds_list_exist(groupid)
101               4.8. ds_is_from_list([groupid [, mode [, uri] ] ])
102               4.9. ds_load_update()
103               4.10. ds_load_unset()
104               4.11. ds_reload()
105
106         5. MI Commands
107
108               5.1. ds_set_state
109               5.2. ds_list
110               5.3. ds_reload
111
112         6. RPC Commands
113
114               6.1. dispatcher.set_state
115               6.2. dispatcher.list
116               6.3. dispatcher.reload
117               6.4. dispatcher.ping_active
118
119         7. Installation and Running
120
121               7.1. Destination List File
122
123                     7.1.1. Special Attributes
124                     7.1.2. File Format
125
126               7.2. Kamailio config file
127
128         8. Event routes
129
130               8.1. dispatcher:dst-down
131               8.2. dispatcher:dst-up
132
133    2. Frequently Asked Questions
134
135    List of Examples
136
137    1.1. Set the “list_file” parameter
138    1.2. Set “db_url” parameter
139    1.3. Set “table_name” parameter
140    1.4. Set “setid_col” parameter
141    1.5. Set “destination_col” parameter
142    1.6. Set “flags_col” parameter
143    1.7. Set “priority_col” parameter
144    1.8. Set the “force_dst” parameter
145    1.9. Set the “flags” parameter
146    1.10. Set the “use_default” parameter
147    1.11. Set the “dst_avp” parameter
148    1.12. Set the “grp_avp” parameter
149    1.13. Set the “cnt_avp” parameter
150    1.14. Set the “dstid_avp” parameter
151    1.15. Set the “attrs_avp” parameter
152    1.16. Set the “sock_avp” parameter
153    1.17. Use $avp(i:273) for hashing:
154    1.18. Use combination of PVs for hashing:
155    1.19. Set the “setid_pvname” parameter
156    1.20. Set the “attrs_pvname” parameter
157    1.21. Set the “ds_ping_method” parameter
158    1.22. Set the “ds_ping_from” parameter
159    1.23. Set the “ds_ping_interval” parameter
160    1.24. Set the “ds_probing_threshold” parameter
161    1.25. Set the “ds_inactive_threshold” parameter
162    1.26. Set the “ds_ping_reply_codes” parameter
163    1.27. Set the “ds_probing_mode” parameter
164    1.28. Set the “ds_hash_size” parameter
165    1.29. Set the “ds_hash_expire” parameter
166    1.30. Set the “ds_hash_initexpire” parameter
167    1.31. Set the “ds_hash_check_interval” parameter
168    1.32. Set the “outbound_proxy” parameter
169    1.33. Set the “ds_default_socket” parameter
170    1.34. Set the “ds_timer_mode” parameter
171    1.35. ds_select_dst usage
172    1.36. ds_select_domain usage
173    1.37. ds_select usage
174    1.38. ds_mark_dst usage
175    1.39. ds_list_exist usage
176    1.40. ds_is_from_list usage
177    1.41. ds_load_unset usage
178    1.42. dispatcher list file
179    1.43. Kamailio config script - sample dispatcher usage
180
181 Chapter 1. Admin Guide
182
183    Table of Contents
184
185    1. Overview
186    2. Dependencies
187
188         2.1. Kamailio modules
189         2.2. External libraries or applications
190
191    3. Parameters
192
193         3.1. list_file (string)
194         3.2. db_url (string)
195         3.3. table_name (string)
196         3.4. setid_col (string)
197         3.5. destination_col (string)
198         3.6. flags_col (string)
199         3.7. priority_col (string)
200         3.8. force_dst (int)
201         3.9. flags (int)
202         3.10. use_default (int)
203         3.11. dst_avp (str)
204         3.12. grp_avp (str)
205         3.13. cnt_avp (str)
206         3.14. dstid_avp (str)
207         3.15. attrs_avp (str)
208         3.16. sock_avp (str)
209         3.17. hash_pvar (str)
210         3.18. setid_pvname (str)
211         3.19. attrs_pvname (str)
212         3.20. ds_ping_method (string)
213         3.21. ds_ping_from (string)
214         3.22. ds_ping_interval (int)
215         3.23. ds_probing_threshold (int)
216         3.24. ds_inactive_threshold (int)
217         3.25. ds_ping_reply_codes (string)
218         3.26. ds_probing_mode (int)
219         3.27. ds_hash_size (int)
220         3.28. ds_hash_expire (int)
221         3.29. ds_hash_initexpire (int)
222         3.30. ds_hash_check_interval (int)
223         3.31. outbound_proxy (str)
224         3.32. ds_default_socket (str)
225         3.33. ds_timer_mode (int)
226
227    4. Functions
228
229         4.1. ds_select_dst(set, alg[, limit])
230         4.2. ds_select_domain(set, alg[, limit])
231         4.3. ds_select(set, alg [, limit])
232         4.4. ds_next_dst()
233         4.5. ds_next_domain()
234         4.6. ds_mark_dst([state])
235         4.7. ds_list_exist(groupid)
236         4.8. ds_is_from_list([groupid [, mode [, uri] ] ])
237         4.9. ds_load_update()
238         4.10. ds_load_unset()
239         4.11. ds_reload()
240
241    5. MI Commands
242
243         5.1. ds_set_state
244         5.2. ds_list
245         5.3. ds_reload
246
247    6. RPC Commands
248
249         6.1. dispatcher.set_state
250         6.2. dispatcher.list
251         6.3. dispatcher.reload
252         6.4. dispatcher.ping_active
253
254    7. Installation and Running
255
256         7.1. Destination List File
257
258               7.1.1. Special Attributes
259               7.1.2. File Format
260
261         7.2. Kamailio config file
262
263    8. Event routes
264
265         8.1. dispatcher:dst-down
266         8.2. dispatcher:dst-up
267
268 1. Overview
269
270    This module offers SIP load balancer functionality and it can be used
271    as SIP traffic dispatcher. There are many load balancing and traffic
272    dispaching algorithms that you can choose from, for example:
273    round-robin, weight based load balancing, call load distribution, and
274    hashing over SIP message attributes.
275
276    The module can be used as a stateless load balancer; it does not depend
277    on any call state tracking module. It requires the TM module if you
278    enable auto-discovery of active/inactive gateways.
279
280    It is very lightweight, therefore suitable for handling heavy SIP
281    traffic. As the module has a small footprint and the ability to load
282    balancing rules from a plain text file, it is suitable for embedded
283    systems.
284
285 2. Dependencies
286
287    2.1. Kamailio modules
288    2.2. External libraries or applications
289
290 2.1. Kamailio modules
291
292    The following modules must be loaded before this module:
293      * TM - only if active recovery of failed hosts is required.
294      * database engine - only if you want to load balancing routes from
295        database instead of plain text file. .
296
297 2.2. External libraries or applications
298
299    The following libraries or applications must be installed before
300    running Kamailio with this module:
301      * none.
302
303 3. Parameters
304
305    3.1. list_file (string)
306    3.2. db_url (string)
307    3.3. table_name (string)
308    3.4. setid_col (string)
309    3.5. destination_col (string)
310    3.6. flags_col (string)
311    3.7. priority_col (string)
312    3.8. force_dst (int)
313    3.9. flags (int)
314    3.10. use_default (int)
315    3.11. dst_avp (str)
316    3.12. grp_avp (str)
317    3.13. cnt_avp (str)
318    3.14. dstid_avp (str)
319    3.15. attrs_avp (str)
320    3.16. sock_avp (str)
321    3.17. hash_pvar (str)
322    3.18. setid_pvname (str)
323    3.19. attrs_pvname (str)
324    3.20. ds_ping_method (string)
325    3.21. ds_ping_from (string)
326    3.22. ds_ping_interval (int)
327    3.23. ds_probing_threshold (int)
328    3.24. ds_inactive_threshold (int)
329    3.25. ds_ping_reply_codes (string)
330    3.26. ds_probing_mode (int)
331    3.27. ds_hash_size (int)
332    3.28. ds_hash_expire (int)
333    3.29. ds_hash_initexpire (int)
334    3.30. ds_hash_check_interval (int)
335    3.31. outbound_proxy (str)
336    3.32. ds_default_socket (str)
337    3.33. ds_timer_mode (int)
338
339 3.1. list_file (string)
340
341    Path to the file with destination sets.
342
343    Default value is “/etc/kamailio/dispatcher.list” or
344    “/usr/local/etc/kamailio/dispatcher.list”.
345
346    Example 1.1. Set the “list_file” parameter
347 ...
348 modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
349 ...
350
351 3.2. db_url (string)
352
353    If you want to load the sets of gateways from the database you must set
354    this parameter.
355
356    Default value is “NULL” (disable DB support).
357
358    Example 1.2. Set “db_url” parameter
359 ...
360 modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database")
361 ...
362
363 3.3. table_name (string)
364
365    If you want to load the sets of gateways from the database you must set
366    this parameter as the database name.
367
368    Default value is “dispatcher”.
369
370    Example 1.3. Set “table_name” parameter
371 ...
372 modparam("dispatcher", "table_name", "my_dispatcher")
373 ...
374
375 3.4. setid_col (string)
376
377    The column's name in the database storing the gateway's group id.
378
379    Default value is “setid”.
380
381    Example 1.4. Set “setid_col” parameter
382 ...
383 modparam("dispatcher", "setid_col", "groupid")
384 ...
385
386 3.5. destination_col (string)
387
388    The column's name in the database storing the destination sip URI.
389
390    Default value is “destination”.
391
392    Example 1.5. Set “destination_col” parameter
393 ...
394 modparam("dispatcher", "destination_col", "uri")
395 ...
396
397 3.6. flags_col (string)
398
399    The column's name in the database storing the flags for the destination
400    URI.
401
402    Default value is “flags”.
403
404    Example 1.6. Set “flags_col” parameter
405 ...
406 modparam("dispatcher", "flags_col", "dstflags")
407 ...
408
409 3.7. priority_col (string)
410
411    The column's name in the database storing the priority for destination
412    URI.
413
414    Default value is “priority”.
415
416    Example 1.7. Set “priority_col” parameter
417 ...
418 modparam("dispatcher", "priority_col", "dstpriority")
419 ...
420
421 3.8. force_dst (int)
422
423    If set to 1, force overwriting of destination address (outbound proxy)
424    when that is already set. If set to 0, will return error when the
425    destination address is already set.
426
427    Default value is “1”.
428
429    Example 1.8. Set the “force_dst” parameter
430 ...
431 modparam("dispatcher", "force_dst", 1)
432 ...
433
434 3.9. flags (int)
435
436    Various flags that affect dispatcher's behaviour. The flags are defined
437    as a bitmask on an integer value. If flag 1 is set only the username
438    part of the URI will be used when computing an URI based hash. If no
439    flags are set the username, hostname and port will be used. The port is
440    used only if different from 5060 (normal sip URI) or 5061 (in the sips:
441    case).
442
443    If flag 2 is set, then failover support is enabled. The functions
444    exported by the module will store the rest of addresses from the
445    destination set in the AVP, and use these AVPs to contact next address
446    if the current-tried destination fails.
447
448    Default value is “0”.
449
450    Example 1.9. Set the “flags” parameter
451  ...
452  modparam("dispatcher", "flags", 3)
453  ...
454
455 3.10. use_default (int)
456
457    If the parameter is set to 1, the last address in destination set is
458    used as a final option to send the request to. For example, it is
459    useful when wanting to send the call to an anouncement server saying:
460    "the gateways are full, try later".
461
462    Default value is “0”.
463
464    Example 1.10. Set the “use_default” parameter
465  ...
466  modparam("dispatcher", "use_default", 1)
467  ...
468
469 3.11. dst_avp (str)
470
471    The name of the avp which will hold the list with addresses, in the
472    order they have been selected by the chosen algorithm. If use_default
473    is 1, the value of last dst_avp_id is the last address in destination
474    set. The first dst_avp_id is the selected destinations. All the other
475    addresses from the destination set will be added in the avp list to be
476    able to implement serial forking.
477
478 Note
479
480    You must set this parameter if you want to do load balancing fail over.
481
482    Default value is “null” - don't add AVPs.
483
484    Example 1.11. Set the “dst_avp” parameter
485  ...
486  modparam("dispatcher", "dst_avp", "$avp(dsdst)")
487  ...
488
489 3.12. grp_avp (str)
490
491    The name of the avp storing the group id of the destination set. Good
492    to have it for later usage or checks.
493
494 Note
495
496    You must set this parameter if you want to do load balancing fail over.
497
498    Default value is “null” - don't add AVP.
499
500    Example 1.12. Set the “grp_avp” parameter
501  ...
502  modparam("dispatcher", "grp_avp", "$avp(dsgrp)")
503  ...
504
505 3.13. cnt_avp (str)
506
507    The name of the avp storing the number of destination addresses kept in
508    dst_avp AVPs.
509
510 Note
511
512    You must set this parameter if you want to do load balancing fail over.
513
514    Default value is “null” - don't add AVP.
515
516    Example 1.13. Set the “cnt_avp” parameter
517  ...
518  modparam("dispatcher", "cnt_avp", "$avp(dscnt)")
519  ...
520
521 3.14. dstid_avp (str)
522
523    The name of the avp storing the destination unique ID used for call
524    load based dispatching.
525
526 Note
527
528    You must set this parameter if you want to do load balancing on call
529    load (alg 10).
530
531    Default value is “null” - don't add AVP.
532
533    Example 1.14. Set the “dstid_avp” parameter
534  ...
535  modparam("dispatcher", "dstid_avp", "$avp(dsdstid)")
536  ...
537
538 3.15. attrs_avp (str)
539
540    The name of the avp storing destination's attributes value.
541
542 Note
543
544    Default value is “null” - don't add AVP.
545
546    Example 1.15. Set the “attrs_avp” parameter
547  ...
548  modparam("dispatcher", "attrs_avp", "$avp(dsattrs)")
549  ...
550
551 3.16. sock_avp (str)
552
553    The name of the avp which will hold the list with the sockets
554    associated to the addresses stored in dst_avp avp.
555
556 Note
557
558    If you want to do load balancing fail over, you have to set this
559    parameter to use the correct socket for each gateway.
560
561    Default value is “null” - don't add AVPs.
562
563    Example 1.16. Set the “sock_avp” parameter
564  ...
565  modparam("dispatcher", "sock_avp", "$avp(dssocket)")
566  ...
567
568 3.17. hash_pvar (str)
569
570    String with PVs used for the hashing algorithm 7.
571
572 Note
573
574    You must set this parameter if you want do hashing over custom message
575    parts.
576
577    Default value is “null” - disabled.
578
579    Example 1.17. Use $avp(i:273) for hashing:
580  ...
581  modparam("dispatcher", "hash_pvar", "$avp(i:273)")
582  ...
583
584    Example 1.18. Use combination of PVs for hashing:
585  ...
586  modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
587  ...
588
589 3.18. setid_pvname (str)
590
591    The name of the PV where to store the set ID (group ID) when calling
592    ds_is_from_list() with no parameter.
593
594    Default value is “null” - don't set PV.
595
596    Example 1.19. Set the “setid_pvname” parameter
597  ...
598  modparam("dispatcher", "setid_pvname", "$var(setid)")
599  ...
600
601 3.19. attrs_pvname (str)
602
603    The name of the PV where to store the attributes of matching address
604    when calling ds_is_from_list().
605
606    Default value is “null” - don't set PV.
607
608    Example 1.20. Set the “attrs_pvname” parameter
609  ...
610  modparam("dispatcher", "attrs_pvname", "$var(attrs)")
611  ...
612
613 3.20. ds_ping_method (string)
614
615    With this method you can define, with which method you want to probe
616    the gateways. Pinging gateways feature depends on ds_ping_interval
617    parameter.
618
619    Default value is “OPTIONS”.
620
621    Example 1.21. Set the “ds_ping_method” parameter
622  ...
623  modparam("dispatcher", "ds_ping_method", "INFO")
624  ...
625
626 3.21. ds_ping_from (string)
627
628    With this Method you can define the "From:"-Line for the request, sent
629    to the failed gateways. This method is only available, if compiled with
630    the probing of failed gateways enabled.
631
632    Default value is “sip:dispatcher@localhost”.
633
634    Example 1.22. Set the “ds_ping_from” parameter
635  ...
636  modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
637  ...
638
639 3.22. ds_ping_interval (int)
640
641    With this parameter you can define the interval for sending a request
642    to a gateway marked as inactive upon a failed request routing to it.
643    This parameter is only used, when the TM-Module is loaded. If set to
644    “0”, the pinging of inactive gateway is disabled.
645
646    Default value is “0”.
647
648    Example 1.23. Set the “ds_ping_interval” parameter
649  ...
650  modparam("dispatcher", "ds_ping_interval", 30)
651  ...
652
653 3.23. ds_probing_threshold (int)
654
655    If you want to set a gateway into inactive mode, there can be a
656    specific number of failed requests until it will change from "active"
657    to "inactive". It is using the state "trying", that allows selection of
658    gateway but indicates there was a failure previously with the gateway.
659    The number of attempts can be set with this parameter. This parameter
660    can be modified via ser config framework.
661
662    Default value is “1” (set inactive with first failure).
663
664    Example 1.24. Set the “ds_probing_threshold” parameter
665  ...
666  modparam("dispatcher", "ds_probing_threshold", 10)
667  ...
668
669 3.24. ds_inactive_threshold (int)
670
671    If you want to set a gateway into active mode (after being inactive),
672    there can be a specific number of successful requests until it will
673    change from "inactive" to "active". The number of attempts can be set
674    with this parameter. This parameter can be modified via ser config
675    framework.
676
677    Default value is “1” (set active with first success).
678
679    Example 1.25. Set the “ds_inactive_threshold” parameter
680  ...
681  modparam("dispatcher", "ds_inactive_threshold", 10)
682  ...
683
684 3.25. ds_ping_reply_codes (string)
685
686    This parameter defines the valid response codes, which are accepted as
687    a valid reply to the PING-Method. It is a list separated by colons,
688    whery you may define either a single code (e.g. "code=202" would accept
689    202 as an additional, valid response) or a class of responses, you want
690    to accept (e.g. "class=2" would accept everything from 200 to 299 as
691    valid response). This parameter can be modified via ser config
692    framework.
693
694    Please note that the response codes the module accepts as valid reply
695    to the PING-Method are not only the ones generated from the remote
696    servers, but also those that are generated locally. E.g.: setting
697    code=408 or class=400 will never set a backend down even if it is,
698    because internally the Kamailio transaction layer generates a 408 in
699    the case of no response from the remote server, and this internal code
700    408 is accepted as valid value.
701
702    Default value is “” (only 200 OK is accepted).
703
704    Example 1.26. Set the “ds_ping_reply_codes” parameter
705  ...
706  modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=
707 3")
708  ...
709
710 3.26. ds_probing_mode (int)
711
712    Controls what gateways are tested to see if they are reachable.
713      * Value 0: If set to 0, only the gateways with state PROBING are
714        tested. After a gateway is probed, the PROBING state is cleared in
715        this mode.
716      * Value 1: If set to 1, all gateways are tested. If set to 1 and
717        there is a failure of keepalive to an active gateway, then it is
718        set to TRYING state.
719      * Value 2: if set to 2, only gateways in inactive state with probing
720        mode set are tested.
721      * Value 3: If set to 3, any gateway with state PROBING is continually
722        probed without modifying/removing the PROBING state. This allows
723        selected gateways to be probed continually, regardless of state
724        changes.
725
726    Default value is “0”.
727
728    Example 1.27. Set the “ds_probing_mode” parameter
729  ...
730  modparam("dispatcher", "ds_probing_mode", 1)
731  ...
732
733 3.27. ds_hash_size (int)
734
735    The value to be used as power of two to set the number of slots to hash
736    table storing data for call load dispatching (e.g., value 8 will create
737    a hash table with 256 slots). It must be greater than 0 to enable call
738    load dispatching feature (alg 10).
739
740    Default value is “0”.
741
742    Example 1.28. Set the “ds_hash_size” parameter
743  ...
744  modparam("dispatcher", "ds_hash_size", 9)
745  ...
746
747 3.28. ds_hash_expire (int)
748
749    Expiration time in seconds to remove the load on a destination if no
750    BYE was received meanwhile.
751
752    Default value is “7200”.
753
754    Example 1.29. Set the “ds_hash_expire” parameter
755  ...
756  modparam("dispatcher", "ds_hash_expire", 3600)
757  ...
758
759 3.29. ds_hash_initexpire (int)
760
761    Expiration time in seconds to remove the load on a destination if no
762    200 for INVITE was received meanwhile and state updated with
763    ds_load_update().
764
765    Default value is “7200”.
766
767    Example 1.30. Set the “ds_hash_initexpire” parameter
768  ...
769  modparam("dispatcher", "ds_hash_initexpire", 60)
770  ...
771
772 3.30. ds_hash_check_interval (int)
773
774    Time interval in seconds to scan internal hash table with call load
775    dispatching data for expired items.
776
777    Default value is “30”.
778
779    Example 1.31. Set the “ds_hash_check_interval” parameter
780  ...
781  modparam("dispatcher", "ds_hash_check_interval", 60)
782  ...
783
784 3.31. outbound_proxy (str)
785
786    SIP URI of outbound proxy to be used when sending pings.
787
788    By default no outbound proxy is defined.
789
790    Example 1.32. Set the “outbound_proxy” parameter
791  ...
792  modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
793  ...
794
795 3.32. ds_default_socket (str)
796
797    Default socket to be used for sending pings and dispatching requests
798    when a gateway has no send socket configured.
799
800    By default no default socket is defined, the first configuration script
801    listen directive is used.
802
803    Example 1.33. Set the “ds_default_socket” parameter
804  ...
805  modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
806  ...
807
808 3.33. ds_timer_mode (int)
809
810    Specify the timer process to be used by the module for keepalives and
811    active dialogs tracking.
812
813    It can be set to:
814      * 0 - use main timer process.
815      * 1 - use secondary timer process.
816
817    On a server with a lot of traffic, using secondary timer can help with
818    performances, because the main timer can be overloaded by taking care
819    of transactions retransmissions and expirations of items in memory.
820
821    Default value is “0”.
822
823    Example 1.34. Set the “ds_timer_mode” parameter
824  ...
825  modparam("dispatcher", "ds_timer_mode", 1)
826  ...
827
828 4. Functions
829
830    4.1. ds_select_dst(set, alg[, limit])
831    4.2. ds_select_domain(set, alg[, limit])
832    4.3. ds_select(set, alg [, limit])
833    4.4. ds_next_dst()
834    4.5. ds_next_domain()
835    4.6. ds_mark_dst([state])
836    4.7. ds_list_exist(groupid)
837    4.8. ds_is_from_list([groupid [, mode [, uri] ] ])
838    4.9. ds_load_update()
839    4.10. ds_load_unset()
840    4.11. ds_reload()
841
842 4.1.  ds_select_dst(set, alg[, limit])
843
844    The method selects a destination from addresses set. It returns true if
845    a new destination is set. The selected address is set to dst_uri field
846    (aka the outbound proxy address or the $du variable), not being visible
847    in the SIP request.
848
849    If the bit 2 in 'flags' parameter is set, the rest of the addresses
850    from the destination set is stored in AVP list (limited with an
851    optional 'limit' parameter). You can use 'ds_next_dst()' to use next
852    address in order to achieve serial forking to all possible
853    destinations.
854
855    Meaning of the parameters is as follows:
856      * set - the id of the set from where to pick up destination address.
857        It is the first column in destination list file. The parameter can
858        be an integer or a variable holding an integer.
859      * alg - the algorithm used to select the destination address. The
860        parameter can be an integer or a variable holding an interger.
861           + “0” - hash over callid
862           + “1” - hash over from URI.
863           + “2” - hash over to URI.
864           + “3” - hash over request-URI.
865           + “4” - round-robin (next destination).
866           + “5” - hash over authorization-username (Proxy-Authorization or
867             "normal" authorization). If no username is found, round robin
868             is used.
869           + “6” - random destination (using rand()).
870           + “7” - hash over the content of PVs string. Note: This works
871             only when the parameter hash_pvar is set.
872           + “8” - select destination sorted by priority attribute value
873             (serial forking ordered by priority).
874           + “9” - use weight based load distribution. You have to set the
875             attribute 'weight' per each address in destination set.
876           + “10” - use call load distribution. You have to set the
877             attribute 'duid' (as an unique string id) per each address in
878             destination set. Also, you must set parameters 'dstid_avp' and
879             'ds_hash_size'.
880             The algorithm can be used even with stateless proxy mode,
881             there is no SIP dialog tracking depending on other modules,
882             just an internal lightweight call tracking by Call-Id, thus is
883             fast and suitable even for embedded systems.
884             The first destination selected by this algorithm is the one
885             that has the least number of calls associated. The rest of the
886             destination list is taken in order of the entries in set -
887             anyhow, until a re-route to next destination happens, the load
888             on each address can change.
889             This algorithm can be used only for dispatching INVITE
890             requests as it is the only SIP method creating a SIP call.
891           + “11” - use relative weight based load distribution. You have
892             to set the attribute 'rweight' per each address in destination
893             set. Active host usage probability is rweight/(SUM of all
894             active host rweights in destination group).
895             The major difference from the weight distribution is the
896             probability recalculation according to rweight value in case
897             of host enabling/disabling
898             For example, 100 calls in 3-hosts group with rweight params
899             1/2/1 will be distributed as 25/50/25. After third host
900             failing distribution will be changed to 33/67/0.
901           + “X” - if the algorithm is not implemented, the first entry in
902             set is chosen.
903      * limit - the maximum number of items to be stored in AVP list for
904        further failovers (the first selected destination and default
905        destination are the first to be put in the list)
906
907    If the bit 2 in 'flags' is set, the rest of the addresses from the
908    destination set is stored in AVP list. You can use 'ds_next_dst()' to
909    use next address to achieve serial forking to all possible
910    destinations.
911
912    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
913
914    Example 1.35. ds_select_dst usage
915 ...
916 ds_select_dst("1", "0");
917 ...
918 $var(a) = 4;
919 ds_select_dst("1", "$var(a)");
920 ...
921 ds_select_dst("1", "4", "3");
922 ...
923
924 4.2.  ds_select_domain(set, alg[, limit])
925
926    The method selects a destination from addresses set and rewrites the
927    host and port from R-URI. The parameters have same meaning as for
928    ds_select_dst().
929
930    If the bit 2 in 'flags' is set, the rest of the addresses from the
931    destination set is stored in AVP list (limited with an optional 'limit'
932    parameter). You can use 'ds_next_domain()' to use next address to
933    achieve serial forking to all possible destinations.
934
935    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
936
937    Example 1.36. ds_select_domain usage
938 ...
939 $var(a) = 4;
940 if(ds_select_domain("1", "$var(a)")) {
941     t_relay();
942     exit;
943 }
944 ...
945
946 4.3.  ds_select(set, alg [, limit])
947
948    The method selects a destination from addresses set and adds it in the
949    AVPs specified for this module. It is not updating R-URI nor the
950    destination URI. The parameters have same meaning as for
951    ds_select_dst().
952
953    If the bit 2 in 'flags' is set, the rest of the addresses from the
954    destination set is stored in AVP list (limited with an optional 'limit'
955    parameter). You can execute 'ds_next_domain()' or 'ds_next_dst()' to
956    use next address to achieve serial forking to all possible
957    destinations.
958
959    This function can be used from ANY_ROUTE.
960
961    Example 1.37. ds_select usage
962 ...
963 $var(a) = 4;
964 if(ds_select("1", "$var(a)")) {
965     ds_next_domain();
966     t_relay();
967     exit;
968 }
969 ...
970
971 4.4.  ds_next_dst()
972
973    Takes the next destination address from the AVPs with id 'dst_avp_id'
974    and sets the dst_uri (outbound proxy address).
975
976    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
977
978 4.5.  ds_next_domain()
979
980    Takes the next destination address from the AVPs with id 'dst_avp_id'
981    and sets the domain part of the request URI.
982
983    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
984
985 4.6.  ds_mark_dst([state])
986
987    Mark the last used address from destination set as inactive ("i"/"I"),
988    active ("a"/"A"), disabled ("d"/"D") or trying ("t"/"T"). Apart of
989    disabled state, a destination can be set in probing mode by adding
990    ("p"/"P") flag. With this function, an automatic detection of failed
991    gateways can be implemented. When an address is marked as inactive or
992    disabled, it will be ignored by 'ds_select_dst' and 'ds_select_domain'.
993
994    The parameter state is optional, when it is missing, then the
995    destination will be marked inactive (i.e., same as 'i').
996
997    Possible values for state parameter:
998      * "a" or "A" - the last destination should be set to active and the
999        error-counter should set to "0".
1000      * "i" or "I" - the last destination should be set to inactive and
1001        will be ignored in future requests.
1002      * "t" or "T" - the last destination should be set to temporary trying
1003        state and failure counter is incremented. When the failure counter
1004        reaches the threshold, the destination will be set inactive.
1005      * "p" and "P" - this has to be used in addition to one of the
1006        previous flags - the last destination will be set to probing. This
1007        mean the destination will be pinged with SIP OPTIONS requests from
1008        time to time to detect if it is up running or down.
1009
1010    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
1011
1012    Example 1.38. ds_mark_dst usage
1013 ...
1014 failure_route[tryagain] {
1015 ...
1016    if(t_check_status("500"))
1017       ds_mark_dst("ip"); # set to inactive and probing
1018 ...
1019 }
1020 ...
1021
1022 4.7.  ds_list_exist(groupid)
1023
1024    Check if a specific group is defined in dispatcher list or database.
1025      * groupid - A group ID to check.
1026
1027    This function can be used from ANY_ROUTE.
1028
1029    Example 1.39. ds_list_exist usage
1030 ...
1031 if(ds_list_exist("10")) {
1032     ...
1033 }
1034 ...
1035
1036 4.8.  ds_is_from_list([groupid [, mode [, uri] ] ])
1037
1038    This function returns true, if there is a match of source address or
1039    uri with an address in the given group of the dispatcher-list;
1040    otherwise false.
1041
1042    Description of parameters:
1043      * groupid (optional) - if not given or its value is -1, the matching
1044        will be done over all addresses in all dispacher groups. Otherwise
1045        the matching will be done only against the addresses in the
1046        specific group id. The parameter can be an integer or a variable
1047        holding an integer value.
1048      * mode - (optional) - a bitmask to specify how the matching should be
1049        done. If is 0, all ip, port and proto are matched. If bit one is
1050        set, then port is ignored. If bit two is set, then protocol is
1051        ignored. The parameter can be an integer or a variable holding an
1052        integer value. It must be provided if the uri parameter is
1053        provided.
1054      * uri (optional) - if is empty or missing, the matching is done
1055        against source IP, port and protocol. Otherwise the value has to be
1056        a valid SIP URI, used to match against addresses in the dispatcher
1057        list. Only IP, port and protocol are matches, any additional
1058        parameters are ignored. The parameter can be a static or dynamic
1059        (with variables) string. The domain part of the URI can be an IP
1060        address or a hostname.
1061
1062    Upon a match, the variable specified by 'setid_pvname' parameter will
1063    be set to groupid of matching address and the attributes will be set in
1064    variable specified by 'attrs_pvname'.
1065
1066    Note that for backward compatibility mode, when no parameter is given
1067    or only groupid is given, the matching is done only for IP address and
1068    port (protocol is ignored).
1069
1070    This function can be used from ANY_ROUTE.
1071
1072    Example 1.40. ds_is_from_list usage
1073 ...
1074 if(ds_is_from_list()) {
1075     ...
1076 }
1077 if(ds_is_from_list("10")) {
1078     ...
1079 }
1080 if(ds_is_from_list("10", "3")) {
1081     ...
1082 }
1083 if(ds_is_from_list("10", "3", "sip:127.0.0.1:5080")) {
1084     ...
1085 }
1086 ...
1087
1088 4.9.  ds_load_update()
1089
1090    Updates the load state:
1091      * if it is a BYE or CANCEL - remove the load from destination address
1092        used to forward the INVITE
1093      * if it is a reply to INVITE - set internal state to confirmed for
1094        call load structure when reply code is 2xx.
1095
1096    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
1097    BRANCH_ROUTE and ONREPLY_ROUTE.
1098
1099 4.10.  ds_load_unset()
1100
1101    Remove the call load for the destination that routed the call.
1102
1103    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
1104    BRANCH_ROUTE and ONREPLY_ROUTE.
1105
1106    Example 1.41. ds_load_unset usage
1107 ...
1108 route {
1109     ...
1110         if(is_method("BYE|CANCEL"))
1111         ds_load_update();
1112     ...
1113         ds_select_dst("1", "10");
1114     ...
1115 }
1116
1117 onreply_route {
1118     ...
1119     if(is_method("INVITE")
1120         {
1121         if(status=~"2[0-9][0-9]")
1122             ds_load_update();
1123         else if(status=~"[3-7][0-9][0-9]")
1124             ds_load_unset();
1125     }
1126     ...
1127 }
1128 ...
1129
1130 4.11.  ds_reload()
1131
1132    Reloads the groups and included destinations.
1133
1134    Name: ds_reload
1135
1136    Parameters: none
1137
1138    This function can be used from ANY_ROUTE.
1139
1140 5. MI Commands
1141
1142    5.1. ds_set_state
1143    5.2. ds_list
1144    5.3. ds_reload
1145
1146 5.1.  ds_set_state
1147
1148    Sets the status for a destination address (can be use to mark the
1149    destination as active or inactive).
1150
1151    Name: ds_set_state
1152
1153    Parameters:
1154      * _state_ : state of the destination address
1155           + “a”: active
1156           + “i”: inactive
1157           + “t”: trying
1158           + “d”: disabled
1159        The states “a”, “i” or “t” can be followed by “p” to set probing
1160        mode (e.g. 'ap', 'ip' or 'tp').
1161      * _group_: destination group id
1162      * _address_: address of the destination in the _group_
1163
1164    MI FIFO Command Format:
1165                 :ds_set_state:_reply_fifo_file_
1166                 _state_
1167                 _group_
1168                 _address_
1169                 _empty_line_
1170
1171 5.2.  ds_list
1172
1173    It lists the groups and included destinations.
1174
1175    Name: ds_list
1176
1177    Parameters: none
1178
1179    MI FIFO Command Format:
1180                 :ds_list:_reply_fifo_file_
1181                 _empty_line_
1182
1183 5.3.  ds_reload
1184
1185    It reloads the groups and included destinations. For algorithm 10 (call
1186    load distribution), old internal list of active calls is destroyed
1187    (because it is bould to the previous list of gateways), meaning that
1188    the module is starting to count active calls again from 0.
1189
1190    Name: ds_reload
1191
1192    Parameters: none
1193
1194    MI DATAGRAM Command Format:
1195                 ":ds_reload:\n."
1196
1197 6. RPC Commands
1198
1199    6.1. dispatcher.set_state
1200    6.2. dispatcher.list
1201    6.3. dispatcher.reload
1202    6.4. dispatcher.ping_active
1203
1204 6.1.  dispatcher.set_state
1205
1206    Sets the state for a destination address (can be use to mark the
1207    destination as active or inactive).
1208
1209    Name: dispatcher.set_state
1210
1211    Parameters:
1212      * _state_ : state of the destination address
1213           + “a”: active
1214           + “i”: inactive
1215           + “t”: trying
1216           + “d”: disabled
1217        The states “a”, “i” or “t” can be followed by “p” to set probing
1218        mode (e.g. 'ap', 'ip' or 'tp').
1219      * _group_: destination group id
1220      * _address_: address of the destination in the _group_
1221
1222    Example:
1223 ...
1224 # prototype: kamcmd dispatcher.set_state _state_ _group_ _address_
1225 kamcmd dispatcher.set_state ip 2 sip:127.0.0.1:5080
1226 ...
1227
1228 6.2.  dispatcher.list
1229
1230    Lists the groups and included destinations.
1231
1232    Name: dispatcher.list
1233
1234    Parameters: none
1235
1236    Example:
1237                 kamcmd dispatcher.list
1238
1239 6.3.  dispatcher.reload
1240
1241    Reloads the groups and included destinations. The command is disabled
1242    for call load based dispatching (algorithm 10) since removal of
1243    destinations may leave the list of active calls with broken references.
1244
1245    Name: dispatcher.reload
1246
1247    Parameters: none
1248
1249    Example
1250                 kamcmd dispatcher.reload
1251
1252 6.4.  dispatcher.ping_active
1253
1254    Sets the global state for sending keepalive requests to destinations.
1255
1256    Name: dispatcher.ping_active
1257
1258    Parameters:
1259      * _state_ : state of sending keepalives
1260           + “0”: inactive (don't send)
1261           + “1”: active (send)
1262
1263    If the state parameter is missing, the current state is returned. When
1264    state is changed, new and old values of the state are returned. Default
1265    value for state is 1.
1266
1267    Example:
1268 ...
1269 # prototype: kamcmd dispatcher.ping_active _state_
1270 kamcmd dispatcher.ping_active 0
1271 ...
1272
1273 7. Installation and Running
1274
1275    7.1. Destination List File
1276
1277         7.1.1. Special Attributes
1278         7.1.2. File Format
1279
1280    7.2. Kamailio config file
1281
1282 7.1. Destination List File
1283
1284    Each destination point must be on one line. First token is the set id
1285    (an integer value), followed by destination address (s string value in
1286    SIP URI format).
1287
1288    Optionally, these fields can be followed by:
1289      * flags (listed by index - can be bitwise mask of values): 0 (value
1290        1) - inactive destination; 1 (value 2) - temporary trying
1291        destination (in the way to become inactive if it does not reply to
1292        keepalives - there is a module parameter to set the threshold of
1293        failures); 2 (value 4) - admin disabled destination; 3 (value 8) -
1294        probing destination (sending keep alives);
1295      * priority: sets the priority in destination list (based on it is
1296        done the initial ordering inside the set)
1297      * attributes: extra fields in form of name1=value1;...;nameN=valueN.
1298
1299 7.1.1. Special Attributes
1300
1301    There are some predefined names:
1302      * 'duid' - used for call load dispatching. It must be an unique value
1303        to identify a destination (gateway address). Practically the load
1304        within the group is associated with this value.
1305      * 'maxload' - used for call load dispatching. It must be a positive
1306        integer, defining the upper limit of active calls per destination.
1307        When the limit is reached, then the gateway is no longer selected
1308        for new calls until an exiting call via that gateway is terminated.
1309        If set to 0, then no active call limit is used.
1310      * 'weight' - used for weight based load distribution. It must be set
1311        to a positive integer value beteen 0 and 100. The value represents
1312        the percent of calls to be sent to that gateways.
1313      * 'rweight' - used for relative weight based load distribution. It
1314        must be set to a positive integer value between 1 and 100
1315        (otherwise host will be excluded from relative weight distribution
1316        type).
1317      * 'socket' - used to set the sending socket for the gateway. It is
1318        used for sending the SIP traffic as well as OPTIONS keepalives.
1319
1320 7.1.2. File Format
1321
1322    Line format is:
1323 ...
1324 setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
1325 ...
1326
1327    Full line example:
1328 ...
1329 1 sip:127.0.0.1:5080 0 0 duid=abc;socket=udp:192.168.0.125:5060;my=xyz
1330 ...
1331
1332    For database, each element of a line resides in a different column.
1333    Next is a dispatcher.list file example:
1334
1335    Example 1.42. dispatcher list file
1336 ...
1337 # $Id$
1338 # dispatcher destination sets
1339 #
1340
1341 # line format
1342 # setit(int) destination(sip uri) flags(int,opt) priority(int,opt) attributes(st
1343 r,opt)
1344
1345 # proxies
1346 2 sip:127.0.0.1:5080
1347 2 sip:127.0.0.1:5082
1348
1349 # gateways
1350 1 sip:127.0.0.1:7070
1351 1 sip:127.0.0.1:7072
1352 1 sip:127.0.0.1:7074
1353
1354 ...
1355
1356 7.2. Kamailio config file
1357
1358    Next listing shows a sample config for using the dispatcher module.
1359
1360    Example 1.43. Kamailio config script - sample dispatcher usage
1361 ...
1362 #!KAMAILIO
1363 #
1364 # sample config file for dispatcher module
1365 # - load balancing of VoIP calls with round robin
1366 # - no TPC listening
1367 # - don't dispatch REGISTER and presence requests
1368 #
1369 # Kamailio SIP Server
1370 #     - web: http://www.kamailio.org
1371 #     - git: http://github.com/kamailio/
1372 #
1373 # Direct your questions about this file to: sr-users@lists.sip-router.org
1374 #
1375 # Refer to the Core CookBook at http://www.kamailio.org/dokuwiki/doku.php
1376 # for an explanation of possible statements, functions and parameters.
1377 #
1378 # Several features can be enabled using '#!define WITH_FEATURE' directives:
1379 #
1380 # *** To run in debug mode:
1381 #     - define WITH_DEBUG
1382 #
1383
1384 #!ifndef DBURL
1385 #!define DBURL "mysql://kamailio:kamailiorw@localhost/kamailio"
1386 #!endif
1387
1388 # - flags
1389 #   FLT_ - per transaction (message) flags
1390 #       FLB_ - per branch flags
1391 #!define FLT_ACC 1
1392 #!define FLT_ACCMISSED 2
1393 #!define FLT_ACCFAILED 3
1394
1395 ####### Global Parameters #########
1396
1397 #!ifdef WITH_DEBUG
1398 debug=4
1399 log_stderror=yes
1400 #!else
1401 debug=2
1402 log_stderror=no
1403 #!endif
1404
1405 memdbg=5
1406 memlog=5
1407
1408 log_facility=LOG_LOCAL0
1409
1410 fork=yes
1411 children=4
1412
1413 /* comment the next line to enable TCP */
1414 disable_tcp=yes
1415
1416 /* uncomment the next line to disable the auto discovery of local aliases
1417    based on revers DNS on IPs (default on) */
1418 auto_aliases=no
1419
1420 /* add local domain aliases */
1421 # alias="mysipserver.com"
1422
1423 port=5060
1424
1425 /* uncomment and configure the following line if you want Kamailio to
1426    bind on a specific interface/port/proto (default bind on all available) */
1427 # listen=udp:127.0.0.1:5060
1428
1429 sip_warning=no
1430
1431 ####### Modules Section ########
1432
1433 # set module path
1434 mpath="/usr/local/lib/kamailio/modules/"
1435
1436 loadmodule "db_mysql.so"
1437 loadmodule "mi_fifo.so"
1438 loadmodule "kex.so"
1439 loadmodule "tm.so"
1440 loadmodule "tmx.so"
1441 loadmodule "sl.so"
1442 loadmodule "rr.so"
1443 loadmodule "pv.so"
1444 loadmodule "maxfwd.so"
1445 loadmodule "textops.so"
1446 loadmodule "siputils.so"
1447 loadmodule "xlog.so"
1448 loadmodule "sanity.so"
1449 loadmodule "ctl.so"
1450 loadmodule "mi_rpc.so"
1451 loadmodule "acc.so"
1452 loadmodule "dispatcher.so"
1453
1454
1455 # ----------------- setting module-specific parameters ---------------
1456
1457
1458 # ----- rr params -----
1459 # add value to ;lr param to cope with most of the UAs
1460 modparam("rr", "enable_full_lr", 1)
1461 # do not append from tag to the RR (no need for this script)
1462 modparam("rr", "append_fromtag", 0)
1463
1464
1465 # ----- acc params -----
1466 modparam("acc", "log_flag", FLT_ACC)
1467 modparam("acc", "failed_transaction_flag", FLT_ACCFAILED)
1468 modparam("acc", "log_extra",
1469         "src_user=$fU;src_domain=$fd;dst_ouser=$tU;dst_user=$rU;dst_domain=$rd;s
1470 rc_ip=$si")
1471
1472 # ----- tm params -----
1473 modparam("tm", "fr_timer", 2000)
1474 modparam("tm", "fr_inv_timer", 40000)
1475
1476 # ----- dispatcher params -----
1477 modparam("dispatcher", "db_url", DBURL)
1478 modparam("dispatcher", "table_name", "dispatcher")
1479 modparam("dispatcher", "flags", 2)
1480 modparam("dispatcher", "dst_avp", "$avp(AVP_DST)")
1481 modparam("dispatcher", "grp_avp", "$avp(AVP_GRP)")
1482 modparam("dispatcher", "cnt_avp", "$avp(AVP_CNT)")
1483 modparam("dispatcher", "sock_avp", "$avp(AVP_SOCK)")
1484
1485 ####### Routing Logic ########
1486
1487
1488 # main request routing logic
1489
1490 request_route {
1491
1492         # per request initial checks
1493         route(REQINIT);
1494
1495         # handle requests within SIP dialogs
1496         route(WITHINDLG);
1497
1498         ### only initial requests (no To tag)
1499
1500         # CANCEL processing
1501         if (is_method("CANCEL"))
1502         {
1503                 if (t_check_trans())
1504                         t_relay();
1505                 exit;
1506         }
1507
1508         # handle retransmissions
1509         if(t_precheck_trans()) {
1510                 t_check_trans();
1511                 exit;
1512         }
1513         t_check_trans();
1514
1515         # record routing for dialog forming requests (in case they are routed)
1516         # - remove preloaded route headers
1517         remove_hf("Route");
1518         if (is_method("INVITE|SUBSCRIBE"))
1519                 record_route();
1520
1521         # account only INVITEs
1522         if (is_method("INVITE")) {
1523                 setflag(FLT_ACC); # do accounting
1524         }
1525
1526         # handle presence related requests
1527         route(PRESENCE);
1528
1529         # handle registrations
1530         route(REGISTRAR);
1531
1532         if ($rU==$null) {
1533                 # request with no Username in RURI
1534                 sl_send_reply("484","Address Incomplete");
1535                 exit;
1536         }
1537
1538         # dispatch destinations
1539         route(DISPATCH);
1540 }
1541
1542
1543 route[RELAY] {
1544         if (!t_relay()) {
1545                 sl_reply_error();
1546         }
1547         exit;
1548 }
1549
1550 # Per SIP request initial checks
1551 route[REQINIT] {
1552         if (!mf_process_maxfwd_header("10")) {
1553                 sl_send_reply("483","Too Many Hops");
1554                 exit;
1555         }
1556
1557         if(!sanity_check("1511", "7")) {
1558                 xlog("Malformed SIP message from $si:$sp\n");
1559                 exit;
1560         }
1561 }
1562
1563 # Handle requests within SIP dialogs
1564 route[WITHINDLG] {
1565         if (has_totag()) {
1566                 # sequential request withing a dialog should
1567                 # take the path determined by record-routing
1568                 if (loose_route()) {
1569                         if (is_method("BYE")) {
1570                                 setflag(FLT_ACC); # do accounting ...
1571                                 setflag(FLT_ACCFAILED); # ... even if the transa
1572 ction fails
1573                         }
1574                         route(RELAY);
1575                 } else {
1576                         if (is_method("SUBSCRIBE") && uri == myself) {
1577                                 # in-dialog subscribe requests
1578                                 route(PRESENCE);
1579                                 exit;
1580                         }
1581                         if ( is_method("ACK") ) {
1582                                 if ( t_check_trans() ) {
1583                                         # non loose-route, but stateful ACK;
1584                                         # must be ACK after a 487 or e.g. 404 fr
1585 om upstream server
1586                                         t_relay();
1587                                         exit;
1588                                 } else {
1589                                         # ACK without matching transaction ... i
1590 gnore and discard.
1591                                         exit;
1592                                 }
1593                         }
1594                         sl_send_reply("404","Not here");
1595                 }
1596                 exit;
1597         }
1598 }
1599
1600 # Handle SIP registrations
1601 route[REGISTRAR] {
1602         if(!is_method("REGISTER"))
1603                 return;
1604         sl_send_reply("404", "No registrar");
1605         exit;
1606 }
1607
1608 # Presence server route
1609 route[PRESENCE] {
1610         if(!is_method("PUBLISH|SUBSCRIBE"))
1611                 return;
1612
1613         sl_send_reply("404", "Not here");
1614         exit;
1615 }
1616
1617 # Dispatch requests
1618 route[DISPATCH] {
1619         # round robin dispatching on gateways group '1'
1620         if(!ds_select_dst("1", "4")) {
1621                 send_reply("404", "No destination");
1622                 exit;
1623         }
1624         xlog("L_DBG", "--- SCRIPT: going to <$ru> via <$du>\n");
1625         t_on_failure("RTF_DISPATCH");
1626         route(RELAY);
1627         exit;
1628 }
1629
1630 # Try next destionations in failure route
1631 failure_route[RTF_DISPATCH] {
1632         if (t_is_canceled()) {
1633                 exit;
1634         }
1635         # next DST - only for 500 or local timeout
1636         if (t_check_status("500")
1637                         or (t_branch_timeout() and !t_branch_replied())) {
1638                 if(ds_next_dst()) {
1639                         t_on_failure("RTF_DISPATCH");
1640                         route(RELAY);
1641                         exit;
1642                 }
1643         }
1644 }
1645
1646 ...
1647
1648 8. Event routes
1649
1650    8.1. dispatcher:dst-down
1651    8.2. dispatcher:dst-up
1652
1653 8.1.  dispatcher:dst-down
1654
1655    When defined, the module calls event_route[dispatcher:ds-down] when a
1656    destination goes down (becomes probing). A typical use case is to
1657    update NMC equipment as to the status of a destination.
1658 ...
1659 event_route[dispatcher:dst-down] {
1660     xlog("L_ERR", "Destination down: $rm $ru ($du)\n");
1661 }
1662 ...
1663
1664 8.2.  dispatcher:dst-up
1665
1666    When defined, the module calls event_route[dispatcher:ds-up] when a
1667    destination that was previously down (probing) comes up. A typical use
1668    case is to update NMC equipment as to the status of a destination.
1669 ...
1670 event_route[dispatcher:dst-up] {
1671     xlog("L_ERR", "Destination up: $rm $ru\n");
1672 }
1673 ...
1674
1675 Chapter 2. Frequently Asked Questions
1676
1677    2.1. Does dispatcher provide a fair distribution?
1678    2.2. Is dispatcher dialog stateful?
1679    2.3. Where can I find more about Kamailio?
1680    2.4. Where can I post a question about this module?
1681    2.5. How can I report a bug?
1682
1683    2.1.
1684
1685        Does dispatcher provide a fair distribution?
1686
1687        The algoritms doing hashing over parts of SIP message don't guarantee a
1688        fair distribution. You should do some measurements to decide what
1689        hashing algorithm fits better in your environment.
1690
1691        Other distribution algorithms such as round robin or call load
1692        dispatching do a fair distribution in terms of delivered calls to
1693        gateways.
1694
1695    2.2.
1696
1697        Is dispatcher dialog stateful?
1698
1699        No. Dispatcher is stateless, although some distribution algorithms are
1700        designed to select same destination for subsequent requests of the same
1701        dialog (e.g., hashing the call-id).
1702
1703    2.3.
1704
1705        Where can I find more about Kamailio?
1706
1707        Take a look at http://www.kamailio.org/.
1708
1709    2.4.
1710
1711        Where can I post a question about this module?
1712
1713        First at all check if your question was already answered on one of our
1714        mailing lists:
1715          * User Mailing List -
1716            http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
1717          * Developer Mailing List -
1718            http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev
1719
1720        E-mails regarding any stable version should be sent to
1721        <sr-users@lists.sip-router.org> and e-mail regarding development
1722        versions or GIT snapshots should be send to
1723        <sr-dev@lists.sip-router.org>.
1724
1725        If you want to keep the mail private, send it to
1726        <sr-users@lists.sip-router.org>.
1727
1728    2.5.
1729
1730        How can I report a bug?
1731
1732        Please follow the guidelines provided at:
1733        https://github.com/kamailio/kamailio/issues