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

src/modules/dispatcher/README

@@ -1,2102 +1,2 @@
-DISPATCHER Module
 
-Daniel-Constantin Mierla
 
-   <[email protected]>
-
-Edited by
-
-Daniel-Constantin Mierla
-
-   <[email protected]>
-
-Carsten Bock
-
-   ng-voice GmbH
-
-Olle E. Johansson
-
-   Edvina AB
-
-Alessandro Arrichiello
-
-   Hewlett Packard
-
-Luis Martin
-
-Julien Chavanton
-
-   <[email protected]>
-
-Federico Cabiddu
-
-   <[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
-
-   Copyright © 2020 Federico Cabiddu, Libon
-     __________________________________________________________________
-
-   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. attrs_col (string)
-              3.9. force_dst (int)
-              3.10. flags (int)
-              3.11. use_default (int)
-              3.12. xavp_dst (str)
-              3.13. xavp_dst_mode (int)
-              3.14. xavp_ctx (str)
-              3.15. xavp_ctx_mode (int)
-              3.16. hash_pvar (str)
-              3.17. setid_pvname (str)
-              3.18. attrs_pvname (str)
-              3.19. ds_ping_method (string)
-              3.20. ds_ping_from (string)
-              3.21. ds_ping_interval (int)
-              3.22. ds_probing_threshold (int)
-              3.23. ds_inactive_threshold (int)
-              3.24. ds_ping_reply_codes (string)
-              3.25. ds_probing_mode (int)
-              3.26. ds_ping_latency_stats (int)
-              3.27. ds_latency_estimator_alpha (int)
-              3.28. ds_hash_size (int)
-              3.29. ds_hash_expire (int)
-              3.30. ds_hash_initexpire (int)
-              3.31. ds_hash_check_interval (int)
-              3.32. outbound_proxy (str)
-              3.33. ds_default_socket (str)
-              3.34. ds_default_sockname (str)
-              3.35. ds_timer_mode (int)
-              3.36. event_callback (str)
-              3.37. ds_attrs_none (int)
-              3.38. ds_db_extra_attrs (str)
-              3.39. ds_load_mode (int)
-              3.40. reload_delta (int)
-
-        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
-              5.5. dispatcher.add
-              5.6. dispatcher.remove
-              5.7. dispatcher.hash
-
-        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 “attrs_col” parameter
-   1.9. Set the “force_dst” parameter
-   1.10. Set the “flags” parameter
-   1.11. Set the “use_default” parameter
-   1.12. Set the “xavp_dst” parameter
-   1.13. Set the “xavp_dst_mode” parameter
-   1.14. Set the “xavp_ctx” parameter
-   1.15. Set the “xavp_ctx_mode” parameter
-   1.16. Use $avp(hash) for hashing:
-   1.17. Use combination of PVs for hashing:
-   1.18. Set the “setid_pvname” parameter
-   1.19. Set the “attrs_pvname” parameter
-   1.20. Set the “ds_ping_method” parameter
-   1.21. Set the “ds_ping_from” parameter
-   1.22. Set the “ds_ping_interval” parameter
-   1.23. Set the “ds_probing_threshold” parameter
-   1.24. Set the “ds_inactive_threshold” parameter
-   1.25. Set the “ds_ping_reply_codes” parameter
-   1.26. Set the “ds_probing_mode” parameter
-   1.27. accessing the metrics
-   1.28. Set the “ds_ping_latency_stats” parameter
-   1.29. Set the “ds_hash_size” parameter
-   1.30. Set the “ds_hash_size” parameter
-   1.31. Set the “ds_hash_expire” parameter
-   1.32. Set the “ds_hash_initexpire” parameter
-   1.33. Set the “ds_hash_check_interval” parameter
-   1.34. Set the “outbound_proxy” parameter
-   1.35. Set the “ds_default_socket” parameter
-   1.36. Set the “ds_default_sockname” parameter
-   1.37. Set the “ds_timer_mode” parameter
-   1.38. Set event_callback parameter
-   1.39. Set the “ds_attrs_none” parameter
-   1.40. Set the “ds_db_extra_attrs” parameter
-   1.41. Set the “ds_load_mode” parameter
-   1.42. Set reload_delta parameter
-   1.43. ds_select_dst usage
-   1.44. configuring load balancing with congestion detection
-   1.45. ds_select_domain usage
-   1.46. ds_select usage
-   1.47. ds_select_routes usage
-   1.48. ds_mark_dst usage
-   1.49. ds_list_exists usage
-   1.50. ds_is_from_list usage
-   1.51. ds_load_unset usage
-   1.52. dispatcher list file
-   1.53. 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. attrs_col (string)
-        3.9. force_dst (int)
-        3.10. flags (int)
-        3.11. use_default (int)
-        3.12. xavp_dst (str)
-        3.13. xavp_dst_mode (int)
-        3.14. xavp_ctx (str)
-        3.15. xavp_ctx_mode (int)
-        3.16. hash_pvar (str)
-        3.17. setid_pvname (str)
-        3.18. attrs_pvname (str)
-        3.19. ds_ping_method (string)
-        3.20. ds_ping_from (string)
-        3.21. ds_ping_interval (int)
-        3.22. ds_probing_threshold (int)
-        3.23. ds_inactive_threshold (int)
-        3.24. ds_ping_reply_codes (string)
-        3.25. ds_probing_mode (int)
-        3.26. ds_ping_latency_stats (int)
-        3.27. ds_latency_estimator_alpha (int)
-        3.28. ds_hash_size (int)
-        3.29. ds_hash_expire (int)
-        3.30. ds_hash_initexpire (int)
-        3.31. ds_hash_check_interval (int)
-        3.32. outbound_proxy (str)
-        3.33. ds_default_socket (str)
-        3.34. ds_default_sockname (str)
-        3.35. ds_timer_mode (int)
-        3.36. event_callback (str)
-        3.37. ds_attrs_none (int)
-        3.38. ds_db_extra_attrs (str)
-        3.39. ds_load_mode (int)
-        3.40. reload_delta (int)
-
-   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
-        5.5. dispatcher.add
-        5.6. dispatcher.remove
-        5.7. dispatcher.hash
-
-   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. attrs_col (string)
-   3.9. force_dst (int)
-   3.10. flags (int)
-   3.11. use_default (int)
-   3.12. xavp_dst (str)
-   3.13. xavp_dst_mode (int)
-   3.14. xavp_ctx (str)
-   3.15. xavp_ctx_mode (int)
-   3.16. hash_pvar (str)
-   3.17. setid_pvname (str)
-   3.18. attrs_pvname (str)
-   3.19. ds_ping_method (string)
-   3.20. ds_ping_from (string)
-   3.21. ds_ping_interval (int)
-   3.22. ds_probing_threshold (int)
-   3.23. ds_inactive_threshold (int)
-   3.24. ds_ping_reply_codes (string)
-   3.25. ds_probing_mode (int)
-   3.26. ds_ping_latency_stats (int)
-   3.27. ds_latency_estimator_alpha (int)
-   3.28. ds_hash_size (int)
-   3.29. ds_hash_expire (int)
-   3.30. ds_hash_initexpire (int)
-   3.31. ds_hash_check_interval (int)
-   3.32. outbound_proxy (str)
-   3.33. ds_default_socket (str)
-   3.34. ds_default_sockname (str)
-   3.35. ds_timer_mode (int)
-   3.36. event_callback (str)
-   3.37. ds_attrs_none (int)
-   3.38. ds_db_extra_attrs (str)
-   3.39. ds_load_mode (int)
-   3.40. reload_delta (int)
-
-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", "/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. attrs_col (string)
-
-   The column's name in the database storing the attributes for
-   destination URI.
-
-   Default value is “attrs”.
-
-   Example 1.8. Set “attrs_col” parameter
-...
-modparam("dispatcher", "attrs_col", "dstattrs")
-...
-
-3.9. 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.9. Set the “force_dst” parameter
-...
-modparam("dispatcher", "force_dst", 1)
-...
-
-3.10. 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.10. Set the “flags” parameter
- ...
- modparam("dispatcher", "flags", 3)
- ...
-
-3.11. 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.11. Set the “use_default” parameter
- ...
- modparam("dispatcher", "use_default", 1)
- ...
-
-3.12. 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. In case of using
-   dispatcher.list file, you have to set the priority field for each
-   destination to ensure a particular order there. 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.12. Set the “xavp_dst” parameter
- ...
- modparam("dispatcher", "xavp_dst", "_dsdst_")
- ...
-
-3.13. 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.
-     * socket - the socket string - it is added only if xavp_dst_mode has
-       bit 2 set (value 2).
-     * sockname - the sockname string - it is added only if xavp_dst_mode
-       has bit 3 set (value 3).
-     * 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 (value 1).
-
-   Default value is “0” (add all fields).
-
-   Example 1.13. Set the “xavp_dst_mode” parameter
-...
-    modparam("dispatcher", "xavp_dst_mode", 1)
-...
-    modparam("dispatcher", "xavp_dst_mode", 2)
-...
-
-3.14. 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.14. Set the “xavp_ctx” parameter
- ...
- modparam("dispatcher", "xavp_ctx", "_dsctx_")
- ...
-
-3.15. 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.15. Set the “xavp_ctx_mode” parameter
- ...
- modparam("dispatcher", "xavp_ctx_mode", 1)
- ...
-
-3.16. 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.16. Use $avp(hash) for hashing:
- ...
- modparam("dispatcher", "hash_pvar", "$avp(hash)")
- ...
-
-   Example 1.17. Use combination of PVs for hashing:
- ...
- modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
- ...
-
-3.17. 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.18. Set the “setid_pvname” parameter
- ...
- modparam("dispatcher", "setid_pvname", "$var(setid)")
- ...
-
-3.18. 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.19. Set the “attrs_pvname” parameter
- ...
- modparam("dispatcher", "attrs_pvname", "$var(attrs)")
- ...
-
-3.19. 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.20. Set the “ds_ping_method” parameter
- ...
- modparam("dispatcher", "ds_ping_method", "INFO")
- ...
-
-3.20. 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.21. Set the “ds_ping_from” parameter
- ...
- modparam("dispatcher", "ds_ping_from", "sip:[email protected]")
- ...
-
-3.21. 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.22. Set the “ds_ping_interval” parameter
- ...
- modparam("dispatcher", "ds_ping_interval", 30)
- ...
-
-3.22. 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.23. Set the “ds_probing_threshold” parameter
- ...
- modparam("dispatcher", "ds_probing_threshold", 10)
- ...
-
-3.23. 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.24. Set the “ds_inactive_threshold” parameter
- ...
- modparam("dispatcher", "ds_inactive_threshold", 10)
- ...
-
-3.24. 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.25. Set the “ds_ping_reply_codes” parameter
- ...
- modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=
-3")
- ...
-
-3.25. 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. This means that no probing will be executed at all only
-       if flag in config file is set to 8/PROBING (please check
-       destination list file syntaxis for more details), it will probe
-       only one time at startup or after dispatcher reload.
-     * 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. This means that probing will be executed all
-       the time, but you can skip some servers with flag 4 in destination
-       list file, for example.
-     * 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.26. Set the “ds_probing_mode” parameter
- ...
- modparam("dispatcher", "ds_probing_mode", 1)
- ...
-
-3.26. 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.27. 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.28. Set the “ds_ping_latency_stats” parameter
- ...
- modparam("dispatcher", "ds_ping_latency_stats", 1)
- ...
-
-3.27. 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.29. Set the “ds_hash_size” parameter
- ...
- modparam("dispatcher", "ds_latency_estimator_alpha", 900)
- ...
-
-3.28. 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.30. Set the “ds_hash_size” parameter
- ...
- modparam("dispatcher", "ds_hash_size", 9)
- ...
-
-3.29. 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.31. Set the “ds_hash_expire” parameter
- ...
- modparam("dispatcher", "ds_hash_expire", 3600)
- ...
-
-3.30. 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.32. Set the “ds_hash_initexpire” parameter
- ...
- modparam("dispatcher", "ds_hash_initexpire", 60)
- ...
-
-3.31. 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.33. Set the “ds_hash_check_interval” parameter
- ...
- modparam("dispatcher", "ds_hash_check_interval", 60)
- ...
-
-3.32. outbound_proxy (str)
-
-   SIP URI of outbound proxy to be used when sending pings.
-
-   By default no outbound proxy is defined.
-
-   Example 1.34. Set the “outbound_proxy” parameter
- ...
- modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
- ...
-
-3.33. 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.
-
-   If parameter "ds_default_sockname" is set, then this parameter is
-   ignored.
-
-   Example 1.35. Set the “ds_default_socket” parameter
- ...
- modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
- ...
-
-3.34. ds_default_sockname (str)
-
-   Default socket name 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.
-
-   This parameter is used even if "ds_default_socket" parameter is set
-   (this parameter has higher priority).
-
-   Example 1.36. Set the “ds_default_sockname” parameter
- ...
- listen=udp:1.2.3.4:5060 name "sock1"
- ...
- modparam("dispatcher", "ds_default_sockname", "sock1")
- ...
-
-3.35. 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.37. Set the “ds_timer_mode” parameter
- ...
- modparam("dispatcher", "ds_timer_mode", 1)
- ...
-
-3.36. 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.38. 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.37. 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.39. Set the “ds_attrs_none” parameter
- ...
- modparam("dispatcher", "ds_attrs_none", 1)
- ...
-
-3.38. 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.40. Set the “ds_db_extra_attrs” parameter
-...
-modparam("dispatcher", "ds_db_extra_attrs", "socket=socket;pref=prefix")
-...
-
-3.39. ds_load_mode (int)
-
-   If set to 1, the module throws error when failing to add a destination
-   address (e.g., invalid URI). If set to 0, it skips the failing address
-   and continues with the next ones.
-
-   Default value is “0”.
-
-   Example 1.41. Set the “ds_load_mode” parameter
- ...
- modparam("dispatcher", "ds_load_mode", 1)
- ...
-
-3.40. reload_delta (int)
-
-   The number of seconds that have to be waited before executing a new
-   reload of dispatcher records. By default there is a rate limiting of
-   maximum one reload in five seconds.
-
-   If set to 0, no rate limit is configured. Note carefully: use this
-   configuration only in tests environments because executing many RPC
-   reload commands at the same time can cause unexpected behavior.
-
-   Default value is “5”.
-
-   Example 1.42. Set reload_delta parameter
-...
-modparam("dispatcher", "reload_delta", 1)
-...
-
-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' for each address (gateway) in destination
-            set. For more see the description of the 'weight' attribute in
-            the 'Special Attributes' section.
-          + “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" below.
-            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.43. 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.44. 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:
-                SOCKNAME:
-                OBPROXY:
-        }
-        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.45. 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.46. 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 one can 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.47. 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.48. 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.
-
-   It returns true (value 1) if the group exists, or otherwise false (-1
-   when the group is not found; -2 when evaluating the parameter fails).
-
-   This function can be used from ANY_ROUTE.
-
-   Example 1.49. 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 dispatcher 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 parameter is 0, all ip, port and proto are matched and
-       active status is ignored. If bit one is set, then port is ignored.
-       If bit two is set, then protocol is ignored. If bit three is set,
-       then state must be active. 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 parameter 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.50. 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.51. 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.5. dispatcher.add
-   5.6. dispatcher.remove
-   5.7. dispatcher.hash
-
-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
- ...
-DEST: {
-        URI: sip:192.168.0.1:5060
-        FLAGS: AP
-        PRIORITY: 12
-}
- ...
-
-   FLAGS consist out of 2 letters. First letter describe status of
-   destination: A-active, I – inactive, T – trying, D – disabled.
-   Second letter might be P or X. P is for probing, so AP means
-   destination is active and it is tested by SIP options continuously. X
-   means that there are no probing or sip pinging. So AX means that
-   destination is assumed as active and it is not tested by SIP options.
-   DX respectively is disabled destination that is not tested, etc.
-
-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
-...
-
-5.5.  dispatcher.add
-
-   Add a destination address to the in-memory dispatcher list. Reloading
-   the dispatcher will remove any destinations that are only added to the
-   in-memory dispatcher list.
-
-   Name: dispatcher.add
-
-   Parameters:
-     * _group_: destination group id
-     * _address_: address of the destination in the _group_
-     * _flags_ (optional): as described in the list file format, default 0
-
-   Example:
-...
-# prototype: kamcmd dispatcher.add _group_ _address_ _flags_
-kamcmd dispatcher.add 2 sip:127.0.0.1:5080
-kamcmd dispatcher.add 3 sip:127.0.0.1:5075 8
-...
-
-5.6.  dispatcher.remove
-
-   Remove a destination address from the in-memory dispatcher list.
-   Reloading the dispatcher from file or database will re-add destinations
-   that are removed using this command.
-
-   This command will remove all entries that match the group and address.
-
-   Name: dispatcher.remove
-
-   Parameters:
-     * _group_: destination group id
-     * _address_: address of the destination in the _group_
-
-   Example:
-...
-# prototype: kamcmd dispatcher.remove _group_ _address_
-kamcmd dispatcher.remove 2 sip:127.0.0.1:5080
-kamcmd dispatcher.remove 3 sip:127.0.0.1:5075;transport=udp
-...
-
-5.7.  dispatcher.hash
-
-   Compute the hash id corresponding to the string parameter values.
-
-   Return the hash id and the corresponding slot, if 'nslots' parameter is
-   not 0.
-
-   Name: dispatcher.hash
-
-   Parameters:
-     * _nslots_: number of slots
-     * _val1_: string value
-     * _val2_: (optional) string value
-
-   It can be useful to find what address in a destination group (setid) is
-   going to be used when hashing a value or a URI. For a URI, the
-   corresponding username and domain have to be provided as _val1_ and
-   _val2_. If the URI has a port different than 5060 (or 5061 for TLS),
-   then the _val2_ has to be 'domain:port'. The _nslots_ has to be the
-   number of addresses in the group (setid). The returned 'slot' value
-   represents the index of the address to be used for routing.
-
-   Example:
-...
-# prototype: kamctl rpc dispatcher.hash _nslots_ _val1_ [_val2_]
-kamctl rpc dispatcher.hash 0 alice server.com
-kamctl rpc dispatcher.hash 4 bob server.com
-...
-
-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 - control the mode of using the destination address and
-       sending keepalives. It is a bitwise value that can be built using
-       the following flags:
-          + 1 (bit at index 0 - 1 <<0) - inactive destination
-          + 2 (bit at index 1 - 1 <<1) - 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)
-          + 4 (bit at index 2 - 1 <<2) - admin disabled destination
-          + 8 (bit at index 3 - 1 <<3) - probing destination (sending keep
-            alives);
-          + 16 (bit at index 4 - 1 <<4) - skip DNS A/AAAA resolve at
-            startup, useful when the hostname of the destination address
-            is a NAPTR or SRV record only. Such addresses cannot be
-            matched anymore with ds_is_from_list(...).
-     * 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.
-     * 'sockname' - used to set by name the sending socket for the
-       gateway. It is used for sending the SIP traffic as well as OPTIONS
-       keepalives and has priority over 'socket' attribute.
-     * 'ping_from' - used to set the From URI in OPTIONS keepalives. It
-       overwrites the general ds_ping_from parameter.
-     * 'obproxy' - SIP URI of outbound proxy to be used when sending
-       pings. It overwrites the general ds_outbound_proxy parameter.
-
-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;ping_from
-=sip:myproxy.com
-...
-
-   For database, each element of a line resides in a different column.
-   Next is a dispatcher.list file example:
-
-   Example 1.52. 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.53. 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 "corex.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_")
-modparam("dispatcher", "ds_ping_from", "sip:[email protected]")
-modparam("dispatcher", "ds_ping_interval", 60)
-modparam("dispatcher", "ds_probing_mode", 1)
-modparam("dispatcher", "ds_timer_mode", 1)
-
-####### 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