DISPATCHER Module

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Carsten Bock

   ng-voice.com

   Copyright © 2004 FhG FOKUS

   Copyright © 2005 Voice Sistem

   Copyright © 2010 Daniel-Constantin Mierla (asipto.com)
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio modules
              2.2. External libraries or applications

        3. Exported 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. hash_pvar (str)
              3.17. setid_pvar (str)
              3.18. ds_ping_method (string)
              3.19. ds_ping_from (string)
              3.20. ds_ping_interval (int)
              3.21. ds_probing_threshhold (int)
              3.22. ds_ping_reply_codes (string)
              3.23. ds_probing_mode (int)
              3.24. ds_hash_size (int)
              3.25. ds_hash_expire (int)
              3.26. ds_hash_initexpire (int)
              3.27. ds_hash_check_interval (int)

        4. Exported Functions

              4.1. ds_select_dst(set, alg)
              4.2. ds_select_domain(set, alg)
              4.3. ds_next_dst()
              4.4. ds_next_domain()
              4.5. ds_mark_dst()
              4.6. ds_mark_dst("s")
              4.7. ds_is_from_list()
              4.8. ds_is_from_list("group")
              4.9. ds_load_update()
              4.10. ds_load_unset()

        5. Exported MI Functions

              5.1. ds_set_state
              5.2. ds_list
              5.3. ds_reload

        6. Exported RPC Commands

              6.1. dispatcher.set_state
              6.2. dispatcher.list
              6.3. dispatcher.reload

        7. Installation and Running

              7.1. Destination List File
              7.2. Kamailio config file

   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. Use $avp(i:273) for hashing:
   1.17. Use combination of PVs for hashing:
   1.18. Set the “setid_pvar” parameter
   1.19. Set the “ds_ping_method” parameter
   1.20. Set the “ds_ping_from” parameter
   1.21. Set the “ds_ping_interval” parameter
   1.22. Set the “ds_probing_threshhold” parameter
   1.23. Set the “ds_ping_reply_codes” parameter
   1.24. Set the “ds_probing_mode” parameter
   1.25. Set the “ds_hash_size” parameter
   1.26. Set the “ds_hash_expire” parameter
   1.27. Set the “ds_hash_initexpire” parameter
   1.28. Set the “ds_hash_check_interval” parameter
   1.29. ds_select_dst usage
   1.30. ds_load_unset usage
   1.31. dispatcher list file
   1.32. 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. Exported 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. hash_pvar (str)
        3.17. setid_pvar (str)
        3.18. ds_ping_method (string)
        3.19. ds_ping_from (string)
        3.20. ds_ping_interval (int)
        3.21. ds_probing_threshhold (int)
        3.22. ds_ping_reply_codes (string)
        3.23. ds_probing_mode (int)
        3.24. ds_hash_size (int)
        3.25. ds_hash_expire (int)
        3.26. ds_hash_initexpire (int)
        3.27. ds_hash_check_interval (int)

   4. Exported Functions

        4.1. ds_select_dst(set, alg)
        4.2. ds_select_domain(set, alg)
        4.3. ds_next_dst()
        4.4. ds_next_domain()
        4.5. ds_mark_dst()
        4.6. ds_mark_dst("s")
        4.7. ds_is_from_list()
        4.8. ds_is_from_list("group")
        4.9. ds_load_update()
        4.10. ds_load_unset()

   5. Exported MI Functions

        5.1. ds_set_state
        5.2. ds_list
        5.3. ds_reload

   6. Exported RPC Commands

        6.1. dispatcher.set_state
        6.2. dispatcher.list
        6.3. dispatcher.reload

   7. Installation and Running

        7.1. Destination List File
        7.2. Kamailio config file

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, like: round-robin,
   weight based load balancing, call load distribution, hashing over SIP
   message attributes.

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

   It is very lightweight, therefore suitable for handling heavy SIP
   traffic. Its small footprint and ability to load balancing rules from a
   text plain file makes it 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. Exported 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. hash_pvar (str)
   3.17. setid_pvar (str)
   3.18. ds_ping_method (string)
   3.19. ds_ping_from (string)
   3.20. ds_ping_interval (int)
   3.21. ds_probing_threshhold (int)
   3.22. ds_ping_reply_codes (string)
   3.23. ds_probing_mode (int)
   3.24. ds_hash_size (int)
   3.25. ds_hash_expire (int)
   3.26. ds_hash_initexpire (int)
   3.27. ds_hash_check_interval (int)

3.1. list_file (string)

   Path to the file with destination sets.

   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 sets 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 sets 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 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's 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 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 the failover support is enabled. The functions
   exported by the module will store the rest of addresses from the
   destination set in AVP, and use these AVPs to contact next address when
   the current-tried 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 last option to send the message. For example, it is good 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. 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(i:273) for hashing:
 ...
 modparam("dispatcher", "hash_pvar", "$avp(i:273)")
 ...

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

