# &adminguide;

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

## Dependencies

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

### External libraries or applications

The following libraries or applications must be installed before running &kamailio; with this module:

- none.

## Parameters

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

#### Set the list_file parameter

    ...
    modparam("dispatcher", "list_file", "/run/kamailio/dispatcher.list")
    ...

### `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).

#### Set db_url parameter

    ...
    modparam("dispatcher", "db_url", "mysql://user:passwd@localhost/database")
    ...

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

#### Set table_name parameter

    ...
    modparam("dispatcher", "table_name", "my_dispatcher")
    ...

### `setid_col` (string)

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

Default value is setid.

#### Set setid_col parameter

    ...
    modparam("dispatcher", "setid_col", "groupid")
    ...

### `destination_col` (string)

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

Default value is destination.

#### Set destination_col parameter

    ...
    modparam("dispatcher", "destination_col", "uri")
    ...

### `flags_col` (string)

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

Default value is flags.

#### Set flags_col parameter

    ...
    modparam("dispatcher", "flags_col", "dstflags")
    ...

### `priority_col` (string)

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

Default value is priority.

#### Set priority_col parameter

    ...
    modparam("dispatcher", "priority_col", "dstpriority")
    ...

### `attrs_col` (string)

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

Default value is attrs.

#### Set attrs_col parameter

    ...
    modparam("dispatcher", "attrs_col", "dstattrs")
    ...

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

#### Set the force_dst parameter

    ...
    modparam("dispatcher", "force_dst", 1)
    ...

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

#### Set the flags parameter

    ...
    modparam("dispatcher", "flags", 3)
    ...

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

#### Set the use_default parameter

    ...
    modparam("dispatcher", "use_default", 1)
    ...

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

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

Default value is _dsdst_.

#### Set the xavp_dst parameter

    ...
    modparam("dispatcher", "xavp_dst", "_dsdst_")
    ...

### `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 grp, uri, sock, attr and optionally dstid fields).

#### Set the xavp_dst_mode parameter

    ...
        modparam("dispatcher", "xavp_dst_mode", 1)
    ...
        modparam("dispatcher", "xavp_dst_mode", 2)
    ...

### `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_.

#### Set the xavp_ctx parameter

    ...
    modparam("dispatcher", "xavp_ctx", "_dsctx_")
    ...

### `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).

#### Set the xavp_ctx_mode parameter

    ...
    modparam("dispatcher", "xavp_ctx_mode", 1)
    ...

### `hash_pvar` (str)

String with PVs used for the hashing algorithm 7.

You must set this parameter if you want do hashing over custom message parts.

Default value is null - disabled.

#### Use $avp(hash) for hashing:

    ...
    modparam("dispatcher", "hash_pvar", "$avp(hash)")
    ...

#### Use combination of PVs for hashing:

    ...
    modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
    ...

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

#### Set the setid_pvname parameter

    ...
    modparam("dispatcher", "setid_pvname", "$var(setid)")
    ...

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

#### Set the attrs_pvname parameter

    ...
    modparam("dispatcher", "attrs_pvname", "$var(attrs)")
    ...

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

#### Set the ds_ping_method parameter

    ...
    modparam("dispatcher", "ds_ping_method", "INFO")
    ...

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

#### Set the ds_ping_from parameter

    ...
    modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
    ...

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

#### Set the ds_ping_interval parameter

    ...
    modparam("dispatcher", "ds_ping_interval", 30)
    ...

### `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).

#### Set the ds_probing_threshold parameter

    ...
    modparam("dispatcher", "ds_probing_threshold", 10)
    ...

### `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).

#### Set the ds_inactive_threshold parameter

    ...
    modparam("dispatcher", "ds_inactive_threshold", 10)
    ...

### `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).

#### Set the ds_ping_reply_codes parameter

    ...
    modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=3")
    ...

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

#### Set the ds_probing_mode parameter

    ...
    modparam("dispatcher", "ds_probing_mode", 1)
    ...

### `ds_ping_latency_stats` (int)

Enable latency measurement when pinging nodes The estimator can be initialized at startup and reload using the attribute latency.

