src/modules/dispatcher/doc/dispatcher_admin.xml
33d03d8d
 <?xml version="1.0" encoding='ISO-8859-1'?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
12a25ed7
  
33d03d8d
 <!-- Include general documentation entities -->
6deb5fcf
 <!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
33d03d8d
 %docentities;
 
 ]>
31ccf6a2
 <!-- Module User's Guide -->
 
33d03d8d
 <chapter xmlns:xi="http://www.w3.org/2001/XInclude">
74581f3a
 
9fc784c6
 	<title>&adminguide;</title>
3d6ab631
 
b68fbcd1
 	<section>
31ccf6a2
 	<title>Overview</title>
 	<para>
51ec1f96
 		This module offers SIP load balancer functionality and it can be
 		used as SIP traffic dispatcher. There are many load balancing and
c1c1de5b
 		traffic dispatching algorithms that you can choose from, for example:
51ec1f96
 		round-robin, weight based load balancing, call load distribution,
91537fc7
 		and hashing over SIP message attributes.
31ccf6a2
 	</para>
 	<para>
91537fc7
 		The module can be used as a stateless load balancer; it does not
f210c266
 		depend on any call state tracking module. It requires the TM module if
51ec1f96
 		you enable auto-discovery of active/inactive gateways.
 	</para>
 	<para>
 		It is very lightweight, therefore suitable for handling heavy SIP
74581f3a
 		traffic. As the module has a small footprint and the ability to load
91537fc7
 		balancing rules from a plain text file, it is suitable for embedded systems.
31ccf6a2
 	</para>
b68fbcd1
 	</section>
 	<section>
31ccf6a2
 	<title>Dependencies</title>
 	<section>
a118a328
 		<title>&kamailio; modules</title>
b68fbcd1
 		<para>
31ccf6a2
 		The following modules must be loaded before this module:
b68fbcd1
 			<itemizedlist>
 			<listitem>
31ccf6a2
 			<para>
51ec1f96
 				<emphasis>TM - only if active recovery of failed hosts
 					is required</emphasis>.
 			</para>
 			</listitem>
 			<listitem>
 			<para>
 				<emphasis>database engine - only if you want to load
 					balancing routes from database instead of plain text file.
 				</emphasis>.
31ccf6a2
 			</para>
b68fbcd1
 			</listitem>
 			</itemizedlist>
 		</para>
31ccf6a2
 	</section>
 	<section>
b68fbcd1
 		<title>External libraries or applications</title>
 		<para>
31ccf6a2
 		The following libraries or applications must be installed before
a118a328
 		running &kamailio; with this module:
b68fbcd1
 			<itemizedlist>
 			<listitem>
31ccf6a2
 			<para>
b68fbcd1
 				<emphasis>none</emphasis>.
31ccf6a2
 			</para>
b68fbcd1
 			</listitem>
 			</itemizedlist>
 		</para>
 	</section>
31ccf6a2
 	</section>
3d6ab631
 
b68fbcd1
 	<section>
9114eebc
 	<title>Parameters</title>
d48d36df
 	<section id="dispatcher.p.list_file">
b68fbcd1
 		<title><varname>list_file</varname> (string)</title>
 		<para>
45989d3c
 		Path to the file with destination sets (destination groups).
b68fbcd1
 		</para>
 		<para>
31ccf6a2
 		<emphasis>
9b64b9f3
 			Default value is <quote>/etc/kamailio/dispatcher.list</quote> or
 			<quote>/usr/local/etc/kamailio/dispatcher.list</quote>.
31ccf6a2
 		</emphasis>
b68fbcd1
 		</para>
 		<example>
31ccf6a2
 		<title>Set the <quote>list_file</quote> parameter</title>
 		<programlisting format="linespecific">
 ...
9b64b9f3
 modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
31ccf6a2
 ...
 </programlisting>
b68fbcd1
 		</example>
31ccf6a2
 	</section>
101e9af4
 
d48d36df
 	<section id="dispatcher.p.db_url">
101e9af4
  		<title><varname>db_url</varname> (string)</title>
  		<para>
45989d3c
 		If you want to load the list of gateways from the database you must set
101e9af4
 		this parameter.
  		</para>
  		<para>
  		<emphasis>
  			Default value is <quote>NULL</quote> (disable DB support).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <quote>db_url</quote> parameter</title>
 		<programlisting format="linespecific">
 ...
c1c1de5b
 modparam("dispatcher", "db_url", "mysql://user:passwd@localhost/database")
101e9af4
 ...
 </programlisting>
 		</example>
 	</section>
 
d48d36df
 	<section id="dispatcher.p.table_name">
101e9af4
 		<title><varname>table_name</varname> (string)</title>
 		<para>
45989d3c
 		If you want to load the list of gateways from the database you must set
101e9af4
 		this parameter as the database name.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>dispatcher</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <quote>table_name</quote> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("dispatcher", "table_name", "my_dispatcher")
 ...
 </programlisting>
 		</example>
 	</section>
 
d48d36df
 	<section id="dispatcher.p.setid_col">
101e9af4
 		<title><varname>setid_col</varname> (string)</title>
 		<para>
45989d3c
 			The column's name in the database storing the gateway's set (group)
 			id.
101e9af4
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>setid</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <quote>setid_col</quote> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("dispatcher", "setid_col", "groupid")
 ...
 </programlisting>
 		</example>
 	</section>
 
d48d36df
 	<section id="dispatcher.p.destination_col">
101e9af4
 		<title><varname>destination_col</varname> (string)</title>
 		<para>
93c65670
 			The column's name in the database storing the destination
 			sip URI.
101e9af4
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>destination</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <quote>destination_col</quote> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("dispatcher", "destination_col", "uri")
 ...
 </programlisting>
 		</example>
 	</section>
 
d48d36df
 	<section id="dispatcher.p.flags_col">
991a77fa
 		<title><varname>flags_col</varname> (string)</title>
 		<para>
 			The column's name in the database storing the flags for
93c65670
 			the destination URI.
991a77fa
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>flags</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <quote>flags_col</quote> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("dispatcher", "flags_col", "dstflags")
 ...
 </programlisting>
 		</example>
 	</section>
 
d48d36df
 	<section id="dispatcher.p.priority_col">
9de77c2b
 		<title><varname>priority_col</varname> (string)</title>
 		<para>
 			The column's name in the database storing the priority for
93c65670
 			destination URI.
9de77c2b
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>priority</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <quote>priority_col</quote> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("dispatcher", "priority_col", "dstpriority")
 ...
 </programlisting>
 		</example>
 	</section>
 
d48d36df
 	<section id="dispatcher.p.force_dst">
b68fbcd1
 		<title><varname>force_dst</varname> (int)</title>
 		<para>
9a5bc6b1
 		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.
b68fbcd1
 		</para>
 		<para>
31ccf6a2
 		<emphasis>
9a5bc6b1
 			Default value is <quote>1</quote>.
31ccf6a2
 		</emphasis>
b68fbcd1
 		</para>
 		<example>
31ccf6a2
 		<title>Set the <quote>force_dst</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "force_dst", 1)
 ...
 </programlisting>
