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

src/modules/dispatcher/README

@@ -1,2 +1,1888 @@
+DISPATCHER Module
 
+Daniel-Constantin Mierla
 
+   <[email protected]>
+
+Edited by
+
+Daniel-Constantin Mierla
+
+   <[email protected]>
+
+Edited by
+
+Carsten Bock
+
+   ng-voice GmbH
+
+Edited by
+
+Olle E. Johansson
+
+   Edvina AB
+
+Edited by
+
+Alessandro Arrichiello
+
+   Hewlett Packard
+
+Edited by
+
+Luis Martin
+
+Edited by
+
+Julien Chavanton
+
+   <[email protected]>
+
+   Copyright © 2004 FhG FOKUS
+
+   Copyright © 2005 Voice Sistem
+
+   Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
+
+   Copyright © 2014 Olle E. Johansson, Edvina AB
+
+   Copyright © 2015 Alessandro Arrichiello, Hewlett Packard
+
+   Copyright © 2017, 2018 Julien chavanton, Flowroute
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio modules
+              2.2. External libraries or applications
+
+        3. Parameters
+
+              3.1. list_file (string)
+              3.2. db_url (string)
+              3.3. table_name (string)
+              3.4. setid_col (string)
+              3.5. destination_col (string)
+              3.6. flags_col (string)
+              3.7. priority_col (string)
+              3.8. force_dst (int)
+              3.9. flags (int)
+              3.10. use_default (int)
+              3.11. xavp_dst (str)
+              3.12. xavp_dst_mode (int)
+              3.13. xavp_ctx (str)
+              3.14. xavp_ctx_mode (int)
+              3.15. hash_pvar (str)
+              3.16. setid_pvname (str)
+              3.17. attrs_pvname (str)
+              3.18. ds_ping_method (string)
+              3.19. ds_ping_from (string)
+              3.20. ds_ping_interval (int)
+              3.21. ds_probing_threshold (int)
+              3.22. ds_inactive_threshold (int)
+              3.23. ds_ping_reply_codes (string)
+              3.24. ds_probing_mode (int)
+              3.25. ds_ping_latency_stats (int)
+              3.26. ds_latency_estimator_alpha (int)
+              3.27. ds_hash_size (int)
+              3.28. ds_hash_expire (int)
+              3.29. ds_hash_initexpire (int)
+              3.30. ds_hash_check_interval (int)
+              3.31. outbound_proxy (str)
+              3.32. ds_default_socket (str)
+              3.33. ds_timer_mode (int)
+              3.34. event_callback (str)
+              3.35. ds_attrs_none (int)
+              3.36. ds_db_extra_attrs (str)
+
+        4. Functions
+
+              4.1. ds_select_dst(set, alg[, limit])
+              4.2. ds_select_domain(set, alg[, limit])
+              4.3. ds_select(set, alg [, limit])
+              4.4. ds_select_routes(rules, mode [, limit])
+              4.5. ds_next_dst()
+              4.6. ds_next_domain()
+              4.7. ds_set_dst()
+              4.8. ds_set_domain()
+              4.9. ds_mark_dst([state])
+              4.10. ds_list_exists(groupid)
+              4.11. ds_is_from_list([groupid [, mode [, uri] ] ])
+              4.12. ds_load_update()
+              4.13. ds_load_unset()
+              4.14. ds_reload()
+
+        5. RPC Commands
+
+              5.1. dispatcher.set_state
+              5.2. dispatcher.list
+              5.3. dispatcher.reload
+              5.4. dispatcher.ping_active
+
+        6. Installation and Running
+
+              6.1. Destination List File
+
+                    6.1.1. Special Attributes
+                    6.1.2. File Format
+
+              6.2. Kamailio config file
+
+        7. Event routes
+
+              7.1. dispatcher:dst-down
+              7.2. dispatcher:dst-up
+
+   2. Frequently Asked Questions
+
+   List of Examples
+
+   1.1. Set the “list_file” parameter
+   1.2. Set “db_url” parameter
+   1.3. Set “table_name” parameter
+   1.4. Set “setid_col” parameter
+   1.5. Set “destination_col” parameter
+   1.6. Set “flags_col” parameter
+   1.7. Set “priority_col” parameter
+   1.8. Set the “force_dst” parameter
+   1.9. Set the “flags” parameter
+   1.10. Set the “use_default” parameter
+   1.11. Set the “xavp_dst” parameter
+   1.12. Set the “xavp_dst_mode” parameter
+   1.13. Set the “xavp_ctx” parameter
+   1.14. Set the “xavp_ctx_mode” parameter
+   1.15. Use $avp(hash) for hashing:
+   1.16. Use combination of PVs for hashing:
+   1.17. Set the “setid_pvname” parameter
+   1.18. Set the “attrs_pvname” parameter
+   1.19. Set the “ds_ping_method” parameter
+   1.20. Set the “ds_ping_from” parameter
+   1.21. Set the “ds_ping_interval” parameter
+   1.22. Set the “ds_probing_threshold” parameter
+   1.23. Set the “ds_inactive_threshold” parameter
+   1.24. Set the “ds_ping_reply_codes” parameter
+   1.25. Set the “ds_probing_mode” parameter
+   1.26. accessing the metrics
+   1.27. Set the “ds_ping_latency_stats” parameter
+   1.28. Set the “ds_hash_size” parameter
+   1.29. Set the “ds_hash_size” parameter
+   1.30. Set the “ds_hash_expire” parameter
+   1.31. Set the “ds_hash_initexpire” parameter
+   1.32. Set the “ds_hash_check_interval” parameter
+   1.33. Set the “outbound_proxy” parameter
+   1.34. Set the “ds_default_socket” parameter
+   1.35. Set the “ds_timer_mode” parameter
+   1.36. Set event_callback parameter
+   1.37. Set the “ds_attrs_none” parameter
+   1.38. Set the “ds_db_extra_attrs” parameter
+   1.39. ds_select_dst usage
+   1.40. configuring load balancing with congestion detection
+   1.41. ds_select_domain usage
+   1.42. ds_select usage
+   1.43. ds_select_routes usage
+   1.44. ds_mark_dst usage
+   1.45. ds_list_exists usage
+   1.46. ds_is_from_list usage
+   1.47. ds_load_unset usage
+   1.48. dispatcher list file
+   1.49. Kamailio config script - sample dispatcher usage
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio modules
+        2.2. External libraries or applications
+
+   3. Parameters
+
+        3.1. list_file (string)
+        3.2. db_url (string)
+        3.3. table_name (string)
+        3.4. setid_col (string)
+        3.5. destination_col (string)
+        3.6. flags_col (string)
+        3.7. priority_col (string)
+        3.8. force_dst (int)
+        3.9. flags (int)
+        3.10. use_default (int)
+        3.11. xavp_dst (str)
+        3.12. xavp_dst_mode (int)
+        3.13. xavp_ctx (str)
+        3.14. xavp_ctx_mode (int)
+        3.15. hash_pvar (str)
+        3.16. setid_pvname (str)
+        3.17. attrs_pvname (str)
+        3.18. ds_ping_method (string)
+        3.19. ds_ping_from (string)
+        3.20. ds_ping_interval (int)
+        3.21. ds_probing_threshold (int)
+        3.22. ds_inactive_threshold (int)
+        3.23. ds_ping_reply_codes (string)
+        3.24. ds_probing_mode (int)
+        3.25. ds_ping_latency_stats (int)
+        3.26. ds_latency_estimator_alpha (int)
+        3.27. ds_hash_size (int)
+        3.28. ds_hash_expire (int)
+        3.29. ds_hash_initexpire (int)
+        3.30. ds_hash_check_interval (int)
+        3.31. outbound_proxy (str)
+        3.32. ds_default_socket (str)
+        3.33. ds_timer_mode (int)
+        3.34. event_callback (str)
+        3.35. ds_attrs_none (int)
+        3.36. ds_db_extra_attrs (str)
+
+   4. Functions
+
+        4.1. ds_select_dst(set, alg[, limit])
+        4.2. ds_select_domain(set, alg[, limit])
+        4.3. ds_select(set, alg [, limit])
+        4.4. ds_select_routes(rules, mode [, limit])
+        4.5. ds_next_dst()
+        4.6. ds_next_domain()
+        4.7. ds_set_dst()
+        4.8. ds_set_domain()
+        4.9. ds_mark_dst([state])
+        4.10. ds_list_exists(groupid)
+        4.11. ds_is_from_list([groupid [, mode [, uri] ] ])
+        4.12. ds_load_update()
+        4.13. ds_load_unset()
+        4.14. ds_reload()
+
+   5. RPC Commands
+
+        5.1. dispatcher.set_state
+        5.2. dispatcher.list
+        5.3. dispatcher.reload
+        5.4. dispatcher.ping_active
+
+   6. Installation and Running
+
+        6.1. Destination List File
+
+              6.1.1. Special Attributes
+              6.1.2. File Format
+
+        6.2. Kamailio config file
+
+   7. Event routes
+
+        7.1. dispatcher:dst-down
+        7.2. dispatcher:dst-up
+
+1. Overview
+
+   This module offers SIP load balancer functionality and it can be used
+   as SIP traffic dispatcher. There are many load balancing and traffic
+   dispatching algorithms that you can choose from, for example:
+   round-robin, weight based load balancing, call load distribution, and
+   hashing over SIP message attributes.
+
+   The module can be used as a stateless load balancer; it does not depend
+   on any call state tracking module. It requires the TM module if you
+   enable auto-discovery of active/inactive gateways.
+
+   It is very lightweight, therefore suitable for handling heavy SIP
+   traffic. As the module has a small footprint and the ability to load
+   balancing rules from a plain text file, it is suitable for embedded
+   systems.
+
+2. Dependencies
+
+   2.1. Kamailio modules
+   2.2. External libraries or applications
+
+2.1. Kamailio modules
+
+   The following modules must be loaded before this module:
+     * TM - only if active recovery of failed hosts is required.
+     * database engine - only if you want to load balancing routes from
+       database instead of plain text file. .
+
+2.2. External libraries or applications
+
+   The following libraries or applications must be installed before
+   running Kamailio with this module:
+     * none.
+
+3. Parameters
+
+   3.1. list_file (string)
+   3.2. db_url (string)
+   3.3. table_name (string)
+   3.4. setid_col (string)
+   3.5. destination_col (string)
+   3.6. flags_col (string)
+   3.7. priority_col (string)
+   3.8. force_dst (int)
+   3.9. flags (int)
+   3.10. use_default (int)
+   3.11. xavp_dst (str)
+   3.12. xavp_dst_mode (int)
+   3.13. xavp_ctx (str)
+   3.14. xavp_ctx_mode (int)
+   3.15. hash_pvar (str)
+   3.16. setid_pvname (str)
+   3.17. attrs_pvname (str)
+   3.18. ds_ping_method (string)
+   3.19. ds_ping_from (string)
+   3.20. ds_ping_interval (int)
+   3.21. ds_probing_threshold (int)
+   3.22. ds_inactive_threshold (int)
+   3.23. ds_ping_reply_codes (string)
+   3.24. ds_probing_mode (int)
+   3.25. ds_ping_latency_stats (int)
+   3.26. ds_latency_estimator_alpha (int)
+   3.27. ds_hash_size (int)
+   3.28. ds_hash_expire (int)
+   3.29. ds_hash_initexpire (int)
+   3.30. ds_hash_check_interval (int)
+   3.31. outbound_proxy (str)
+   3.32. ds_default_socket (str)
+   3.33. ds_timer_mode (int)
+   3.34. event_callback (str)
+   3.35. ds_attrs_none (int)
+   3.36. ds_db_extra_attrs (str)
+
+3.1. list_file (string)
+
+   Path to the file with destination sets (destination groups).
+
+   Default value is “/etc/kamailio/dispatcher.list” or
+   “/usr/local/etc/kamailio/dispatcher.list”.
+
+   Example 1.1. Set the “list_file” parameter
+...
+modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
+...
+
+3.2. db_url (string)
+
+   If you want to load the list of gateways from the database you must set
+   this parameter.
+
+   Default value is “NULL” (disable DB support).
+
+   Example 1.2. Set “db_url” parameter
+...
+modparam("dispatcher", "db_url", "mysql://user:passwd@localhost/database")
+...
+
+3.3. table_name (string)
+
+   If you want to load the list of gateways from the database you must set
+   this parameter as the database name.
+
+   Default value is “dispatcher”.
+
+   Example 1.3. Set “table_name” parameter
+...
+modparam("dispatcher", "table_name", "my_dispatcher")
+...
+
+3.4. setid_col (string)
+
+   The column's name in the database storing the gateway's set (group) id.
+
+   Default value is “setid”.
+
+   Example 1.4. Set “setid_col” parameter
+...
+modparam("dispatcher", "setid_col", "groupid")
+...
+
+3.5. destination_col (string)
+
+   The column's name in the database storing the destination sip URI.
+
+   Default value is “destination”.
+
+   Example 1.5. Set “destination_col” parameter
+...
+modparam("dispatcher", "destination_col", "uri")
+...
+
+3.6. flags_col (string)
+
+   The column's name in the database storing the flags for the destination
+   URI.
+
+   Default value is “flags”.
+
+   Example 1.6. Set “flags_col” parameter
+...
+modparam("dispatcher", "flags_col", "dstflags")
+...
+
+3.7. priority_col (string)
+
+   The column's name in the database storing the priority for destination
+   URI.
+
+   Default value is “priority”.
+
+   Example 1.7. Set “priority_col” parameter
+...
+modparam("dispatcher", "priority_col", "dstpriority")
+...
+
+3.8. force_dst (int)
+
+   If set to 1, force overwriting of destination address (outbound proxy)
+   when that is already set. If set to 0, will return error when the
+   destination address is already set.
+
+   Default value is “1”.
+
+   Example 1.8. Set the “force_dst” parameter
+...
+modparam("dispatcher", "force_dst", 1)
+...
+
+3.9. flags (int)
+
+   Various flags that affect dispatcher's behaviour. The flags are defined
+   as a bitmask on an integer value. If flag 1 is set only the username
+   part of the URI will be used when computing an URI based hash. If no
+   flags are set the username, hostname and port will be used. The port is
+   used only if different from 5060 (normal sip URI) or 5061 (in the sips:
+   case).
+
+   If flag 2 is set, then failover support is enabled. The functions
+   exported by the module will store the rest of addresses from the
+   destination set in XAPVs, and use these XAVPs to try next address if
+   the current-tried destination fails.
+
+   Default value is “0”.
+
+   Example 1.9. Set the “flags” parameter
+ ...
+ modparam("dispatcher", "flags", 3)
+ ...
+
+3.10. use_default (int)
+
+   If the parameter is set to 1, the last address in destination set is
+   used as a final option to send the request to. For example, it is
+   useful when wanting to send the call to an announcement server saying:
+   "the gateways are full, try later".
+
+   Default value is “0”.
+
+   Example 1.10. Set the “use_default” parameter
+ ...
+ modparam("dispatcher", "use_default", 1)
+ ...
+
+3.11. xavp_dst (str)
+
+   The name of the XAVP which will hold the list with addresses and
+   associated properties, in the order they have been selected by the
+   chosen algorithm. If use_default is 1, the values of last XAVP
+   correspond to the last address in destination set. The first XAVP is
+   the current selected destination. All the other addresses from the
+   destination set will be added in the XAVP list to be able to implement
+   serial forking.
+
+Note
+
+   You must set this parameter if you want to do load balancing fail over.
+
+   Default value is “_dsdst_”.
+
+   Example 1.11. Set the “xavp_dst” parameter
+ ...
+ modparam("dispatcher", "xavp_dst", "_dsdst_")
+ ...
+
+3.12. xavp_dst_mode (int)
+
+   Control what fields are added to the XAVP specified by xavp_dst
+   parameter.
+
+   The addeded fields are:
+     * grp - the set id (group id).
+     * uri - the URI address.
+     * sock - the socket pointer.
+     * dstid - the destination unique id (in case of call load
+       distribution algorithm).
+     * attrs - the attributes - they are added if xavp_dst_mode does not
+       have the bit 1 set.
+
+   Default value is “0” (add all fields).
+
+   Example 1.12. Set the “xavp_dst_mode” parameter
+ ...
+ modparam("dispatcher", "xavp_dst_mode", 1)
+ ...
+
+3.13. xavp_ctx (str)
+
+   The name of the XAVP which will hold some attributes specific to
+   dispatcher routing context. The XAVP can hold the next fields: cnt -
+   the number of addresses selected for routing.
+
+   Default value is “_dsctx_”.
+
+   Example 1.13. Set the “xavp_ctx” parameter
+ ...
+ modparam("dispatcher", "xavp_ctx", "_dsctx_")
+ ...
+
+3.14. xavp_ctx_mode (int)
+
+   Control what fields are added to the XAVP specified by xavp_ctx
+   parameter. The cnt field is added if xavp_cnt_mode does not have the
+   bit 1 set.
+
+   Default value is “0” (add all fields).
+
+   Example 1.14. Set the “xavp_ctx_mode” parameter
+ ...
+ modparam("dispatcher", "xavp_ctx_mode", 1)
+ ...
+
+3.15. hash_pvar (str)
+
+   String with PVs used for the hashing algorithm 7.
+
+Note
+
+   You must set this parameter if you want do hashing over custom message
+   parts.
+
+   Default value is “null” - disabled.
+
+   Example 1.15. Use $avp(hash) for hashing:
+ ...
+ modparam("dispatcher", "hash_pvar", "$avp(hash)")
+ ...
+
+   Example 1.16. Use combination of PVs for hashing:
+ ...
+ modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
+ ...
+
+3.16. setid_pvname (str)
+
+   The name of the PV where to store the set ID (group ID) when calling
+   ds_is_from_list() with no parameter.
+
+   Default value is “null” - don't set PV.
+
+   Example 1.17. Set the “setid_pvname” parameter
+ ...
+ modparam("dispatcher", "setid_pvname", "$var(setid)")
+ ...
+
+3.17. attrs_pvname (str)
+
+   The name of the PV where to store the attributes of matching address
+   when calling ds_is_from_list().
+
+   Default value is “null” - don't set PV.
+
+   Example 1.18. Set the “attrs_pvname” parameter
+ ...
+ modparam("dispatcher", "attrs_pvname", "$var(attrs)")
+ ...
+
+3.18. ds_ping_method (string)
+
+   With this method you can define, with which method you want to probe
+   the gateways. Pinging gateways feature depends on ds_ping_interval
+   parameter.
+
+   Default value is “OPTIONS”.
+
+   Example 1.19. Set the “ds_ping_method” parameter
+ ...
+ modparam("dispatcher", "ds_ping_method", "INFO")
+ ...
+
+3.19. ds_ping_from (string)
+
+   With this Method you can define the "From:"-Line for the request, sent
+   to the failed gateways. This method is only available, if compiled with
+   the probing of failed gateways enabled.
+
+   Default value is “sip:dispatcher@localhost”.
+
+   Example 1.20. Set the “ds_ping_from” parameter
+ ...
+ modparam("dispatcher", "ds_ping_from", "sip:[email protected]")
+ ...
+
+3.20. ds_ping_interval (int)
+
+   With this parameter you can define the interval for sending a request
+   to a gateway marked as inactive upon a failed request routing to it.
+   This parameter is only used, when the TM-Module is loaded. If set to
+   “0”, the pinging of inactive gateway is disabled.
+
+   Default value is “0”.
+
+   Example 1.21. Set the “ds_ping_interval” parameter
+ ...
+ modparam("dispatcher", "ds_ping_interval", 30)
+ ...
+
+3.21. ds_probing_threshold (int)
+
+   If you want to set a gateway into inactive mode, there can be a
+   specific number of failed requests until it will change from "active"
+   to "inactive". It is using the state "trying", that allows selection of
+   gateway but indicates there was a failure previously with the gateway.
+   The number of attempts can be set with this parameter. This parameter
+   can be modified via ser config framework.
+
+   Default value is “1” (set inactive with first failure).
+
+   Example 1.22. Set the “ds_probing_threshold” parameter
+ ...
+ modparam("dispatcher", "ds_probing_threshold", 10)
+ ...
+
+3.22. ds_inactive_threshold (int)
+
+   If you want to set a gateway into active mode (after being inactive),
+   there can be a specific number of successful requests until it will
+   change from "inactive" to "active". The number of attempts can be set
+   with this parameter. This parameter can be modified via ser config
+   framework.
+
+   Default value is “1” (set active with first success).
+
+   Example 1.23. Set the “ds_inactive_threshold” parameter
+ ...
+ modparam("dispatcher", "ds_inactive_threshold", 10)
+ ...
+
+3.23. ds_ping_reply_codes (string)
+
+   This parameter defines the valid response codes, which are accepted as
+   a valid reply to the PING-Method. It is a list separated by colons,
+   where you may define either a single code (e.g. "code=202" would accept
+   202 as an additional, valid response) or a class of responses, you want
+   to accept (e.g. "class=2" would accept everything from 200 to 299 as
+   valid response). This parameter can be modified via config framework.
+
+   Please note that the response codes the module accepts as valid reply
+   to the PING-Method are not only the ones generated from the remote
+   servers, but also those that are generated locally. E.g.: setting
+   code=408 or class=400 will never set a backend down even if it is,
+   because internally the Kamailio transaction layer generates a 408 in
+   the case of no response from the remote server, and this internal code
+   408 is accepted as valid value.
+
+   Default value is “” (only 200 OK is accepted).
+
+   Example 1.24. Set the “ds_ping_reply_codes” parameter
+ ...
+ modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=
+3")
+ ...
+
+3.24. ds_probing_mode (int)
+
+   Controls what gateways are tested to see if they are reachable.
+     * Value 0: If set to 0, only the gateways with state PROBING are
+       tested. After a gateway is probed, the PROBING state is cleared in
+       this mode.
+     * Value 1: If set to 1, all gateways are tested. If set to 1 and
+       there is a failure of keepalive to an active gateway, then it is
+       set to TRYING state.
+     * Value 2: if set to 2, only gateways in inactive state with probing
+       mode set are tested.
+     * Value 3: If set to 3, any gateway with state PROBING is continually
+       probed without modifying/removing the PROBING state. This allows
+       selected gateways to be probed continually, regardless of state
+       changes.
+
+   Default value is “0”.
+
+   Example 1.25. Set the “ds_probing_mode” parameter
+ ...
+ modparam("dispatcher", "ds_probing_mode", 1)
+ ...
+
+3.25. ds_ping_latency_stats (int)
+
+   Enable latency measurement when pinging nodes
+     * If set to 0, disable latency measurement.
+     * If set to 1, enable latency measurement.
+
+   Default value is “0”.
+
+   Example 1.26. accessing the metrics
+# using the command :
+kamcmd dispatcher.list
+ ...
+DEST: {
+        URI: sip:1.2.3.4
+        FLAGS: AX
+        PRIORITY: 9
+        LATENCY: {
+                AVG: 24.250000 # weighted moving average for the last few weeks
+                STD: 1.035000  # standard deviation of AVG
+                EST: 25.000000 # short term estimate, see parameter: ds_latency_
+estimator_alpha
+                MAX: 26        # maximum value seen
+                TIMEOUT: 0     # count of ping timeouts
+        }
+}
+ ...
+
+   Example 1.27. Set the “ds_ping_latency_stats” parameter
+ ...
+ modparam("dispatcher", "ds_ping_latency_stats", 1)
+ ...
+
+3.26. ds_latency_estimator_alpha (int)
+
+   The value to be used to control the memory of the estimator EWMA
+   "exponential weighted moving average" or "the speed at which the older
+   samples are dampened" a good explanation can be found here :
+   http://www.itl.nist.gov/div898/handbook/pmc/section3/pmc324.htm Because
+   Kamailio doesn't support float parameter types, the value in the
+   parameter is divided by 1000 and stored as float. For example, if you
+   want to set the alpha to be 0.75, use value 750 here.
+
+   Default value is “900 => 0.9”.
+
+   Example 1.28. Set the “ds_hash_size” parameter
+ ...
+ modparam("dispatcher", "ds_latency_estimator_alpha", 900)
+ ...
+
+3.27. ds_hash_size (int)
+
+   The value to be used as power of two to set the number of slots to hash
+   table storing data for call load dispatching (e.g., value 8 will create
+   a hash table with 256 slots). It must be greater than 0 to enable call
+   load dispatching feature (alg 10).
+
+   Default value is “0”.
+
+   Example 1.29. Set the “ds_hash_size” parameter
+ ...
+ modparam("dispatcher", "ds_hash_size", 9)
+ ...
+
+3.28. ds_hash_expire (int)
+
+   Expiration time in seconds to remove the load on a destination if no
+   BYE was received meanwhile.
+
+   Default value is “7200”.
+
+   Example 1.30. Set the “ds_hash_expire” parameter
+ ...
+ modparam("dispatcher", "ds_hash_expire", 3600)
+ ...
+
+3.29. ds_hash_initexpire (int)
+
+   Expiration time in seconds to remove the load on a destination if no
+   200 for INVITE was received meanwhile and state updated with
+   ds_load_update().
+
+   Default value is “7200”.
+
+   Example 1.31. Set the “ds_hash_initexpire” parameter
+ ...
+ modparam("dispatcher", "ds_hash_initexpire", 60)
+ ...
+
+3.30. ds_hash_check_interval (int)
+
+   Time interval in seconds to scan internal hash table with call load
+   dispatching data for expired items.
+
+   Default value is “30”.
+
+   Example 1.32. Set the “ds_hash_check_interval” parameter
+ ...
+ modparam("dispatcher", "ds_hash_check_interval", 60)
+ ...
+
+3.31. outbound_proxy (str)
+
+   SIP URI of outbound proxy to be used when sending pings.
+
+   By default no outbound proxy is defined.
+
+   Example 1.33. Set the “outbound_proxy” parameter
+ ...
+ modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
+ ...
+
+3.32. ds_default_socket (str)
+
+   Default socket to be used for sending pings and dispatching requests
+   when a gateway has no send socket configured.
+
+   By default no default socket is defined, the first configuration script
+   listen directive is used.
+
+   Example 1.34. Set the “ds_default_socket” parameter
+ ...
+ modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
+ ...
+
+3.33. ds_timer_mode (int)
+
+   Specify the timer process to be used by the module for keepalives and
+   active dialogs tracking.
+
+   It can be set to:
+     * 0 - use main timer process.
+     * 1 - use secondary timer process.
+
+   On a server with a lot of traffic, using secondary timer can help with
+   performances, because the main timer can be overloaded by taking care
+   of transactions retransmissions and expirations of items in memory.
+
+   Default value is “0”.
+
+   Example 1.35. Set the “ds_timer_mode” parameter
+ ...
+ modparam("dispatcher", "ds_timer_mode", 1)
+ ...
+
+3.34. event_callback (str)
+
+   The name of the function in the kemi configuration file (embedded
+   scripting language such as Lua, Python, ...) to be executed instead of
+   event_route[...] blocks.
+
+   The function receives a string parameter with the name of the event,
+   the values are: 'dispatcher:dst-down', 'dispatcher:dst-up'.
+
+   Default value is 'empty' (no function is executed for events).
+
+   Example 1.36. Set event_callback parameter
+...
+modparam("dispatcher", "event_callback", "ksr_dispatcher_event")
+...
+-- event callback function implemented in Lua
+function ksr_dispatcher_event(evname)
+        KSR.info("===== dispatcher module triggered event: " .. evname .. "\n");
+        return 1;
+end
+...
+
+3.35. ds_attrs_none (int)
+
+   If set to 1, "none=yes" is set in the attrs for those records that have
+   no attrs value, to ensure that corresponding XAVP fields for records do
+   not get mixed up.
+
+   Default value is “0”.
+
+   Example 1.37. Set the “ds_attrs_none” parameter
+ ...
+ modparam("dispatcher", "ds_attrs_none", 1)
+ ...
+
+3.36. ds_db_extra_attrs (str)
+
+   Set a list of column names to be loaded from database dispatcher table
+   and be concatenated to 'attrs' field. The format is:
+   'aname1=cname1;aname2=cname2;...;anameN=cnameN'.
+
+   The 'anameX' is the attribute name and 'cnameX' is column name. The
+   additional columns must be added to database dispatcher table and their
+   type must be VARCHAR (string).
+
+   Default value is “empty”.
+
+   Example 1.38. Set the “ds_db_extra_attrs” parameter
+...
+modparam("dispatcher", "ds_db_extra_attrs", "socket=socket;pref=prefix")
+...
+
+4. Functions
+
+   4.1. ds_select_dst(set, alg[, limit])
+   4.2. ds_select_domain(set, alg[, limit])
+   4.3. ds_select(set, alg [, limit])
+   4.4. ds_select_routes(rules, mode [, limit])
+   4.5. ds_next_dst()
+   4.6. ds_next_domain()
+   4.7. ds_set_dst()
+   4.8. ds_set_domain()
+   4.9. ds_mark_dst([state])
+   4.10. ds_list_exists(groupid)
+   4.11. ds_is_from_list([groupid [, mode [, uri] ] ])
+   4.12. ds_load_update()
+   4.13. ds_load_unset()
+   4.14. ds_reload()
+
+4.1.  ds_select_dst(set, alg[, limit])
+
+   The method selects a destination from addresses set. It returns true if
+   a new destination is set. The selected address is set to dst_uri field
+   (aka the outbound proxy address or the $du variable), not being visible
+   in the SIP request.
+
+   If the bit 2 in 'flags' parameter is set, the rest of the addresses
+   from the destination set are stored in XAVP list (limited with an
+   optional 'limit' parameter). You can use 'ds_next_dst()' to use next
+   address in order to achieve serial forking to all possible
+   destinations.
+
+   Meaning of the parameters is as follows:
+     * set - the id of the set from where to pick up destination address.
+       It is the first column in destination list file. The parameter can
+       be an integer or a variable holding an integer.
+     * alg - the algorithm used to select the destination address. The
+       parameter can be an integer or a variable holding an integer.
+          + “0” - hash over callid
+          + “1” - hash over from URI.
+          + “2” - hash over to URI.
+          + “3” - hash over request-URI.
+          + “4” - round-robin (next destination).
+          + “5” - hash over authorization-username (Proxy-Authorization or
+            "normal" authorization). If no username is found, round robin
+            is used.
+          + “6” - random destination (using rand()).
+          + “7” - hash over the content of PVs string. Note: This works
+            only when the parameter hash_pvar is set.
+          + “8” - select destination sorted by priority attribute value
+            (serial forking ordered by priority).
+          + “9” - use weight based load distribution. You have to set the
+            attribute 'weight' per each address in destination set.
+          + “10” - use call load distribution. You have to set the
+            attribute 'duid' (as an unique string id) per each address in
+            destination set. Also, you must set the parameter
+            'ds_hash_size'.
+            The algorithm can be used even with stateless proxy mode,
+            there is no SIP dialog tracking depending on other modules,
+            just an internal lightweight call tracking by Call-Id, thus is
+            fast and suitable even for embedded systems.
+            The first destination selected by this algorithm is the one
+            that has the least number of calls associated. The rest of the
+            destination list is taken in order of the entries in set -
+            anyhow, until a re-route to next destination happens, the load
+            on each address can change.
+            This algorithm can be used only for dispatching INVITE
+            requests as it is the only SIP method creating a SIP call.
+          + “11” - use relative weight based load distribution. You have
+            to set the attribute 'rweight' per each address in destination
+            set. Active host usage probability is rweight/(SUM of all
+            active host rweights in destination group).
+            The major difference from the weight distribution is the
+            probability recalculation according to rweight value in case
+            of host enabling/disabling
+            For example, 100 calls in 3-hosts group with rweight params
+            1/2/1 will be distributed as 25/50/25. After third host
+            failing distribution will be changed to 33/67/0.
+            Using this algorithm, you can also enable congestion control
+            by setting the attibute 'cc=1', when 'cc' is enabled the
+            'rweight' attribute will also be used to control congestion
+            tolerance. When facing congestion the weight of a gateway is
+            lowered by 1 for every ms of estimated congestion, a 'rweight'
+            value of 50 is recommended. See the example "configuring load
+            balancing with congestion detection" bellow.
+            The congestion estimation is done using an EWMA (see
+            ds_latency_estimator_alpha). If all the gateways in a set are
+            above their congestion threshold(weight), the load
+            distribution is instead done using the ratio of estimated
+            congestion ms.
+          + “12” - dispatch to all destination in setid at once (parallel
+            forking). Note that the XAVPs are no longer set with the
+            values of the destination records, no re-routing making sense
+            in this case.
+          + “X” - if the algorithm is not implemented, the first entry in
+            set is chosen.
+     * limit - the maximum number of items to be stored in XAVP list for
+       further fail-overs (the first selected destination and default
+       destination are the first to be put in the list)
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
+
+   Example 1.39. ds_select_dst usage
+...
+ds_select_dst("1", "0");
+...
+$var(a) = 4;
+ds_select_dst("1", "$var(a)");
+...
+ds_select_dst("1", "4", "3");
+...
+
+   Example 1.40. configuring load balancing with congestion detection
+...
+# sample of SQL provisionning statements
+INSERT INTO "dispatcher"
+VALUES(1,1,'sip:192.168.0.1:5060',0,12,'rweight=50;weight=50;cc=1;','');
+INSERT INTO "dispatcher"
+VALUES(2,1,'sip:192.168.0.2:5060',0,12,'rweight=50;weight=50;cc=1;','');
+...
+modparam("dispatcher", "ds_ping_interval", 1) # ping gateways once/second
+modparam("dispatcher", "ds_ping_latency_stats", 1) # update congestion metrics
+# configure the latency estimator
+modparam("dispatcher", "ds_latency_estimator_alpha", 900)
+...
+if (!ds_select_dst("1", "11")) { # use relative weight based load distribution
+...
+# sample of output from 'kamcmd dispatcher.list'
+DEST: {
+        URI: sip:192.168.0.1:5060
+        FLAGS: AP
+        PRIORITY: 12
+        ATTRS: {
+                BODY: rweight=50;weight=50;cc=1 # configuration values
+                DUID:
+                MAXLOAD: 0
+                WEIGHT: 50
+                RWEIGHT: 50
+                SOCKET:
+        }
+        LATENCY: {
+                AVG: 20.104000
+                STD: 1.273000
+                # estimated congestion is currently 25ms = 45ms(EST) -20ms(AVG)
+                EST: 45.005000
+                MAX: 132
+                TIMEOUT: 3
+        }
+}
+...
+
+4.2.  ds_select_domain(set, alg[, limit])
+
+   The method selects a destination from addresses set and rewrites the
+   host and port from R-URI. The parameters have same meaning as for
+   ds_select_dst().
+
+   If the bit 2 in 'flags' is set, the rest of the addresses from the
+   destination set are stored in XAVP list (limited with an optional
+   'limit' parameter). You can use 'ds_next_domain()' to use next address
+   to achieve serial forking to all possible destinations.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
+
+   Example 1.41. ds_select_domain usage
+...
+$var(a) = 4;
+if(ds_select_domain("1", "$var(a)")) {
+    t_relay();
+    exit;
+}
+...
+
+4.3.  ds_select(set, alg [, limit])
+
+   The method selects a destination from addresses set and adds it in the
+   XAVP specified for this module. It is not updating R-URI nor the
+   destination URI. The parameters have same meaning as for
+   ds_select_dst().
+
+   If the bit 2 in 'flags' is set, the rest of the addresses from the
+   destination set are stored in XAVP list (limited with an optional
+   'limit' parameter). You can execute 'ds_next_domain()' or
+   'ds_next_dst()' to use next address to achieve serial forking to all
+   possible destinations.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.42. ds_select usage
+...
+$var(a) = 4;
+if(ds_select("1", "$var(a)")) {
+    ds_next_domain();
+    t_relay();
+    exit;
+}
+...
+
+4.4.  ds_select_routes(rules, mode [, limit])
+
+   The method selects destinations following the rules combining groups
+   add algorithms, controlling where the first destination address is
+   pushed, and optionally setting a limit of selected addresses.
+
+   Parameters:
+     * rules - a string in the format "grp1=alg1;grp2=alg2;...grpN=algN",
+       where grpX is an integer number identifying a dispatcher set id and
+       algN is a dispatcher algorithm identifier. No white spaces should
+       be given in the parameter value. The parameter can contain
+       pseudo-variables.
+     * mode - control where to push the first selected target address.
+       Valid values are: '0', 'd' or 'D' to push the address in
+       destination URI; '1', 'r' or 'R' to push the address in R-URI; '2',
+       'x' or 'X' to push the address only in the XAVP when failure
+       rerouting is enabled. Note that only first character of the
+       parameter matters, therefore once case use a more meaningful value
+       such as 'ruri' instead of 'r'. The parameter can contain pseudo
+       variables.
+     * limit - a positive integer value to restrict the number of selected
+       target addresses. If it is 0, then no limit is considered. The
+       parameter can be a static integer or a variable holding an integer
+       value.
+
+   If the bit 2 in 'flags' is set, the rest of the addresses from the
+   destination groups are stored in XAVP list (limited with an optional
+   'limit' parameter). You can execute 'ds_next_domain()' or
+   'ds_next_dst()' to use next address to achieve serial forking to all
+   possible destinations.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.43. ds_select_routes usage
+...
+$var(alg) = 4;
+$var(limit) = 8;
+if(ds_select_routes("1=4;2=$var(alg)", "ruri", "$var(limit)")) {
+    t_on_failure("REROUTE");
+    t_relay();
+    exit;
+}
+failure_route[REROUTE] {
+    if(t_check_status("408|5[0-9][0-9]")) {
+        if(ds_next_domain()) {
+            t_on_failure("REROUTE");
+            t_relay();
+            exit;
+        }
+    }
+}
+...
+
+4.5.  ds_next_dst()
+
+   Takes the next destination address from the corresponding XAVPs and
+   sets the dst_uri (outbound proxy address).
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
+
+4.6.  ds_next_domain()
+
+   Takes the next destination address from the corresponding XAVPs and
+   sets the domain part of the request URI.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
+
+4.7.  ds_set_dst()
+
+   Takes the current destination address from the corresponding XAVPs and
+   sets the dst_uri (outbound proxy address).
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
+
+4.8.  ds_set_domain()
+
+   Takes the current destination address from the corresponding XAVPs and
+   sets the domain part of the request URI.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
+
+4.9.  ds_mark_dst([state])
+
+   Mark the last used address from destination set as inactive ("i"/"I"),
+   active ("a"/"A"), disabled ("d"/"D") or trying ("t"/"T"). Apart of
+   disabled state, a destination can be set in probing mode by adding
+   ("p"/"P") flag. With this function, an automatic detection of failed
+   gateways can be implemented. When an address is marked as inactive or
+   disabled, it will be ignored by 'ds_select_dst' and 'ds_select_domain'.
+
+   The parameter state is optional, when it is missing, then the
+   destination will be marked inactive (i.e., same as 'i').
+
+   Possible values for state parameter:
+     * "a" or "A" - the last destination should be set to active and the
+       error-counter should set to "0".
+     * "i" or "I" - the last destination should be set to inactive and
+       will be ignored in future requests.
+     * "t" or "T" - the last destination should be set to temporary trying
+       state and failure counter is incremented. When the failure counter
+       reaches the threshold, the destination will be set inactive.
+     * "p" and "P" - this has to be used in addition to one of the
+       previous flags - the last destination will be set to probing. This
+       mean the destination will be pinged with SIP OPTIONS requests from
+       time to time to detect if it is up or down.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
+
+   Example 1.44. ds_mark_dst usage
+...
+failure_route[tryagain] {
+...
+   if(t_check_status("500"))
+      ds_mark_dst("ip"); # set to inactive and probing
+...
+}
+...
+
+4.10.  ds_list_exists(groupid)
+
+   Function alias: ds_list_exist(groupid)
+
+   Check if a specific group is defined in dispatcher list or database.
+     * groupid - A group ID to check.
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.45. ds_list_exists usage
+...
+if(ds_list_exists("10")) {
+    ...
+}
+...
+
+4.11.  ds_is_from_list([groupid [, mode [, uri] ] ])
+
+   This function returns true, if there is a match of source address or
+   uri with an address in the given group of the dispatcher-list;
+   otherwise false.
+
+   Description of parameters:
+     * groupid (optional) - if not given or its value is -1, the matching
+       will be done over all addresses in all dispacher groups. Otherwise
+       the matching will be done only against the addresses in the
+       specific group id. The parameter can be an integer or a variable
+       holding an integer value.
+     * mode - (optional) - a bitmask to specify how the matching should be
+       done. If is 0, all ip, port and proto are matched. If bit one is
+       set, then port is ignored. If bit two is set, then protocol is
+       ignored. The parameter can be an integer or a variable holding an
+       integer value. It must be provided if the uri parameter is
+       provided.
+     * uri (optional) - if is empty or missing, the matching is done
+       against source IP, port and protocol. Otherwise the value has to be
+       a valid SIP URI, used to match against addresses in the dispatcher
+       list. Only IP, port and protocol are matches, any additional
+       parameters are ignored. The parameter can be a static or dynamic
+       (with variables) string. The domain part of the URI can be an IP
+       address or a hostname.
+
+   Upon a match, the variable specified by 'setid_pvname' parameter will
+   be set to groupid of matching address and the attributes will be set in
+   variable specified by 'attrs_pvname'.
+
+   Note that for backward compatibility mode, when no parameter is given
+   or only groupid is given, the matching is done only for IP address and
+   port (protocol is ignored).
+
+   This function can be used from ANY_ROUTE.
+
+   Example 1.46. ds_is_from_list usage
+...
+if(ds_is_from_list()) {
+    ...
+}
+if(ds_is_from_list("10")) {
+    ...
+}
+if(ds_is_from_list("10", "3")) {
+    ...
+}
+if(ds_is_from_list("10", "3", "sip:127.0.0.1:5080")) {
+    ...
+}
+...
+
+4.12.  ds_load_update()
+
+   Updates the load state:
+     * if it is a BYE or CANCEL - remove the load from destination address
+       used to forward the INVITE
+     * if it is a reply to INVITE - set internal state to confirmed for
+       call load structure when reply code is 2xx.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
+   BRANCH_ROUTE and ONREPLY_ROUTE.
+
+4.13.  ds_load_unset()
+
+   Remove the call load for the destination that routed the call.
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
+   BRANCH_ROUTE and ONREPLY_ROUTE.
+
+   Example 1.47. ds_load_unset usage
+...
+route {
+    ...
+        if(is_method("BYE|CANCEL"))
+        ds_load_update();
+    ...
+        ds_select_dst("1", "10");
+    ...
+}
+
+onreply_route {
+    ...
+    if(is_method("INVITE")
+        {
+        if(status=~"2[0-9][0-9]")
+            ds_load_update();
+        else if(status=~"[3-7][0-9][0-9]")
+            ds_load_unset();
+    }
+    ...
+}
+...
+
+4.14.  ds_reload()
+
+   Reloads the groups and included destinations.
+
+   Name: ds_reload
+
+   Parameters: none
+
+   This function can be used from ANY_ROUTE.
+
+5. RPC Commands
+
+   5.1. dispatcher.set_state
+   5.2. dispatcher.list
+   5.3. dispatcher.reload
+   5.4. dispatcher.ping_active
+
+5.1.  dispatcher.set_state
+
+   Sets the state for a destination address (can be use to mark the
+   destination as active or inactive).
+
+   Name: dispatcher.set_state
+
+   Parameters:
+     * _state_ : state of the destination address
+          + “a”: active
+          + “i”: inactive
+          + “t”: trying
+          + “d”: disabled
+       The states “a”, “i” or “t” can be followed by “p” to set probing
+       mode (e.g. 'ap', 'ip' or 'tp').
+     * _group_: destination group id
+     * _address_: address of the destination in the _group_ or 'all' to
+       update all destinations in the group
+
+   Example:
+...
+# prototype: kamcmd dispatcher.set_state _state_ _group_ _address_
+kamcmd dispatcher.set_state ip 2 sip:127.0.0.1:5080
+kamcmd dispatcher.set_state ip 3 all
+...
+
+5.2.  dispatcher.list
+
+   Lists the groups and included destinations.
+
+   Name: dispatcher.list
+
+   Parameters: none
+
+   Example:
+                kamcmd dispatcher.list
+
+5.3.  dispatcher.reload
+
+   Reloads the groups and included destinations. The command is disabled
+   for call load based dispatching (algorithm 10) since removal of
+   destinations may leave the list of active calls with broken references.
+
+   Name: dispatcher.reload
+
+   Parameters: none
+
+   Example
+                kamcmd dispatcher.reload
+
+5.4.  dispatcher.ping_active
+
+   Sets the global state for sending keepalive requests to destinations.
+
+   Name: dispatcher.ping_active
+
+   Parameters:
+     * _state_ : state of sending keepalives
+          + “0”: inactive (don't send)
+          + “1”: active (send)
+
+   If the state parameter is missing, the current state is returned. When
+   state is changed, new and old values of the state are returned. Default
+   value for state is 1.
+
+   Example:
+...
+# prototype: kamcmd dispatcher.ping_active _state_
+kamcmd dispatcher.ping_active 0
+...
+
+6. Installation and Running
+
+   6.1. Destination List File
+
+        6.1.1. Special Attributes
+        6.1.2. File Format
+
+   6.2. Kamailio config file
+
+6.1. Destination List File
+
+   Each destination point must be on one line. First token is the set id
+   (an integer value, also referenced by group id), followed by
+   destination address (string value in full SIP URI format).
+
+   Optionally, these fields can be followed by:
+     * flags (listed by index - can be bitwise mask of values): 0 (value
+       1) - inactive destination; 1 (value 2) - temporary trying
+       destination (in the way to become inactive if it does not reply to
+       keepalives - there is a module parameter to set the threshold of
+       failures); 2 (value 4) - admin disabled destination; 3 (value 8) -
+       probing destination (sending keep alives);
+     * priority: sets the priority in destination list (based on it is
+       done the initial ordering inside the set)
+     * attributes: extra fields in form of name1=value1;...;nameN=valueN.
+
+6.1.1. Special Attributes
+
+   There are some predefined names:
+     * 'duid' - used for call load dispatching. It must be an unique value
+       to identify a destination (gateway address). Practically the load
+       within the group is associated with this value.
+     * 'maxload' - used for call load dispatching. It must be a positive
+       integer, defining the upper limit of active calls per destination.
+       When the limit is reached, then the gateway is no longer selected
+       for new calls until an exiting call via that gateway is terminated.
+       If set to 0, then no active call limit is used.
+     * 'weight' - used for weight based load distribution. It must be set
+       to a positive integer value beteen 0 and 100. The value represents
+       the percent of calls to be sent to that gateways.
+     * 'rweight' - used for relative weight based load distribution. It
+       must be set to a positive integer value between 1 and 100
+       (otherwise host will be excluded from relative weight distribution
+       type).
+     * 'socket' - used to set the sending socket for the gateway. It is
+       used for sending the SIP traffic as well as OPTIONS keepalives.
+
+6.1.2. File Format
+
+   Line format is:
+...
+setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
+...
+
+   Full line example:
+...
+1 sip:127.0.0.1:5080 0 0 duid=abc;socket=udp:192.168.0.125:5060;my=xyz
+...
+
+   For database, each element of a line resides in a different column.
+   Next is a dispatcher.list file example:
+
+   Example 1.48. dispatcher list file
+...
+#
+# dispatcher destination sets (groups)
+#
+
+# line format
+# setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attributes(st
+r,opt)
+
+# proxies
+2 sip:127.0.0.1:5080;transport=tcp 0 10 class=4;prefix=448;strip=2
+2 sip:127.0.0.1:5082;px=vx 0 5 duid=abc;socket=udp:192.168.0.125:5060;pipe=p10
+
+# gateways
+1 sip:127.0.0.1:7070 0 0 duid=xyz;maxload=20
+1 sip:127.0.0.1:7072 0 5
+1 sip:127.0.0.1:7074
+
+...
+
+6.2. Kamailio config file
+
+   Next listing shows a sample config for using the dispatcher module.
+
+   Example 1.49. Kamailio config script - sample dispatcher usage
+...
+#!KAMAILIO
+#
+# sample config file for dispatcher module
+# - load balancing of VoIP calls with round robin
+# - no TPC listening
+# - don't dispatch REGISTER and presence requests
+#
+# Kamailio SIP Server
+#     - web: http://www.kamailio.org
+#     - git: http://github.com/kamailio/
+#
+# Direct your questions about this file to: [email protected]
+#
+# Refer to the Core CookBook at http://www.kamailio.org/dokuwiki/doku.php
+# for an explanation of possible statements, functions and parameters.
+#
+# Several features can be enabled using '#!define WITH_FEATURE' directives:
+#
+# *** To run in debug mode:
+#     - define WITH_DEBUG
+#
+
+#!ifndef DBURL
+#!define DBURL "mysql://kamailio:kamailiorw@localhost/kamailio"
+#!endif
+
+# - flags
+#   FLT_ - per transaction (message) flags
+#       FLB_ - per branch flags
+#!define FLT_ACC 1
+#!define FLT_ACCMISSED 2
+#!define FLT_ACCFAILED 3
+
+####### Global Parameters #########
+
+#!ifdef WITH_DEBUG
+debug=4
+log_stderror=yes
+#!else
+debug=2
+log_stderror=no
+#!endif
+
+memdbg=5
+memlog=5
+
+log_facility=LOG_LOCAL0
+
+fork=yes
+children=4
+
+/* comment the next line to enable TCP */
+disable_tcp=yes
+
+/* uncomment the next line to disable the auto discovery of local aliases
+   based on revers DNS on IPs (default on) */
+auto_aliases=no
+
+/* add local domain aliases */
+# alias="mysipserver.com"
+
+port=5060
+
+/* uncomment and configure the following line if you want Kamailio to
+   bind on a specific interface/port/proto (default bind on all available) */
+# listen=udp:127.0.0.1:5060
+
+sip_warning=no
+
+####### Modules Section ########
+
+# set module path
+mpath="/usr/local/lib/kamailio/modules/"
+
+loadmodule "db_mysql.so"
+loadmodule "jsonrpcs.so"
+loadmodule "kex.so"
+loadmodule "tm.so"
+loadmodule "tmx.so"
+loadmodule "sl.so"
+loadmodule "rr.so"
+loadmodule "pv.so"
+loadmodule "maxfwd.so"
+loadmodule "textops.so"
+loadmodule "siputils.so"
+loadmodule "xlog.so"
+loadmodule "sanity.so"
+loadmodule "ctl.so"
+loadmodule "acc.so"
+loadmodule "dispatcher.so"
+
+
+# ----------------- setting module-specific parameters ---------------
+
+
+# ----- jsonrpcs params -----
+modparam("jsonrpcs", "pretty_format", 1)
+
+
+# ----- rr params -----
+# add value to ;lr param to cope with most of the UAs
+modparam("rr", "enable_full_lr", 1)
+# do not append from tag to the RR (no need for this script)
+modparam("rr", "append_fromtag", 0)
+
+
+# ----- acc params -----
+modparam("acc", "log_flag", FLT_ACC)
+modparam("acc", "failed_transaction_flag", FLT_ACCFAILED)
+modparam("acc", "log_extra",
+        "src_user=$fU;src_domain=$fd;dst_ouser=$tU;dst_user=$rU;dst_domain=$rd;s
+rc_ip=$si")
+
+# ----- tm params -----
+modparam("tm", "fr_timer", 2000)
+modparam("tm", "fr_inv_timer", 40000)
+
+# ----- dispatcher params -----
+modparam("dispatcher", "db_url", DBURL)
+modparam("dispatcher", "table_name", "dispatcher")
+modparam("dispatcher", "flags", 2)
+modparam("dispatcher", "xavp_dst", "_dsdst_")
+modparam("dispatcher", "xavp_ctx", "_dsctx_")
+
+####### Routing Logic ########
+
+
+# main request routing logic
+
+request_route {
+
+        # per request initial checks
+        route(REQINIT);
+
+        # CANCEL processing
+        if (is_method("CANCEL")) {
+                if (t_check_trans()) {
+                        route(RELAY);
+                }
+                exit;
+        }
+
+        # handle retransmissions
+        if (!is_method("ACK")) {
+                if(t_precheck_trans()) {
+                        t_check_trans();
+                        exit;
+                }
+                t_check_trans();
+        }
+
+        # handle requests within SIP dialogs
+        route(WITHINDLG);
+
+        ### only initial requests (no To tag)
+
+        # record routing for dialog forming requests (in case they are routed)
+        # - remove preloaded route headers
+        remove_hf("Route");
+        if (is_method("INVITE|SUBSCRIBE"))
+                record_route();
+
+        # account only INVITEs
+        if (is_method("INVITE")) {
+                setflag(FLT_ACC); # do accounting
+        }
+
+        # handle presence related requests
+        route(PRESENCE);
+
+        # handle registrations
+        route(REGISTRAR);
+
+        if ($rU==$null) {
+                # request with no Username in RURI
+                sl_send_reply("484","Address Incomplete");
+                exit;
+        }
+
+        # dispatch destinations
+        route(DISPATCH);
+}
+
+
+route[RELAY] {
+        if (!t_relay()) {
+                sl_reply_error();
+        }
+        exit;
+}
+
+# Per SIP request initial checks
+route[REQINIT] {
+        if (!mf_process_maxfwd_header("10")) {
+                sl_send_reply("483","Too Many Hops");
+                exit;
+        }
+
+        if(!sanity_check("1511", "7")) {
+                xlog("Malformed SIP message from $si:$sp\n");
+                exit;
+        }
+}
+
+# Handle requests within SIP dialogs
+route[WITHINDLG] {
+        if (has_totag()) {
+                # sequential request withing a dialog should
+                # take the path determined by record-routing
+                if (loose_route()) {
+                        if (is_method("BYE")) {
+                                setflag(FLT_ACC); # do accounting ...
+                                setflag(FLT_ACCFAILED); # ... even if the transa
+ction fails
+                        }
+                        route(RELAY);
+                } else {
+                        if (is_method("SUBSCRIBE") && uri == myself) {
+                                # in-dialog subscribe requests
+                                route(PRESENCE);
+                                exit;
+                        }
+                        if ( is_method("ACK") ) {
+                                if ( t_check_trans() ) {
+                                        # non loose-route, but stateful ACK;
+                                        # must be ACK after a 487 or e.g. 404 fr
+om upstream server
+                                        t_relay();
+                                        exit;
+                                } else {
+                                        # ACK without matching transaction ... i
+gnore and discard.
+                                        exit;
+                                }
+                        }
+                        sl_send_reply("404","Not here");
+                }
+                exit;
+        }
+}
+
+# Handle SIP registrations
+route[REGISTRAR] {
+        if(!is_method("REGISTER"))
+                return;
+        sl_send_reply("404", "No registrar");
+        exit;
+}
+
+# Presence server route
+route[PRESENCE] {
+        if(!is_method("PUBLISH|SUBSCRIBE"))
+                return;
+
+        sl_send_reply("404", "Not here");
+        exit;
+}
+
+# Dispatch requests
+route[DISPATCH] {
+        # round robin dispatching on gateways group '1'
+        if(!ds_select_dst("1", "4")) {
+                send_reply("404", "No destination");
+                exit;
+        }
+        xdbg("--- SCRIPT: going to <$ru> via <$du> (attrs: $xavp(_dsdst_=>attrs)
+)\n");
+        t_on_failure("RTF_DISPATCH");
+        route(RELAY);
+        exit;
+}
+
+# Try next destionations in failure route
+failure_route[RTF_DISPATCH] {
+        if (t_is_canceled()) {
+                exit;
+        }
+        # next DST - only for 500 or local timeout
+        if (t_check_status("500")
+                        or (t_branch_timeout() and !t_branch_replied())) {
+                if(ds_next_dst()) {
+                        xdbg("--- SCRIPT: retrying to <$ru> via <$du> (attrs: $x
+avp(_dsdst_=>attrs))\n");
+                        t_on_failure("RTF_DISPATCH");
+                        route(RELAY);
+                        exit;
+                }
+        }
+}
+
+...
+
+7. Event routes
+
+   7.1. dispatcher:dst-down
+   7.2. dispatcher:dst-up
+
+7.1.  dispatcher:dst-down
+
+   When defined, the module calls event_route[dispatcher:ds-down] when a
+   destination goes down (becomes probing). A typical use case is to
+   update NMC equipment as to the status of a destination.
+...
+event_route[dispatcher:dst-down] {
+    xlog("L_ERR", "Destination down: $rm $ru ($du)\n");
+}
+...
+
+7.2.  dispatcher:dst-up
+
+   When defined, the module calls event_route[dispatcher:ds-up] when a
+   destination that was previously down (probing) comes up. A typical use
+   case is to update NMC equipment as to the status of a destination.
+...
+event_route[dispatcher:dst-up] {
+    xlog("L_ERR", "Destination up: $rm $ru\n");
+}
+...
+
+Chapter 2. Frequently Asked Questions
+
+   2.1. Does dispatcher provide a fair distribution?
+   2.2. Is dispatcher dialog stateful?
+   2.3. Where can I find more about Kamailio?
+   2.4. Where can I post a question about this module?
+   2.5. How can I report a bug?
+
+   2.1.
+
+       Does dispatcher provide a fair distribution?
+
+       The algorithms doing hashing over parts of SIP message don't guarantee
+       a fair distribution. You should do some measurements to decide what
+       hashing algorithm fits better in your environment.
+
+       Other distribution algorithms such as round robin or call load
+       dispatching do a fair distribution in terms of delivered calls to
+       gateways.
+
+   2.2.
+
+       Is dispatcher dialog stateful?
+
+       No. Dispatcher is stateless, although some distribution algorithms are
+       designed to select same destination for subsequent requests of the same
+       dialog (e.g., hashing the call-id).
+
+   2.3.
+
+       Where can I find more about Kamailio?
+
+       Take a look at https://www.kamailio.org/.
+
+   2.4.
+
+       Where can I post a question about this module?
+
+       First at all check if your question was already answered on one of our
+       mailing lists:
+         * User Mailing List -
+           https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-users
+         * Developer Mailing List -
+           https://lists.kamailio.org/cgi-bin/mailman/listinfo/sr-dev
+
+       E-mails regarding any stable version should be sent to
+       <[email protected]> and e-mail regarding development versions
+       or GIT snapshots should be send to <[email protected]>.
+
+   2.5.
+
+       How can I report a bug?
+
+       Please follow the guidelines provided at:
+       https://github.com/kamailio/kamailio/issues