modules/carrierroute/doc/carrierroute_admin.xml
33d03d8d
 <?xml version="1.0" encoding='ISO-8859-1'?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
 "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
 
 <!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
 %docentities;
 
 ]>
60b5fe93
 
 <chapter>
42b7832d
     <title>&adminguide;</title>
60b5fe93
 
     <section>
 	<title>Overview</title>
 	<para>A module which provides routing, balancing and blacklisting capabilities.</para>
 	<para>
101452ab
 		The module provides routing, balancing and blacklisting capabilities.
39adc361
 		It reads routing entries from a database source or from a config file at &kamailio;
00fb8a7a
 		startup. It can uses one routing tree (for one carrier), or if needed for every user
 		a different routing tree (unique for each carrier) for number prefix based routing.
 		It supports several route tree domains,	e.g. for failback routes or different routing
8efd99bc
 		rules for VoIP and PSTN targets.
00fb8a7a
 	</para>
 	<para>
 		Based on the tree, the module decides which number prefixes are forwarded to which
 		gateway. It can also distribute the traffic by ratio parameters. Furthermore, the
 		requests can be distributed by a hash funcion to predictable destinations. The hash
 		source is configurable, two different hash functions are available.
101452ab
 	</para>
 	<para>
940d1c1f
 		This modules scales up to more than a few million users, and is able to handle
3843f738
 		more than several hundred thousand routing table entries. We received reports of
8efd99bc
 		some setups that used more than a million routing table entries. It also supports
 		a large number of carriers and domains which can be efficiently looked up in most of
 		the cases (see below for more informations). In load balancing scenarios the usage
 		of the config file mode is recommended, to avoid the additional complexity that the
 		database driven routing creates.
101452ab
 	</para>
 	<para>
8efd99bc
 		Routing tables can be reloaded and edited (in config file mode) with the MI
 		interface, the config file is updated according the changes. This is not
 		implemented for the db interface, because its easier to do the changes
 		directly on the db. But the reload and dump functions works of course here
101452ab
 		too.
 	</para>
ef6551fe
 	<para>
 		Some module functionality is not fully available in the config file mode, as
 		it is not possible to specify all information that can be stored in the database
 		tables in the config file. Further information about these limitations is given
c2ead767
 		in later sections. For user based routing or LCR you should use the database mode.
ef6551fe
 	</para>
8efd99bc
 	<para>
 		In database mode, this module supports names and IDs for the carriers and domains.
 		When using IDs for the routing functions, efficient binary search is used to find the
 		needed data structures. If you are using constant strings as parameter, these will
 		be converted to IDs during the fixup procedure. However, if you are using AVPs as
 		parameter and they contain strings, this cannot be converted to IDs during the
 		fixup procedure. In that case linear search is performed to find the needed data
 		structures. So from a performance point of view it is better to pass only IDs in
 		AVPs to the routing functions.
 	</para>
101452ab
 	<para>
5bad9d33
 		Basically this module could be used as an replacement for the lcr and the
 		dispatcher module, if you have certain flexibility, integration and/or performance
 		requirements that can't be satisfied with these modules. But for smaller
 		installations it probably make more sense to use the lcr and dispatcher module.
101452ab
 	</para>
696a85cf
 	<para>
22cb1944
 		Starting with version 3.1 , if you want to use this module in failure routes,
c44529a8
 		it is not needed to call<quote>append_branch()</quote> after rewriting the request URI in order to
940d1c1f
 		relay the message to the new target. Its also supportes the usage of database
 		derived failure routing descisions with the carrierfailureroute table.
696a85cf
 	</para>
60b5fe93
     </section>
     <section>
 	<title>Dependencies</title>
 	<section>
912dc8e8
 	    <title>&kamailio; Modules</title>
60b5fe93
 	    <para>
101452ab
 		The following module must be loaded before this module:
60b5fe93
 	    	<itemizedlist>
 		    <listitem>
 			<para>
 				<emphasis>a database module</emphasis>, when a database is used as configuration data source.
696a85cf
 				Only SQL based databases are supported, as this module needs the capability to
 				issue raw queries. Its not possible to use the dbtext or db_berkeley module at the moment.
60b5fe93
 			</para>
 		    </listitem>
aa4a3b3d
 			<listitem>
 			<para>
 				The <emphasis>tm module</emphasis>, when you want to use the $T_reply_code pseudo-variable in
 				the <quote>cr_next_domain</quote> function.
 			</para>
 			</listitem>
60b5fe93
 	    	</itemizedlist>
 	    </para>
 	</section>
     </section>
     <section>
9114eebc
 	<title>Parameters</title>
60b5fe93
     <section>
 	    <title><varname>subscriber_table</varname> (string)</title>
 	    <para>
 		    The name of the table containing the subscribers
 	    </para>
 	    <para>
 		    <emphasis>
 			    Default value is <quote>subscriber</quote>.
 		    </emphasis>
 	    </para>
 	    <example>
 		    <title>Set <varname>subscriber_table</varname> parameter</title>
 		    <programlisting format="linespecific">
 ...
 modparam("carrierroute", "subscriber_table", "subscriber")
 ...
 		    </programlisting>
 	    </example>
     </section>
 
     <section>
 	    <title><varname>subscriber_user_col</varname> (string)</title>
 	    <para>
 		    The name of the column in the subscriber table containing the usernames.
 	    </para>
 	    <para>
 		    <emphasis>
 			    Default value is <quote>username</quote>.
 		    </emphasis>
 	    </para>
 	    <example>
 		    <title>Set <varname>subscriber_user_col</varname> parameter</title>
 		    <programlisting format="linespecific">
 ...