b68fbcd1
 		</example>
 	</section>
d48d36df
  	<section id="dispatcher.p.flags">
3d6ab631
  		<title><varname>flags</varname> (int)</title>
  		<para>
a4ba0359
  		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
93c65670
  		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).
3d6ab631
  		</para>
  		<para>
93c65670
 		If flag 2 is set, then failover support is enabled. The functions
a4ba0359
 		exported by the module will store the rest of addresses from the
422e7dbd
 		destination set in XAPVs, and use these XAVPs to try next address if
93c65670
 		the current-tried destination fails.
a4ba0359
  		</para>
  		<para>
ee4a9fb2
  		<emphasis>
3d6ab631
  			Default value is <quote>0</quote>.
ee4a9fb2
  		</emphasis>
3d6ab631
  		</para>
  		<example>
ee4a9fb2
  		<title>Set the <quote>flags</quote> parameter</title>
  <programlisting format="linespecific">
  ...
a4ba0359
  modparam("dispatcher", "flags", 3)
  ...
  </programlisting>
  		</example>
  	</section>
d48d36df
  	<section id="dispatcher.p.use_default">
a4ba0359
  		<title><varname>use_default</varname> (int)</title>
  		<para>
  		If the parameter is set to 1, the last address in destination set
93c65670
 		is used as a final option to send the request to. For example, it is useful
c1c1de5b
 		when wanting to send the call to an announcement server saying:
a4ba0359
 		"the gateways are full, try later".
  		</para>
  		<para>
  		<emphasis>
  			Default value is <quote>0</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>use_default</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "use_default", 1)
  ...
  </programlisting>
  		</example>
 	</section>
422e7dbd
  	<section id="dispatcher.p.xavp_dst">
  		<title><varname>xavp_dst</varname> (str)</title>
a4ba0359
  		<para>
422e7dbd
  		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. 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.
a4ba0359
  		</para>
ff4dd78e
 		<note>
  		<para>
bef7e92f
 		You must set this parameter if you want to do load balancing fail over.
ff4dd78e
  		</para>
 		</note>
a4ba0359
  		<para>
  		<emphasis>
422e7dbd
  			Default value is <quote>_dsdst_</quote>.
a4ba0359
  		</emphasis>
  		</para>
  		<example>
422e7dbd
  		<title>Set the <quote>xavp_dst</quote> parameter</title>
a4ba0359
  <programlisting format="linespecific">
  ...
422e7dbd
  modparam("dispatcher", "xavp_dst", "_dsdst_")
a4ba0359
  ...
  </programlisting>
  		</example>
  	</section>
422e7dbd
  	<section id="dispatcher.p.xavp_dst_mode">
  		<title><varname>xavp_dst_mode</varname> (int)</title>
a4ba0359
  		<para>
422e7dbd
  		Control what fields are added to the XAVP specified by xavp_dst
5799e272
 		parameter.
 		</para>
 		<para>
 		The addeded fields are:
 		<itemizedlist>
 			<listitem>
 			grp - the set id (group id).
 			</listitem>
 			<listitem>
 			uri - the URI address.
 			</listitem>
 			<listitem>
 			sock - the socket pointer.
 			</listitem>
 			<listitem>
 			dstid - the destination unique id (in case of call load distribution algorithm).
 			</listitem>
 			<listitem>
 			attrs - the attributes - they are added if xavp_dst_mode does not have the bit 1 set.
 			</listitem>
 		</itemizedlist>
a4ba0359
  		</para>
  		<para>
  		<emphasis>
422e7dbd
  			Default value is <quote>0</quote> (add all fields).
a4ba0359
  		</emphasis>
  		</para>
  		<example>
422e7dbd
  		<title>Set the <quote>xavp_dst_mode</quote> parameter</title>
a4ba0359
  <programlisting format="linespecific">
  ...
422e7dbd
  modparam("dispatcher", "xavp_dst_mode", 1)
bef7e92f
  ...
  </programlisting>
  		</example>
  	</section>
422e7dbd
  	<section id="dispatcher.p.xavp_ctx">
  		<title><varname>xavp_ctx</varname> (str)</title>
bef7e92f
  		<para>
422e7dbd
  		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.
bef7e92f
  		</para>
  		<para>
  		<emphasis>
422e7dbd
  			Default value is <quote>_dsctx_</quote>.
bef7e92f
  		</emphasis>
  		</para>
  		<example>
422e7dbd
  		<title>Set the <quote>xavp_ctx</quote> parameter</title>
bef7e92f
  <programlisting format="linespecific">
  ...
422e7dbd
  modparam("dispatcher", "xavp_ctx", "_dsctx_")
bef7e92f
  ...
  </programlisting>
  		</example>
  	</section>
422e7dbd
  	<section id="dispatcher.p.xavp_ctx_mode">
  		<title><varname>xavp_ctx_mode</varname> (int)</title>
bef7e92f
  		<para>
422e7dbd
  		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.
bef7e92f
  		</para>
  		<para>
  		<emphasis>
422e7dbd
  			Default value is <quote>0</quote> (add all fields).
bef7e92f
  		</emphasis>
  		</para>
  		<example>
422e7dbd
  		<title>Set the <quote>xavp_ctx_mode</quote> parameter</title>
bef7e92f
  <programlisting format="linespecific">
  ...
422e7dbd
  modparam("dispatcher", "xavp_ctx_mode", 1)
ee4a9fb2
  ...
  </programlisting>
3d6ab631
  		</example>
ee4a9fb2
  	</section>
d48d36df
  	<section id="dispatcher.p.hash_pvar">
095ab21d
  		<title><varname>hash_pvar</varname> (str)</title>
  		<para>
  		String with PVs used for the hashing algorithm 7.
  		</para>
 		<note>
  		<para>
 		You must set this parameter if you want do hashing over custom message
 		parts.
  		</para>
 		</note>
  		<para>
  		<emphasis>
  			Default value is <quote>null</quote> - disabled.
  		</emphasis>
  		</para>
  		<example>
5a5959b1
  		<title>Use $avp(hash) for hashing:</title>
095ab21d
  <programlisting format="linespecific">
  ...
5a5959b1
  modparam("dispatcher", "hash_pvar", "$avp(hash)")
095ab21d
  ...
  </programlisting>
  		</example>
  		<example>
  		<title>Use combination of PVs for hashing:</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "hash_pvar", "hash the $fU@$ci")
  ...
  </programlisting>
  		</example>
  	</section>
d48d36df
  	<section id="dispatcher.p.setid_pvname">
e1149b05
  		<title><varname>setid_pvname</varname> (str)</title>
b14bb7d7
  		<para>
 		The name of the PV where to store the set ID (group ID) when calling
 		ds_is_from_list() with no parameter.
  		</para>
  		<para>
  		<emphasis>
  			Default value is <quote>null</quote> - don't set PV.
  		</emphasis>
  		</para>
  		<example>
e1149b05
  		<title>Set the <quote>setid_pvname</quote> parameter</title>
b14bb7d7
  <programlisting format="linespecific">
  ...
e1149b05
  modparam("dispatcher", "setid_pvname", "$var(setid)")