- If set to 0, disable latency measurement.

- If set to 1, enable latency measurement.

Default value is 0.

#### accessing the metrics

    # using the command :
    kamcmd dispatcher.list
    ...
    DEST: {
    	URI: sip:1.2.3.4
    	FLAGS: AX
    	PRIORITY: 9
    	ATTRS: {
    		BODY: latency=24
    	}
    	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
    	}
    }
    ...

#### Set the ds_ping_latency_stats parameter

    ...
    modparam("dispatcher", "ds_ping_latency_stats", 1)
    ...

### `ds_retain_latency_stats` (int)

Retain latency stats for existing destinations when reloading from file or database.

- If set to 0, stats for all destinations will be reset on reload.

- If set to 1, stats for existing destinations will persist across reloads.

Default value is 0.

#### Set the ds_retain_latency_stats parameter

    ...
    modparam("dispatcher", "ds_retain_latency_stats", 1)
    ...

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

#### Set the ds_latency_estimator_alpha parameter

    ...
    modparam("dispatcher", "ds_latency_estimator_alpha", 900)
    ...

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

#### Set the ds_hash_size parameter

    ...
    modparam("dispatcher", "ds_hash_size", 9)
    ...

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

#### Set the ds_hash_expire parameter

    ...
    modparam("dispatcher", "ds_hash_expire", 3600)
    ...

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

#### Set the ds_hash_initexpire parameter

    ...
    modparam("dispatcher", "ds_hash_initexpire", 60)
    ...

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

#### Set the ds_hash_check_interval parameter

    ...
    modparam("dispatcher", "ds_hash_check_interval", 60)
    ...

### `outbound_proxy` (str)

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

By default no outbound proxy is defined.

#### Set the outbound_proxy parameter

    ...
    modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
    ...

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

#### Set the ds_default_socket parameter

    ...
    modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
    ...

### `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).

#### Set the ds_default_sockname parameter

    ...
     listen=udp:1.2.3.4:5060 name "sock1"
    ...
    modparam("dispatcher", "ds_default_sockname", "sock1")
    ...

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

#### Set the ds_timer_mode parameter

    ...
    modparam("dispatcher", "ds_timer_mode", 1)
    ...

### `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).

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

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

#### Set the ds_attrs_none parameter

    ...
    modparam("dispatcher", "ds_attrs_none", 1)
    ...

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

#### Set the ds_db_extra_attrs parameter

    ...
    modparam("dispatcher", "ds_db_extra_attrs", "socket=socket;pref=prefix")
    ...

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

#### Set the ds_load_mode parameter

    ...
    modparam("dispatcher", "ds_load_mode", 1)
    ...

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

#### Set `reload_delta` parameter

    ...
    modparam("dispatcher", "reload_delta", 1)
    ...

### `ds_dns_mode` (int)

Specify the how DNS resolving is done for destination addresses.

It is a bitwise flag and can be set to one or the sum of:

- 1 - do it at startup and reload (previous behaviour).

- 2 - do it always when the address is matched with ds_is_from_list().

- 4 - do it startup/reload and refresh on the timer interval specified by ds_dns_interval.

- 8 - do SRV (and NAPTR if enabled in core) query instead of A/AAAA lookup. NAPTR is done if protocol and port are not set. SRV is done if port is not set.

Default value is 1.

#### Set the ds_dns_mode parameter

    ...
    modparam("dispatcher", "ds_dns_mode", 2)
    ...

### `ds_dns_interval` (int)

The interval in seconds to periodically refresh the DNS queries for destination addresses if ds_dns_mode has value 4 set.

Default value is 600.

#### Set the ds_dns_interval parameter

    ...
    modparam("dispatcher", "ds_interval_mode", 1800)
    ...

### `ds_dns_ttl` (int)

The interval in seconds to set TTL for DNS results received for queries dones inside this module. If 0, this TTL is not set, result and core values are used.

Default value is 0.

#### Set the ds_dns_ttl parameter

    ...
    modparam("dispatcher", "ds_interval_mode", 7200)
    ...

