<?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" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
%docentities;

]>
<!-- Module User's Guide -->

<chapter xmlns:xi="http://www.w3.org/2001/XInclude">

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		This module offers SIP load balancer functionality and it can be
		used as SIP traffic dispatcher. There are many load balancing and
		traffic dispaching algorithms that you can choose from, for example:
		round-robin, weight based load balancing, call load distribution,
		and hashing over SIP message attributes.
	</para>
	<para>
		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.
	</para>
	<para>
		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.
	</para>
	</section>
	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<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>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External libraries or applications</title>
		<para>
		The following libraries or applications must be installed before
		running &kamailio; with this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>

	<section>
	<title>Parameters</title>
	<section id="dispatcher.p.list_file">
		<title><varname>list_file</varname> (string)</title>
		<para>
		Path to the file with destination sets (destination groups).
		</para>
		<para>
		<emphasis>
			Default value is <quote>/etc/kamailio/dispatcher.list</quote> or
			<quote>/usr/local/etc/kamailio/dispatcher.list</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set the <quote>list_file</quote> parameter</title>
		<programlisting format="linespecific">
...
modparam("dispatcher", "list_file", "/var/run/kamailio/dispatcher.list")
...
</programlisting>
		</example>
	</section>

	<section id="dispatcher.p.db_url">
 		<title><varname>db_url</varname> (string)</title>
 		<para>
		If you want to load the list of gateways from the database you must set
		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">
...
modparam("dispatcher", "db_url", "mysql://user:passwb@localhost/database")
...
</programlisting>
		</example>
	</section>

	<section id="dispatcher.p.table_name">
		<title><varname>table_name</varname> (string)</title>
		<para>
		If you want to load the list of gateways from the database you must set
		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>

	<section id="dispatcher.p.setid_col">
		<title><varname>setid_col</varname> (string)</title>
		<para>
			The column's name in the database storing the gateway's set (group)
			id.
		</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>

	<section id="dispatcher.p.destination_col">
		<title><varname>destination_col</varname> (string)</title>
		<para>
			The column's name in the database storing the destination
			sip URI.
		</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>

	<section id="dispatcher.p.flags_col">
		<title><varname>flags_col</varname> (string)</title>
		<para>
			The column's name in the database storing the flags for
			the destination URI.
		</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>

	<section id="dispatcher.p.priority_col">
		<title><varname>priority_col</varname> (string)</title>
		<para>
			The column's name in the database storing the priority for
			destination URI.
		</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>

	<section id="dispatcher.p.force_dst">
		<title><varname>force_dst</varname> (int)</title>
		<para>
		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.
		</para>
		<para>
		<emphasis>
			Default value is <quote>1</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set the <quote>force_dst</quote> parameter</title>
