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

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

<chapter>
	<title>&adminguide;</title>
	
	<section>
	<title>Overview</title>
	<section>
	<title>Introduction</title>

	<para>Dynamic Routing is a module for selecting (based on multiple
	criteria) the the best gateway/destination to be used for delivering a
	certain call. Least Cost Routing (LCR) is a special case of dynamic
	routing - when the rules are ordered based on costs. Dynamic Routing 
	comes with many features regarding routing rule selection:
	</para>
	<itemizedlist>
		<listitem><para>prefix based</para></listitem>
		<listitem><para>caller/group based</para></listitem>
		<listitem><para>time based</para></listitem>
		<listitem><para>priority based</para></listitem>
	</itemizedlist>
	<para>
	, processing :
	</para>
	<itemizedlist>
		<listitem><para>stripping and prefixing</para></listitem>
		<listitem><para>default rules</para></listitem>
		<listitem><para>inbound and outbound processing</para></listitem>
		<listitem><para>script route triggering</para></listitem>
	</itemizedlist>
	<para>
	and failure handling:
	<itemizedlist>
		<listitem><para>serial forking</para></listitem>
		<listitem><para>weight based GW selection</para></listitem>
		<listitem><para>random GW selection</para></listitem>
	</itemizedlist>
	</para>
</section>

	<section>
	<title>Features</title>
	<para>
	The dynamic routing implementation for &kamailio; is designed with the
	following properties:
	</para>
	<itemizedlist>
	<listitem>
	<para>
	routing info (destinations, rules, groups) are stored in a database and
	loaded into memory at start up time; reload at runtime via RPC command
	</para>
	</listitem>

	<listitem>
	<para>
	load balancing or random selection of the destinations (from a given set)
	</para>
	</listitem>

	<listitem>
	<para>
	able to handle large volume of routing info (300K of rules) with minimal
	speed/time and memory consumption penalties
	</para>
	</listitem>
	
	<listitem>
	<para>
	script integration - Pseudo variables support in functions; scripting
	route triggering when rules are matched
	</para>
	</listitem>
	
	<listitem>
	<para>
	bidirectional behavior - inbound and outbound processing (strip and 
	prefixing when sending and receiving from a destination/GW)
	</para>
	</listitem>

	</itemizedlist>
	</section>

	<section>
	<title>Performance</title>
	<para>
	There were several tests performed regarding the performance of the module
	when dealing with a large number of routing rules.
	</para>
	<para>
	The tests were performed with a set of 383000 rules and to values were
	measured:
	</para>
	<itemizedlist>
	<listitem><para>time to load from DB</para></listitem>
	<listitem><para>used shared memory</para></listitem>
	</itemizedlist>
	<para>
	The time to load was varying between 4 seconds and 8 seconds, depending of
	the caching of the DB client - the first load was the slowest (as the DB 
	query hits the disk drive); the following are faster as data is already 
	cached in the DB client. So technically speaking, the time to load (without
	the time to query which is DB type dependent) is ~4 seconds
	</para>
	<para>
	After loading the data into shared memory ~ 96M of memory were used 
	exclusively for the DR data.
	</para>
	</section>


	<section>
	<title>Routing Rule Definition</title>
	<para>
	Dynamic routing rules are stored in a database, in four tables:
	</para>
	<itemizedlist>
	<listitem>
	<para>one for storing the gateway definitions
	</para>
	</listitem>
	<listitem>
	<para>one for storing the routing rule definitions
	</para>
	</listitem>
	<listitem>
	<para>one for storing the users mappings over groups
	</para>
	</listitem>
	<listitem>
        <para>one for storing a list of gateways, so you don't have to enter all
	the elements every time you need it
        </para>
        </listitem>
	</itemizedlist>
	<section>
	<title>Gateway Addresses</title>
	<para>
	Default name for the table storing gateway addresses is 
	<quote>dr_gateways</quote>.
	Gateway addresses are stored in a separate table because of need to
	access them independent of Dynamic Routing processing (e.g., adding/
	removing gateway PRI prefix before/after performing other operation
	-- receiving/relaying to gateway).
	</para>
	<para>
	<table>
	<title>Definition of table dr_gateways</title>
	<tgroup cols="4">
	<thead>
	<row>
	<entry>Column name</entry>
	<entry>Type</entry>
	<entry>Default value</entry>
	<entry>Description</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry>gwid</entry>
	<entry>integer</entry>
	<entry>auto increment</entry>
	<entry>unique identifier for GW</entry>
	</row>
	<row>
	<entry>type</entry>
	<entry>unsigned int</entry>
	<entry>0</entry>
	<entry>type/class of GW</entry>
	</row>
	<row>
	<entry>address</entry>
	<entry>varchar(128)</entry>
	<entry></entry>
	<entry>address of the gateway</entry>
	</row>
	<row>
	<entry>strip</entry>
	<entry>unsigned int</entry>
	<entry>0</entry>
	<entry>no of digits to strip</entry>
	</row>
	<row>
	<entry>pri_prefix</entry>
	<entry>varchar(255)</entry>
	<entry></entry>
	<entry>PRI prefix of the gateway</entry>
	</row>
	<row>
	<entry>description</entry>
	<entry>varchar(128)</entry>
	<entry></entry>
	<entry>description of the gateway</entry>
	</row>
	</tbody>
	</tgroup>
	</table> 
	
	</para>
	<para>
	Once a rule is matched, the STRIP number of digits are removed from the
	username part of the RURI and then the PRI prefix has to be added to the 
	request URI before forwarding the call to the gateway. 
	</para>

	<para>
	<table>
	<title>Sample dr_gateways records</title>
	<tgroup cols="6">
	<thead>
	<row>
	<entry>gwid</entry>
	<entry>type</entry>
	<entry>address</entry>
	<entry>strip</entry>
	<entry>pri_prefix</entry>
	<entry>description</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry>1</entry>
	<entry>10</entry>
	<entry>10.10.10.10:5080</entry>
	<entry>0</entry>
	<entry>2222</entry>
	<entry>Gateway 1</entry>
	</row>
	<row>
	<entry>2</entry>
	<entry>10</entry>
	<entry>10.10.10.10</entry>
	<entry>2</entry>
	<entry>3333</entry>
	<entry>Gateway 2</entry>
	</row>
	<row>
	<entry>3</entry>
	<entry>20</entry>
	<entry>10.10.10.11</entry>
	<entry>0</entry>
	<entry></entry>
	<entry>Gateway 3</entry>
	</row>
	</tbody>
	</tgroup>
	</table> 
	</para>
	</section>


	<section>
	<title>Destination/GW lists</title>
	<para>
	For each rule, you can set a list of destinations to be used. The list is
	comma or pipe separated enumeration of the destinations. The module
	will use (one by one) each destination from the list (in the given order).
	</para>
	<para>
	Also the module allows the usage of groups in the destination lists. A
	group of destinations is delimited by semi-colon char. inside the whole
	destination list ( like: 2,4;5,78,23;4;7;2 ). The destinations from 
	within a group may be act differently (like load-balancing, random 
	selection, etc), depending of the <quote>sort_order</quote> module 
	parameter - more about this is available under the module paramters 
	section.
	</para>
	</section>


	<section>
	<title>Routing Rules</title>
	<para>
	Default name for the table storing rule definitions is 
	<quote>dr_rules</quote>.
	</para>

	<para>
	<table>
	<title>Definition of dr_rules table</title>
	<tgroup cols="4">
	<thead>
	<row>
	<entry>Column name</entry>
	<entry>Type</entry>
	<entry>Default</entry>
	<entry>Description</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry>ruleid</entry>
	<entry>integer</entry>
	<entry>auto</entry>
	<entry>UID of the rule</entry>
	</row>
	<row>
	<entry>groupid</entry>
	<entry>varchar(255)</entry>
	<entry></entry>
	<entry>list of routing group IDs</entry>
	</row>
	<row>
	<entry>prefix</entry>
	<entry>varchar(64)</entry>
	<entry></entry>
	<entry>destination prefix for this route</entry>
	</row>
	<row>
	<entry>timerec</entry>
	<entry>varchar(255)</entry>
	<entry></entry>
	<entry>time recurrence for this rule</entry>
	</row>
	<row>
	<entry>priority</entry>
	<entry>integer</entry>
	<entry>0</entry>
	<entry>priority of the rule</entry>
	</row>
	<row>
	<entry>routeid</entry>
	<entry>integer</entry>
	<entry>0</entry>
	<entry>route block to be execute</entry>
	</row>
	<row>
	<entry>gwlist</entry>
	<entry>varchar(255)</entry>
	<entry></entry>
	<entry>the list with GWs to be used</entry>
	</row>
	<row>
	<entry>description</entry>
	<entry>varchar(128)</entry>
	<entry></entry>
	<entry>description of this rule</entry>
	</row>
	</tbody>
	</tgroup>
	</table> 
	</para>

	<para>
	<orderedlist numeration="loweralpha">
	<listitem>
	<para>
		<emphasis>groupid column</emphasis> 
	</para>
	<para>
	Each user must be member of only one routing group. It must be 
	specified in user's profile.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>prefix column</emphasis> 
	</para>
	<para>
	Destination URI must start with prefix value to match the rule.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>time rec column</emphasis> 
	</para>
	<para>
	A date-time expression that defines the time recurrence to match for
	current rule. Time recurrences are based closely on the specification
	of recurring intervals of time in the Internet Calendaring and Scheduling
	Core Object Specification (calendar COS), RFC 2445. The set of attributes
	used in routing rule specification is subset of time recurrence attributes
	used by Call Processing Language (CPL). These attributes are (extracted
	from CPL draft 09):
	</para>

	<para>
	<table>
	<title>Time recurrence attributes</title>
	<tgroup cols="2">
	<thead>
	<row>
	<entry>Attribute</entry>
	<entry>Description</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry>dastard</entry>
	<entry>Start of interval (RFC 2445 DATE-TIME)</entry>
	</row>
	<row>
	<entry>duration</entry>
	<entry>Length of interval (RFC 2445 DURATION)</entry>
	</row>
	<row>
	<entry>freq</entry>
	<entry>Frequency of recurrence (secondly,minutely,hourly, daily,weekly,
	monthly, or yearly).</entry>
	</row>
	<row>
	<entry>until</entry>
	<entry>bound of recurrence (RFC 2445 DATE-TIME)</entry>
	</row>
	<row>
	<entry>interval</entry>
	<entry>How often the recurrence repeats</entry>
	</row>
	<row>
	<entry>byday</entry>
	<entry>List of days of the week</entry>
	</row>
	<row>
	<entry>bymonthday</entry>
	<entry>List of days of the month</entry>
	</row>
	<row>
	<entry>byyearday</entry>
	<entry>List of days of the year</entry>
	</row>
	<row>
	<entry>byweekno</entry>
	<entry>List of weeks of the year</entry>
	</row>
	<row>
	<entry>bymonth</entry>
	<entry>List of months of the year</entry>
	</row>
	</tbody>
	</tgroup>
	</table>
	</para>

	<para>
	The value stored in database has the format of:
	<![CDATA[
	<dtstart>|<duration>|<freq>|<until>|<interval>|<byday>|<bymonthday>|<byyearday>|<byweekno>|<bymonth>
	]]>
	</para>
	<para>
	When an attribute is not specified, the corresponding place must be left
	empty, whenever another attribute that follows in the list has to be
	specified.
	</para>
	<para>
	Detailed description of time recurrence attributes:
	<itemizedlist>
	<listitem>
	<para>
		<emphasis>dtstart</emphasis> - specifies the beginning of the first 
		period.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>duration</emphasis> - specifies the duration of the period.
		For a recurring interval, the <quote>duration</quote> parameter MUST
		be small enough such that subsequent intervals do not overlap. 
		For non-recurring intervals, durations of any positive length are 
		permitted, zero-length duration means <quote>forever</quote>. 
		Negative-length durations are not allowed.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>freq</emphasis> - takes one of the following values: 
		<quote>daily</quote>,
		to specify repeating periods based on an interval of a day or more;
		<quote>weekly</quote>, to specify repeating periods based on an 
		interval of a week or more; <quote>monthly</quote>, to specify 
		repeating periods based on an interval of a month or more; and 
		<quote>yearly</quote>, to specify repeating periods based
		on an interval of a year or more. These values are not case-sensitive.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>until</emphasis> - defines an iCalendar COS DATE or DATE-TIME
		value which bounds the recurrence rule in an inclusive manner. If the
		value specified by <quote>until</quote> is synchronized with the 
		specified 
		recurrence, this date or date-time becomes the last instance of the 
		recurrence. If not present, the recurrence is considered to repeat 
		forever.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>interval</emphasis> - contains a positive integer 
		representing how often the recurrence rule repeats. The default value
		is <quote>1</quote>, meaning every day for a <quote>daily</quote> rule,
		every week for a <quote>weekly</quote>
		rule, every month for a <quote>monthly</quote> rule and every year for
		a <quote>yearly</quote> rule.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>interval</emphasis> - contains a positive integer 
		representing how often the recurrence rule repeats. The default value 
		is <quote>1</quote>, meaning every day for a <quote>daily</quote> rule,
		every week for a <quote>weekly</quote> rule, every
		month for a <quote>monthly</quote> rule and every year for a 
		<quote>yearly</quote> rule.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>byday</emphasis> - specifies a comma-separated list of days 
		of the week. <quote>MO</quote> indicates Monday; <quote>TU</quote> 
		indicates Tuesday; <quote>WE</quote> indicates Wednesday; 
		<quote>TH</quote> indicates Thursday; <quote>FR</quote> indicates 
		Friday; <quote>SA</quote> indicates Saturday; <quote>SU</quote> 
		indicates Sunday. These values are not case-sensitive.
	</para>
	<para>
		Each <quote>byday</quote> value can also be preceded by a positive 
		(+n) or negative (-n) integer. If present, this indicates the nth 
		occurrence of the specific day within the <quote>monthly</quote> or 
		<quote>yearly</quote> recurrence. For example, within a 
		<quote>monthly</quote> rule, +1MO (or simply 1MO) represents the first 
		Monday within the month, whereas -1MO represents the last Monday of
		the month. If an integer modifier is not present, it means all days
		of this type within the specified frequency. For example, within a 
		<quote>monthly</quote> rule, MO represents all Mondays within the month.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>bymonthday</emphasis> - parameter specifies a comma-separated
		list of days of the month. Valid values are 1 to 31 or -31 to -1. For 
		example, -10 represents the tenth to the last day of the month.
	</para>
	</listitem>

	<listitem>
	<para>
		<emphasis>byyearday</emphasis> - specifies a comma-separated list of 
		days of the year. Valid values are 1 to 366 or -366 to -1. For example,
		-1 represents the last day of the year (December 31st) and -306 
		represents the 306th to the last day of the year (March 1st).
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>byweekno</emphasis> - specifies a comma-separated list of 
		ordinals specifying weeks of the year. Valid values are 1 to 53 or 
		-53 to -1.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>bymonth</emphasis> - parameter specifies a comma-separated
		list of months of the year. Valid values are 1 to 12.
	</para>
	</listitem>
	</itemizedlist>
