DISPATCHER Module

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Carsten Bock

   ng-voice GmbH

Edited by

Olle E. Johansson

   Edvina AB

Edited by

Alessandro Arrichiello

   Hewlett Packard

Edited by

Luis Martin

   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
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio modules
              2.2. External libraries or applications

        3. Parameters

              3.1. list_file (string)
              3.2. db_url (string)
              3.3. table_name (string)
              3.4. setid_col (string)
              3.5. destination_col (string)
              3.6. flags_col (string)
              3.7. priority_col (string)
              3.8. force_dst (int)
              3.9. flags (int)
              3.10. use_default (int)
              3.11. dst_avp (str)
              3.12. grp_avp (str)
              3.13. cnt_avp (str)
              3.14. dstid_avp (str)
              3.15. attrs_avp (str)
              3.16. sock_avp (str)
              3.17. hash_pvar (str)
              3.18. setid_pvname (str)
              3.19. attrs_pvname (str)
              3.20. ds_ping_method (string)
              3.21. ds_ping_from (string)
              3.22. ds_ping_interval (int)
              3.23. ds_probing_threshold (int)
              3.24. ds_inactive_threshold (int)
              3.25. ds_ping_reply_codes (string)
              3.26. ds_probing_mode (int)
              3.27. ds_hash_size (int)
              3.28. ds_hash_expire (int)
              3.29. ds_hash_initexpire (int)
              3.30. ds_hash_check_interval (int)
              3.31. outbound_proxy (str)
              3.32. ds_default_socket (str)
              3.33. ds_timer_mode (int)

        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_next_dst()
              4.5. ds_next_domain()
              4.6. ds_mark_dst([state])
              4.7. ds_list_exist(groupid)
              4.8. ds_is_from_list([groupid [, mode [, uri] ] ])
              4.9. ds_load_update()
              4.10. ds_load_unset()
              4.11. ds_reload()

        5. RPC Commands

              5.1. dispatcher.set_state
              5.2. dispatcher.list
              5.3. dispatcher.reload
              5.4. dispatcher.ping_active

        6. Installation and Running

              6.1. Destination List File

                    6.1.1. Special Attributes
                    6.1.2. File Format

              6.2. Kamailio config file

        7. Event routes

              7.1. dispatcher:dst-down
              7.2. dispatcher:dst-up

   2. Frequently Asked Questions

   List of Examples

   1.1. Set the “list_file” parameter
   1.2. Set “db_url” parameter
   1.3. Set “table_name” parameter
   1.4. Set “setid_col” parameter
   1.5. Set “destination_col” parameter
   1.6. Set “flags_col” parameter
   1.7. Set “priority_col” parameter
   1.8. Set the “force_dst” parameter
   1.9. Set the “flags” parameter
   1.10. Set the “use_default” parameter
   1.11. Set the “dst_avp” parameter
   1.12. Set the “grp_avp” parameter
   1.13. Set the “cnt_avp” parameter
   1.14. Set the “dstid_avp” parameter
   1.15. Set the “attrs_avp” parameter
   1.16. Set the “sock_avp” parameter
   1.17. Use $avp(hash) for hashing:
   1.18. Use combination of PVs for hashing:
   1.19. Set the “setid_pvname” parameter
   1.20. Set the “attrs_pvname” parameter
   1.21. Set the “ds_ping_method” parameter
   1.22. Set the “ds_ping_from” parameter
   1.23. Set the “ds_ping_interval” parameter
   1.24. Set the “ds_probing_threshold” parameter
   1.25. Set the “ds_inactive_threshold” parameter
   1.26. Set the “ds_ping_reply_codes” parameter
   1.27. Set the “ds_probing_mode” parameter
   1.28. Set the “ds_hash_size” parameter
   1.29. Set the “ds_hash_expire” parameter
   1.30. Set the “ds_hash_initexpire” parameter
   1.31. Set the “ds_hash_check_interval” parameter
   1.32. Set the “outbound_proxy” parameter
   1.33. Set the “ds_default_socket” parameter
   1.34. Set the “ds_timer_mode” parameter
   1.35. ds_select_dst usage
   1.36. ds_select_domain usage
   1.37. ds_select usage
   1.38. ds_mark_dst usage
   1.39. ds_list_exist usage
   1.40. ds_is_from_list usage
   1.41. ds_load_unset usage
   1.42. dispatcher list file
   1.43. Kamailio config script - sample dispatcher usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio modules
        2.2. External libraries or applications

   3. Parameters

        3.1. list_file (string)
        3.2. db_url (string)
        3.3. table_name (string)
        3.4. setid_col (string)
        3.5. destination_col (string)
        3.6. flags_col (string)
        3.7. priority_col (string)
        3.8. force_dst (int)
        3.9. flags (int)
        3.10. use_default (int)
        3.11. dst_avp (str)
        3.12. grp_avp (str)
        3.13. cnt_avp (str)
        3.14. dstid_avp (str)
        3.15. attrs_avp (str)
        3.16. sock_avp (str)
        3.17. hash_pvar (str)
        3.18. setid_pvname (str)
        3.19. attrs_pvname (str)
        3.20. ds_ping_method (string)
        3.21. ds_ping_from (string)
        3.22. ds_ping_interval (int)
        3.23. ds_probing_threshold (int)
        3.24. ds_inactive_threshold (int)
        3.25. ds_ping_reply_codes (string)
        3.26. ds_probing_mode (int)
        3.27. ds_hash_size (int)
        3.28. ds_hash_expire (int)
        3.29. ds_hash_initexpire (int)
        3.30. ds_hash_check_interval (int)
        3.31. outbound_proxy (str)
        3.32. ds_default_socket (str)
        3.33. ds_timer_mode (int)

   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_next_dst()
        4.5. ds_next_domain()
        4.6. ds_mark_dst([state])
        4.7. ds_list_exist(groupid)
        4.8. ds_is_from_list([groupid [, mode [, uri] ] ])
        4.9. ds_load_update()
        4.10. ds_load_unset()
        4.11. ds_reload()

   5. RPC Commands

        5.1. dispatcher.set_state
        5.2. dispatcher.list
        5.3. dispatcher.reload
        5.4. dispatcher.ping_active

   6. Installation and Running

        6.1. Destination List File

              6.1.1. Special Attributes
              6.1.2. File Format

        6.2. Kamailio config file

   7. Event routes

        7.1. dispatcher:dst-down
        7.2. dispatcher:dst-up