3ff19dea
 modparam("carrierroute", "subscriber_user_col", "username")
60b5fe93
 ...
 		    </programlisting>
 	    </example>
     </section>
 
     <section>
 	    <title><varname>subscriber_domain_col</varname> (string)</title>
 	    <para>
 		    The name of the column in the subscriber table containing the domain of 
 		    the subscriber.
 	    </para>
 	    <para>
 		    <emphasis>
 			    Default value is <quote>domain</quote>.
 		    </emphasis>
 	    </para>
 	    <example>
 		    <title>Set <varname>subscriber_domain_col</varname> parameter</title>
 		    <programlisting format="linespecific">
 ...
 modparam("carrierroute", "subscriber_domain_col", "domain")
 ...
 		    </programlisting>
 	    </example>
     </section>
 
     <section>
 	    <title><varname>subscriber_carrier_col</varname> (string)</title>
 	    <para>
 		    The name of the column in the subscriber table containing the carrier id
 		    of the subscriber.
 
 	    </para>
 	    <para>
 		    <emphasis>
 			    Default value is <quote>cr_preferred_carrier</quote>.
 		    </emphasis>
 	    </para>
 	    <example>
 		    <title>Set <varname>subscriber_carrier_col</varname> parameter</title>
 		    <programlisting format="linespecific">
 ...
 modparam("carrierroute", "subscriber_carrier_col", "cr_preferred_carrier")
 ...
 		    </programlisting>
 	    </example>
     </section>
 
     <section>
 	    <title><varname>config_source</varname> (string)</title>
 	    <para>
 		    Specifies whether the module loads its config data from a file or from a
 		    database. Possible values are file or db.
 	    </para>
 	    <para>
 		    <emphasis>
 			    Default value is <quote>file</quote>.
 		    </emphasis>
 	    </para>
 	    <example>
 		    <title>Set <varname>config_source</varname> parameter</title>
 		    <programlisting format="linespecific">
 ...
 modparam("carrierroute", "config_source", "file")
 ...
 		    </programlisting>
 	    </example>
     </section>
 
     <section>
 	    <title><varname>config_file</varname> (string)</title>
 	    <para>
 		    Specifies the path to the config file.
 	    </para>
 	    <para>
 		    <emphasis>
39c1da61
 			    Default value is <quote>/etc/kamailio/carrierroute.conf</quote>.
60b5fe93
 		    </emphasis>
 	    </para>
 	    <example>
 		    <title>Set <varname>config_file</varname> parameter</title>
 		    <programlisting format="linespecific">
 ...
39c1da61
 modparam("carrierroute", "config_file", "/etc/kamailio/carrierroute.conf")
60b5fe93
 ...
 		    </programlisting>
 	    </example>
     </section>
 
     <section>
 	    <title><varname>default_tree</varname> (string)</title>
 	    <para>
 		    The name of the carrier tree used per default (if the current
 		    subscriber has no preferred tree)
 	    </para>
 	    <para>
 		    <emphasis>
 			    Default value is <quote>default</quote>.
 		    </emphasis>
 	    </para>
 	    <example>
 		    <title>Set <varname>default_tree</varname> parameter</title>
 		    <programlisting format="linespecific">
 ...
 modparam("carrierroute", "default_tree", "default")
 ...
 		    </programlisting>
 	    </example>
     </section>
 
     <section>
38a1bb0e
 	    <title><varname>use_domain</varname> (int)</title>
60b5fe93
 	    <para>
 		    When using tree lookup per user, this parameter specifies whether
1c327b73
 		    to use the domain part for user matching or not. This parameter
 		    is tunable via the ser cfg framework.
60b5fe93
 	    </para>
 	    <para>
 		    <emphasis>
 			    Default value is <quote>0</quote>.
 		    </emphasis>
 	    </para>
 	    <example>
 		    <title>Set <varname>use_domain</varname> parameter</title>
 		    <programlisting format="linespecific">
 ...
38a1bb0e
 modparam("carrierroute", "use_domain", 0)
60b5fe93
 ...
 		    </programlisting>
 	    </example>
     </section>
 
     <section>
38a1bb0e
 	    <title><varname>fallback_default</varname> (int)</title>
60b5fe93
 	    <para>
 		    This parameter defines the behaviour when using user-based tree
 		    lookup. If the user has a non-existing tree set and fallback_default
 		    is set to 1, the default tree is used. Otherwise, cr_user_rewrite_uri
1c327b73
 		    returns an error. This parameter is tunable via the ser cfg framework.
60b5fe93
 	    </para>
 	    <para>
 		    <emphasis>
 			    Default value is <quote>1</quote>.
 		    </emphasis>
 	    </para>
 	    <example>
 		    <title>Set <varname>fallback_default</varname> parameter</title>
 		    <programlisting format="linespecific">
 ...
38a1bb0e
 modparam("carrierroute", "fallback_default", 1)
60b5fe93
 ...
 		    </programlisting>
 	    </example>
     </section>
9fb5298c
 		<section>
 		<title><varname>fetch_rows</varname> (integer)</title>
 		<para>
 		The number of the rows to be fetched at once from database
 		when loading the routing data. This value can be used to tune
 		the load time at startup. For 1MB of private memory (default)
 		it should be below 3750. The database driver must support the
1c327b73
 		fetch_result() capability. This parameter is tunable via the ser
 		cfg framework.
9fb5298c
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>2000</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>fetch_rows</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("carrierroute", "fetch_rows", 3000)
 ...
 </programlisting>
 		</example>
 	</section>