</para>
<para>
</para>
	<para></para>
	<para>
		A recurrence is specified by including the <quote>freq</quote> 
		parameter, which indicates the type of recurrence rule. Parameters 
		other than <quote>dtstart</quote>
		and <quote>duration</quote> SHOULD NOT be specified unless 
		<quote>freq</quote> is present.
	</para>
	<para></para>
	<para>
		If byxxx parameter values are found which are beyond the available 
		scope (ie, bymonthday=<quote>30</quote> in February), they are simply
		ignored. 
	</para>
	<sbr></sbr>
	<para></para>
	<para>
		Byxxx parameters modify the recurrence in some manner. Byxxx rule 
		parts for a period of time which is the same or greater than the 
		frequency generally reduce or limit the number of occurrences of the 
		recurrence generated. For example, freq=<quote>daily</quote> 
		bymonth=<quote>1</quote> reduces the number of
		recurrence instances from all days (if the <quote>bymonth</quote> 
		parameter is not present) to all days in January. Byxxx parameters for 
		a period of time less than the frequency generally increase or expand 
		the number of occurrences of the recurrence. For example, 
		freq=<quote>yearly</quote> bymonth=<quote>1,2</quote>
		increases the number of days within the yearly recurrence set from 1 
		(if <quote>bymonth</quote> parameter is not present) to 2.
	</para>
	<para>
		If multiple Byxxx parameters are specified, then after evaluating the
		specified <quote>freq</quote> and <quote>interval</quote> parameters,
		the Byxxx parameters are 
		applied to the current set of evaluated occurrences in the following
		order: <quote>bymonth</quote>, <quote>byweekno</quote>, 
		<quote>byyearday</quote>, <quote>bymonthday</quote>, 
		<quote>byday</quote>; then <quote>until</quote> is  evaluated.
	</para>
	<para>
		Here is an example of evaluating multiple Byxxx parameters.
	</para>
	<para>
		dtstart=<quote>19970105T083000</quote> duration=<quote>10M</quote>
		freq=<quote>yearly</quote> interval=<quote>2</quote> 
		bymonth=<quote>1</quote> byday=<quote>SU</quote>
	</para>
	<para>
		First, the interval=<quote>2</quote> would be applied to 
		freq=<quote>yearly</quote> to arrive at <quote>every other year</quote>
		. Then, bymonth=<quote>1</quote> would be applied to arrive at 
		<quote>every January, every other year</quote>. Then,
		byday=<quote>SU</quote> would be applied to arrive at <quote>every 
		Sunday in January, 
		every other year, from 8:30 to 8:40 </quote>. The appropriate minutes 
		and hours have been retrieved from the <quote>dtstart</quote> and 
		<quote>duration</quote> parameters.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>priority column</emphasis> 
	</para>
	<para>
	If many rules are eligible, choose the one with highest priority.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>routeid column</emphasis> 
	</para>
	<para>
	If different than 0, then execute the route with the specified ID.
	That is, a route which can be used to perform custom
	operations on message. At this route, no modification is performed
	at signaling level.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>gwlist column</emphasis> 
	</para>
	<para>
	A comma separated list of gateway identifiers corresponding to a row in 
	table <quote>dr_gateways</quote>. You can use a predefined list from the
	table <quote>dr_gw_lists</quote> preceded by the character
	<quote>#</quote>. The first gateway is tried first and if routing to it
	fails, then the second one, and so one. If no gateway is left a negative 
	response is sent back to caller.
	</para>
	</listitem>
	<listitem>
	<para>
		<emphasis>Routing Rules Examples</emphasis> 
	</para>
	
	<para>
	<table align="center" frame= "all" pgwide="1">
	<title>Sample dr_rules records</title>
	<tgroup cols="8" align='left' colsep='1' rowsep='1'>
	<thead>
	<row>
	<entry>ruleid</entry>
	<entry>group</entry>
	<entry>prefix</entry>
	<entry>timerec</entry>
	<entry>priority</entry>
	<entry>routeid</entry>
	<entry>gwlist</entry>
	<entry>description</entry>
	</row>
	</thead>
	<tbody>
	<row>
	<entry>1</entry>
	<entry>6</entry>
	<entry>0049</entry>
	<entry>20040101T083000|10H|weekly|||MO,TU,WE,TH,FR</entry>
	<entry>5</entry>
	<entry>23</entry>
	<entry>1,2</entry>
	<entry>Rule 1</entry>
	</row>
	<row>
	<entry>2</entry>
	<entry>8</entry>
	<entry>0049</entry>
	<entry>20040101T083000</entry>
	<entry>0</entry>
	<entry>0</entry>
	<entry>1,2</entry>
	<entry>Rule 2</entry>
	</row>
	<row>
	<entry>3</entry>
	<entry>7,8,9</entry>
	<entry>0049</entry>
	<entry>20040101T083000</entry>
	<entry>0</entry>
	<entry>0</entry>
	<entry>3</entry>
	<entry>Rule 3</entry>
	</row>
	</tbody>
	</tgroup>
	</table>

	</para>
	<para>
	(The time recurrence for first rule is:
	<quote>20040101T083000|10H|weekly|||MO,TU,WE,TH,FR</quote>)
	</para>

	</listitem>