3.17. setid_pvar (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_pvar” parameter
 ...
 modparam("dispatcher", "setid_pvar", "$var(setid)")
 ...

3.18. ds_ping_method (string)

   With this Method you can define, with which method you want to probe
   the gateways. Pinging gateways feature depends on ds_ping_interval
   parameter.

   Default value is “OPTIONS”.

   Example 1.19. Set the “ds_ping_method” parameter
 ...
 modparam("dispatcher", "ds_ping_method", "INFO")
 ...

3.19. ds_ping_from (string)

   With this Method you can define the "From:"-Line for the request, sent
   to the failed gateways. This method is only available, if compiled with
   the probing of failed gateways enabled.

   Default value is “sip:dispatcher@localhost”.

   Example 1.20. Set the “ds_ping_from” parameter
 ...
 modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
 ...

3.20. ds_ping_interval (int)

   With this parameter you can define the interval for sending a request
   to a gateway marked as inactive upon a failed request routing to it.
   This parameter is only used, when the TM-Module is loaded. If set to
   “0”, the pinging of inactive gateway is disabled.

   Default value is “0”.

   Example 1.21. Set the “ds_ping_interval” parameter
 ...
 modparam("dispatcher", "ds_ping_interval", 30)
 ...

3.21. ds_probing_threshhold (int)

   If you want to set a gateway into probing mode, you will need a
   specific number of requests until it will change from "active" to
   probing. The number of attempts can be set with this parameter. This
   parameter can be modified via ser config framework.

   Default value is “3”.

   Example 1.22. Set the “ds_probing_threshhold” parameter
 ...
 modparam("dispatcher", "ds_probing_threshhold", 10)
 ...

3.22. 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 ser config
   framework.

   Default value is “” (only 200 OK is accepted).

   Example 1.23. Set the “ds_ping_reply_codes” parameter
 ...
 modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=
3")
 ...

3.23. ds_probing_mode (int)

   Controls what gateways are tested to see if they are reachable. If set
   to 0, only the gateways with state PROBING are tested, if set to 1, all
   gateways are tested. If set to 1 and the response is 408 (timeout), an
   active gateway is set to PROBING state.

   Default value is “0”.

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

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

3.25. 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.26. Set the “ds_hash_expire” parameter
 ...
 modparam("dispatcher", "ds_hash_expire", 3600)
 ...

3.26. 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.27. Set the “ds_hash_initexpire” parameter
 ...
 modparam("dispatcher", "ds_hash_initexpire", 60)
 ...

3.27. 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.28. Set the “ds_hash_check_interval” parameter
 ...
 modparam("dispatcher", "ds_hash_check_interval", 60)
 ...

4. Exported Functions

   4.1. ds_select_dst(set, alg)
   4.2. ds_select_domain(set, alg)
   4.3. ds_next_dst()
   4.4. ds_next_domain()
   4.5. ds_mark_dst()
   4.6. ds_mark_dst("s")
   4.7. ds_is_from_list()
   4.8. ds_is_from_list("group")
   4.9. ds_load_update()
   4.10. ds_load_unset()

4.1.  ds_select_dst(set, alg)

   The method selects a destination from addresses set.

   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 interger.
     * 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 (using rand()).
          + “7” - hash over the content of PVs string. Note: This works
            only when the parameter hash_pvar is set.
          + “8” - use first destination (good for failover).
          + “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.
          + “X” - if the algorithm is not implemented, the first entry in
            set is chosen.

   If the bit 2 in 'flags' is set, the rest of the addresses from the
   destination set is stored in AVP list. You can use 'ds_next_dst()' to
   use next address to achieve serial forking to all possible
   destinations.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

   Example 1.29. ds_select_dst usage
...
ds_select_dst("1", "0");
...
$var(a) = 4;
ds_select_dst("1", "$var(a)");
...

4.2.  ds_select_domain(set, alg)

   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. 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.

4.3.  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.4.  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.5.  ds_mark_dst()

   Mark the last used address from destination set as inactive, in order
   to be ingnored in the future. In this way it can be implemented an
   automatic detection of failed gateways. When an address is marked as
   inactive, it will be ignored by 'ds_select_dst' and 'ds_select_domain'.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

4.6.  ds_mark_dst("s")

   Mark the last used address from destination set as inactive
   ("i"/"I"/"0"), active ("a"/"A"/"1") or probing ("p"/"P"/"2"). With this
   function, an automatic detection of failed gateways can be implemented.
   When an address is marked as inactive or probing, it will be ignored by
   'ds_select_dst' and 'ds_select_domain'.

   possible parameters:
     * "i", "I" or "0" - the last destination should be set to inactive
       and will be ignored in future requests.
     * "a", "A" or "1" - the last destination should be set to active and
       the error-counter should set to "0".
     * "p", "P" or "2" - the last destination will be set to probing.
       Note: You will need to call this function "threshhold"-times,
       before it will be actually set to probing.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

4.7.  ds_is_from_list()

   This function returns true, if the current request comes from a host
   from the dispatcher-list; otherwise false.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE and ONREPLY_ROUTE.

4.8.  ds_is_from_list("group")

   This function returns true, if the current request comes from a host in
   the given group of the dispatcher-list; otherwise false.

   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
   BRANCH_ROUTE and ONREPLY_ROUTE.

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.30. 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();
    }
    ...
}
...