## Functions

### `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 user.

  - 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. See also 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 destinations being active or inactive.

    For example, 100 calls in 3-destinations group with rweight params 1/2/1 will be distributed as 25/50/25. If the third destination becomes inactive, the distribution is changed to 33/67/0. If the computation of percentage per destination is not an exact integer number, the value is trucated and the last destination is used to fill the remaining percentage till 100.

    Using this algorithm, you can also enable congestion control by setting the attribute 'cc=1', when 'cc' is enabled the 'weight' 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.

    See also the description of the 'rweight' attribute in the 'Special Attributes' section.

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

  - 13 - latency optimized dispatching

    - The algorithm will load balance using round-robin prioritizing the gateways with the highest priority.

    - If ds_ping_latency_stats is active the algorithm will adjust the priority of the gateway automatically, the priority will be lowered by 1 point every time the latency ms is as high as the priority.

    - If the attribute 'cc=1' is set, the latency used is congestion ms : estimate (current latency ms) - average (normal condition latency ms).

    #### `latency_optimized_dispatching` usage

        Using this simple formula :
            ADJUSTED_PRIORITY = PRIORITY - (ESTIMATED_LATENCY_MS/PRIORITY)

        GATEWAY | PRIORITY | ESTIMATED | ADJUSTED | LOAD
           #    |          |  LATENCY  | PRIORITY | DISTRIBUTION
           1    |    30    |    21     |    30    | 33%
           2    |    30    |    91     |    27    | 0%
           3    |    30    |    61     |    28    | 0%
           4    |    30    |    19     |    30    | 33%
           5    |    30    |    32     |    29    | 0%
           6    |    30    |    0      |    30    | 33%
           7    |    30    |    201    |    24    | 0%

        With congestion control the formula becomes :
            CONGESTION_MS = CURRENT_LATENCY_MS - NORMAL_CONDITION_LATENCY_MS
            ADJUSTED_PRIORITY = PRIORITY - (CONGESTION_MS/PRIORITY)

  - 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 can improve the performance especially if you are using a large list of gateways.

This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.

#### `ds_select_dst` usage

    ...
    ds_select_dst("1", "0");
    ...
    $var(a) = 4;
    ds_select_dst("1", "$var(a)");
    ...
    ds_select_dst("1", "4", "3");
    ...

#### configuring load balancing with congestion detection

    ...
    # sample of SQL provisioning 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
    	}
    }
    ...

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

#### `ds_select_domain` usage

    ...
    $var(a) = 4;
    if(ds_select_domain("1", "$var(a)")) {
        t_relay();
        exit;
    }
    ...

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

#### `ds_select` usage

    ...
    $var(a) = 4;
    if(ds_select("1", "$var(a)")) {
        ds_next_domain();
        t_relay();
        exit;
    }
    ...

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

#### `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;
            }
        }
    }
    ...

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

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

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

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

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

#### `ds_mark_dst` usage

    ...
    failure_route[tryagain] {
    ...
       if(t_check_status("500"))
          ds_mark_dst("ip"); # set to inactive and probing
    ...
    }
    ...

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

#### `ds_list_exists` usage

    ...
    if(ds_list_exists("10")) {
        ...
    }
    ...

### `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 the parameter is missing, the matching is done with ignoring the protocol (value 2). 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. If bit four is set, then socket/sockname be matched. If bit five is set, then try to find the most closest target from all dispatcher targets with the mandatory ip and combination of local socket, protocol, port, the weighted search result is combined from bit flags of matched components: ip - 1, port - 2, protocol - 4, local socket - 8, the target with the maximum value of flags combination will be selected. 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.

#### `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")) {
        ...
    }
    ...

### `ds_is_active(groupid [, uri])`

This function returns true, if there is an active URI in the destination group; otherwise false. If the uri parameter is provided, then the corresponding destination has to be active.

Description of parameters:

- groupid - the group id. The parameter can be an integer or a variable holding an integer value.

- uri (optional) - the URI of the destination. if parameter is empty or missing, the any destination is matched.

This function can be used from ANY_ROUTE.