</orderedlist>
	</para>
</section>

</section>
<section>
	<title>Routing Rule Processing</title>
	<para>
	The module can be used to find out which is the best gateway to use for new
	calls terminated to PSTN. The algorithm to select the rule is as follows:
	<itemizedlist mark='bullet'>
	<listitem>
	<para>
	the module discovers the routing group of the originating user. This 
	step is skipped if a routing group is passed from the script as parameter.
	</para>
	</listitem>
	<listitem>
	<para>
	once the group is known, in the subset of the rules for this group the 
	module looks for the one that matches the destination based on "prefix"
	column. The set of rules with the longest prefix is chosen. If no digit 
	from the prefix matches, the default rules are used (rules with no prefix)
	</para>
	</listitem>
	<listitem>
	<para>
	within the set of rules is applied the time criteria, and the rule which
	has the highest priority and matches the time criteria is selected to drive
	the routing.
	</para>
	</listitem>
	<listitem>
	<para>
	Once found the rule, it may contain a route ID to execute. If a certain 
	flag is set, then the processing is stopped after executing the route
	block.
	</para>
	</listitem>
	<listitem>
	<para>
	The rule must contain a gateway chain. The module will execute serial 
	forking for each address in chain. The next address in chain is used only
	if the previously has failed.
	</para>
	</listitem>
	<listitem>
	<para>
	With the right gateway address found, the prefix (PRI) of the gateway is
	added to the request URI and then the request is forwarded.
	</para>
	</listitem>
	</itemizedlist>
	</para>
	<para>
	If no rule is found to match the selection criteria an default action must
	be taken (e.g., error response sent back). If the gateway in the chain has 
	no prefix the request is forwarded without adding any prefix to the request
	URI.
	</para>