6a738a91
 <section>
 		<title><varname>db_load_description</varname> (integer)</title>
 		<para>
 		Toggle on/off loading in memory the description column in the 
 		carrierroute/carrierfailureroute database tables. This reduces the 
 		shared memory used by the module.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>1</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Unset <varname>db_load_description</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("carrierroute", "db_load_description", 0)
 ...
 </programlisting>
 		</example>
 	</section>
cc0ba2f0
 	<section>
 		<title><varname>match_mode</varname> (integer)</title>
 		<para>
 		The number of individual characters that are used for matching.
 		Valid values are 10 or 128. When you specifiy 10, only digits
 		will be used for matching, this operation mode is equivalent to
 		the old behaviour. When configured with 128, all standard ascii
 		chars are available for matching. Please be aware that memory
 		requirements for storing the routing tree in shared memory
 		will also increase by a factor of 12.8.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>10</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>match_mode</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("carrierroute", "match_mode", 10)
 ...
 </programlisting>
 		</example>
 	</section>
f09551a9
 
 	<section>
 		<title><varname>avoid_failed_destinations</varname> (integer)</title>
 		<para>
 		Integer parameter to toggle on/off the possibility that in the failurerouting cases 
 		destinations that previously failed are avoided. Possible values are 0 (off), 1 (on).
 		Also see cr_route section.
 		</para>
 		<para>
 		<emphasis>
 			Default value is <quote>1</quote>.
 		</emphasis>
 		</para>
 		<example>
 		<title>Set <varname>avoid_failed_destinations</varname> parameter</title>
 		<programlisting format="linespecific">
 ...
 modparam("carrierroute", "avoid_failed_destinations", 0)
 ...
 </programlisting>
 		</example>
 	</section>
 
e27b0961
 </section>
cc0ba2f0
 
e27b0961
     <section>
9114eebc
 	<title>Functions</title>
e27b0961
 	<para>
278bb47a
     Previous versions of carrierroute had some more function. All the
e27b0961
     old semantics can be achieved by using the few new functions
     like this:
 	</para>
 
   <programlisting format="linespecific">
 cr_rewrite_uri(domain, hash_source)
d955bb91
 -> cr_route("default", domain, "$rU", "$rU", hash_source)
e27b0961
 
 cr_rewrite_by_to(domain, hash_source)
d955bb91
 -> cr_route("default", domain, "$tU", "$rU", hash_source)
e27b0961
 
 cr_rewrite_by_from(domain, hash_source)
d955bb91
 -> cr_route("default", domain, "$fU", "$rU", hash_source)
e27b0961
 
 cr_user_rewrite_uri(uri, domain)
aa4a3b3d
 -> cr_user_carrier(user, domain, "$avp(tree_avp)")
d955bb91
 -> cr_route("$avp(tree_avp)", domain, "$rU", "$rU", "call_id")
e27b0961
 
 cr_tree_rewrite_uri(tree, domain)
d955bb91
 -> cr_route(tree, domain, "$rU", "$rU", "call_id")
e27b0961
   </programlisting>
 		
 	<section>
14679719
 	    <title>
aa4a3b3d
 		<function moreinfo="none">cr_user_carrier(user, domain, dstavp)</function>
14679719
 	    </title>
 	    <para>
e27b0961
       This function loads the carrier and stores it in an AVP.
6a9a02da
       It cannot be used in the config file mode, as it needs a mapping of the
9306b01c
 	  given user to a certain carrier. The is derived from a database entry
 	  belonging to the user parameter. This mapping must be available in the
6a9a02da
 	  table that is specified in the <quote>subscriber_table</quote> variable.
9306b01c
 	  This data is not cached in memory, that means for every execution of this
 	  function a database query will be done.
14679719
 	    </para>
 	    <para>Meaning of the parameters is as follows:</para>
 	    <itemizedlist>
e27b0961
         <listitem>
           <para><emphasis>user</emphasis> - Name of the user for the carrier tree lookup.
             Additional to a string any pseudo-variable could
             be used as input.
 		      </para>
         </listitem>
         <listitem>
           <para><emphasis>domain</emphasis> - Name of the routing domain to be used.
             Additional to a string any pseudo-variable could
             be used as input.
 		      </para>
         </listitem>
 	      <listitem>
           <para><emphasis>dstavp</emphasis> - Name of the AVP where to store the carrier id.
 		      </para>
         </listitem>
14679719
 	    </itemizedlist>
60b5fe93
 	</section>
 	<section>
 	    <title>
0d6a3802
 		<function moreinfo="none">cr_route(carrier, domain, prefix_matching, rewrite_user, hash_source, descavp)</function>
60b5fe93
 	    </title>
 	    <para>
e27b0961
         This function searches for the longest match for the user given
         in prefix_matching at the given domain in the given carrier tree.
         The Request URI is rewritten using rewrite_user and the given
         hash source and algorithm. Returns -1 if there is no data found
0d6a3802
         or an empty rewrite host on the longest match is found. On sucess
         also the description is stored in the given AVP (if obmitted, nothing
         is stored in an AVP). This is useful if you need some additional
         informations that belongs to each gw, like the destination or the
         number of channels.
6bb98ddd
 		</para>
 		<para>
f09551a9
 		Depending on the value of the avoid_failed_destinations module parameter,
 		the function pays special attention to the failurerouting cases, so that
6bb98ddd
 		any destination that has failed to provide a successful response will not
 		be reused in a subsequent call of cr_route. This situation can appear when
 		different route domains contain a set of common gateways.
 		</para>
b516feb8
         <para>
e27b0961
         This function is only usable with rewrite_user and prefix_matching
892c7710
         containing a valid string. This string needs to be numerical if the match_mode
