mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1354 lines
36 KiB
1354 lines
36 KiB
<?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. In the common case of
|
|
a duration less than one day, the value starts with 'PT' followed by
|
|
number of hours, minutes and seconds, e.g., a duration of 8 hours
|
|
and 30 minutes is written 'PT8H30M'. See RFC 2445 DURATION
|
|
specifications for full format.
|
|
</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>PT10M</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>
|
|
|