b14bb7d7
  ...
  </programlisting>
  		</example>
aa0156ea
 	</section>
 	<section id="dispatcher.p.attrs_pvname">
 		<title><varname>attrs_pvname</varname> (str)</title>
 		<para>
 		The name of the PV where to store the attributes of matching address
 		when calling ds_is_from_list().
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>null</quote> - don't set PV.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>attrs_pvname</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "attrs_pvname", "$var(attrs)")
  ...
  </programlisting>
 		</example>
 	</section>
d48d36df
  	<section id="dispatcher.p.ds_ping_method">
081b5d4e
  		<title><varname>ds_ping_method</varname> (string)</title>
  		<para>
93c65670
 		With this method you can define, with which method you want to probe the gateways.
35c2d3cd
 		Pinging gateways feature depends on ds_ping_interval parameter.
081b5d4e
  		</para>
  		<para>
  		<emphasis>
  			Default value is <quote>OPTIONS</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_ping_method</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_ping_method", "INFO")
  ...
  </programlisting>
  		</example>
74581f3a
 	</section>
d48d36df
  	<section id="dispatcher.p.ds_ping_from">
081b5d4e
  		<title><varname>ds_ping_from</varname> (string)</title>
  		<para>
74581f3a
  		With this Method you can define the "From:"-Line for the request, sent to the failed gateways.
081b5d4e
  		This method is only available, if compiled with the probing of failed gateways enabled.
  		</para>
  		<para>
  		<emphasis>
  			Default value is <quote>sip:dispatcher@localhost</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_ping_from</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_ping_from", "sip:proxy@sip.somehost.com")
  ...
  </programlisting>
  		</example>
74581f3a
 	</section>
081b5d4e
 
d48d36df
  	<section id="dispatcher.p.ds_ping_interval">
081b5d4e
  		<title><varname>ds_ping_interval</varname> (int)</title>
  		<para>
7560e490
 		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.
081b5d4e
  		This parameter is only used, when the TM-Module is loaded.
7560e490
 		If set to <quote>0</quote>, the pinging of inactive gateway is disabled.
081b5d4e
  		</para>
  		<para>
  		<emphasis>
7560e490
 			Default value is <quote>0</quote>.
081b5d4e
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_ping_interval</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_ping_interval", 30)
  ...
  </programlisting>
  		</example>
74581f3a
 	</section>
 
d48d36df
  	<section id="dispatcher.p.ds_probing_threshold">
  		<title><varname>ds_probing_threshold</varname> (int)</title>
081b5d4e
  		<para>
0b8f2ee4
 		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.
ec903da3
 		This parameter can be modified via ser config framework.
081b5d4e
  		</para>
  		<para>
  		<emphasis>
0b8f2ee4
 		Default value is <quote>1</quote> (set inactive with first failure).
081b5d4e
  		</emphasis>
  		</para>
  		<example>
1dd98c58
  		<title>Set the <quote>ds_probing_threshold</quote> parameter</title>
081b5d4e
  <programlisting format="linespecific">
  ...
1dd98c58
  modparam("dispatcher", "ds_probing_threshold", 10)
081b5d4e
  ...
  </programlisting>
  		</example>
 	</section>
cac6ea3e
 	<section id="dispatcher.p.ds_inactive_threshold">
                 <title><varname>ds_inactive_threshold</varname> (int)</title>
                 <para>
                 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.
                 </para>
                 <para>
                 <emphasis>
                 Default value is <quote>1</quote> (set active with first success).
                 </emphasis>
                 </para>
                 <example>
                 <title>Set the <quote>ds_inactive_threshold</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_inactive_threshold", 10)
  ...
  </programlisting>
                 </example>
         </section>
d48d36df
  	<section id="dispatcher.p.ds_ping_reply_codes">
ec903da3
  		<title><varname>ds_ping_reply_codes</varname> (string)</title>
  		<para>
5a5959b1
 			This parameter defines the valid response codes, which are accepted
 			as a valid reply to the PING-Method. It is a list separated by
c1c1de5b
 			colons, where you may define either a single code (e.g. "code=202"
5a5959b1
 			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.
ec903da3
  		</para>
  		<para>
a584f40b
 			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
74581f3a
 			generates a 408 in the case of no response from the remote server, and this
02482d1b
 			internal code 408 is accepted as valid value.
a584f40b
  		</para>
  		<para>
ec903da3
  		<emphasis>
  			Default value is <quote></quote> (only 200 OK is accepted).
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_ping_reply_codes</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_ping_reply_codes", "class=2;code=403;code=488;class=3")
  ...
  </programlisting>
  		</example>
74581f3a
 	</section>
d48d36df
  	<section id="dispatcher.p.ds_probing_mode">
d1de0cc5
  		<title><varname>ds_probing_mode</varname> (int)</title>
  		<para>
74581f3a
 		Controls what gateways are tested to see if they are reachable.
44e3691b
 		</para>
 
 		<itemizedlist>
 		<listitem>
 			<para>Value 0: If set to 0, only the gateways with state PROBING are tested.
14a87383
             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.</para>
44e3691b
 		</listitem>
 		<listitem>
5a5959b1
 			<para>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
14a87383
 			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.</para>
44e3691b
 		</listitem>
 		<listitem>
5a5959b1
 			<para>Value 2: if set to 2, only gateways in inactive state with
 			probing mode set are tested.</para>
44e3691b
 		</listitem>
 		<listitem>
 			<para>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.</para>
 		</listitem>
 		</itemizedlist>
 
d1de0cc5
  		<para>
  		<emphasis>
  			Default value is <quote>0</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_probing_mode</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_probing_mode", 1)
  ...
  </programlisting>
  		</example>
 	</section>
 
12a25ed7
  	<section id="dispatcher.p.ds_ping_latency_stats">
  		<title><varname>ds_ping_latency_stats</varname> (int)</title>
  		<para>
 		Enable latency measurement when pinging nodes
 		</para>
 
 		<itemizedlist>
 		<listitem>
 			<para>If set to 0, disable latency measurement.</para>
 		</listitem>
 		<listitem>
 			<para>If set to 1, enable latency measurement.
 			</para>
 		</listitem>
 		</itemizedlist>
  		<para>
  		<emphasis>
  			Default value is <quote>0</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>accessing the metrics</title>
  <programlisting format="linespecific">
 # using the command :
 kamcmd dispatcher.list
  ...
 DEST: {
 	URI: sip:1.2.3.4
 	FLAGS: AX
 	PRIORITY: 9
 	LATENCY: {
c1c1de5b
 		AVG: 24.250000 # weighted moving average for the last few weeks
12a25ed7
 		STD: 1.035000  # standard deviation of AVG
 		EST: 25.000000 # short term estimate, see parameter: ds_latency_estimator_alpha
c1c1de5b
 		MAX: 26        # maximum value seen
12a25ed7
 		TIMEOUT: 0     # count of ping timeouts
 	}
 }
  ...
  </programlisting>
  		</example>
  		<example>
  		<title>Set the <quote>ds_ping_latency_stats</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_ping_latency_stats", 1)
  ...
  </programlisting>
  		</example>
 	</section>
  	<section id="dispatcher.p.ds_latency_estimator_alpha">
  		<title><varname>ds_latency_estimator_alpha</varname> (int)</title>
 		<para>
 		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"
c1c1de5b
 		a good explanation can be found here : http://www.itl.nist.gov/div898/handbook/pmc/section3/pmc324.htm
12a25ed7
 		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.
  		</para>
  		<para>
  		<emphasis>
 			Default value is <quote>900 => 0.9</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_hash_size</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_latency_estimator_alpha", 900)
  ...
  </programlisting>
  		</example>
 	</section>
d48d36df
  	<section id="dispatcher.p.ds_hash_size">
bef7e92f
  		<title><varname>ds_hash_size</varname> (int)</title>
  		<para>
 		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).
  		</para>
  		<para>
  		<emphasis>
  			Default value is <quote>0</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_hash_size</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_hash_size", 9)
  ...
  </programlisting>
  		</example>
 	</section>