1. Overview

   This module offers SIP load balancer functionality and it can be used
   as SIP traffic dispatcher. There are many load balancing and traffic
   dispaching algorithms that you can choose from, for example:
   round-robin, weight based load balancing, call load distribution, and
   hashing over SIP message attributes.

   The module can be used as a stateless load balancer; it does not depend
   on any call state tracking module. It requires the TM module if you
   enable auto-discovery of active/inactive gateways.

   It is very lightweight, therefore suitable for handling heavy SIP
   traffic. As the module has a small footprint and the ability to load
   balancing rules from a plain text file, it is suitable for embedded
   systems.

2. Dependencies

   2.1. Kamailio modules
   2.2. External libraries or applications

2.1. Kamailio modules

   The following modules must be loaded before this module:
     * TM - only if active recovery of failed hosts is required.
     * database engine - only if you want to load balancing routes from
       database instead of plain text file. .

2.2. External libraries or applications

   The following libraries or applications must be installed before
   running Kamailio with this module:
     * none.

3. Parameters

   3.1. list_file (string)
   3.2. db_url (string)
   3.3. table_name (string)
   3.4. setid_col (string)
   3.5. destination_col (string)
   3.6. flags_col (string)
   3.7. priority_col (string)
   3.8. force_dst (int)
   3.9. flags (int)
   3.10. use_default (int)
   3.11. dst_avp (str)
   3.12. grp_avp (str)
   3.13. cnt_avp (str)
   3.14. dstid_avp (str)
   3.15. attrs_avp (str)
   3.16. sock_avp (str)
   3.17. hash_pvar (str)
   3.18. setid_pvname (str)
   3.19. attrs_pvname (str)
   3.20. ds_ping_method (string)
   3.21. ds_ping_from (string)
   3.22. ds_ping_interval (int)
   3.23. ds_probing_threshold (int)
   3.24. ds_inactive_threshold (int)
   3.25. ds_ping_reply_codes (string)
   3.26. ds_probing_mode (int)
   3.27. ds_hash_size (int)
   3.28. ds_hash_expire (int)
   3.29. ds_hash_initexpire (int)
   3.30. ds_hash_check_interval (int)
   3.31. outbound_proxy (str)
   3.32. ds_default_socket (str)
   3.33. ds_timer_mode (int)