b516feb8
         parameter is set to 10. It uses the standard CRC32 algorithm to calculate
         the hash values.
         </para>
         <para>
         If flags and masks values are specified in the routing rule, they will be
         compared by this function to the message flags. Specify a flag and mask value of
         <quote>0</quote> to match to all possible message flags (this is the default value).
         If flags and mask are not zero, and no match to the message flags is possible, no
         routing will be done. The calculation of the hash and the load-balancing is done
         after the flags matching.
60b5fe93
 	    </para>
 	    <para>Meaning of the parameters is as follows:</para>
 	    <itemizedlist>
e27b0961
         <listitem>
 		      <para><emphasis>carrier</emphasis> - The routing tree to be used. Additional to a string
             any pseudo-variable could be used as input.
   		    </para>
         </listitem>
         <listitem>
 		      <para><emphasis>domain</emphasis> - Name of the routing domain to be used.
             Additional to a string any pseudo-variable could
             be used as input.
   		    </para>
         </listitem>
         <listitem>
 		      <para><emphasis>prefix_matching</emphasis> - User name to be used for prefix matching
             in the routing tree.
             Additional to a string any pseudo-variable could
             be used as input.
   		    </para>
         </listitem>
         <listitem>
 		      <para><emphasis>rewrite_user</emphasis> - The user name to be used for applying the
             rewriting rule. Usually this is the user part of the request
             URI. Additional to a string any pseudo-variable could
             be used as input.
   		    </para>
         </listitem>
         <listitem>
 		      <para><emphasis>hash_source</emphasis> - The hash values of the destination set must
             be a contiguous range starting at 1, limited by the
             configuration parameter max_targets. Possible values for
3b701407
             hash_source are: call_id, from_uri, from_user, to_uri,
             to_user and rand
e27b0961
   		    </para>
         </listitem>
         <listitem>
0d6a3802
 		      <para><emphasis>decsavp</emphasis> - Name of the AVP where to store the description.
940d1c1f
 			This parameter is optional.
   		    </para>
         </listitem>
 	    </itemizedlist>
 	</section>
8dc53feb
 		<section>
 	    <title>
 		<function moreinfo="none">cr_nofallback_route(carrier, domain, prefix_matching, rewrite_user, hash_source, descavp)</function>
 	    </title>
 	    <para>
         This function searches for the longest match for the user given
         in prefix_matching at the given domain in the given carrier tree.
         The Request URI is rewritten using rewrite_user and the given
         hash source and algorithm. Returns -1 if there is no data found
         or an empty rewrite host on the longest match is found. On success
         also the description is stored in the given AVP (if obmitted, nothing
         is stored in an AVP). This is useful if you need some additional
         informations that belongs to each gw, like the destination or the
         number of channels.
         This function is only usable with rewrite_user and prefix_matching
         containing a valid string. This string needs to be numerical if the match_mode
         parameter is set to 10.
 	    </para>
 	    <para>
 		It uses the standard CRC32 algorithm to calculate the hash values. In contrast
 		to the normal <emphasis>cr_route</emphasis> function the backup
7b898cec
 		rules of (now obselete) cr_prime_route is used. This means not the configured
8dc53feb
 		probabilities will be used, only a fixed hash distribution. This
 		makes sense to distribute incoming register requests e.g. to a bunch of
 		registrar servers. If one of the hash targets is not available and
 		backup rule is configured, the function will return -1.
 	    </para>
 	    <para>Meaning of the parameters is as follows:</para>
 	    <itemizedlist>
         <listitem>
 		      <para><emphasis>carrier</emphasis> - The routing tree to be used. Additional to a string
             any pseudo-variable could be used as input.
 		      </para>
         </listitem>
         <listitem>
 		      <para><emphasis>domain</emphasis> - Name of the routing domain to be used.
             Additional to a string any pseudo-variable could
             be used as input.
 		      </para>
         </listitem>
         <listitem>
 		      <para><emphasis>prefix_matching</emphasis> - User name to be used for prefix matching
             in the routing tree.
             Additional to a string any pseudo-variable could
             be used as input.
 		      </para>
         </listitem>
         <listitem>
 		      <para><emphasis>rewrite_user</emphasis> - The user name to be used for applying the
             rewriting rule. Usually this is the user part of the request
             URI. Additional to a string any pseudo-variable could
             be used as input.
 		      </para>
         </listitem>
         <listitem>
 		      <para><emphasis>hash_source</emphasis> - The hash values of the destination set must
             be a contiguous range starting at 1, limited by the
             configuration parameter max_targets. Possible values for
             hash_source are: call_id, from_uri, from_user, to_uri
             and to_user.
 		      </para>
         </listitem>
         <listitem>
 		      <para><emphasis>descavp</emphasis> - Name of the AVP where to store the description.
 			This parameter is optional.
 		      </para>
         </listitem>
 	    </itemizedlist>
 	</section>
 
60b5fe93
 	<section>
 	    <title>
883aff8d
 		<function moreinfo="none">cr_next_domain(carrier, domain, prefix_matching, host, reply_code, dstavp)</function>
60b5fe93
 	    </title>
 	    <para>
e27b0961
         This function searches for the longest match for the user given
         in prefix_matching at the given domain in the given carrier
         failure tree. It tries to find a next domain matching the given
883aff8d
         host, reply_code and the message flags. The matching is done in this order:
e27b0961
         host, reply_code and then flags. The more wildcards in reply_code
         and the more bits used in flags, the lower the priority.
         Returns -1 if there is no data found or an empty next_domain on
         the longest match is found. Otherwise the next domain is stored
         in the given AVP.
892c7710
         This function is only usable with rewrite_user and prefix_matching
         containing a valid string. This string needs to be numerical if the match_mode
 		parameter is set to 10.
60b5fe93
 	    </para>
 	    <para>Meaning of the parameters is as follows:</para>
 	    <itemizedlist>
