src/modules/dispatcher/README
e6aefebf
 DISPATCHER Module
31ccf6a2
 
e6aefebf
 Daniel-Constantin Mierla
31ccf6a2
 
e6aefebf
    <miconda@gmail.com>
 
 Edited by
 
 Daniel-Constantin Mierla
 
    <miconda@gmail.com>
 
 Carsten Bock
 
    ng-voice GmbH
 
 Olle E. Johansson
 
    Edvina AB
 
 Alessandro Arrichiello
 
    Hewlett Packard
 
 Luis Martin
 
 Julien Chavanton
 
    <jchavanton@gmail.com>
 
 Federico Cabiddu
 
    <federico.cabiddu@gmail.com>
 
    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.set_duid_state
               5.3. dispatcher.list
               5.4. dispatcher.reload
               5.5. dispatcher.ping_active
               5.6. dispatcher.add
               5.7. dispatcher.remove
               5.8. 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.set_duid_state
         5.3. dispatcher.list
         5.4. dispatcher.reload
         5.5. dispatcher.ping_active
         5.6. dispatcher.add
         5.7. dispatcher.remove
         5.8. 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
bcae4ab3
 ...
 modparam("dispatcher", "flags", 3)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "use_default", 1)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "xavp_dst", "_dsdst_")
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "xavp_ctx", "_dsctx_")
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "xavp_ctx_mode", 1)
 ...
e6aefebf
 
 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:
bcae4ab3
 ...
 modparam("dispatcher", "hash_pvar", "$avp(hash)")
 ...
e6aefebf
 
    Example 1.17. Use combination of PVs for hashing:
bcae4ab3
 ...
 modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "setid_pvname", "$var(setid)")
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "attrs_pvname", "$var(attrs)")
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_ping_method", "INFO")
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_ping_interval", 30)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_probing_threshold", 10)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_inactive_threshold", 10)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=3
 ")
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_probing_mode", 1)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
e6aefebf
 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
         }
 }
bcae4ab3
 ...
e6aefebf
 
    Example 1.28. Set the “ds_ping_latency_stats” parameter
bcae4ab3
 ...
 modparam("dispatcher", "ds_ping_latency_stats", 1)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_latency_estimator_alpha", 900)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_hash_size", 9)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_hash_expire", 3600)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_hash_initexpire", 60)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_hash_check_interval", 60)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
 ...
e6aefebf
 
 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
bcae4ab3
 ...
e6aefebf
  listen=udp:1.2.3.4:5060 name "sock1"
bcae4ab3
 ...
 modparam("dispatcher", "ds_default_sockname", "sock1")
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_timer_mode", 1)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_attrs_none", 1)
 ...
e6aefebf
 
 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
bcae4ab3
 ...
 modparam("dispatcher", "ds_load_mode", 1)
 ...
e6aefebf
 
 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.set_duid_state
    5.3. dispatcher.list
    5.4. dispatcher.reload
    5.5. dispatcher.ping_active
    5.6. dispatcher.add
    5.7. dispatcher.remove
    5.8. 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.set_duid_state
 
    Sets the state for a destination by matching on 'duid' attribute. The
    parameters first two parameter 'state' and 'group' are the same like
    for RPC command 'dispatcher.set_state'. The third parameter 'duid' is
    the value to be matched against the 'duid' attribute of dispatcher
    destinations.
 
    Example:
 ...
 # prototype: kamcmd dispatcher.set_duid_state _state_ _group_ _duid_
 kamcmd dispatcher.set_duid_state ip 2 xyz
 ...
 
 5.3.  dispatcher.list
 
    Lists the groups and included destinations.
 
    Name: dispatcher.list
 
    Parameters: none
 
    Example:
                 kamcmd dispatcher.list
bcae4ab3
 ...
e6aefebf
 DEST: {
         URI: sip:192.168.0.1:5060
         FLAGS: AP
         PRIORITY: 12
 }
bcae4ab3
 ...
e6aefebf
 
    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.4.  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.5.  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.6.  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
0feab05b
      * _attrs_ (optional): as described in the list file format, default
        ""
e6aefebf
 
    Example:
 ...
0feab05b
 # prototype: kamcmd dispatcher.add _group_ _address_ _flags_ _attrs_
e6aefebf
 kamcmd dispatcher.add 2 sip:127.0.0.1:5080
 kamcmd dispatcher.add 3 sip:127.0.0.1:5075 8
0feab05b
 kamcmd dispatcher.add 3 sip:127.0.0.1:5075 0 duid=abc;socket=udp:127.0.0.1:5060
e6aefebf
 ...
 
 5.7.  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.8.  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
bcae4ab3
        within the group is associated with this value.>
e6aefebf
      * '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.
bcae4ab3
        If set to 0, then no active call limit is used.>
e6aefebf
      * 'weight' - used for weight based load distribution. It must be set
        to a positive integer value beteen 0 and 100. The value represents
bcae4ab3
        the percent of calls to be sent to that gateways.>
e6aefebf
      * '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: sr-users@lists.kamailio.org
 #
 # 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:proxy@kamailio.org")
 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] {
bcae4ab3
         if (!has_totag()) {
                 return;
         }
 
         # 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 transaction fa
 ils
                 }
                 route(RELAY);
         }
 
         if (is_method("SUBSCRIBE") && uri == myself) {
                 # in-dialog subscribe requests
                 route(PRESENCE);
         }
 
         if ( is_method("ACK") ) {
                 if ( t_check_trans() ) {
                         # non loose-route, but stateful ACK;
                         # must be ACK after a 487 or e.g. 404 from upstream serv
 er
                         t_relay();
                         exit;
e6aefebf
                 } else {
bcae4ab3
                         # ACK without matching transaction ... ignore and discar
 d.
                         exit;
e6aefebf
                 }
         }
bcae4ab3
 
         sl_send_reply("404","Not here");
         exit;
e6aefebf
 }
 
 # 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
    <sr-users@lists.kamailio.org> and e-mail regarding development versions
    or GIT snapshots should be send to <sr-dev@lists.kamailio.org>.
 
    2.5.
 
    How can I report a bug?
 
    Please follow the guidelines provided at:
    https://github.com/kamailio/kamailio/issues