d48d36df
  	<section id="dispatcher.p.ds_hash_expire">
bef7e92f
  		<title><varname>ds_hash_expire</varname> (int)</title>
  		<para>
 		Expiration time in seconds to remove the load on a destination if no
 		BYE was received meanwhile.
  		</para>
  		<para>
  		<emphasis>
  			Default value is <quote>7200</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_hash_expire</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_hash_expire", 3600)
  ...
  </programlisting>
  		</example>
 	</section>
d48d36df
  	<section id="dispatcher.p.ds_hash_initexpires">
bef7e92f
  		<title><varname>ds_hash_initexpire</varname> (int)</title>
  		<para>
 		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().
  		</para>
  		<para>
  		<emphasis>
  			Default value is <quote>7200</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_hash_initexpire</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_hash_initexpire", 60)
  ...
  </programlisting>
  		</example>
 	</section>
d48d36df
  	<section id="dispatcher.p.ds_hash_check_interval">
bef7e92f
  		<title><varname>ds_hash_check_interval</varname> (int)</title>
  		<para>
 		Time interval in seconds to scan internal hash table with call load
 		dispatching data for expired items.
  		</para>
  		<para>
  		<emphasis>
  			Default value is <quote>30</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_hash_check_interval</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_hash_check_interval", 60)
  ...
  </programlisting>
  		</example>
 	</section>
d48d36df
  	<section id="dispatcher.p.outbound_proxy">
a201a338
  		<title><varname>outbound_proxy</varname> (str)</title>
  		<para>
 		SIP URI of outbound proxy to be used when sending pings.
  		</para>
  		<para>
  		<emphasis>
  			By default no outbound proxy is defined.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>outbound_proxy</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "outbound_proxy", "sip:outbound.example.com")
  ...
  </programlisting>
  		</example>
 	</section>
390ec435
 
aae77585
 	<section id="dispatcher.p.ds_default_socket">
 		<title><varname>ds_default_socket</varname> (str)</title>
 		<para>
536b0ab1
 			Default socket to be used for sending pings and dispatching requests
 			when a gateway has no send socket configured.
aae77585
 		</para>
 		<para>
 		<emphasis>
536b0ab1
 			By default no default socket is defined, the first configuration
 			script <emphasis>listen</emphasis> directive is used.
aae77585
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>ds_default_socket</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_default_socket", "udp:192.168.0.125:5060")
  ...
  </programlisting>
 		</example>
 	</section>
 
536b0ab1
  	<section id="dispatcher.p.ds_timer_mode">
  		<title><varname>ds_timer_mode</varname> (int)</title>
  		<para>
 			Specify the timer process to be used by the module for
74581f3a
 			keepalives and active dialogs tracking.
536b0ab1
 		</para>
 		<para>
 			It can be set to:
 		</para>
 		<itemizedlist>
 		<listitem>
 			<para>0 - use main timer process.</para>
 		</listitem>
 		<listitem>
 			<para>1 - use secondary timer process.</para>
 		</listitem>
 		</itemizedlist>
 
  		<para>
 			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.
 		</para>
 		<para>
  		<emphasis>
  			Default value is <quote>0</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_timer_mode</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_timer_mode", 1)
  ...
  </programlisting>
  		</example>
 	</section>
9b72c40a
 	<section id="dispatcher.p.event_callback">
 		<title><varname>event_callback</varname> (str)</title>
 		<para>
 			The name of the function in the kemi configuration file (embedded
 			scripting language such as Lua, Python, ...) to be executed instead
a1756010
 			of event_route[...] blocks.
 		</para>
 		<para>
 			The function receives a string parameter with the name of the event,
 			the values are: 'dispatcher:dst-down', 'dispatcher:dst-up'.
9b72c40a
 		</para>
 		<para>
 		<emphasis>
 			Default value is 'empty' (no function is executed for events).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>event_callback</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 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
 ...
 </programlisting>
 		</example>
 	</section>
536b0ab1
 
a9c89c4b
  	<section id="dispatcher.p.ds_attrs_none">
  		<title><varname>ds_attrs_none</varname> (int)</title>
  		<para>
 		If set to 1, "none=yes" is set in the attrs for those records that
422e7dbd
 		have no attrs value, to ensure that corresponding XAVP fields for
 		records do not get mixed up.
a9c89c4b
  		</para>
  		<para>
  		<emphasis>
  			Default value is <quote>0</quote>.
  		</emphasis>
  		</para>
  		<example>
  		<title>Set the <quote>ds_attrs_none</quote> parameter</title>
  <programlisting format="linespecific">
  ...
  modparam("dispatcher", "ds_attrs_none", 1)
  ...
  </programlisting>
  		</example>
 	</section>
 
4e4053ca
 	<section id="dispatcher.p.ds_db_extra_attrs">
 		<title><varname>ds_db_extra_attrs</varname> (str)</title>
 		<para>
 		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'.
 		</para>
 		<para>
 		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).
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>empty</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>ds_db_extra_attrs</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "ds_db_extra_attrs", "socket=socket;pref=prefix")
 ...
 </programlisting>
 		</example>
 	</section>
 
31ccf6a2
 	</section>
3d6ab631
 
b68fbcd1
 	<section>
9114eebc
 	<title>Functions</title>
d48d36df
 	<section id="dispatcher.f.ds_select_dst">
b68fbcd1
 		<title>
15d1022b
 		<function moreinfo="none">ds_select_dst(set, alg[, limit])</function>
31ccf6a2
 		</title>
b68fbcd1
 		<para>
78f0c33c
 		The method selects a destination from addresses set. It returns true if
f210c266
 		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.
 		</para>
 		<para>
 		If the bit 2 in 'flags' parameter is set, the rest of the addresses from
422e7dbd
 		the destination set are stored in XAVP list (limited with an optional 'limit'
15d1022b
 		parameter). You can use 'ds_next_dst()' to use next address in order to
 		achieve serial forking to all possible destinations.
cfba1f78
 		</para>
b68fbcd1
 		<para>Meaning of the parameters is as follows:</para>
 		<itemizedlist>
31ccf6a2
 		<listitem>