<programlisting format="linespecific">
...
modparam("dispatcher", "force_dst", 1)
...
</programlisting>
		</example>
	</section>
 	<section id="dispatcher.p.flags">
 		<title><varname>flags</varname> (int)</title>
 		<para>
 		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).
 		</para>
 		<para>
		If flag 2 is set, then failover support is enabled. The functions
		exported by the module will store the rest of addresses from the
		destination set in the AVP, and use these AVPs to contact next address if
		the current-tried destination fails.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>0</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>flags</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "flags", 3)
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="dispatcher.p.use_default">
 		<title><varname>use_default</varname> (int)</title>
 		<para>
 		If the parameter is set to 1, the last address in destination set
		is used as a final option to send the request to. For example, it is useful
		when wanting to send the call to an anouncement server saying:
		"the gateways are full, try later".
 		</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>
 	<section id="dispatcher.p.dst_avp">
 		<title><varname>dst_avp</varname> (str)</title>
 		<para>
 		The name of the avp which will hold the list with addresses, in the
		order
		they have been selected by the chosen algorithm. If use_default is 1,
		the value of last dst_avp_id is the last address in destination set. The
		first dst_avp_id is the selected destinations. All the other addresses
		from the destination set will be added in the avp list to be able to
		implement serial forking.
 		</para>
		<note>
 		<para>
		You must set this parameter if you want to do load balancing fail over.
 		</para>
		</note>
 		<para>
 		<emphasis>
 			Default value is <quote>null</quote> - don't add AVPs.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>dst_avp</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "dst_avp", "$avp(dsdst)")
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="dispatcher.p.grp_avp">
 		<title><varname>grp_avp</varname> (str)</title>
 		<para>
 		The name of the avp storing the group id of the destination set. Good
		to have it for later usage or checks.
 		</para>
		<note>
 		<para>
		You must set this parameter if you want to do load balancing fail over.
 		</para>
		</note>
 		<para>
 		<emphasis>
 			Default value is <quote>null</quote> - don't add AVP.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>grp_avp</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "grp_avp", "$avp(dsgrp)")
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="dispatcher.p.cnt_avp">
 		<title><varname>cnt_avp</varname> (str)</title>
 		<para>
 		The name of the avp storing the number of destination addresses kept in
		dst_avp AVPs.
 		</para>
		<note>
 		<para>
		You must set this parameter if you want to do load balancing fail over.
 		</para>
		</note>
 		<para>
 		<emphasis>
 			Default value is <quote>null</quote> - don't add AVP.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>cnt_avp</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "cnt_avp", "$avp(dscnt)")
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="dispatcher.p.dstid_avp">
 		<title><varname>dstid_avp</varname> (str)</title>
 		<para>
		The name of the avp storing the destination unique ID used for
		call load based dispatching.
 		</para>
		<note>
 		<para>
		You must set this parameter if you want to do load balancing on
		call load (alg 10).
 		</para>
		</note>
 		<para>
 		<emphasis>
 			Default value is <quote>null</quote> - don't add AVP.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>dstid_avp</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "dstid_avp", "$avp(dsdstid)")
 ...
 </programlisting>
 		</example>
 	</section>
 	<section id="dispatcher.p.attrs_avp">
 		<title><varname>attrs_avp</varname> (str)</title>
 		<para>
		The name of the avp storing destination's attributes value.
 		</para>
		<note>
		</note>
 		<para>
 		<emphasis>
 			Default value is <quote>null</quote> - don't add AVP.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>attrs_avp</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "attrs_avp", "$avp(dsattrs)")
 ...
 </programlisting>
 		</example>
 	</section>
	<section id="dispatcher.p.sock_avp">
		<title><varname>sock_avp</varname> (str)</title>
		<para>
			The name of the avp which will hold the list with the sockets associated to the addresses stored in dst_avp avp.
		</para>
		<note>
		<para>
			If you want to do load balancing fail over, you have to set this parameter to use the correct socket for each gateway.
		</para>
		</note>
		<para>
		<emphasis>
			Default value is <quote>null</quote> - don't add AVPs.
		</emphasis>
		</para>
		<example>
		<title>Set the <quote>sock_avp</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "sock_avp", "$avp(dssocket)")
 ...
 </programlisting>
		</example>
	</section>
 	<section id="dispatcher.p.hash_pvar">
 		<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>
 		<title>Use $avp(i:273) for hashing:</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "hash_pvar", "$avp(i:273)")
 ...
 </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>
 	<section id="dispatcher.p.setid_pvname">
 		<title><varname>setid_pvname</varname> (str)</title>
 		<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>
 		<title>Set the <quote>setid_pvname</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "setid_pvname", "$var(setid)")
 ...
 </programlisting>
 		</example>
	</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>
 	<section id="dispatcher.p.ds_ping_method">
 		<title><varname>ds_ping_method</varname> (string)</title>
 		<para>
		With this method you can define, with which method you want to probe the gateways.
		Pinging gateways feature depends on ds_ping_interval parameter.
 		</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>
	</section>
 	<section id="dispatcher.p.ds_ping_from">
 		<title><varname>ds_ping_from</varname> (string)</title>
 		<para>
 		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.
 		</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>
	</section>

 	<section id="dispatcher.p.ds_ping_interval">
 		<title><varname>ds_ping_interval</varname> (int)</title>
 		<para>
		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 <quote>0</quote>, the pinging of inactive gateway is disabled.
 		</para>
 		<para>
 		<emphasis>
			Default value is <quote>0</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>ds_ping_interval</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "ds_ping_interval", 30)
 ...
 </programlisting>
 		</example>
	</section>

 	<section id="dispatcher.p.ds_probing_threshold">
 		<title><varname>ds_probing_threshold</varname> (int)</title>
 		<para>
		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.
 		</para>
 		<para>
 		<emphasis>
		Default value is <quote>1</quote> (set inactive with first failure).
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>ds_probing_threshold</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "ds_probing_threshold", 10)
 ...
 </programlisting>
 		</example>
	</section>
	<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>
 	<section id="dispatcher.p.ds_ping_reply_codes">
 		<title><varname>ds_ping_reply_codes</varname> (string)</title>
 		<para>
		This parameter defines the valid response codes, which are accepted as a valid reply to the PING-Method.
		It is a list separated by colons, whery you may define either a single code (e.g. "code=202" would accept 202 as an additional, valid response) or a class of responses, you want to accept (e.g. "class=2" would accept everything from 200 to 299 as valid response).
		This parameter can be modified via ser config framework.
 		</para>
 		<para>
			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.
 		</para>
 		<para>
 		<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>
	</section>
 	<section id="dispatcher.p.ds_probing_mode">
 		<title><varname>ds_probing_mode</varname> (int)</title>
 		<para>
		Controls what gateways are tested to see if they are reachable.
		</para>

		<itemizedlist>
		<listitem>
			<para>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.</para>
		</listitem>
		<listitem>
			<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 set to TRYING state.</para>
		</listitem>
		<listitem>
			<para>Value 2: if set to 2, only gateways in inactive state with probing mode set are tested.</para>
		</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>

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

 	<section id="dispatcher.p.ds_hash_size">
 		<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>
 	<section id="dispatcher.p.ds_hash_expire">
 		<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>
 	<section id="dispatcher.p.ds_hash_initexpires">
 		<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>
 	<section id="dispatcher.p.ds_hash_check_interval">
 		<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>
 	<section id="dispatcher.p.outbound_proxy">
 		<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>

	<section id="dispatcher.p.ds_default_socket">
		<title><varname>ds_default_socket</varname> (str)</title>
		<para>
			Default socket to be used for sending pings and dispatching requests
			when a gateway has no send socket configured.
		</para>
		<para>
		<emphasis>
			By default no default socket is defined, the first configuration
			script <emphasis>listen</emphasis> directive is used.
		</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>

 	<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
			keepalives and active dialogs tracking.
		</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>

	</section>

	<section>
	<title>Functions</title>
	<section id="dispatcher.f.ds_select_dst">
		<title>
		<function moreinfo="none">ds_select_dst(set, alg[, limit])</function>
		</title>
		<para>
		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.
		</para>
		<para>
		If the bit 2 in 'flags' parameter is set, the rest of the addresses from
		the destination set is stored in AVP list (limited with an optional 'limit'
		parameter). You can use 'ds_next_dst()' to use next address in order to
		achieve serial forking to all possible destinations.
		</para>
		<para>Meaning of the parameters is as follows:</para>
		<itemizedlist>
		<listitem>
			<para>
			<emphasis>set</emphasis> - 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.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>alg</emphasis> - the algorithm used to select the
			destination address. The parameter can be an integer or a
			variable holding an interger.
			</para>
			<itemizedlist>
			<listitem>
				<para>
				<quote>0</quote> - hash over callid
				</para>
			</listitem>
			<listitem>
				<para>
				<quote>1</quote> - hash over from URI.
				</para>
			</listitem>
			<listitem>
				<para>
				<quote>2</quote> - hash over to URI.
				</para>
			</listitem>
			<listitem>
				<para>
				<quote>3</quote> - hash over request-URI.
				</para>
			</listitem>
			<listitem>
				<para>
				<quote>4</quote> - round-robin (next destination).
				</para>
			</listitem>
			<listitem>
				<para>
				<quote>5</quote> - hash over authorization-username
				(Proxy-Authorization or "normal" authorization). If no
				username is found, round robin is used.
				</para>
			</listitem>
			<listitem>
				<para>
				<quote>6</quote> - random destination (using rand()).
				</para>
			</listitem>
			<listitem>
				<para>
				<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>
				<quote>8</quote> - select destination sorted by priority
				attribute value (serial forking ordered by priority).
				</para>
			</listitem>
			<listitem>
				<para>
				<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
				parameters 'dstid_avp' and 'ds_hash_size'.
				</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>
				<quote>11</quote> - 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).
				</para>
				<para>
				The major difference from the weight distribution is the
				probability recalculation according to rweight value in case of
				host enabling/disabling
				</para>
				<para>
				For example, 100 calls in 3-hosts group with rweight params 1/2/1
				will be distributed as 25/50/25. After third host failing
				distribution will be changed to 33/67/0.
				</para>
			</listitem>
			<listitem>
				<para>
				<quote>X</quote> - if the algorithm is not implemented, the
				first entry in set is chosen.
				</para>
			</listitem>
			</itemizedlist>
		</listitem>
		<listitem>
			<para>
			<emphasis>limit</emphasis> - the maximum number of items to be
			stored in AVP list for further failovers (the first selected
			destination and default destination are the first to be put in
			the list)
                        </para>
                </listitem>
		</itemizedlist>
		<para>
		If the bit 2 in 'flags' is set, the rest of the addresses from the
		destination set is stored in AVP list. You can use 'ds_next_dst()' to
		use next address to achieve serial forking to all possible
		destinations.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>ds_select_dst</function> usage</title>
		<programlisting format="linespecific">