e27b0961
         <listitem>
 		      <para><emphasis>carrier</emphasis> - The routing tree to be used. Additional to a string
             any pseudo-variable could be used as input.
   		    </para>
         </listitem>
         <listitem>
 		      <para><emphasis>domain</emphasis> - Name of the routing domain to be used.
             Additional to a string any pseudo-variable could
             be used as input.
   		    </para>
         </listitem>
         <listitem>
 		      <para><emphasis>prefix_matching</emphasis> - User name to be used for prefix matching
             in the routing tree.
             Additional to a string any pseudo-variable could
             be used as input.
   		    </para>
         </listitem>
         <listitem>
 		      <para><emphasis>host</emphasis> - The host name to be used for failure route rule
             matching. Usually this is the last tried routing destination
             stored in an avp by cr_route. Additional to a string any
             pseudo-variable could be used as input.
   		    </para>
         </listitem>
         <listitem>
 		      <para><emphasis>reply_code</emphasis> - The reply code to be used for failure route rule
             matching. Additional to a string any pseudo-variable
             could be used as input.
   		    </para>
         </listitem>
         <listitem>
 		      <para><emphasis>dstavp</emphasis> - Name of the AVP where to store the next routing domain.
   		    </para>
         </listitem>
60b5fe93
 	    </itemizedlist>
 	</section>
     </section>
 
     <section>
 	    <title><acronym>MI</acronym> Commands</title>
614f67f5
 		<para>All commands understand the "-?" parameter to print a short help message.
 		The options have to be quoted as one string to be passed to MI interface.
 		Each option except host and new host can be wildcarded by * (but only * and not things
 		like "-d prox*").</para>
60b5fe93
 	<section>
088f1d09
 	    <title><function moreinfo="none">cr_reload_routes</function></title>
60b5fe93
 	    <para>
 		This command reloads the routing data from the data source.
2b31121f
 		</para>
 		<para>
 		Important: When new domains have been added, a restart of the server must be
 		done, because the mapping of the ids used in the config script cannot be
 		updated at runtime at the moment. So a reload could result in a wrong routing
 		behaviour, because the ids used in the script could differ from the one used
 		internally from the server. Modifying of already existing domains is no problem.
60b5fe93
 	    </para>
 	</section>
 	<section>
088f1d09
 	    <title><function moreinfo="none">cr_dump_routes</function></title>
60b5fe93
 	    <para>
 		This command prints the route rules on the command line.
 	    </para>
 	</section>
 	<section>
088f1d09
 	    <title><function moreinfo="none">cr_replace_host</function></title>
60b5fe93
 	    <para>
 		This command can replace the rewrite_host of a route rule, it is only
 		usable in file mode. Following options are possible:
 	    </para>
 	    <itemizedlist>
 		<listitem>
 		    <para><emphasis>-d</emphasis> - the domain containing the host</para>
 	        </listitem>
 		<listitem>
 		    <para><emphasis>-p</emphasis> - the prefix containing the host</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-h</emphasis> - the host to be replaced</para>
 		</listitem>
 		<listitem>
 			<para><emphasis>-t</emphasis> - the new host</para>
 		</listitem>
 	    </itemizedlist>
614f67f5
 	    <para>Use the "null" prefix to specify an empty prefix.</para>
60b5fe93
 	    <example>
1deaa69e
 		<title><function>cr_replace_host</function> usage</title>
60b5fe93
 		<programlisting format="linespecific">
 ...
93eb30d6
 &ctltool; fifo cr_replace_host "-d proxy -p 49 -h proxy1 -t proxy2"
60b5fe93
 ...
 		</programlisting>
 	    </example>
 	</section>
 	<section>
088f1d09
 	    <title><function moreinfo="none">cr_deactivate_host</function></title>
60b5fe93
 	    <para>
 		    This command deactivates the specified host, i.e. it sets its status to 0.
 		    It is only usable in file mode. Following options are possible:
 	    </para>
 	    <itemizedlist>
 		<listitem>
 		    <para><emphasis>-d</emphasis> - the domain containing the host</para>
 	        </listitem>
 		<listitem>
 		    <para><emphasis>-p</emphasis> - the prefix containing the host</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-h</emphasis> - the host to be deactivated</para>
 		</listitem>
614f67f5
 		<listitem>
 			<para><emphasis>-t</emphasis> - the new host used as backup</para>
 		</listitem>
60b5fe93
 	    </itemizedlist>
614f67f5
 	    <para>When -t (new_host) is specified, the portion of traffic for the deactivated host
 		is routed to the host given by -t. This is indicated in the output of dump_routes.
 		The backup route is deactivated if the host is activated again.</para>
 		<para>Use the "null" prefix to specify an empty prefix.</para>
60b5fe93
 	    <example>
1deaa69e
 		<title><function>cr_deactivate_host</function> usage</title>
60b5fe93
 		<programlisting format="linespecific">
 ...
93eb30d6
 &ctltool; fifo cr_deactivate_host "-d proxy -p 49 -h proxy1"
60b5fe93
 ...
 		</programlisting>
 	    </example>
 	</section>
 	<section>
088f1d09
 	    <title><function moreinfo="none">cr_activate_host</function></title>
60b5fe93
 	    <para>
 		    This command activates the specified host, i.e. it sets its status to 1.
 		    It is only usable in file mode. Following options are possible:
 	    </para>
 	    <itemizedlist>
 		<listitem>
 		    <para><emphasis>-d</emphasis> - the domain containing the host</para>
 	        </listitem>
 		<listitem>
 		    <para><emphasis>-p</emphasis> - the prefix containing the host</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-h</emphasis> - the host to be activated</para>
 		</listitem>
 	    </itemizedlist>