</section>

</section>


	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>a database module</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>

	<section>
		<title>External Libraries or Applications</title>
		<itemizedlist>
			<listitem>
			<para>
				<emphasis>none</emphasis>.
			</para>
			</listitem>
		</itemizedlist>

		</section>
	</section>
	
	<section>
	<title>Parameters</title>
	<section>
		<title><varname>db_url</varname>(str)</title>
		<para>
		The database url.
		</para>
		<para>
		<emphasis>	Default value is <quote>NULL</quote>.	
		</emphasis>
		</para>
		<example>
		<title>Set <varname>db_url</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "db_url", 
	"&defaultdb;")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>drd_table</varname>(str)</title>
		<para>
		The name of the db table storing gateway addresses.
		</para>
		<para>
		<emphasis>	Default value is <quote>dr_gateways</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>drd_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "drd_table", "dr_gateways")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>drr_table</varname>(str)</title>
		<para>
		The name of the db table storing routing rules.
		</para>
		<para>
		<emphasis>	Default value is <quote>dr_rules</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>drr_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "drr_table", "rules")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>drg_table</varname>(str)</title>
		<para>
		The name of the db table storing groups.
		</para>
		<para>
		<emphasis>	Default value is <quote>dr_groups</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>drg_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "drg_table", "groups")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>drl_table</varname>(str)</title>
		<para>
		The name of the db table storing definitions of destination lists (to 
		be used directly by the routing rules).
		You will have a identifier to a group of gateways instead of having all the
		members of the group as a individual elements.
		Very useful to reuse a list of gateways in different places.
		</para>
		<para>
		<emphasis>	Default value is <quote>dr_gw_lists</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>drl_table</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "drl_table", "my_gw_lists")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>sort_order</varname> (int)</title>
		<para>
		Defines how the destination list should be processed (ordering of
		the elements). Possible modes are
		<itemizedlist>
		<listitem>
			<emphasis>0</emphasis> - destination groups are ignored and all the
			destinations are tried in the given order; 
			Ex: list 1,2;3,4,5;6 will lead to usage as 1,2,3,4,5,6 
		</listitem>
		<listitem>
			<emphasis>1</emphasis> - the destinations from each group are
			randomly arranged (only the two elements are randomly selected);
			groups do maintain their order (as given); the resulting list is 
			used (with all the defined destinations).
			Ex: 1,2;3,4,5;6 -> randomizer -> 
			(A) 2,1;4,3,5;6  -> usage 2,1,4,3,5,6
			(B) 1,2;3,5,4;6  -> usage 1,2,3,5,4,6
		</listitem>
		<listitem>
			<emphasis>2</emphasis> - from each destination group, only a 
			single destination is randomly selected; groups do maintain their
			order (as given);
			<para>
			Ex: 1,2;3,4,5;6 -> randomizer ->
			</para>
			<para>
			(A) 2;4;6  -> usage 2,4,6
			</para>
			<para>
			(B) 1;5;6  -> usage 1,5,6
			</para>
			<para>
			It is ok to have repeating gateways in different groups. The module will
			take care internally in case of failure not to choose a gateway that
			was tried already.
			</para>
			<para>
			Ex: 1,2,3; 1,2,3; 1,2,3 -> no gateway will be chosen twice. So in case there
			are 2 failures, all the three gateways (1,2,3) will be tried in a random order.
			</para>
		</listitem>
		</itemizedlist>
		</para>
		<para>
		<emphasis>Default value is <quote>0</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>sort_order</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "sort_order", 2)
