$Revision: 2241 $
$Date: 2007-05-17 19:48:49 +0300 (Thu, 17 May 2007) $
User's Guide
Overview
Least cost routing (LCR) module implements two related capabilities:
sequential forwarding of a request to one or more gateways
(functions load_gws and next_gw)
sequential forwarding to contacts if they don't share the
the same qvalue (functions load_contacts and next_contacts).
Gateway selection is based on caller's RPID URI (if available in
caller's RPID AVP after authentication) or From URI and user part of
Request-URI (telephone number). A gateway matches a request if user
part of Request-URI and "From" URI match the prefix and From pattern
of the gateway. Matching gateways are then ordered for forwarding
purpose (1) according to longest user part match, (2) according to
gateway's priority, and (3) randomly.
Each gateway belongs to a gateway group either alone or among other
gateways. All gateways in a group share the same priority.
Gateway and routing information is kept in two tables: gw and lcr.
When a gateway is selected, the Request-URI user part is stripped by
the number of digits specified in the strip parameter. Subsequently,
the Request-URI is rewritten with information from gw table:
URI scheme, prefix, IP address, port, and transport protocol. Valid
URI scheme values are NULL = sip, 1 = sip and 2 = sips. Prefix is
appended in front of Request-URI user part. Currently valid transport
protocol values are NULL = none, 1 = udp, 2 = tcp, and 3 = tls.
Table lcr contains prefix of user part of Request-URI, From URI,
gateway group id, and priority. From URI is a regular
expression. Empty From URI pattern matches any From
URI. Smaller priority value means higher priority (highest
priority value being 0).
In addition to gw and lcr tables there is third table gw_grp that is
used to associate names with gateway group ids.
Dependencies
&ser; modules
The following modules must be loaded before this module:
TM module
A database module like mysql, postgres or
dbtext.
External libraries or applications
The following libraries or applications must be installed before
running &ser; with this module:
none.
Exported Parameters
<varname>db_url</varname> (string)
&url; of the database table to be used.
Default value is
mysql://openserro:openserro@localhost/openser
.
Setting <varname>db_url</varname> module parameter
...
modparam("lcr","db_url","mysql://muser:pwd@localhost/openser")
...
<varname>gw_table</varname> (string)
Name of the table holding the gateways definitions.
Default value is gw
.
Setting <varname>gw_table</varname> module parameter
...
modparam("lcr","gw_table","gw")
...
<varname>gw_name_column</varname> (string)
Name of the column holding the gateway name.
Default value is gw_name
.
Setting <varname>gw_name_column</varname> module parameter
...
modparam("lcr","gw_name_column","gw_name")
...
<varname>ip_addr_column</varname> (string)
Name of the column holding the IP address of the gateway.
Default value is ip_addr
.
Setting <varname>ip_addr_column</varname> module parameter
...
modparam("lcr","ip_addr_column","ip_addr")
...
<varname>port_column</varname> (string)
Name of the column holding the port number of the gateway.
Default value is port
.
Setting <varname>port_column</varname> module parameter
...
modparam("lcr","port_column","port")
...
<varname>uri_scheme_column</varname> (string)
Name of the column holding the uri scheme of the gateway.
Default value is uri_scheme
.
Setting <varname>uri_scheme_column</varname> module
parameter
...
modparam("lcr","uri_scheme_column","scheme")
...
<varname>transport_column</varname> (string)
Name of the column holding the transport type to be used for
the gateway.
Default value is transport
.
Setting <varname>transport_column</varname> module
parameter
...
modparam("lcr","transport_column","transport")
...
<varname>grp_id_column</varname> (string)
Name of the column holding the group ID.
Default value is grp_id
.
Setting <varname>grp_id_column</varname> module parameter
...
modparam("lcr","grp_id_column","grp_id")
...
<varname>lcr_table</varname> (string)
Name of the table holding the LCR rules.
Default value is lcr
.
Setting <varname>lcr_table</varname> module parameter
...
modparam("lcr","lcr_table","lcr")
...
<varname>strip_column</varname> (string)
Name of the column holding the number of digits to strip from the RURI before applying the prefix.
Default value is strip
.
Setting <varname>strip_column</varname> module parameter
...
modparam("lcr","strip_column","strip")
...
<varname>prefix_column</varname> (string)
Name of the column holding the RURI(destination) prefix.
Default value is prefix
.
Setting <varname>prefix_column</varname> module parameter
...
modparam("lcr","prefix_column","prefix")
...
<varname>from_uri_column</varname> (string)
Name of the column holding the FROM (source) URI.
Default value is from_uri
.
Setting <varname>from_uri_column</varname> module parameter
...
modparam("lcr","from_uri_column","from_uri")
...
<varname>priority_column</varname> (string)
Name of the column holding the priority of the rule.
Default value is priority
.
Setting <varname>priority_column</varname> module parameter
...
modparam("lcr","priority_column","priority")
...
<varname>gw_uri_avp</varname> (string)
Overrides the name of the AVP containing URI scheme, host, port, and
transport of a gateway. If the string name of the AVP contains only
digits, the name of the AVP is integer value of the string.
Default value is 1400
.
Setting <varname>gw_uri_avp</varname> module parameter
...
modparam("lcr","gw_uri_avp","1400")
...
<varname>ruri_user_avp</varname> (string)
Overrides the name of the AVP containing user part of Request-URI
after the first next_gw() call. If the string
name of the AVP contains only digits, the name of the AVP is integer
value of the string.
Default value is 1402
.
Setting <varname>ruri_user_avp</varname> module parameter
...
modparam("lcr","ruri_user_avp","500")
...
<varname>contact_avp</varname> (string)
Overrides the name of the AVP containing the contact. If the string
name of the AVP contains only digits, the name of the AVP is integer
value of the string.
Default value is 1401
.
Setting <varname>contact_avp</varname> module parameter
...
modparam("lcr","contact_avp","1401")
...
<varname>fr_inv_timer_avp</varname> (string)
Overrides the name of the AVP carrying the Final Response timeout
for INVITEs.
Default value is fr_inv_timer_avp
.
Setting <varname>fr_inv_timer_avp</varname> module parameter
...
modparam("lcr","fr_inv_timer_avp","fr_inv_timer_avp")
...
<varname>fr_inv_timer</varname> (integer)
Sets the value of the fist INVITE's Final Response timeout to be used
during sequential forwarding:
Default value is 90.
Setting <varname>fr_inv_timer</varname> module parameter
...
modparam("lcr","fr_inv_timer",90)
...
<varname>fr_inv_timer_next</varname> (integer)
Sets the value of the next INVITE's Final Response timeouts to be used
during sequential forwarding:
Function next_contacts() sets tm fr_inv_timer to fr_inv_timer_next
value if, after next contacts, there are still lower qvalue
contacts available, and to fr_inv_timer value if next contacts are
the last ones left.
Default value is 30.
Setting <varname>fr_inv_timer_next</varname> module parameter
...
modparam("lcr","fr_inv_timer_next",30)
...
<varname>rpid_avp</varname> (string)
Sets the string name of the AVP containing the RPID.
Default value is rpid
.
Setting <varname>rpid_avp</varname> module parameter
...
modparam("lcr","rpid_avp","rpid")
...
Exported Functions
<function moreinfo="none">load_gws([group-id])</function>
Loads URI schemes, addresses, ports, and transports of gateways
that match user part of Request-URI to gw_uri_avp AVPs (see Overview
section). If an optional group-id is specified, only gateways belonging
to this group are loaded.
Returns 1 or -1 depending on success.
This function can be used from REQUEST_ROUTE.
<function>load_gws</function> usage
...
if (!load_gws()) {
sl_send_reply("500", "Server Internal Error - Cannot load gateways");
exit;
};
...
<function>load_gws</function> usage with group-id
...
if (!load_gws("1")) {
sl_send_reply("500", "Server Internal Error - Cannot load gateways from group 1");
exit;
};
...
<function moreinfo="none">next_gw()</function>
If called from a route block, replaces URI scheme, host, port, and
transport of Request-URI by the values stored in first gw_uri_avp AVP
and destroys that AVP. Saves user part of Request-URI into
ruri_user_avp AVP for use in subsequent next_gw() calls.
If called from a failure route block, appends a new branch to
request, where URI scheme, host, port, and transport of Request-URI
is replaced by the values stored in the first gw_uri_avp AVP and
destroys that AVP. Request-URI user is taken from ruri_user_avp
AVP.
Returns 1 on success and -1 if there were no gateways left or if an
error occurred (see syslog).
Must be preceded by successful load_gws() call.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
<function>next_gw</function> usage from a route block
...
if (!next_gw()) {
sl_send_reply("503", "Service not available - No gateways");
exit;
};
...
<function>next_gw</function> usage from a failure route block
...
if (!next_gw()) {
t_reply("503", "Service not available - No more gateways");
exit;
};
...
<function moreinfo="none">from_gw([group-id])</function>
Checks if request came from IP address of a gateway. If an
optional group-id is given, only gateways belonging to this
group are checked.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
ONREPLY_ROUTE.
<function>from_gw</function> usage
...
if (from_gw()) {
...
exit;
};
...
<function>from_gw</function> usage with group-id
...
if (from_gw("1")) {
...
exit;
};
...
<function moreinfo="none">to_gw([group-id])</function>
Checks if in-dialog request goes to a gateway. If an optional
group-id is given, only gateways belonging to this group
are checked.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
<function>to_gw</function> usage
...
if (to_gw()) {
...
exit;
};
...
<function>to_gw</function> usage with group-id
...
if (to_gw("1")) {
...
exit;
};
...
<function moreinfo="none">load_contacts()</function>
Loads contacts in destination set in increasing qvalue order as
values of lcr_contact AVP. If all contacts in the destination set
have the same qvalue, load_contacts() does not do anything thus
minimizing performance impact of sequential forking capability when
it is not needed. Returns 1 if loading of contacts succeeded or
there was nothing to do. Returns -1 on error (see syslog).
This function can be used from REQUEST_ROUTE.
<function>load_contacts</function> usage
...
if (!load_contacts()) {
sl_send_reply("500", "Server Internal Error - Cannot load contacts");
exit;
};
...
<function moreinfo="none">next_contacts()</function>
If called from a route block, replaces Request-URI with the first
lcr_contact AVP value, adds the remaining lcr_contact AVP values
with the same qvalue as branches, and destroys those AVPs. It does
nothing if there are no lcr_contact AVPs. Returns 1 if there were
no errors and -1 if an error occurred (see syslog).
If called from a failure route block, adds the first lcr_contact
AVP value and all following lcr_contact AVP values with the same
qvalue as new branches to request and destroys those AVPs.
Returns 1 if new branches were successfully added and -1 on error
(see syslog) or if there were no more lcr_contact AVPs.
Must be preceded by successful load_contacts() call.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
<function>next_contacts</function> usage from route block
...
if (!next_contacts()) {
sl_send_reply("500", "Server Internal Error");
exit;
} else {
t_relay();
};
...
<function>next_contacts</function> usage from
failure route block
if (next_contacts()) {
t_relay();
};
Exported MI Commands
<function>lcr_reload</function>
Causes lcr module to re-read the contents of gateway table
into memory.
Name: lcr_reload
Parameters: none
MI FIFO Command Format:
:lcr_reload:_reply_fifo_file_
_empty_line_
<function>lcr_dump</function>
Causes lcr module to dump the contents of its in-memory gateway
table.
Name: lcr_dump
Parameters: none
MI FIFO Command Format:
:lcr_dump:_reply_fifo_file_
_empty_line_
Known Limitations
There is an unlikely race condition on lcr reload. If a process uses
in memory gw table, which is reloaded at the same time twice through
FIFO, the second reload will delete the original table still in use
by the process.
TODO
Function load_gws() currently makes an SQL query for the matching
gateways. In order to avoid the query, also lcr table should be
read into memory and the corresponding query should be rewritten in
C.