<?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 modules implements a dispatcher for destination addresses. It 
		computes hashes over parts of the request and selects an address from
		a destination set. The selected address is used then as outbound
		proxy.
	</para>
	<para>
		The module can be used as a stateless load balancer, having no
		guarantee of fair distribution.
	</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>
			</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>Exported Parameters</title>
	<section>
		<title><varname>list_file</varname> (string)</title>
		<para>
		Path to the file with destination sets.
		</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>
 		<title><varname>db_url</varname> (string)</title>
 		<para>
		If you want to load the sets 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>
		<title><varname>table_name</varname> (string)</title>
		<para>
		If you want to load the sets 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>
		<title><varname>setid_col</varname> (string)</title>
		<para>
			The column's name in the database storing the gateway's 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>
		<title><varname>destination_col</varname> (string)</title>
		<para>
			The column's name in the database storing the destination's
			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>
		<title><varname>flags_col</varname> (string)</title>
		<para>
			The column's name in the database storing the flags for
			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>
		<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>
		<title><varname>force_dst</varname> (int)</title>
		<para>
		If set to 1, force overwriting of destination address when that is
		already set.
		</para>
		<para>
		<emphasis>
			Default value is <quote>0</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>
 		<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 the failover support is enabled. The functions
		exported by the module will store the rest of addresses from the
		destination set in AVP, and use these AVPs to contact next address when
		the current-tried fails.
 		</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>
 		<title><varname>use_default</varname> (int)</title>
 		<para>
 		If the parameter is set to 1, the last address in destination set
		is used as last option to send the message. For example, it is good
		when wanting to send the call to an anouncement server saying:
		"the gateways are full, try later".
 		</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>
 		<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 do 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(i:271)")
 ...
 </programlisting>
 		</example>
 	</section>
 	<section>
 		<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 do 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(i:272)")
 ...
 </programlisting>
 		</example>
 	</section>
 	<section>
 		<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 do 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(i:273)")
 ...
 </programlisting>
 		</example>
 	</section>
 	<section>
 		<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>
 		<title><varname>setid_pvar</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_pvar</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "setid_pvar", "$var(setid)")
 ...
 </programlisting>
 		</example>
 	</section>

 	<section>
 		<title><varname>ds_ping_method</varname> (string)</title>
 		<para>
 		With this Method you can define, with which method you want to probe the failed gateways.
 		This method is only available, if compiled with the probing of failed gateways enabled. 		
 		</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>
 		<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>
 		<title><varname>ds_ping_interval</varname> (int)</title>
 		<para>
 		With this Method you can define the interval for sending a request to a failed gateway.
 		This parameter is only used, when the TM-Module is loaded.
		If set to <quote>0</quote>, the pinging of failed requests is disabled.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>10</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>
 		<title><varname>ds_probing_threshhold</varname> (int)</title>
 		<para>
		If you want to set a gateway into probing mode, you will need a specific number of requests until it will change from "active" to probing.
		The number of attempts can be set with this parameter.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>3</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>ds_probing_threshhold</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "ds_probing_threshhold", 10)
 ...
 </programlisting>
 		</example>
	</section>

 	<section>
 		<title><varname>ds_probing_mode</varname> (int)</title>
 		<para>
		Controls what gateways are tested to see if they are reachable. If set
		to 0, only the gateways with state PROBING are tested, if set to 1, all
		gateways are tested. If set to 1 and the response is 408 (timeout),
		an active gateway is set to PROBING state.
 		</para>
 		<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>
 		<title><varname>ds_append_branch</varname> (int)</title>
 		<para>
		If set to 1, functions will automaticall append a new branch if
		called in FAILURE_ROUTE. If set to 0, script writer has to call
		append_branch() in config after calling dispatcher functions.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>1</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set the <quote>ds_append_branch</quote> parameter</title>
 <programlisting format="linespecific">
 ...
 modparam("dispatcher", "ds_append_branch", 0)
 ...
 </programlisting>
 		</example>
	</section>

	</section>

	<section>
	<title>Exported Functions</title>
	<section>
		<title>
		<function moreinfo="none">ds_select_dst(set, alg)</function>
		</title>
		<para>
		The method selects a destination from addresses set.
		</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.
			</para>
		</listitem>
		<listitem>
			<para>
			<emphasis>alg</emphasis> - the algorithm used to select the
			destination address.
			</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 (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> - use first destination (good for failover).
				</para>
			</listitem>
			<listitem>
				<para>
				<quote>X</quote> - if the algorithm is not implemented, the
				first entry in set is chosen.
				</para>
			</listitem>
			</itemizedlist>
		</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.
		</para>
		<example>
		<title><function>ds_select_dst</function> usage</title>
		<programlisting format="linespecific">
...
ds_select_dst("1", "0");
...
</programlisting>
		</example>
	</section>
  	<section>
 		<title>
 		<function moreinfo="none">ds_select_domain(set, alg)</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. 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.
		</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 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 FAILURE_ROUTE.
		</para>
 	</section>
  	<section>
 		<title>
 		<function moreinfo="none">ds_mark_dst()</function>
 		</title>
 		<para>
 		Mark the last used address from destination set as inactive, in order
		to be ingnored in the future. In this way it can be implemented an
		automatic detection of failed gateways. When an address is marked as
		inactive, it will be ignored by 'ds_select_dst' and 'ds_select_domain'.
 		</para>
		<para>
		This function can be used from FAILURE_ROUTE.
		</para>
 	</section>
  	<section>
 		<title>
 		<function moreinfo="none">ds_mark_dst("s")</function>
 		</title>
 		<para>
 		Mark the last used address from destination set as inactive ("i"/"I"/"0"), active ("a"/"A"/"1") or probing ("p"/"P"/"2").
 		With this function, an automatic detection of failed gateways can be implemented. When an address is marked as
		inactive or probing, it will be ignored by 'ds_select_dst' and 'ds_select_domain'.
 		</para>
		<para>possible parameters:</para>
		<itemizedlist>
		<listitem>
			<para><emphasis>"i", "I" or "0"</emphasis> - the last destination should be set to inactive and will be ignored in future requests.</para>
		</listitem>
		<listitem>
			<para><emphasis>"a", "A" or "1"</emphasis> - the last destination should be set to active.</para>
		</listitem>
		<listitem>
			<para><emphasis>"p", "P" or "2"</emphasis> - the last destination will be set to probing. Note: You will need to call this function "threshhold"-times, before it will be actually set to probing.</para>
		</listitem>
		</itemizedlist>
		<para>
		This function can be used from FAILURE_ROUTE.
		</para>
 	</section>
  	<section>
 		<title>
 		<function moreinfo="none">ds_is_from_list()</function>
 		</title>
 		<para>
 		This function returns true, if the current request comes from a host from the dispatcher-list; otherwise false.
 		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and ONREPLY_ROUTE.
		</para>
 	</section>
  	<section>
 		<title>
 		<function moreinfo="none">ds_is_from_list("group")</function>
 		</title>
 		<para>
 		This function returns true, if the current request comes from a host in the given group of the dispatcher-list; otherwise false.
 		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, BRANCH_ROUTE and ONREPLY_ROUTE.
		</para>
 	</section>
	</section>

	<section>
	<title>Exported MI Functions</title>
	<section>
		<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>p</quote>: probing </para></listitem>
				  </itemizedlist>
			</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>
		<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>
		<title>
		<function moreinfo="none">ds_reload</function>
		</title>
		<para>
		It reloads the groups and included destinations.
		</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>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, followed by destination address. Optionally, the third field can
		be flags value (1 - destination inactive, 2 - destination in probing
		mod -- you can do bitwise OR to set both flags). The set id must be
		an integer value. Destination address must be a valid SIP URI. Empty
		lines or lines starting with <quote>#</quote> are ignored.
		</para>
		<example>
		<title>dispatcher list file</title>
		<programlisting format="linespecific">
...
<xi:include href="dispatcher.list" parse="text"/>
...
</programlisting>
		</example>
		</section>
	
		<section>
		<title>&kamailio; config file</title>
		<para>
		Next picture displays a sample usage of dispatcher.
		</para>
		<example>
		<title>&kamailio; config script - sample dispatcher usage</title>
		<programlisting format="linespecific">
...
<xi:include href="dispatcher.cfg" parse="text"/>
...
		</programlisting>
		</example>
	</section>
	</section>
</chapter>