...
</programlisting>
		</example>
	</section>

<section>
		<title><varname>ruri_avp</varname> (str)</title>
		<para>
		The name of the avp for storing Request URIs to be later used 
		(alternative destiantions for the current one).
		</para>
		<para>
		<emphasis>Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>ruri_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "ruri_avp", '$avp(dr_ruri)')
modparam("drouting", "ruri_avp", '$avp(i:33)')
...
	</programlisting>
		</example>
	</section>

	<section>
		<title><varname>attrs_avp</varname> (str)</title>
		<para>
		The name of the avp for storing the attribute of the current selected
		destination - once a new destination is selected (via the 
		use_next_gw() function), the AVP will be updated with the attrs of the
		new used destination.
		</para>
		<para>
		<emphasis>Default value is <quote>NULL</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>attrs_avp</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "attrs_avp", '$avp(dr_attrs)')
modparam("drouting", "atrrs_avp", '$avp(i:67)')
...
	</programlisting>
		</example>
	</section>

	<section>
		<title><varname>use_domain</varname> (int)</title>
		<para>
			Flag to configure whether to use domain match when querying
			database for user's routing group.
		</para>
		<para>
		<emphasis>Default value is <quote>1</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>use_domain</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "use_domain", 0)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>drg_user_col</varname> (str)</title>
		<para>
		The name of the column in group db table where the username is stored.
		</para>
		<para>
		<emphasis>Default value is <quote>username</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>drg_user_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "drg_user_col", "user")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>drg_domain_col</varname> (str)</title>
		<para>
		The name of the column in group db table where the domain is stored.
		</para>
		<para>
		<emphasis>Default value is <quote>domain</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>drg_domain_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "drg_domain_col", "host")