...
ds_select_dst("1", "0");
...
$var(a) = 4;
ds_select_dst("1", "$var(a)");
...
ds_select_dst("1", "4", "3");
...
</programlisting>
		</example>
	</section>
  	<section id="dispatcher.f.ds_select_domain">
 		<title>
 		<function moreinfo="none">ds_select_domain(set, alg[, limit])</function>
 		</title>
 		<para>
 		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().
 		</para>
		<para>
		If the bit 2 in 'flags' is set, the rest of the addresses from the
		destination set is stored in AVP list (limited with an optional 'limit'
                parameter). You can use 'ds_next_domain()' to use next address to
		achieve serial forking to all possible destinations.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
 	</section>
  	<section>
 		<title>
 		<function moreinfo="none">ds_next_dst()</function>
 		</title>
 		<para>
 		Takes the next destination address from the AVPs with id 'dst_avp_id'
		and sets the dst_uri (outbound proxy address).
 		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
 	</section>
  	<section>
 		<title>
 		<function moreinfo="none">ds_next_domain()</function>
 		</title>
 		<para>
 		Takes the next destination address from the AVPs with id 'dst_avp_id'
		and sets the domain part of the request URI.
 		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
 	</section>
  	<section id="dispatcher.f.ds_mark_dst">
 		<title>
 		<function moreinfo="none">ds_mark_dst([state])</function>
 		</title>
 		<para>
		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'.
 		</para>
 		<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>
		<itemizedlist>
		<listitem>
			<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
				should be set to inactive and will be ignored in future
				requests.</para>
		</listitem>
		<listitem>
			<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>
		</listitem>
		<listitem>
			<para><emphasis>"p" and "P"</emphasis> - 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.</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
		</para>
		<example>
		<title><function>ds_mark_dst</function> usage</title>
		<programlisting format="linespecific">