3.1. list_file (string)

   Path to the file with destination sets (destination groups).

   Default value is “/etc/kamailio/dispatcher.list” or
   “/usr/local/etc/kamailio/dispatcher.list”.

   Example 1.1. Set the “list_file” parameter
...
modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
...

3.2. db_url (string)

   If you want to load the list of gateways from the database you must set
   this parameter.

   Default value is “NULL” (disable DB support).

   Example 1.2. Set “db_url” parameter
...
modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database")
...

3.3. table_name (string)

   If you want to load the list of gateways from the database you must set
   this parameter as the database name.

   Default value is “dispatcher”.

   Example 1.3. Set “table_name” parameter
...
modparam("dispatcher", "table_name", "my_dispatcher")
...

3.4. setid_col (string)

   The column's name in the database storing the gateway's set (group) id.

   Default value is “setid”.

   Example 1.4. Set “setid_col” parameter
...
modparam("dispatcher", "setid_col", "groupid")
...

3.5. destination_col (string)

   The column's name in the database storing the destination sip URI.

   Default value is “destination”.

   Example 1.5. Set “destination_col” parameter
...
modparam("dispatcher", "destination_col", "uri")
...

3.6. flags_col (string)

   The column's name in the database storing the flags for the destination
   URI.

   Default value is “flags”.

   Example 1.6. Set “flags_col” parameter
...
modparam("dispatcher", "flags_col", "dstflags")
...

3.7. priority_col (string)

   The column's name in the database storing the priority for destination
   URI.

   Default value is “priority”.

   Example 1.7. Set “priority_col” parameter
...
modparam("dispatcher", "priority_col", "dstpriority")
...

3.8. force_dst (int)

   If set to 1, force overwriting of destination address (outbound proxy)
   when that is already set. If set to 0, will return error when the
   destination address is already set.

   Default value is “1”.

   Example 1.8. Set the “force_dst” parameter
...
modparam("dispatcher", "force_dst", 1)
...

3.9. flags (int)

   Various flags that affect dispatcher's behaviour. The flags are defined
   as a bitmask on an integer value. If flag 1 is set only the username
   part of the URI will be used when computing an URI based hash. If no
   flags are set the username, hostname and port will be used. The port is
   used only if different from 5060 (normal sip URI) or 5061 (in the sips:
   case).

   If flag 2 is set, then failover support is enabled. The functions
   exported by the module will store the rest of addresses from the
   destination set in the AVP, and use these AVPs to contact next address
   if the current-tried destination fails.

   Default value is “0”.

   Example 1.9. Set the “flags” parameter
 ...
 modparam("dispatcher", "flags", 3)
 ...

3.10. use_default (int)

   If the parameter is set to 1, the last address in destination set is
   used as a final option to send the request to. For example, it is
   useful when wanting to send the call to an anouncement server saying:
   "the gateways are full, try later".

   Default value is “0”.

   Example 1.10. Set the “use_default” parameter
 ...
 modparam("dispatcher", "use_default", 1)
 ...

3.11. dst_avp (str)

   The name of the avp which will hold the list with addresses, in the
   order they have been selected by the chosen algorithm. If use_default
   is 1, the value of last dst_avp_id is the last address in destination
   set. The first dst_avp_id is the selected destinations. All the other
   addresses from the destination set will be added in the avp 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 “null” - don't add AVPs.

   Example 1.11. Set the “dst_avp” parameter
 ...
 modparam("dispatcher", "dst_avp", "$avp(dsdst)")
 ...