614f67f5
 	    <para>Use the "null" prefix to specify an empty prefix.</para>
60b5fe93
 	    <example>
1deaa69e
 		<title><function>cr_activate_host</function> usage</title>
60b5fe93
 		<programlisting format="linespecific">
 ...
93eb30d6
 &ctltool; fifo cr_activate_host "-d proxy -p 49 -h proxy1"
60b5fe93
 ...
 		</programlisting>
 	    </example>
 	</section>
 
 	<section>
088f1d09
 	    <title><function moreinfo="none">cr_add_host</function></title>
60b5fe93
 	    <para>
 		    This command adds a route rule, it is only usable in file mode. Following options
 		    are possible:
 	    </para>
 	    <itemizedlist>
 		<listitem>
 		    <para><emphasis>-d</emphasis> - the domain containing the host</para>
 	        </listitem>
 		<listitem>
 		    <para><emphasis>-p</emphasis> - the prefix containing the host</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-h</emphasis> - the host to be added</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-w</emphasis> - the weight of the rule</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-P</emphasis> - an optional rewrite prefix</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-S</emphasis> - an optional rewrite suffix</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-i</emphasis> - an optional hash index</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-s</emphasis> - an optional strip value</para>
d9d8064d
 		</listitem>
60b5fe93
 	    </itemizedlist>
614f67f5
 		<para>Use the "null" prefix to specify an empty prefix.</para>
60b5fe93
 	    <example>
1deaa69e
 		<title><function>cr_add_host</function> usage</title>
60b5fe93
 		<programlisting format="linespecific">
 ...
93eb30d6
 &ctltool; fifo cr_add_host "-d proxy -p 49 -h proxy1 -w 0.25"
60b5fe93
 ...
 		</programlisting>
 	    </example>
 	</section>
 
 	<section>
088f1d09
 	    <title><function moreinfo="none">cr_delete_host</function></title>
60b5fe93
 	    <para>
 		    This command delete the specified hosts or rules, i.e. remove 
 		    them from the route tree. It is only usable in file mode.
 		    Following options are possible:
 	    </para>
 	    <itemizedlist>
 		<listitem>
 		    <para><emphasis>-d</emphasis> - the domain containing the host</para>
 	        </listitem>
 		<listitem>
 		    <para><emphasis>-p</emphasis> - the prefix containing the host</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-h</emphasis> - the host to be added</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-w</emphasis> - the weight of the rule</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-P</emphasis> - an optional rewrite prefix</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-S</emphasis> - an optional rewrite suffix</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-i</emphasis> - an optional hash index</para>
 		</listitem>
 		<listitem>
 		    <para><emphasis>-s</emphasis> - an optional strip value</para>
d9d8064d
 		</listitem>
60b5fe93
 	    </itemizedlist>
614f67f5
 	    <para>Use the "null" prefix to specify an empty prefix.</para>
1deaa69e
 	    <example>
 		<title><function>cr_delete_host</function> usage</title>
 		<programlisting format="linespecific">
 ...
93eb30d6
 &ctltool; fifo cr_delete_host "-d proxy -p 49 -h proxy1 -w 0.25"
1deaa69e
 ...
 		</programlisting>
 	    </example>
60b5fe93
 	</section>
     </section>
     <section>
e098b963
 	<title>Configuration examples</title>
60b5fe93
 	<example>
e27b0961
 		<title>Configuration example - Routing to default tree</title>
60b5fe93
 		<programlisting format="linespecific">
 ...
2169e97d
 route {
 	# route calls based on hash over callid
67215f10
 	# choose route domain 0 of the default carrier
e27b0961
 	
18a91e77
 	if(!cr_route("default", "0", "$rU", "$rU", "call_id")){
2169e97d
 		sl_send_reply("403", "Not allowed");
 	} else {
 		# In case of failure, re-route the request
 		t_on_failure("1");
 		# Relay the request to the gateway
 		t_relay();
 	}
 }
 
7dd5c92f
 failure_route[1] {
bf570f4b
 	revert_uri();
2169e97d
 	# In case of failure, send it to an alternative route:
 	if (t_check_status("408|5[0-9][0-9]")) {
bf570f4b
 	#choose route domain 1 of the default carrier
18a91e77
 	if(!cr_route("default", "1", "$rU", "$rU", "call_id")){
2169e97d
 			t_reply("403", "Not allowed");
 		} else {
 			t_on_failure("2");
 			t_relay();
 		}
 	}
 }
 
7dd5c92f
 failure_route[2] {
2169e97d
 	# further processing
60b5fe93
 }
e27b0961
 
 		</programlisting>
 	</example>
 	
 	<example>
 		<title>Configuration example - Routing to user tree</title>
 		<programlisting format="linespecific">
 ...
 route[1] {
6a9a02da
 	cr_user_carrier("$fU", "$fd", "$avp(s:carrier)");
e27b0961
 
6a9a02da
 	# just an example domain
 	$avp(s:domain)="start";
 	if (!cr_route("$avp(s:carrier)", "$avp(s:domain)", "$rU", "$rU",
0d6a3802
 			"call_id")) {
e27b0961
 		xlog("L_ERR", "cr_route failed\n");
 		exit;
 	}
0d6a3802
 	# if you store also the port as part of the rewrite host,
 	# otherwise you can just use $rd later
 	$avp(s:host)= $rd+":"+$rp;
e27b0961
 	t_on_failure("1");
 		if (!t_relay()) {
 			sl_reply_error();
 	};
 }
 
 failure_route[1] {
 	revert_uri();
6a9a02da
 	if (!cr_next_domain("$avp(s:carrier)", "$avp(s:domain)", "$rU",
 			"$avp(s:host)", "$T_reply_code", "$avp(s:domain)")) {
aa4a3b3d
 		xlog("L_ERR", "cr_next_domain failed\n");
 		exit;
 	}
6a9a02da
 	if (!cr_route("$avp(s:carrier)", "$avp(s:domain)", "$rU", "$rU",
0d6a3802
 			"call_id")) {
aa4a3b3d
 		xlog("L_ERR", "cr_route failed\n");
 		exit;
 	}
0d6a3802
 	$avp(s:host)= $rd+":"+$rp;
aa4a3b3d
 	t_on_failure("1");
 	if (!t_relay()) {
 		xlog("L_ERR", "t_relay failed\n");
 		exit;
 	};
e27b0961
 }