...
failure_route[tryagain] {
...
   if(t_check_status("500"))
      ds_mark_dst("ip"); # set to inactive and probing
...
}
...
</programlisting>
		</example>
 	</section>
  	<section  id="dispatcher.f.ds_list_exist">
 		<title>
		<function moreinfo="none">ds_list_exist(groupid)</function>
 		</title>
 		<para>
		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>
		<title><function>ds_list_exist</function> usage</title>
		<programlisting format="linespecific">
...
if(ds_list_exist("10")) {
    ...
}
...
</programlisting>
	</example>
	</section>
  	<section  id="dispatcher.f.ds_is_from_list">
 		<title>
		<function moreinfo="none">ds_is_from_list([groupid [, mode [, uri] ] ])</function>
 		</title>
 		<para>
		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>
        <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>
		</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'.
 		</para>
		<para>
		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).
 		</para>
		<para>
			This function can be used from ANY_ROUTE.
		</para>
		<example>
		<title><function>ds_is_from_list</function> usage</title>
		<programlisting format="linespecific">
...
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")) {
    ...
}
...
</programlisting>
		</example>
 	</section>
  	<section id="dispatcher.f.ds_load_update">
 		<title>
 		<function moreinfo="none">ds_load_update()</function>
 		</title>
 		<para>
		Updates the load state:
 		</para>
		<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>
		<para>
			This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
			BRANCH_ROUTE and ONREPLY_ROUTE.
		</para>
 	</section>
  	<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>
	</section>

	<section>
	<title>MI Commands</title>
	<section id="dispatcher.mi.ds_set_state">
		<title>
		<function moreinfo="none">ds_set_state</function>
		</title>
		<para>
        Sets the status for a destination address (can be use to mark the destination
		as active or inactive).
		</para>
		<para>
		Name: <emphasis>ds_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>
			         <listitem><para> <quote>t</quote>: trying</para></listitem>
			         <listitem><para> <quote>d</quote>: disabled</para></listitem>
				  </itemizedlist>
				  <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>
			</listitem>

			<listitem><para>_group_: destination group id</para></listitem>

			<listitem><para>_address_: address of the destination in the _group_</para></listitem>
		</itemizedlist>
		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:ds_set_state:_reply_fifo_file_
		_state_
		_group_
		_address_
		_empty_line_
		</programlisting>
    </section>
	<section id="dispatcher.mi.ds_list">
		<title>
		<function moreinfo="none">ds_list</function>
		</title>
		<para>
		It lists the groups and included destinations.
		</para>
		<para>
		Name: <emphasis>ds_list</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI FIFO Command Format:
		</para>
        <programlisting  format="linespecific">
		:ds_list:_reply_fifo_file_
		_empty_line_
		</programlisting>
    </section>
	<section id="dispatcher.mi.ds_reload">
		<title>
		<function moreinfo="none">ds_reload</function>
		</title>
		<para>
		It reloads the groups and included destinations. For algorithm 10
		(call load distribution), old internal list of active calls is
		destroyed (because it is bould to the previous list of gateways),
		meaning that the module is starting to count active calls again
		from 0.
		</para>
		<para>
		Name: <emphasis>ds_reload</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
 		<para>
		MI DATAGRAM Command Format:
		</para>
        <programlisting  format="linespecific">
		":ds_reload:\n."
		</programlisting>
    </section>

    </section>

	<section>
	<title>RPC Commands</title>
	<section id="dispatcher.rpc.set_state">
		<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>
			         <listitem><para> <quote>t</quote>: trying</para></listitem>
			         <listitem><para> <quote>d</quote>: disabled</para></listitem>
				  </itemizedlist>
				  <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>
			</listitem>

			<listitem><para>_group_: destination group id</para></listitem>

			<listitem><para>_address_: address of the destination in the _group_</para></listitem>
		</itemizedlist>
		<para>
		Example:
		</para>