3.12. grp_avp (str)

   The name of the avp storing the group id of the destination set. Good
   to have it for later usage or checks.

Note

   You must set this parameter if you want to do load balancing fail over.

   Default value is “null” - don't add AVP.

   Example 1.12. Set the “grp_avp” parameter
 ...
 modparam("dispatcher", "grp_avp", "$avp(dsgrp)")
 ...

3.13. cnt_avp (str)

   The name of the avp storing the number of destination addresses kept in
   dst_avp AVPs.

Note

   You must set this parameter if you want to do load balancing fail over.

   Default value is “null” - don't add AVP.

   Example 1.13. Set the “cnt_avp” parameter
 ...
 modparam("dispatcher", "cnt_avp", "$avp(dscnt)")
 ...

3.14. dstid_avp (str)

   The name of the avp storing the destination unique ID used for call
   load based dispatching.

Note

   You must set this parameter if you want to do load balancing on call
   load (alg 10).

   Default value is “null” - don't add AVP.

   Example 1.14. Set the “dstid_avp” parameter
 ...
 modparam("dispatcher", "dstid_avp", "$avp(dsdstid)")
 ...

3.15. attrs_avp (str)

   The name of the avp storing destination's attributes value.

Note

   Default value is “null” - don't add AVP.

   Example 1.15. Set the “attrs_avp” parameter
 ...
 modparam("dispatcher", "attrs_avp", "$avp(dsattrs)")
 ...

3.16. sock_avp (str)

   The name of the avp which will hold the list with the sockets
   associated to the addresses stored in dst_avp avp.

Note

   If you want to do load balancing fail over, you have to set this
   parameter to use the correct socket for each gateway.

   Default value is “null” - don't add AVPs.

   Example 1.16. Set the “sock_avp” parameter
 ...
 modparam("dispatcher", "sock_avp", "$avp(dssocket)")
 ...

3.17. 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.17. Use $avp(hash) for hashing:
 ...
 modparam("dispatcher", "hash_pvar", "$avp(hash)")
 ...

   Example 1.18. Use combination of PVs for hashing:
 ...
 modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
 ...

3.18. 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.19. Set the “setid_pvname” parameter
 ...
 modparam("dispatcher", "setid_pvname", "$var(setid)")
 ...

3.19. 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.20. Set the “attrs_pvname” parameter
 ...
 modparam("dispatcher", "attrs_pvname", "$var(attrs)")
 ...

3.20. 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.21. Set the “ds_ping_method” parameter
 ...
 modparam("dispatcher", "ds_ping_method", "INFO")
 ...

3.21. 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.22. Set the “ds_ping_from” parameter
 ...
 modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
 ...

3.22. 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.23. Set the “ds_ping_interval” parameter
 ...
 modparam("dispatcher", "ds_ping_interval", 30)
 ...

3.23. 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.24. Set the “ds_probing_threshold” parameter
 ...
 modparam("dispatcher", "ds_probing_threshold", 10)
 ...

3.24. 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.25. Set the “ds_inactive_threshold” parameter
 ...
 modparam("dispatcher", "ds_inactive_threshold", 10)
 ...

3.25. 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,
   whery 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.26. Set the “ds_ping_reply_codes” parameter
 ...
 modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=
3")
 ...

3.26. ds_probing_mode (int)

   Controls what gateways are tested to see if they are reachable.
     * Value 0: If set to 0, only the gateways with state PROBING are
       tested. After a gateway is probed, the PROBING state is cleared in
       this mode.
     * Value 1: If set to 1, all gateways are tested. If set to 1 and
       there is a failure of keepalive to an active gateway, then it is
       set to TRYING state.
     * Value 2: if set to 2, only gateways in inactive state with probing
       mode set are tested.
     * Value 3: If set to 3, any gateway with state PROBING is continually
       probed without modifying/removing the PROBING state. This allows
       selected gateways to be probed continually, regardless of state
       changes.

   Default value is “0”.

   Example 1.27. Set the “ds_probing_mode” parameter
 ...
 modparam("dispatcher", "ds_probing_mode", 1)
 ...