60b5fe93
 ...
 		</programlisting>
 	</example>
 
e27b0961
 			
60b5fe93
 	<example>
 		<title>Configuration example - module configuration</title>
ef6551fe
 		<para>
 			The following config file specifies within the default carrier two
 			domains, each with an prefix that contains two hosts. It is not possible
 			to specify another carrier if you use the config file as data source.
 		</para>
 		<para>
 			All traffic will be equally distributed between the hosts, both are
 			active. The hash algorithm will working over the [1,2] set, messages
 			hashed to one will go to the first host, the other to the second one.
 			Don't use a hash index value of zero. If you ommit the hash completly,
 			the module gives them a autogenerated value, starting from one.
 		</para>
 		<para>
d4a6ccb0
 			Use the <quote>NULL</quote> prefix to specify an empty prefix in the config file.
7dd5c92f
 			Please note that the prefix is matched against the request URI (or to URI),
892c7710
 			if they did not contain a valid (numerical) URI, no match is possible. So
7dd5c92f
 			for loadbalancing purposes e.g. for your registrars, you should use an empty
 			prefix.
e24c1b13
 		</para>
60b5fe93
 		<programlisting format="linespecific">
 ...
 domain proxy {
    prefix 49 {
896b7ab8
      max_targets = 2
ef6551fe
       target proxy1.localdomain {
          prob = 0.500000
          hash_index = 1
          status = 1
          comment = "test target 1"
       }
       target proxy2.localdomain {
          prob = 0.500000
          hash_index = 2
          status = 1
          comment = "test target 2"
       }
    }
 }
 
 domain register {
7dd5c92f
    prefix NULL {
896b7ab8
      max_targets = 2
ef6551fe
       target register1.localdomain {
60b5fe93
          prob = 0.500000
          hash_index = 1
          status = 1
          comment = "test target 1"
       }
ef6551fe
       target register2.localdomain {
60b5fe93
          prob = 0.500000
          hash_index = 2
          status = 1
          comment = "test target 2"
       }
    }
 }
 ...
 		</programlisting>
 	</example>
     </section>
 
     <section>
d9d8064d
 	<title>Installation and Running</title>
60b5fe93
 	<section>
 		<title>Database setup</title>
 		<para>
912dc8e8
 			Before running &kamailio; with carrierroute, you have to setup the database 
60b5fe93
 			table where the module will store the routing data. For that, if 
 			the table was not created by the installation script or you choose
 			to install everything by yourself you can use the carrierroute-create.sql
 			<acronym>SQL</acronym> script in the database directories in the 
39c1da61
 			kamailio/scripts folder as template. 
60b5fe93
 			Database and table name can be set with module parameters so they 
 			can be changed, but the name of the columns must be as they are 
 			in the <acronym>SQL</acronym> script.
 			You can also find the complete database documentation on the
912dc8e8
 			project webpage, &kamailiodbdocs;.
883aff8d
 			The flags and mask columns have the same function as in the
 			carrierfailureroute table. A zero value in the flags and mask
 			column means that any message flags will match this rule.
60b5fe93
 		</para>
 		<para>
 			For a minimal configuration either use the config file given above, or
 			insert some data into the tables of the module.
 		</para>
e098b963
 	</section>
 	
 	<section>
 		<title>Database examples</title>
60b5fe93
 	<example>
 		<title>Example database content - carrierroute table</title>
 		<programlisting format="linespecific">
 ...
883aff8d
 +----+---------+--------+-------------+-------+------+---------------+
 | id | carrier | domain | scan_prefix | flags | prob | rewrite_host  |
 +----+---------+--------+-------------+-------+------+---------------+
68b6d2a9
 | 1  |       1 |      1 | 49          |     0 |  0.5 | de-1.carrier1 |
 | 2  |       1 |      1 | 49          |     0 |  0.5 | de-2.carrier1 |
 | 3  |       1 |      1 | 49          |    16 |    1 | de-3.carrier1 |
 | 4  |       1 |      1 |             |     0 |    1 | gw.carrier1-1 |
 | 5  |       1 |      2 | 49          |     0 |    1 | gw.carrier1-1 |
 | 6  |       1 |      3 |             |     0 |    1 | gw.carrier1-2 |
 | 7  |       1 |      4 |             |     0 |    1 | gw.carrier1-3 |
 | 8  |       2 |      1 | 49          |     0 |  0.5 | de-1.carrier2 |
 | 9  |       2 |      1 | 49          |     0 |  0.5 | de-2.carrier2 |
 | 10 |       2 |      1 |             |     0 |    1 | gw.carrier2   |
 | 11 |       2 |      2 | 49          |     0 |    1 | gw.carrier2   |
8efd99bc
 | 12 |       3 |      8 | 49          |     0 |    1 | de-gw.default |
 | 13 |       3 |      8 |             |     0 |    1 | gw.default    |