<programlisting  format="linespecific">
...
# prototype: &sercmd; dispatcher.set_state _state_ _group_ _address_
&sercmd; dispatcher.set_state ip 2 sip:127.0.0.1:5080
...
</programlisting>
    </section>
	<section id="dispatcher.rpc.list">
		<title>
		<function moreinfo="none">dispatcher.list</function>
		</title>
		<para>
		Lists the groups and included destinations.
		</para>
		<para>
		Name: <emphasis>dispatcher.list</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
		<para>
		Example:
		</para>
        <programlisting  format="linespecific">
		&sercmd; dispatcher.list
		</programlisting>
    </section>
	<section id="dispatcher.f.reload">
		<title>
		<function moreinfo="none">dispatcher.reload</function>
		</title>
		<para>
		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.
		</para>
		<para>
		Name: <emphasis>dispatcher.reload</emphasis>
		</para>
		<para>Parameters: <emphasis>none</emphasis></para>
		<para>
		Example
		</para>
        <programlisting  format="linespecific">
		&sercmd; dispatcher.reload
		</programlisting>
    </section>

	<section id="dispatcher.rpc.ping_active">
		<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>

   </section>

	<section id="dispatcher.ex.install">
	<title>Installation and Running</title>
	<section>
		<title>Destination List File</title>
		<para>
		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).
		</para>
		<para>
		Optionally, these fields can be followed by:
		</para>
		<itemizedlist>
			<listitem>
			<para>flags (listed by index - can be bitwise mask of values):
			0 (value 1) - inactive destination; 1 (value 2) - temporary trying
			destination (in the way to become inactive if it does not reply to
			keepalives - there is a module parameter to set the threshold of
			failures); 2 (value 4)  - admin disabled destination; 3 (value 8)
			- probing destination (sending keep alives);</para>
			</listitem>
			<listitem>
			<para>priority: sets the priority in destination list (based on it
			is done the initial ordering inside the set)</para>
			</listitem>
			<listitem>
			<para>attributes: extra fields in form of
				name1=value1;...;nameN=valueN.
			</para>
			</listitem>
		</itemizedlist>
		<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>
					'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).
				</listitem>
				<listitem>
					'socket' - used to set the sending socket for the gateway.
					It is used for sending the SIP traffic as well as
					OPTIONS keepalives.
				</listitem>
			</itemizedlist>
		</para>
		</section>
		<section id="dispatcher.ex.fileforma">
			<title>File Format</title>
		<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">
...
1 sip:127.0.0.1:5080 0 0 duid=abc;socket=udp:192.168.0.125:5060;my=xyz
...
</programlisting>

		<para>
		For database, each element of a line resides in a different column.
		Next is a dispatcher.list file example:
		</para>
		<example>
		<title>dispatcher list file</title>
		<programlisting format="linespecific">
...
<xi:include href="dispatcher.list" parse="text"/>
...
</programlisting>
		</example>
		</section>
		</section>

		<section id="dispatcher.ex.config">
		<title>&kamailio; config file</title>
		<para>
		Next listing shows a sample config for using the dispatcher module.
		</para>
		<example>
		<title>&kamailio; config script - sample dispatcher usage</title>
		<programlisting format="linespecific">
...
<xi:include href="dispatcher.cfg" parse="text"/>
...
		</programlisting>
		</example>
	</section>
	</section>

        <section id="dispatcher.ex.event_routes">
        <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>

</chapter>