3.27. ds_hash_size (int)

   The value to be used as power of two to set the number of slots to hash
   table storing data for call load dispatching (e.g., value 8 will create
   a hash table with 256 slots). It must be greater than 0 to enable call
   load dispatching feature (alg 10).

   Default value is “0”.

   Example 1.28. Set the “ds_hash_size” parameter
 ...
 modparam("dispatcher", "ds_hash_size", 9)
 ...

3.28. ds_hash_expire (int)

   Expiration time in seconds to remove the load on a destination if no
   BYE was received meanwhile.

   Default value is “7200”.

   Example 1.29. Set the “ds_hash_expire” parameter
 ...
 modparam("dispatcher", "ds_hash_expire", 3600)
 ...

3.29. ds_hash_initexpire (int)

   Expiration time in seconds to remove the load on a destination if no
   200 for INVITE was received meanwhile and state updated with
   ds_load_update().

   Default value is “7200”.

   Example 1.30. Set the “ds_hash_initexpire” parameter
 ...
 modparam("dispatcher", "ds_hash_initexpire", 60)
 ...

3.30. ds_hash_check_interval (int)

   Time interval in seconds to scan internal hash table with call load
   dispatching data for expired items.

   Default value is “30”.

   Example 1.31. Set the “ds_hash_check_interval” parameter
 ...
 modparam("dispatcher", "ds_hash_check_interval", 60)
 ...

3.31. outbound_proxy (str)

   SIP URI of outbound proxy to be used when sending pings.

   By default no outbound proxy is defined.

   Example 1.32. Set the “outbound_proxy” parameter
 ...
 modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
 ...

3.32. ds_default_socket (str)

   Default socket to be used for sending pings and dispatching requests
   when a gateway has no send socket configured.

   By default no default socket is defined, the first configuration script
   listen directive is used.

   Example 1.33. Set the “ds_default_socket” parameter
 ...
 modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
 ...