b68fbcd1
 			<para>
31ccf6a2
 			<emphasis>set</emphasis> - the id of the set from where to pick
 			up destination address. It is the first column in destination
f3d35135
 			list file. The parameter can be an integer or a variable holding
78f0c33c
 			an integer.
b68fbcd1
 			</para>
31ccf6a2
 		</listitem>
 		<listitem>
b68fbcd1
 			<para>
31ccf6a2
 			<emphasis>alg</emphasis> - the algorithm used to select the
f3d35135
 			destination address. The parameter can be an integer or a
c1c1de5b
 			variable holding an integer.
b68fbcd1
 			</para>
 			<itemizedlist>
31ccf6a2
 			<listitem>
b68fbcd1
 				<para>
31ccf6a2
 				<quote>0</quote> - hash over callid
b68fbcd1
 				</para>
31ccf6a2
 			</listitem>
 			<listitem>
b68fbcd1
 				<para>
93c65670
 				<quote>1</quote> - hash over from URI.
b68fbcd1
 				</para>
 			</listitem>
 			<listitem>
 				<para>
93c65670
 				<quote>2</quote> - hash over to URI.
b68fbcd1
 				</para>
31ccf6a2
 			</listitem>
 			<listitem>
b68fbcd1
 				<para>
93c65670
 				<quote>3</quote> - hash over request-URI.
b68fbcd1
 				</para>
 			</listitem>
 			<listitem>
 				<para>
a082d858
 				<quote>4</quote> - round-robin (next destination).
 				</para>
 			</listitem>
 			<listitem>
 				<para>
f3d35135
 				<quote>5</quote> - hash over authorization-username
 				(Proxy-Authorization or "normal" authorization). If no
 				username is found, round robin is used.
081b5d4e
 				</para>
 			</listitem>
 			<listitem>
 				<para>
aaf6c2bd
 				<quote>6</quote> - random destination (using rand()).
101e9af4
 				</para>
 			</listitem>
 			<listitem>
 				<para>
095ab21d
 				<quote>7</quote> - hash over the content of PVs string.
 				Note: This works only when the parameter hash_pvar is set.
 				</para>
 			</listitem>
 			<listitem>
 				<para>
aaf6c2bd
 				<quote>8</quote> - select destination sorted by priority
 				attribute value (serial forking ordered by priority).
bd1f4427
 				</para>
 			</listitem>
 			<listitem>
 				<para>
bef7e92f
 				<quote>9</quote> - use weight based load distribution. You
 				have to set the attribute 'weight' per each address in
 				destination set.
 				</para>
 			</listitem>
 			<listitem>
 				<para>
 				<quote>10</quote> - 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
422e7dbd
 				the parameter 'ds_hash_size'.
bef7e92f
 				</para>
 				<para>
 				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.
 				</para>
 				<para>
 				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.
 				</para>
 				<para>
 				This algorithm can be used only for dispatching INVITE
 				requests as it is the only SIP method creating a SIP call.
 				</para>
 			</listitem>
 			<listitem>
 				<para>
bd2feeae
 				<quote>11</quote> - use relative weight based load distribution.
 				You have to set the attribute 'rweight' per each address in
74581f3a
 				destination set. Active host usage probability is
 				rweight/(SUM of all active host rweights in destination group).
bd2feeae
 				</para>
 				<para>
 				The major difference from the weight distribution is the
74581f3a
 				probability recalculation according to rweight value in case of
bd2feeae
 				host enabling/disabling
 				</para>
 				<para>
74581f3a
 				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
bd2feeae
 				distribution will be changed to 33/67/0.
 				</para>
1d304002
 				<para>
 				Using this algorithm, you can also enable congestion control by setting the
 				attibute 'cc=1', when 'cc' is enabled the 'rweight' attribute will also be
 				used to control congestion tolerance. When facing congestion the weight of
 				a gateway is lowered by 1 for every ms of estimated congestion, a 'rweight'
 				value of 50 is recommended. See the example "configuring load balancing with
586b766a
 				congestion detection" below.
1d304002
 				</para>
 				<para>
 				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.
 				</para>
bd2feeae
 			</listitem>
 			<listitem>
 				<para>
e84ee3be
 				<quote>12</quote> - dispatch to all destination in setid at
422e7dbd
 				once (parallel forking). Note that the XAVPs are no longer set
e84ee3be
 				with the values of the destination records, no re-routing
 				making sense in this case.
 				</para>
 			</listitem>
 			<listitem>
 				<para>
31ccf6a2
 				<quote>X</quote> - if the algorithm is not implemented, the
 				first entry in set is chosen.
b68fbcd1
 				</para>
31ccf6a2
 			</listitem>
b68fbcd1
 			</itemizedlist>
31ccf6a2
 		</listitem>
15d1022b
 		<listitem>
 			<para>
 			<emphasis>limit</emphasis> - the maximum number of items to be
422e7dbd
 			stored in XAVP list for further fail-overs (the first selected
15d1022b
 			destination and default destination are the first to be put in
 			the list)
7bda0ce9
 			</para>
 		</listitem>
b68fbcd1
 		</itemizedlist>
7b56ffd7
 		<para>
54723bfd
 		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
7b56ffd7
 		</para>
b68fbcd1
 		<example>
31ccf6a2
 		<title><function>ds_select_dst</function> usage</title>
 		<programlisting format="linespecific">
 ...
 ds_select_dst("1", "0");
 ...
f3d35135
 $var(a) = 4;
 ds_select_dst("1", "$var(a)");
 ...
15d1022b
 ds_select_dst("1", "4", "3");
 ...
31ccf6a2
 </programlisting>
b68fbcd1
 		</example>