...
</programlisting>
		</example>
	</section>
	<section>
		<title><varname>drg_grpid_col</varname> (str)</title>
		<para>
			The name of the column in group db table where the
			group id is stored.
		</para>
		<para>
		<emphasis>Default value is <quote>groupid</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>drg_grpid_col</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "drg_grpid_col", "grpid")
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>fetch_rows</varname> (int)</title>
		<para>
		</para>
		The number of rows that should be fetched from the result of a
		query in rules db table.
		<para>
		<emphasis>Default value is <quote>2000</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>fetch_rows</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "fetch_rows", 1500)
...
</programlisting>
		</example>
	</section>

	<section>
		<title><varname>force_dns</varname> (int)</title>
		<para>
		Force DNS resolving of GW/destination names (if not IPs) during 
		startup. If not enabled, the GW name will be blindly used during 
		routing.
		</para>
		<para>
		<emphasis>Default value is <quote>1 (enabled)</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>force_dns</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("drouting", "force_dns", 0)
...
	</programlisting>
		</example>
	</section>

</section>

<section>
	<title>Functions</title>
	<section>
		<title>
		<function moreinfo="none">do_routing("[groupID]")</function>
		</title>
		<para>
		Function to trigger routing of the message according to the 
		rules in the database table and the configured parameters.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<para>
		The module can take one optional parameter: the routing group the 
		caller belongs to - this may be a static numerical value or an AVP
		specification. If none specified, the function will automatically
		try to query the dr_group table to get this information.
		</para>
		<example>
		<title><function>do_routing</function> usage</title>
		<programlisting format="linespecific">