3.33. ds_timer_mode (int)

   Specify the timer process to be used by the module for keepalives and
   active dialogs tracking.

   It can be set to:
     * 0 - use main timer process.
     * 1 - use secondary timer process.

   On a server with a lot of traffic, using secondary timer can help with
   performances, because the main timer can be overloaded by taking care
   of transactions retransmissions and expirations of items in memory.

   Default value is “0”.

   Example 1.34. Set the “ds_timer_mode” parameter
 ...
 modparam("dispatcher", "ds_timer_mode", 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_next_dst()
   4.5. ds_next_domain()
   4.6. ds_mark_dst([state])
   4.7. ds_list_exist(groupid)
   4.8. ds_is_from_list([groupid [, mode [, uri] ] ])
   4.9. ds_load_update()
   4.10. ds_load_unset()
   4.11. 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 is stored in AVP 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 interger.
          + “0” - hash over callid
          + “1” - hash over from URI.
          + “2” - hash over to URI.
          + “3” - hash over request-URI.
          + “4” - round-robin (next destination).
          + “5” - hash over authorization-username (Proxy-Authorization or
            "normal" authorization). If no username is found, round robin
            is used.
          + “6” - random destination (using rand()).
          + “7” - hash over the content of PVs string. Note: This works
            only when the parameter hash_pvar is set.
          + “8” - select destination sorted by priority attribute value
            (serial forking ordered by priority).
          + “9” - use weight based load distribution. You have to set the
            attribute 'weight' per each address in destination set.
          + “10” - use call load distribution. You have to set the
            attribute 'duid' (as an unique string id) per each address in
            destination set. Also, you must set parameters 'dstid_avp' and
            '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.
          + “X” - if the algorithm is not implemented, the first entry in
            set is chosen.
     * limit - the maximum number of items to be stored in AVP list for
       further failovers (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.35. ds_select_dst usage
...
ds_select_dst("1", "0");
...
$var(a) = 4;
ds_select_dst("1", "$var(a)");
...
ds_select_dst("1", "4", "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 is stored in AVP 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.36. 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
   AVPs 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 is stored in AVP 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.37. ds_select usage
...
$var(a) = 4;
if(ds_select("1", "$var(a)")) {
    ds_next_domain();
    t_relay();
    exit;
}
...

4.4.  ds_next_dst()

   Takes the next destination address from the AVPs with id 'dst_avp_id'
   and sets the dst_uri (outbound proxy address).

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

4.5.  ds_next_domain()

   Takes the next destination address from the AVPs with id 'dst_avp_id'
   and sets the domain part of the request URI.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

4.6.  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.38. ds_mark_dst usage
...
failure_route[tryagain] {
...
   if(t_check_status("500"))
      ds_mark_dst("ip"); # set to inactive and probing
...
}
...

4.7.  ds_list_exist(groupid)

   Check if a specific group is defined in dispatcher list or database.
     * groupid - A group ID to check.

   This function can be used from ANY_ROUTE.

   Example 1.39. ds_list_exist usage
...
if(ds_list_exist("10")) {
    ...
}
...

4.8.  ds_is_from_list([groupid [, mode [, uri] ] ])

   This function returns true, if there is a match of source address or
   uri with an address in the given group of the dispatcher-list;
   otherwise false.

   Description of parameters:
     * groupid (optional) - if not given or its value is -1, the matching
       will be done over all addresses in all dispacher groups. Otherwise
       the matching will be done only against the addresses in the
       specific group id. The parameter can be an integer or a variable
       holding an integer value.
     * mode - (optional) - a bitmask to specify how the matching should be
       done. If is 0, all ip, port and proto are matched. If bit one is
       set, then port is ignored. If bit two is set, then protocol is
       ignored. The parameter can be an integer or a variable holding an
       integer value. It must be provided if the uri parameter is
       provided.
     * uri (optional) - if is empty or missing, the matching is done
       against source IP, port and protocol. Otherwise the value has to be
       a valid SIP URI, used to match against addresses in the dispatcher
       list. Only IP, port and protocol are matches, any additional
       parameters are ignored. The parameter can be a static or dynamic
       (with variables) string. The domain part of the URI can be an IP
       address or a hostname.

   Upon a match, the variable specified by 'setid_pvname' parameter will
   be set to groupid of matching address and the attributes will be set in
   variable specified by 'attrs_pvname'.

   Note that for backward compatibility mode, when no parameter is given
   or only groupid is given, the matching is done only for IP address and
   port (protocol is ignored).

   This function can be used from ANY_ROUTE.

   Example 1.40. 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.9.  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.10.  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.41. 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.11.  ds_reload()

   Reloads the groups and included destinations.

   Name: ds_reload

   Parameters: none

   This function can be used from ANY_ROUTE.

5. RPC Commands

   5.1. dispatcher.set_state
   5.2. dispatcher.list
   5.3. dispatcher.reload
   5.4. dispatcher.ping_active

5.1.  dispatcher.set_state

   Sets the state for a destination address (can be use to mark the
   destination as active or inactive).

   Name: dispatcher.set_state

   Parameters:
     * _state_ : state of the destination address
          + “a”: active
          + “i”: inactive
          + “t”: trying
          + “d”: disabled
       The states “a”, “i” or “t” can be followed by “p” to set probing
       mode (e.g. 'ap', 'ip' or 'tp').
     * _group_: destination group id
     * _address_: address of the destination in the _group_

   Example:
...
# prototype: kamcmd dispatcher.set_state _state_ _group_ _address_
kamcmd dispatcher.set_state ip 2 sip:127.0.0.1:5080
...

5.2.  dispatcher.list

   Lists the groups and included destinations.

   Name: dispatcher.list

   Parameters: none

   Example:
                kamcmd dispatcher.list

5.3.  dispatcher.reload

   Reloads the groups and included destinations. The command is disabled
   for call load based dispatching (algorithm 10) since removal of
   destinations may leave the list of active calls with broken references.

   Name: dispatcher.reload

   Parameters: none

   Example
                kamcmd dispatcher.reload

5.4.  dispatcher.ping_active

   Sets the global state for sending keepalive requests to destinations.

   Name: dispatcher.ping_active

   Parameters:
     * _state_ : state of sending keepalives
          + “0”: inactive (don't send)
          + “1”: active (send)

   If the state parameter is missing, the current state is returned. When
   state is changed, new and old values of the state are returned. Default
   value for state is 1.

   Example:
...
# prototype: kamcmd dispatcher.ping_active _state_
kamcmd dispatcher.ping_active 0
...

6. Installation and Running

   6.1. Destination List File

        6.1.1. Special Attributes
        6.1.2. File Format

   6.2. Kamailio config file

6.1. Destination List File

   Each destination point must be on one line. First token is the set id
   (an integer value, also referenced by group id), followed by
   destination address (string value in full SIP URI format).

   Optionally, these fields can be followed by:
     * flags (listed by index - can be bitwise mask of values): 0 (value
       1) - inactive destination; 1 (value 2) - temporary trying
       destination (in the way to become inactive if it does not reply to
       keepalives - there is a module parameter to set the threshold of
       failures); 2 (value 4) - admin disabled destination; 3 (value 8) -
       probing destination (sending keep alives);
     * priority: sets the priority in destination list (based on it is
       done the initial ordering inside the set)
     * attributes: extra fields in form of name1=value1;...;nameN=valueN.

6.1.1. Special Attributes

   There are some predefined names:
     * 'duid' - used for call load dispatching. It must be an unique value
       to identify a destination (gateway address). Practically the load
       within the group is associated with this value.
     * 'maxload' - used for call load dispatching. It must be a positive
       integer, defining the upper limit of active calls per destination.
       When the limit is reached, then the gateway is no longer selected
       for new calls until an exiting call via that gateway is terminated.
       If set to 0, then no active call limit is used.
     * 'weight' - used for weight based load distribution. It must be set
       to a positive integer value beteen 0 and 100. The value represents
       the percent of calls to be sent to that gateways.
     * 'rweight' - used for relative weight based load distribution. It
       must be set to a positive integer value between 1 and 100
       (otherwise host will be excluded from relative weight distribution
       type).
     * 'socket' - used to set the sending socket for the gateway. It is
       used for sending the SIP traffic as well as OPTIONS keepalives.

6.1.2. File Format

   Line format is:
...
setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
...

   Full line example:
...
1 sip:127.0.0.1:5080 0 0 duid=abc;socket=udp:192.168.0.125:5060;my=xyz
...

   For database, each element of a line resides in a different column.
   Next is a dispatcher.list file example:

   Example 1.42. 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.43. 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.sip-router.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 "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", "dst_avp", "$avp(AVP_DST)")
modparam("dispatcher", "grp_avp", "$avp(AVP_GRP)")
modparam("dispatcher", "cnt_avp", "$avp(AVP_CNT)")
modparam("dispatcher", "sock_avp", "$avp(AVP_SOCK)")

####### Routing Logic ########


# main request routing logic

request_route {

        # per request initial checks
        route(REQINIT);

        # handle requests within SIP dialogs
        route(WITHINDLG);

        ### only initial requests (no To tag)

        # CANCEL processing
        if (is_method("CANCEL"))
        {
                if (t_check_trans())
                        t_relay();
                exit;
        }

        # handle retransmissions
        if(t_precheck_trans()) {
                t_check_trans();
                exit;
        }
        t_check_trans();

        # 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;
        }
        xlog("L_DBG", "--- SCRIPT: going to <$ru> via <$du>\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()) {
                        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 algoritms 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>.

       If you want to keep the mail private, send it to
       <sr-users@lists.kamailio.org>.

   2.5.

       How can I report a bug?

       Please follow the guidelines provided at:
       https://github.com/kamailio/kamailio/issues