1d304002
 		<example>
 		<title>configuring load balancing with congestion detection</title>
 		<programlisting format="linespecific">
 ...
 # sample of SQL provisionning statements
 INSERT INTO "dispatcher" 
 VALUES(1,1,'sip:192.168.0.1:5060',0,12,'rweight=50;weight=50;cc=1;','');
 INSERT INTO "dispatcher" 
 VALUES(2,1,'sip:192.168.0.2:5060',0,12,'rweight=50;weight=50;cc=1;','');
 ...
 modparam("dispatcher", "ds_ping_interval", 1) # ping gateways once/second
 modparam("dispatcher", "ds_ping_latency_stats", 1) # update congestion metrics
 # configure the latency estimator
 modparam("dispatcher", "ds_latency_estimator_alpha", 900)
 ...
 if (!ds_select_dst("1", "11")) { # use relative weight based load distribution
 ...
 # sample of output from 'kamcmd dispatcher.list'
 DEST: {
 	URI: sip:192.168.0.1:5060
 	FLAGS: AP
 	PRIORITY: 12
 	ATTRS: {
 		BODY: rweight=50;weight=50;cc=1 # configuration values
 		DUID: 
 		MAXLOAD: 0
 		WEIGHT: 50
 		RWEIGHT: 50
 		SOCKET: 
 	}
 	LATENCY: {
 		AVG: 20.104000
 		STD: 1.273000
 		# estimated congestion is currently 25ms = 45ms(EST) -20ms(AVG)
 		EST: 45.005000
 		MAX: 132
 		TIMEOUT: 3
 	}
 }
 ...
 </programlisting>
 		</example>
b68fbcd1
 	</section>
d48d36df
   	<section id="dispatcher.f.ds_select_domain">
3d6ab631
  		<title>
15d1022b
  		<function moreinfo="none">ds_select_domain(set, alg[, limit])</function>
44f3472f
  		</title>
3d6ab631
  		<para>
f210c266
  		The method selects a destination from addresses set and rewrites the
44f3472f
  		host and port from R-URI. The parameters have same meaning as for
  		ds_select_dst().
cfba1f78
  		</para>
7b56ffd7
 		<para>
a4ba0359
 		If the bit 2 in 'flags' is set, the rest of the addresses from the
422e7dbd
 		destination set are stored in XAVP list (limited with an optional 'limit'
e93bb3db
 		parameter). You can use 'ds_next_domain()' to use next address to
15d1022b
 		achieve serial forking to all possible destinations.
a4ba0359
 		</para>
 		<para>
54723bfd
 		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
7b56ffd7
 		</para>
e93bb3db
 		<example>
 		<title><function>ds_select_domain</function> usage</title>
 		<programlisting format="linespecific">
 ...
 $var(a) = 4;
 if(ds_select_domain("1", "$var(a)")) {
     t_relay();
     exit;
 }
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="dispatcher.f.ds_select">
 		<title>
 		<function moreinfo="none">ds_select(set, alg [, limit])</function>
 		</title>
 		<para>
 		The method selects a destination from addresses set and adds it
422e7dbd
 		in the XAVP specified for this module. It is not updating R-URI
e93bb3db
 		nor the destination URI. The parameters have same
 		meaning as for ds_select_dst().
 		</para>
 		<para>
 		If the bit 2 in 'flags' is set, the rest of the addresses from the
422e7dbd
 		destination set are stored in XAVP list (limited with an optional 'limit'
e93bb3db
 		parameter). You can execute 'ds_next_domain()' or 'ds_next_dst()' to use
 		next address to achieve serial forking to all possible destinations.
 		</para>
 		<para>
 		This function can be used from ANY_ROUTE.
 		</para>
 		<example>
 		<title><function>ds_select</function> usage</title>
 		<programlisting format="linespecific">
 ...
 $var(a) = 4;
 if(ds_select("1", "$var(a)")) {
     ds_next_domain();
     t_relay();
     exit;
 }
 ...
 </programlisting>
 		</example>
 	</section>
8446409d
 	<section id="dispatcher.f.ds_select_routes">
 		<title>
 		<function moreinfo="none">ds_select_routes(rules, mode [, limit])</function>
 		</title>
 		<para>
 		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.
 		</para>
 		<para>Parameters:</para>
 		<itemizedlist>
 		<listitem>
 			<para><emphasis>rules</emphasis> - 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.
 			</para>
 		</listitem>
 		<listitem>
 			<para><emphasis>mode</emphasis> - 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 once case use a more meaningful value
 			such as 'ruri' instead of 'r'. The parameter can contain pseudo
 			variables.
 			</para>
 		</listitem>
 		<listitem>
 			<para><emphasis>limit</emphasis> - 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.
 			</para>
 		</listitem>
3c410368
 		</itemizedlist>
8446409d
 		<para>
 		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.
 		</para>
 		<para>
 		This function can be used from ANY_ROUTE.
 		</para>
 		<example>
 		<title><function>ds_select_routes</function> usage</title>
 		<programlisting format="linespecific">
 ...
 $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;
         }
     }
 }
 ...
 </programlisting>
 		</example>
 	</section>
e93bb3db
 	<section>
 		<title>
 		<function moreinfo="none">ds_next_dst()</function>
 		</title>
 		<para>
422e7dbd
 		Takes the next destination address from the corresponding XAVPs
a4ba0359
 		and sets the dst_uri (outbound proxy address).
  		</para>
 		<para>
54723bfd
 		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
a4ba0359
 		</para>
  	</section>
   	<section>
  		<title>
  		<function moreinfo="none">ds_next_domain()</function>
  		</title>
  		<para>
422e7dbd
  		Takes the next destination address from the corresponding XAVPs
93c65670
 		and sets the domain part of the request URI.
a4ba0359
  		</para>
 		<para>
54723bfd
 		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
a4ba0359
 		</para>
  	</section>
540450a2
 	<section id="dispatcher.f.ds_set_dst">
 		<title>
 		<function moreinfo="none">ds_set_dst()</function>
 		</title>
 		<para>
 		Takes the current destination address from the corresponding XAVPs
 		and sets the dst_uri (outbound proxy address).
  		</para>
 		<para>
 		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 		</para>
  	</section>
   	<section id="dispatcher.f.ds_set_domain">
  		<title>
  		<function moreinfo="none">ds_set_domain()</function>
  		</title>
  		<para>
  		Takes the current destination address from the corresponding XAVPs
 		and sets the domain part of the request URI.
  		</para>
 		<para>
 		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
 		</para>
  	</section>
d48d36df
   	<section id="dispatcher.f.ds_mark_dst">
a4ba0359
  		<title>
9056b574
  		<function moreinfo="none">ds_mark_dst([state])</function>
081b5d4e
  		</title>
  		<para>
bef7e92f
 		Mark the last used address from destination set as inactive
