Copyright © 2005-2009 Juha Heinanen
Revision History | |
---|---|
Revision $Revision$ | $Date$ |
Table of Contents
db_url
(string)
gw_table
(string)
lcr_id_column
(string)
gw_name_column
(string)
grp_id_column
(string)
ip_addr_column
(string)
hostname_column
(string)
port_column
(string)
uri_scheme_column
(string)
transport_column
(string)
strip_column
(string)
tag_column
(string)
weight_column
(string)
flags_column
(string)
defunct_column
(string)
lcr_table
(string)
prefix_column
(string)
from_uri_column
(string)
priority_column
(string)
lcr_count
(integer)
gw_uri_avp
(AVP string)
ruri_user_avp
(AVP string)
flags_avp
(AVP string)
defunct_capability
(integer)
lcr_id_avp
(AVP string)
defunct_gw_avp
(AVP string)
lcr_hash_size
(integer)
fetch_rows
(integer)
List of Examples
db_url
module parametergw_table
module parameterlcr_id_column
module parametergw_name_column
module parametergrp_id_column
module parameterip_addr_column
module parameterhostname_column
module parameterport_column
module parameteruri_scheme_column
module
parametertransport_column
module
parameterstrip_column
module
parametertag_column
module parameterweight_column
module parameterflags_column
module parameterdefunct_column
module parameterlcr_table
module parameterprefix_column
module parameterfrom_uri_column
module parameterpriority_column
module parameter
lcr_count
module
parameter
gw_uri_avp
module parameterruri_user_avp
module parameterflags_avp
module parameterdefunct_capability
module
parameter
lcr_id_avp
module parameterdefunct_gw_avp
module parameterlcr_hash_size
module
parameter
fetch_rows
parameterload_gws
usagenext_gw
usage from a route blocknext_gw
usage from a failure route block
defunct_gw
usagefrom_gw
usagefrom_gw
usageto_gw
usageto_gw
usagelcr.reload
RPC examplelcr.dump_gws
RPC examplelcr.dump_lcr
RPC exampleTable of Contents
db_url
(string)
gw_table
(string)
lcr_id_column
(string)
gw_name_column
(string)
grp_id_column
(string)
ip_addr_column
(string)
hostname_column
(string)
port_column
(string)
uri_scheme_column
(string)
transport_column
(string)
strip_column
(string)
tag_column
(string)
weight_column
(string)
flags_column
(string)
defunct_column
(string)
lcr_table
(string)
prefix_column
(string)
from_uri_column
(string)
priority_column
(string)
lcr_count
(integer)
gw_uri_avp
(AVP string)
ruri_user_avp
(AVP string)
flags_avp
(AVP string)
defunct_capability
(integer)
lcr_id_avp
(AVP string)
defunct_gw_avp
(AVP string)
lcr_hash_size
(integer)
fetch_rows
(integer)
Least cost routing (LCR) module implements capability to serially forward a request to one or more gateways so that the order in which the gateways is tried is based on admin defined "least cost" rules.
LCR module supports many independent LCR instances (gateways and least cost rules). Each such instance has its own LCR identifier.
For the purpose of facilitating least cost routing of requests, each gateway of an LCR instance belongs to a gateway group and each gateway group is associated with one or more <prefix, from pattern, priority> tuples. A gateway matches a request if user part of Request URI matches a prefix and caller's URI matches a from pattern in a tuple that belongs to the group of the gateway.
When function load_gws() is called, matching gateways (that are not currently designated as defunct) are ordered for forwarding purpose (1) according to longest user part match, (2) according to tuple's priority, and (3) gateway's randomized weight within its group. Prefix is a string of characters or NULL. From pattern is a regular expression (see 'man pcresyntax' for syntax), an empty string, or NULL. Empty or NULL from pattern or prefix matches anything. Smaller priority value means higher priority (highest priority value being 0). Weight is an integer value from 1 to 254.
Function next_gw() can then be used to select one gateway at a time for forwarding. Upon each call, user part of original Request URI is first stripped by the number of characters as specified by the gateway's strip count and then prefixed by gateway's tag. Upon first call, if gateway's hostname is NULL, Request URI is rewritten based on gateway's URI scheme, IP address, port, and transport protocol. If hostname is not NULL, Request-URI is rewritten based on gateway's URI scheme and hostname, and destination URI is set based on gateway's URI scheme, IP address, port, and transport protocol. Upon subsequent calls, the same is done, but instead of rewriting Request URI, a new branch is added.
Valid URI scheme values are NULL = sip, 1 = sip and 2 = sips. Currently valid transport protocol values are NULL = none, 1 = udp, 2 = tcp, 3 = tls, and 4 = sctp.
As a side effect of gateway selection, gateway's flags (that may contain information about capabilities of the gateway) are stored into an AVP.
The following modules must be loaded before this module:
TM module
A database module like mysql, postgres or dbtext.
URL of the database table to be used.
Default value is “mysql://openserro:openserro@localhost/openser”.
Example 1.1. Setting db_url
module parameter
... modparam("lcr","db_url","dbdriver://username:password@dbhost/dbname") ...
Name of the table holding gateways definitions.
Default value is “gw”.
Name of the column holding the identifier of LCR instance. Common to both gw and lcr tables.
Default value is “lcr_id”.
Example 1.3. Setting lcr_id_column
module parameter
... modparam("lcr", "lcr_id_column", "lcr_identifier") ...
Name of the column holding the gateway name.
Default value is “gw_name”.
Example 1.4. Setting gw_name_column
module parameter
... modparam("lcr","gw_name_column","gw_name") ...
Name of the column holding the group ID of gateway both in gw and lcr tables.
Default value is “grp_id”.
Example 1.5. Setting grp_id_column
module parameter
... modparam("lcr","grp_id_column","grp_id") ...
Name of the column holding the IP address of the gateway.
Default value is “ip_addr”.
Example 1.6. Setting ip_addr_column
module parameter
... modparam("lcr","ip_addr_column","ip_addr") ...
Name of the column holding gateway's hostname that is used in Request-URI, when request is sent to the gateway. Note that request is not forwarded based on hostname, but based on gateway's IP address in destination uri.
Default value is “hostname”.
Example 1.7. Setting hostname_column
module parameter
... modparam("lcr", "hostname_column","host") ...
Name of the column holding the port number of the gateway.
Default value is “port”.
Name of the column holding the uri scheme of the gateway.
Default value is “uri_scheme”.
Example 1.9. Setting uri_scheme_column
module
parameter
... modparam("lcr","uri_scheme_column","scheme") ...
Name of the column holding the transport type to be used for the gateway.
Default value is “transport”.
Example 1.10. Setting transport_column
module
parameter
... modparam("lcr","transport_column","transport") ...
Name of the column holding the number of characters to be stripped from the front of Request URI user part before inserting tag.
Default value is “strip”.
Example 1.11. Setting strip_column
module
parameter
... modparam("lcr","strip_column","strip_count") ...
Name of the column holding gateway specific tag string.
Default value is “tag”.
Name of the column holding gateway's weight within its group.
Default value is “weight”.
Example 1.13. Setting weight_column
module parameter
... modparam("lcr","weight_column","gw_weight") ...
Name of the column holding gateway specific flag values.
Default value is “flags”.
Example 1.14. Setting flags_column
module parameter
... modparam("lcr","flags_column","gw_flags") ...
Name of the column holding UNIX timestamp telling the time until which the gw is considered as defunct.
Default value is “defunct”.
Example 1.15. Setting defunct_column
module parameter
... modparam("lcr","defunct_column","defunct_until") ...
Name of the table holding the LCR rules.
Default value is “lcr”.
Name of the column holding prefix of Request URI user part.
Default value is “prefix”.
Example 1.17. Setting prefix_column
module parameter
... modparam("lcr","prefix_column","prefix") ...
Name of the column holding the FROM (source) URI.
Default value is “from_uri”.
Example 1.18. Setting from_uri_column
module parameter
... modparam("lcr","from_uri_column","from_uri") ...
Name of the column holding the priority of the rule.
Default value is “priority”.
Example 1.19. Setting priority_column
module parameter
... modparam("lcr","priority_column","priority") ...
Number of LCR instances.
Default value is 1.
Internal AVP that load_gws() function uses to store information of matching gateways.
There is NO default value, thus this variable must be defined in sip-router.cfg.
Example 1.21. Setting gw_uri_avp
module parameter
... modparam("lcr", "gw_uri_avp", "$avp(i:709)") ...
Internal AVP that next_gw function uses to store Request-URI user for subsequent next_gw calls.
There is NO default value, thus this variable must be defined in sip-router.cfg.
Example 1.22. Setting ruri_user_avp
module parameter
... modparam("lcr", "ruri_user_avp", "$avp(i:500)") ...
An AVP where successful next_gw and from_gw functions store gateway's flags.
There is NO default value, thus this variable must be defined in sip-router.cfg.
Example 1.23. Setting flags_avp
module parameter
... modparam("lcr", "flags_avp", "$avp(i:712)") ...
Tells if defunct capability of (non-responsive) gateways is supported. Non-zero value turns on defunct capability.
Default value is 0.
Example 1.24.
Setting defunct_capability
module
parameter
... modparam("lcr", "defunct_capability", 1) ...
Internal AVP that load_gws() function uses to store LCR instance identifier of loaded gateways. Only needed if gateway defunct capability has been activated.
There is NO default value.
Example 1.25. Setting lcr_id_avp
module parameter
... modparam("lcr", "lcr_id_avp", "$avp(s:lcr_id_avp)") ...
Internal AVP that next_gw() function uses to store IP address of the selected gateway for later use by defunct_gw() function. Only needed if gateway defunct capability has been activated.
There is NO default value.
Example 1.26. Setting defunct_gw_avp
module parameter
... modparam("lcr", "defunct_gw_avp", "$avp(s:defunct_gw_avp)") ...
Defines the size of hash table used to store <prefix, from_pattern, priority> tuples. Hashing is done based on prefix. Larger value means less collisions with other prefixes. Hash size value should be a power of 2.
Default value is 128.
The number of the rows to be fetched at once from database when loading data from lcr table. This value can be used to tune the load time at startup. For 1MB of private memory (default) it should be below 3750. In order for this parameter to have effect, database driver must support fetch_result() capability.
Default value is “2000”.
Loads URI schemes, IP addresses, hostnames, ports, and transports of matching gateways to gw_uri_avp (see Overview section). Argument lcr_id specifies the used LCR instance. It can be an integer or a pseudo variable containing an integer value. Caller's URI is given by caller_uri argument, which must be a pseudo variable.
Returns 1 on success and -1 on error.
Execution time of load_gws() function is O(N) * O(M), where N is number of different prefix lengths and M is number of collisions for matching prefix(es) in lcr hash table of the LCR instance.
This function can be used from REQUEST_ROUTE.
Example 1.29. load_gws
usage
... if (!load_gws("1", "$var(caller_uri)")) { sl_send_reply("500", "Server Internal Error - Cannot load gateways"); exit; }; ...
Upon first call, replaces URI scheme, host, port, and transport of Request-URI by the values stored in first gw_uri_avp and destroys that AVP (see Overview section). Saves user part of Request-URI into ruri_user_avp for use in subsequent next_gw() calls.
Upon subsequent calls, appends a new branch URI to the request, where URI scheme, host, port, and transport of are taken from values stored in the first gw_uri_avp and destroys that AVP. URI user is taken from ruri_user_avp.
As a side effect, stores gateway's flags to flags_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.
Example 1.30. next_gw
usage from a route block
... if (!next_gw()) { sl_send_reply("503", "Service not available - No gateways"); exit; }; ...
Example 1.31. next_gw
usage from a failure route block
... if (!next_gw()) { t_reply("503", "Service not available - No more gateways"); exit; }; ...
Defuncts gateway selected by preceding next_gw() call for a period of seconds given as argument. Argument must be a positive integer constant or a pseudo variable with positive integer value. Value of defunct column in database is not updated.
Returns 1 on success and -1 in case of error (see syslog).
Must be preceded by successful next_gw() call.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
Checks if request comes from IP address of a gateway in LCR instance specified by lcr_id argument, which can be an integer constant or a pseudo variable with integer value. IP address to be checked is either taken from source IP address of the request or (if present) from ip_addr pseudo variable argument.
If request comes from a gateway, gateway's flags are stored into flags_avp as side effect.
Returns 1 on success and -1 on failure or on error.
Execution time of from_gw() function is O(log N), where N is number of gateways in the LCR instance.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE.
Checks if request comes from IP address of any gateway. IP address to be checked is either taken from source IP address of the request or (if present) from ip_addr pseudo variable argument.
If any gateway has the IP address, function returns LCR identifier of the gateway. Returns -1 on error or if request does not come from a gateway.
If request comes from a gateway, gateway's flags are stored into flags_avp as side effect.
Execution time of from_gw() function is M * O(log N), where M is number of LCR instances and N is average number of gateways in LCR instances.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE.
Checks if in-dialog request goes to a gateway in LCR instance specified by lcr_id argument. IP address to be checked is either taken from Request-URI hostpart or (if present) from ip_addr pseudo variable argument.
Returns 1 on success and -1 on failure and error.
Execution time of to_gw() function is O(log N), where N is number of gateways in the LCR instance.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
Checks if in-dialog request goes to any gateway. IP address to be checked is either taken from Request-URI hostpart or (if present) from ip_addr pseudo variable argument.
Execution time of to_any_gw() function is M * O(log N), where M is number of LCR instances and N is average number of gateways in LCR instances.
If any gateway has the IP address, returns LCR identifier of the gateway. Returns -1 if request does not go to a gateway and on error.
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
Causes lcr module to re-read the contents of gw and lcr tables into memory.
Reload fails if number of gateways is larger than value of constant MAX_NO_OF_GWS in file lcr_mod.h, which defaults to 128. If you have more than 128 gateways, you need to increase the value of this constant and recompile lcr module.
Name: lcr_reload
Parameters: none
MI FIFO Command Format:
:lcr_reload:_reply_fifo_file_ _empty_line_
Causes lcr module to dump the contents of its in-memory gw table.
Name: lcr_gw_dump
Parameters: none
MI FIFO Command Format:
:lcr_gw_dump:_reply_fifo_file_ _empty_line_
Causes lcr module to re-read the contents of gw and lcr tables into memory.
Name: lcr.reload
Parameters: none
Causes lcr module to dump the contents of its in-memory gw table.
Parameters: none