#### `ds_is_active` usage

    ...
    if(ds_is_active("10")) {
        ...
    }
    if(ds_is_active("10", "sip:127.0.0.1:5080")) {
        ...
    }
    ...

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

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

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

### `ds_reload()`

Reloads the groups and included destinations.

Name: ds_reload

Parameters: none

This function can be used from ANY_ROUTE.

#### `ds_reload` usage

    ...
        ds_reload();
    ...

### `ds_dsg_fetch(setid)`

Sets the destination group id to setid for fetching $dsg(key) attributes.

Parameters: setid - integer or variable holding the set id value

This function can be used from ANY_ROUTE.

#### `ds_dsg_fetch()` usage

    ...
        ds_dsg_fetch("1");
        xinfo("set id: 1 - all: $dsg(count); active: $dsg(active)\n");
    ...

## RPC Commands

### `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: &sercmd; dispatcher.set_state _state_ _group_ _address_
    &sercmd; dispatcher.set_state ip 2 sip:127.0.0.1:5080
    &sercmd; dispatcher.set_state ip 3 all
    ...

### `dispatcher.set_duid_state`

Sets the state for a destination by matching on 'duid' attribute. The first two parameters '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: &sercmd; dispatcher.set_duid_state _state_ _group_ _duid_
    &sercmd; dispatcher.set_duid_state ip 2 xyz
    ...

### `dispatcher.list`

Lists the routing groups with destination addresses and corresponding attributes.

Name: dispatcher.list

Parameters:

- _rmode_ - (optional) response mode - can be: 'short' to get a shorter version of groups and destinations; 'full' to get more attributes per destination

Example:

    		&sercmd; dispatcher.list
    ...
    DEST: {
            URI: sip:192.168.0.1:5060
            FLAGS: AP
            PRIORITY: 12
    }
    ...

FLAGS consist out of 2 letters. First letter describe status of destination: A-active, I – inactive, T – trying, D – disabled. Second letter might be P or X. P is for probing, so AP means destination is active and it is tested by SIP options continuously. X means that there are no probing or sip pinging. So AX means that destination is assumed as active and it is not tested by SIP options. DX respectively is disabled destination that is not tested, etc.

### `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

    		&sercmd; dispatcher.reload

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

### `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

- _priority_ (optional): as described in the list file format, default 0

- _attrs_ (optional): as described in the list file format, default ""

Example:

    ...
    # prototype: &sercmd; dispatcher.add _group_ _address_ _flags_ _priority_ _attrs_
    &sercmd; dispatcher.add 2 sip:127.0.0.1:5080
    &sercmd; dispatcher.add 3 sip:127.0.0.1:5075 8
    &sercmd; dispatcher.add 3 sip:127.0.0.1:5075 0 0 duid=abc;socket=udp:127.0.0.1:5060
    ...

### `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: &sercmd; dispatcher.remove _group_ _address_
    &sercmd; dispatcher.remove 2 sip:127.0.0.1:5080
    &sercmd; dispatcher.remove 3 sip:127.0.0.1:5075;transport=udp
    ...

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

## Installation and Running

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

#### 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 between 1 and 100 (inclusive the limits), otherwise the destination address is ignored (its weight set to 0). The value represents the percent of calls to be sent to that gateways. The sum must not exceed 100, otherwise the destinations whose weight added to the sum go over 100 are ignored. If the sum is less than 100, then the last destination is used to fill the missing percentage. See also the description of the corresponding algorithm parameter for ds_select_dst().

- 'rweight' - used for relative weight based load distribution. It must be set to a positive integer value between 1 and 100 (inclusive the limits) otherwise host will be excluded from relative weight distribution type - its rweight is set to 0. See also the description of the corresponding algorithm parameter for ds_select_dst().

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

- 'latency' - latency_stats initialization in ms.

#### 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:

##### dispatcher list file

    ...

    ...

### &kamailio; config file

Next listing shows a sample config for using the dispatcher module.

#### &kamailio; config script - sample dispatcher usage

    ...

    ...

## Event routes

### `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");
    }
    ...

### `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");
    }
    ...