372b113b
 		("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
bef7e92f
 		'ds_select_domain'.
081b5d4e
  		</para>
9056b574
  		<para>
 		The parameter state is optional, when it is missing, then
 		the destination will be marked inactive (i.e., same as 'i').
  		</para>
 		<para>Possible values for state parameter:</para>
081b5d4e
 		<itemizedlist>
 		<listitem>
372b113b
 			<para><emphasis>"a" or "A"</emphasis> - the last destination
 				should be set to active and the error-counter should set to "0".
 			</para>
 		</listitem>
 		<listitem>
 			<para><emphasis>"i" or "I"</emphasis> - the last destination
bef7e92f
 				should be set to inactive and will be ignored in future
 				requests.</para>
081b5d4e
 		</listitem>
 		<listitem>
372b113b
 			<para><emphasis>"t" or "T"</emphasis> - 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.
 			</para>
081b5d4e
 		</listitem>
 		<listitem>
372b113b
 			<para><emphasis>"p" and "P"</emphasis> - this has to be used in
 				addition to one of the previous flags - the last destination
9056b574
 				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
72f28fdc
 				up or down.</para>
081b5d4e
 		</listitem>
 		</itemizedlist>
 		<para>
54723bfd
 		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
081b5d4e
 		</para>
9056b574
 		<example>
 		<title><function>ds_mark_dst</function> usage</title>
 		<programlisting format="linespecific">
 ...
 failure_route[tryagain] {
 ...
    if(t_check_status("500"))
372b113b
       ds_mark_dst("ip"); # set to inactive and probing
9056b574
 ...
 }
 ...
 </programlisting>
 		</example>
081b5d4e
  	</section>
b02480d4
   	<section  id="dispatcher.f.ds_list_exists">
bef88a0d
  		<title>
b02480d4
 		<function moreinfo="none">ds_list_exists(groupid)</function>
bef88a0d
  		</title>
  		<para>
b02480d4
 		Function alias: ds_list_exist(groupid)
  		</para>
  		<para>
bef88a0d
 		Check if a specific group is defined in dispatcher list
 		or database.
 		</para>
 		<itemizedlist>
 		<listitem>
 			<para><emphasis>groupid</emphasis> - A group ID to check.
 			</para>
 		</listitem>
 		</itemizedlist>
 		<para>
 			This function can be used from ANY_ROUTE.
 		</para>
 		<example>
b02480d4
 		<title><function>ds_list_exists</function> usage</title>
bef88a0d
 		<programlisting format="linespecific">
 ...
b02480d4
 if(ds_list_exists("10")) {
bef88a0d
     ...
 }
 ...
 </programlisting>
 	</example>
 	</section>
d48d36df
   	<section  id="dispatcher.f.ds_is_from_list">
081b5d4e
  		<title>
121cb0f4
 		<function moreinfo="none">ds_is_from_list([groupid [, mode [, uri] ] ])</function>
081b5d4e
  		</title>
  		<para>
37e1fb44
 		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.
 		</para>
 		<para>Description of parameters:</para>
 		<itemizedlist>
 		<listitem>
 			<para><emphasis>groupid</emphasis> (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.
 			</para>
 		</listitem>
 		<listitem>
 			<para><emphasis>mode</emphasis> - (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.
 			</para>
 		</listitem>
121cb0f4
         <listitem>
             <para><emphasis>uri</emphasis> (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.
             </para>
         </listitem>
37e1fb44
 		</itemizedlist>
 
 		<para>
 		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'.
bef7e92f
  		</para>
 		<para>
37e1fb44
 		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).
9056b574
  		</para>
 		<para>
 			This function can be used from ANY_ROUTE.
bef7e92f
 		</para>
9056b574
 		<example>
a412047b
 		<title><function>ds_is_from_list</function> usage</title>
9056b574
 		<programlisting format="linespecific">
 ...
37e1fb44
 if(ds_is_from_list()) {
     ...
 }
9056b574
 if(ds_is_from_list("10")) {
     ...
 }
a412047b
 if(ds_is_from_list("10", "3")) {
     ...
 }
 if(ds_is_from_list("10", "3", "sip:127.0.0.1:5080")) {
37e1fb44
     ...
 }
9056b574
 ...
 </programlisting>
 		</example>
bef7e92f
  	</section>
d48d36df
   	<section id="dispatcher.f.ds_load_update">
bef7e92f
  		<title>
  		<function moreinfo="none">ds_load_update()</function>
  		</title>
  		<para>
 		Updates the load state:
081b5d4e
  		</para>
bef7e92f
 		<itemizedlist>
 		<listitem>
 			<para>if it is a BYE or CANCEL - remove the load from
 			destination address used to forward the INVITE</para>
 		</listitem>
 		<listitem>
 			<para>if it is a reply to INVITE - set internal state
 				to confirmed for call load structure when reply code is
 				2xx.</para>
 		</listitem>
 		</itemizedlist>
081b5d4e
 		<para>
bef7e92f
 			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
 			BRANCH_ROUTE and ONREPLY_ROUTE.
081b5d4e
 		</para>
  	</section>
bef7e92f
   	<section>
  		<title>
  		<function moreinfo="none">ds_load_unset()</function>
  		</title>
  		<para>
 		Remove the call load for the destination that routed the call.
  		</para>
 		<para>
 			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
 			BRANCH_ROUTE and ONREPLY_ROUTE.
 		</para>
 		<example>
 		<title><function>ds_load_unset</function> usage</title>
 		<programlisting format="linespecific">
 ...
 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();
     }
     ...
 }
 ...
 </programlisting>
 		</example>
  	</section>
1f54ffa3
 	<section id="dispatcher.f.ds_reload">
7cf474fd
 		<title>
 		<function moreinfo="none">ds_reload()</function>
 		</title>
 		<para>
7287da30
 		Reloads the groups and included destinations.
7cf474fd
 		</para>
 		<para>
 		Name: <emphasis>ds_reload</emphasis>
 		</para>
 		<para>Parameters: <emphasis>none</emphasis></para>
7287da30
 		<para>
 		This function can be used from ANY_ROUTE.
 		</para>
31ccf6a2
 	</section>
8c4d2ca3
 	</section>
e5495f50
 
 	<section>
45eae146
 	<title>RPC Commands</title>
5a5959b1
 	<section id="dispatcher.r.set_state">
3979c562
 		<title>
 		<function moreinfo="none">dispatcher.set_state</function>
 		</title>
 		<para>
 		Sets the state for a destination address (can be use to mark the destination
 		as active or inactive).
 		</para>
 		<para>
 		Name: <emphasis>dispatcher.set_state</emphasis>
 		</para>
 		<para>Parameters:</para>
 		<itemizedlist>
 			<listitem><para>_state_ : state of the destination address</para>
 			      <itemizedlist>
 	                 <listitem><para> <quote>a</quote>: active</para></listitem>
 			         <listitem><para> <quote>i</quote>: inactive</para></listitem>
372b113b
 			         <listitem><para> <quote>t</quote>: trying</para></listitem>
3979c562
 			         <listitem><para> <quote>d</quote>: disabled</para></listitem>
 				  </itemizedlist>
372b113b
 				  <para>The states <quote>a</quote>, <quote>i</quote> or
 					  <quote>t</quote> can be followed by <quote>p</quote>
 					  to set probing mode (e.g. 'ap', 'ip' or 'tp').</para>
3979c562
 			</listitem>
 
 			<listitem><para>_group_: destination group id</para></listitem>
 
d4003b91
 			<listitem><para>_address_: address of the destination in the _group_
 					or 'all' to update all destinations in the group</para></listitem>
3979c562
 		</itemizedlist>
 		<para>
 		Example:
 		</para>
372b113b
 <programlisting  format="linespecific">
 ...
922e7f4a
 # prototype: &sercmd; dispatcher.set_state _state_ _group_ _address_
 &sercmd; dispatcher.set_state ip 2 sip:127.0.0.1:5080
d4003b91
 &sercmd; dispatcher.set_state ip 3 all
372b113b
 ...
 </programlisting>
3979c562
     </section>
5a5959b1
 	<section id="dispatcher.r.list">
3979c562
 		<title>
 		<function moreinfo="none">dispatcher.list</function>
 		</title>
 		<para>
93c65670
 		Lists the groups and included destinations.
3979c562
 		</para>
 		<para>
 		Name: <emphasis>dispatcher.list</emphasis>
 		</para>
 		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
 		Example:
 		</para>
         <programlisting  format="linespecific">
922e7f4a
 		&sercmd; dispatcher.list
14a87383
  ...
 DEST: {
         URI: sip:192.168.0.1:5060
         FLAGS: AP
         PRIORITY: 12
 }
  ...
 </programlisting>
14b4d23a
 		<para>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.
 		</para>
 	</section>
5a5959b1
 	<section id="dispatcher.r.reload">
3979c562
 		<title>
 		<function moreinfo="none">dispatcher.reload</function>
 		</title>
 		<para>
93c65670
 		Reloads the groups and included destinations. The command is
3979c562
 		disabled for call load based dispatching (algorithm 10) since
 		removal of destinations may leave the list of active
 		calls with broken references.
 		</para>
 		<para>
 		Name: <emphasis>dispatcher.reload</emphasis>
 		</para>
 		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
 		Example
 		</para>
         <programlisting  format="linespecific">
922e7f4a
 		&sercmd; dispatcher.reload
3979c562
 		</programlisting>
     </section>
 
5a5959b1
 	<section id="dispatcher.r.ping_active">
95aad518
 		<title>
 		<function moreinfo="none">dispatcher.ping_active</function>
 		</title>
 		<para>
 		Sets the global state for sending keepalive requests to destinations.
 		</para>
 		<para>
 		Name: <emphasis>dispatcher.ping_active</emphasis>
 		</para>
 		<para>Parameters:</para>
 		<itemizedlist>
 			<listitem><para>_state_ : state of sending keepalives</para>
 			    <itemizedlist>
 	               <listitem><para> <quote>0</quote>: inactive (don't send)</para></listitem>
 			       <listitem><para> <quote>1</quote>: active (send)</para></listitem>
 				</itemizedlist>
 			</listitem>
 		</itemizedlist>
 		<para>
 			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.
 		</para>
 		<para>
 		Example:
 		</para>
 <programlisting  format="linespecific">
 ...
 # prototype: &kamcmd; dispatcher.ping_active _state_
 &kamcmd; dispatcher.ping_active 0
 ...
 </programlisting>
     </section>
 
3979c562
    </section>
 
fa54c699
 	<section id="dispatcher.ex.install">
cfba1f78
 	<title>Installation and Running</title>
31ccf6a2
 	<section>
b68fbcd1
 		<title>Destination List File</title>
 		<para>
31ccf6a2
 		Each destination point must be on one line. First token is the set
45989d3c
 		id (an integer value, also referenced by group id), followed by
 		destination address (string value in full SIP URI format).
bef7e92f
 		</para>
 		<para>
 		Optionally, these fields can be followed by:
 		</para>
 		<itemizedlist>
 			<listitem>
f073f72a
 			<para>flags - control the mode of using the destination address and
 			sending keepalives. It is a bitwise value that can be built using
 			the folowing flags:
 			<itemizedlist>
ba31f4ec
 				<listitem><para>1 (bit at index 0 - 1 &lt;&lt;0) - inactive destination</para>
f073f72a
 				</listitem>
 				<listitem><para>2 (bit at index 1 - 1 &lt;&lt;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
ba31f4ec
 				failures)</para>
f073f72a
 				</listitem>
ba31f4ec
 				<listitem><para>4 (bit at index 2 - 1 &lt;&lt;2) - admin disabled destination</para>
f073f72a
 				</listitem>
 				<listitem><para>8 (bit at index 3 - 1 &lt;&lt;3) - probing destination (sending keep alives);</para>
 				</listitem>
ba31f4ec
 				<listitem><para>16 (bit at index 4 - 1 &lt;&lt;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(...).</para>
 				</listitem>
f073f72a
 			</itemizedlist>
 			</para>
bef7e92f
 			</listitem>
 			<listitem>
 			<para>priority: sets the priority in destination list (based on it
 			is done the initial ordering inside the set)</para>
 			</listitem>
 			<listitem>
aae77585
 			<para>attributes: extra fields in form of
610a93ea
 				name1=value1;...;nameN=valueN.
aae77585
 			</para>
bef7e92f
 			</listitem>
 		</itemizedlist>
610a93ea
 		<section id="dispatcher.ex.attributes">
 			<title>Special Attributes</title>
 			<para>
 			There are some predefined names:
 			<itemizedlist>
 				<listitem>
 					'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.
 				</listitem>
 				<listitem>
 					'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.
 				</listitem>
 				<listitem>
 					'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.
 				</listitem>
 				<listitem>
74581f3a
 					'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).
bd2feeae
 				</listitem>
 				<listitem>
610a93ea
 					'socket' - used to set the sending socket for the gateway.
 					It is used for sending the SIP traffic as well as
 					OPTIONS keepalives.
 				</listitem>
3f9c38be
 				<listitem>
 					'ping_from' - used to set the From URI in OPTIONS keepalives.
 					It overwrites the general ds_ping_from parameter.
 				</listitem>
610a93ea
 			</itemizedlist>
 		</para>
 		</section>
 		<section id="dispatcher.ex.fileforma">
 			<title>File Format</title>
bef7e92f
 		<para>
 		Line format is:
 		</para>
 		<programlisting format="linespecific">
 ...
 setid(int) destination(sip uri) flags(int,opt) priority(int,opt) attrs(str,opt)
 ...
 </programlisting>
 
 		<para>
 		Full line example:
 		</para>
 		<programlisting format="linespecific">
 ...
3f9c38be
 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
bef7e92f
 ...
 </programlisting>
 
 		<para>
 		For database, each element of a line resides in a different column.
 		Next is a dispatcher.list file example:
31ccf6a2
 		</para>
b68fbcd1
 		<example>
31ccf6a2
 		<title>dispatcher list file</title>
 		<programlisting format="linespecific">
 ...
33d03d8d
 <xi:include href="dispatcher.list" parse="text"/>
31ccf6a2
 ...
 </programlisting>
 		</example>
b68fbcd1
 		</section>
610a93ea
 		</section>
74581f3a
 
fa54c699
 		<section id="dispatcher.ex.config">
a118a328
 		<title>&kamailio; config file</title>
b68fbcd1
 		<para>
74581f3a
 		Next listing shows a sample config for using the dispatcher module.
b68fbcd1
 		</para>
 		<example>
a118a328
 		<title>&kamailio; config script - sample dispatcher usage</title>
31ccf6a2
 		<programlisting format="linespecific">
 ...
33d03d8d
 <xi:include href="dispatcher.cfg" parse="text"/>
31ccf6a2
 ...
 		</programlisting>
b68fbcd1
 		</example>
 	</section>
31ccf6a2
 	</section>
390ec435
 
fa54c699
         <section id="dispatcher.ex.event_routes">
390ec435
         <title>Event routes</title>
         <section>
                 <title>
                 <function moreinfo="none">dispatcher:dst-down</function>
                 </title>
                 <para>
 			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.
                 </para>
         <programlisting  format="linespecific">
 ...
 event_route[dispatcher:dst-down] {
     xlog("L_ERR", "Destination down: $rm $ru ($du)\n");
 }
 ...
                 </programlisting>
 	</section>
         <section>
                 <title>
                 <function moreinfo="none">dispatcher:dst-up</function>
                 </title>
                 <para>
 			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.
                 </para>
         <programlisting  format="linespecific">
 ...
 event_route[dispatcher:dst-up] {
     xlog("L_ERR", "Destination up: $rm $ru\n");
 }
 ...
                 </programlisting>
     </section>
     </section>
 
31ccf6a2
 </chapter>