5. Exported MI Functions

   5.1. ds_set_state
   5.2. ds_list
   5.3. ds_reload

5.1.  ds_set_state

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

   Name: ds_set_state

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

   MI FIFO Command Format:
                :ds_set_state:_reply_fifo_file_
                _state_
                _group_
                _address_
                _empty_line_

5.2.  ds_list

   It lists the groups and included destinations.

   Name: ds_list

   Parameters: none

   MI FIFO Command Format:
                :ds_list:_reply_fifo_file_
                _empty_line_

5.3.  ds_reload

   It 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: ds_reload

   Parameters: none

   MI DATAGRAM Command Format:
                ":ds_reload:\n."

6. Exported RPC Commands

   6.1. dispatcher.set_state
   6.2. dispatcher.list
   6.3. dispatcher.reload

6.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
          + “d”: disabled
       The states “a” or “i” can be followed by “p” to set probing mode
       (e.g. 'ap' or 'ip')
     * _group_: destination group id
     * _address_: address of the destination in the _group_

   Example:
                sercmd dispatcher.set_state _state_ _group_ _address_

6.2.  dispatcher.list

   It lists the groups and included destinations.

   Name: dispatcher.list

   Parameters: none

   Example:
                sercmd dispatcher.list

6.3.  dispatcher.reload

   It 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
                sercmd dispatcher.reload

7. Installation and Running

   7.1. Destination List File
   7.2. Kamailio config file

7.1. Destination List File

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

   Optionally, these fields can be followed by:
     * flags: 1 - destination inactive, 2 - destination in probing mode --
       you can do bitwise OR to set both flags
     * priority: sets the priority in destination list (based on it is
       done the initial ordering inside the set)
     * attributes: extra filed in form of name1=value1;...;nameN=valueN.
       There are some predefined names that are used of weight and call
       load dispatching.

   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;my=xyz
...

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

   Example 1.31. dispatcher list file
...
# $Id$
# dispatcher destination sets
#

# line format
# setit(int) destination(sip uri) flags(int,opt) priority(int,opt) attributes(st
r,opt)

# proxies
2 sip:127.0.0.1:5080
2 sip:127.0.0.1:5082

# gateways
1 sip:127.0.0.1:7070
1 sip:127.0.0.1:7072
1 sip:127.0.0.1:7074

...

7.2. Kamailio config file

   Next picture displays a sample usage of dispatcher.

   Example 1.32. Kamailio config script - sample dispatcher usage
...
# $Id$
# sample config file for dispatcher module
#

debug=9          # debug level (cmd line: -dddddddddd)
fork=no
log_stderror=yes  # (cmd line: -E)

children=2
check_via=no      # (cmd. line: -v)
dns=off           # (cmd. line: -r)
rev_dns=off       # (cmd. line: -R)
port=5060

# for more info: sip_router -h

# ------------------ module loading ----------------------------------
mpath="/usr/local/lib/kamailio/modules/"
loadmodule "maxfwd.so"
loadmodule "sl.so"
loadmodule "dispatcher.so"
loadmodule "tm.so"

# ----------------- setting module-specific parameters ---------------

# -- dispatcher params --
modparam("dispatcher", "list_file", "/usr/local/etc/kamailio/dispatcher.list")
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)")

# main request routing block
route {
        if ( !mf_process_maxfwd_header("10") )
        {
                sl_send_reply("483","To Many Hops");
                exit;
        }

        # select from first dst group by round-robin
        if(!ds_select_dst("1", "4"))
        {
                sl_send_reply("500", "No destination available");
                exit;
        }

        t_on_failure("RTF_DISPATCH");
        if(!t_relay())
        {
                sl_reply_error();
                exit;
        }
}

# dispatcher failure routing block
failure_route[RTF_DISPATCH] {
        if (t_is_canceled()) {
                exit;
        }
        # select next destination only for local timeout
        if (t_branch_timeout() &amp;&amp; !t_branch_replied())
        {
                if(ds_next_dst())
                {
                        t_on_failure("RTF_DISPATCH");
                        t_relay();
                        exit;
                }
        }
}

...

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?

       There is no guarantee of that. You should do some measurements to
       decide what distribution algorithm fits better in your environment.

   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 http://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 -
           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-users
         * Developer Mailing List -
           http://lists.sip-router.org/cgi-bin/mailman/listinfo/sr-dev

       E-mails regarding any stable version should be sent to
       <sr-users@lists.sip-router.org> and e-mail regarding development
       versions or CVS snapshots should be send to
       <sr-dev@lists.sip-router.org>.

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

   2.5.

       How can I report a bug?

       Please follow the guidelines provided at: http://sip-router.org/tracker