883aff8d
 +----+---------+--------+-------------+-------+------+---------------+
60b5fe93
 ...
 		</programlisting>
 	</example>
 		<para>
883aff8d
 			This table contains three routes to two gateways for the <quote>49</quote> prefix,
118b2890
 			and a default route for other prefixes over carrier 2 and carrier 1. The
 			gateways for the default carrier will be used for functions that don't
 			support the user specific carrier lookup. The routing rules for carrier 1
 			and carrier 2 for the <quote>49</quote> prefix contains a additional rule
68b6d2a9
 			with the domain 2, that can be used for example as fallback if the gateways
 			in domain 1 are not reachable. Two more fallback rules (domain 3 and 4) for 
e27b0961
 			carrier 1 are also supplied to support the functionality of the carrierfailureroute
e098b963
 			table example that is provided in the next section.
60b5fe93
 		</para>
883aff8d
 		<para>
e098b963
 			This table provides also a <quote>carrier 1</quote> routing rule for the
883aff8d
 			<quote>49</quote> prefix, that is only choosen if some message flags are set.
 			If this flags are not set, the other two rules are used. The <quote>strip</quote>,
 			<quote>mask</quote> and <quote>comment</quote> colums are omitted for brevity.
 		</para>
e27b0961
 	<example>
 		<title>Example database content - simple carrierfailureroute table</title>
 		<programlisting format="linespecific">
 ...
 +----+---------+--------+---------------+------------+-------------+
 | id | carrier | domain | host_name     | reply_code | next_domain |
 +----+---------+--------+---------------+------------+-------------+
68b6d2a9
 |  1 |       1 | 1      | gw.carrier1-2 | ...        | 3           |
 |  2 |       1 | 1      | gw.carrier1-3 | ...        | 2           |
e27b0961
 +----+---------+--------+---------------+------------+-------------+
 ...
 </programlisting>
 	</example>
 		<para>
 			This table contains two failure routes for the <quote>gw.carrier1-1</quote> and
 			<quote>-2</quote> gateways. For any (failure) reply code the respective next
 			domain is choosen. After that no more failure routes are available, an error will
aa4a3b3d
 			be returned from the <quote>cr_next_domain</quote> function. Not all table
e27b0961
 			colums are show here for brevity.
 		</para>
940d1c1f
 		<para>
 			For each failure route domain and carrier that is added to the carrierfailureroute
 			table there must be at least one corresponding entry in the carrierroute table,
 			otherwise the module will not load the routing data.
 		</para>
e27b0961
 
 	<example>
 		<title>Example database content - more complex carrierfailureroute table</title>
 		<programlisting format="linespecific">
 ...
 +----+---------+-----------+------------+--------+-----+-------------+
 | id | domain  | host_name | reply_code | flags | mask | next_domain |
 +----+---------+-----------+------------+-------+------+-------------+
 |  1 |      99 |           | 408        |    16 |   16 |             |
 |  2 |      99 | gw1       | 404        |     0 |    0 | 100         |
 |  3 |      99 | gw2       | 50.        |     0 |    0 | 100         |
8efd99bc
 |  4 |      99 |           | 404        |  2048 | 2112 | 101         |
77ef284f
 +----+---------+-----------+------------+-------+------+-------------+
e27b0961
 ...
 </programlisting>
 	</example>
 		<para>
 			This table contains four failure routes that shows the usage of more
 			advanced features. The first route matches to a 408, and to some flag
 			for example that indicates that ringing has happened. If this flag is set,
 			there will be no further forwarding, because next_domain is empty. In the
 			second and third routes are certain gateway errors matched, if this errors
cfc11b88
 			have occured, then the next domain will be choosen. Note that the reply_code must be
 			3 characters wide, and only the "." character is accepted as wildcard.The last route
 			does forwarding according some flags, e.g. the customer came from a certain carrier,
e27b0961
 			and has call-forwarding deactivated. In order to use the routing that is
 			specified above, a matching carrierroute table must be provided, that holds
 			domain entries for this routing rules. Not all table colums are show here for
 			brevity.
 		</para>
 
60b5fe93
 	<example>
8efd99bc
 		<title>Example database content - carrier_name table</title>
60b5fe93
 		<programlisting format="linespecific">
 ...
 +----+----------+
 | id | carrier  |
 +----+----------+
 |  1 | carrier1 |
 |  2 | carrier2 |
 |  3 | default  |
 +----+----------+
 ...
 		</programlisting>
 		</example>
 		<para>
ef6551fe
 			This table contains the mapping of the carrier id to actual names.
 		</para>
e098b963
 		<example>
 		<title>Example database content - domain_name table</title>
 		<programlisting format="linespecific">
 ...
 +----+----------+
6a24f519
 | id | domain   |
e098b963
 +----+----------+
 |  1 | domain1  |
 |  2 | domain2  |
 |  3 | domain3  |
 +----+----------+
 ...
 		</programlisting>
 		</example>
 		<para>
 			This table contains the mapping of the domain id to actual names.
 		</para>
 
 	</section>
 	<section>
 		<title>User specific routing</title>
ef6551fe
 		<para>
c2ead767
 			For a functional routing the <quote>cr_preferred_carrier</quote> column must
 			be added to the subscriber table (or to the table and column that you specified
 			as modul parameter) to choose the actual carrier for the users.
60b5fe93
 		</para>
698edd64
 	<example>
 		<title>Necessary extensions for the user table</title>
 		<para>Suggested changes:</para>
 		<programlisting format="linespecific">
 ...
 ALTER TABLE subscriber ADD cr_preferred_carrier int(10) default NULL; 
 ...
 		</programlisting>
 	</example>
60b5fe93
 		</section>
     </section>
 </chapter>