...
do_routing();
...
do_routing("0");
...
do_routing("$avp(i:10)");
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">use_next_gw()/next_routing()</function>
		</title>
		<para>
		The function takes the next available destination (set by do_routing, 
		as alternative destinations) and push it into RURI. Note that the 
		function just sets the RURI (nothing more).
		</para>
		<para>
		If a new RURI is set, the used destination is removed from the 
		pending set of alternative destinations.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<para>
		The function returns true only if a new RURI was set. False
		is returned is no other alternative destinations are found or in case
		of internal processing error.
		</para>
		<example>
		<title><function>use_next_gw</function> usage</title>
		<programlisting format="linespecific">
...
if (use_next_gw()) {
	t_relay();
	exit;
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">goes_to_gw([type])</function>
		</title>
		<para>
		Function returns true if the destination of the current request 
		(destination URI or Request URI) points (as IP) to one of the gateways.
		There no DNS lookups done if the domain part of the URI is not an IP.
		</para>
		<para>
		This function does not change anything in the message.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<para>
			The function can take one optional parameter:
			<itemizedlist>
				<listitem>
					<emphasis>type</emphasis> (optional) - GW/destination 
					type to be checked
				</listitem>
			</itemizedlist>
		</para>
		<example>
		<title><function>goes_to_gw</function> usage</title>
		<programlisting format="linespecific">
...
if (goes_to_gw("1")) {
	sl_send_reply("403","Forbidden");
	exit;
}
...
</programlisting>
		</example>
	</section>


	<section>
		<title>
		<function moreinfo="none">is_from_gw([type])</function>
		</title>
		<para>
		The function checks if the sender of the message is a gateway
		from a certain group.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and 
		ONREPLY_ROUTE
		</para>
		<para>
			The function can take one optional parameter:
			<itemizedlist>
				<listitem>
					<emphasis>type</emphasis> (optional) - GW/destination type
					to be checked
				</listitem>
				<listitem>
					<emphasis>flags</emphasis> - if message is a request and
					the GW has a STRIP defined, then apply it if GW is source.
				</listitem>
			</itemizedlist>
		</para>
		<example>
		<title><function>is_from_gw</function> usage</title>
		<programlisting format="linespecific">
...
if (is_from_gw("1") {
}
...
</programlisting>
		</example>
	</section>

	<section>
		<title>
		<function moreinfo="none">is_from_gw( type, [flag])</function>
		</title>
		<para>
		The function checks if the sender of the message is a gateway
		from a certain group.
		</para>
		<para>
		This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
		</para>
		<para>
			The function can take two parameters:
			<itemizedlist>
				<listitem>
					<emphasis>type</emphasis> (mandatory) - GW/destination
					type to be checked
				</listitem>
				<listitem>
					<emphasis>flags</emphasis> (optional) - if message is a 
					request and the GW has a STRIP defined, then apply it 
					if GW is source.
				</listitem>
			</itemizedlist>
		</para>
		<example>
		<title><function>is_from_gw</function> usage</title>
		<programlisting format="linespecific">
...
if (is_from_gw("3","1") {
}
...
</programlisting>
		</example>
	</section>
</section>



<section>
	<title>RPC Commands</title>
	<section>
		<title>
		<function moreinfo="none">drouting.reload</function>
		</title>
		<para>Command to reload routing rules from database.</para>
		<para>It takes no parameter.</para>
		<para>RPC Command Format:</para>
		<programlisting  format="linespecific">
	kamcmd drouting.reload
		</programlisting>
	</section>
</section>

<section>
	<title>Installation</title>
	<para>
	The module requires 3 table in &kamailio; database: dr_groups,
	dr_gateways, dr_rules. The SQL syntax to create them can be
	found in drouting-create.sql script in &ctltool; db directories.
	You can also find the complete
	database documentation on the project webpage, &kamailiodbdocslink;.
	</para>
</section>

</chapter>