Table of Contents
db_url
(string)
lcr_gw_table
(string)
id_column
(string)
lcr_id_column
(string)
gw_name_column
(string)
ip_addr_column
(string)
hostname_column
(string)
port_column
(string)
params_column
(string)
uri_scheme_column
(string)
transport_column
(string)
strip_column
(string)
tag_column
(string)
flags_column
(string)
defunct_column
(string)
lcr_rule_table
(string)
prefix_column
(string)
from_uri_column
(string)
mt_tvalue_column
(string)
request_uri_column
(string)
stopper_column
(string)
enabled_column
(string)
lcr_rule_target_table
(string)
rule_id_column
(string)
gw_id_column
(string)
priority_column
(string)
weight_column
(string)
lcr_count
(integer)
gw_uri_avp
(AVP string)
ruri_user_avp
(AVP string)
tag_avp
(AVP string)
flags_avp
(AVP string)
rule_id_avp
(AVP string)
mt_pv_values
(AVP string)
mtree
(string)
defunct_capability
(integer)
lcr_id_avp
(AVP string)
defunct_gw_avp
(AVP string)
lcr_rule_hash_size
(integer)
lcr_gw_count
(integer)
dont_strip_or_prefix_flag
(integer)
priority_ordering
(integer)
fetch_rows
(integer)
ping_interval
(integer)
ping_inactivate_threshold
(integer)
ping_valid_reply_codes
(string)
ping_from
(string)
ping_socket
(string)
List of Examples
db_url
module parameterlcr_gw_table
module parameterid_column
module
parameterlcr_id_column
module
parametergw_name_column
module parameterip_addr_column
module
parameterhostname_column
module parameterport_column
module parameterparams_column
module parameteruri_scheme_column
module
parametertransport_column
module
parameterstrip_column
module
parametertag_column
module parameterflags_column
module parameterdefunct_column
module parameterlcr_rule_table
module parameterprefix_column
module
parameterfrom_uri_column
module parameterfrom_uri_column
module parameterrequest_uri_column
module parameterstopper_column
module
parameter
enabled_column
module
parameter
lcr_rule_target_table
module parameterrule_id_column
module
parameter
gw_id_column
module
parameter
priority_column
module
parameterweight_column
module
parameterlcr_count
module
parameter
gw_uri_avp
module
parameterruri_user_avp
module parametertag_avp
module parameterflags_avp
module parameterrule_id_avp
module parametertag_avp
module parametermtree
module parameterdefunct_capability
module
parameter
lcr_id_avp
module
parameterdefunct_gw_avp
module
parameterlcr_rule_hash_size
module
parameter
lcr_gw_count
module parameter
dont_strip_or_prefix_flag
module
parameter
priority_ordering
module
parameter
fetch_rows
parameterping_interval
parameter
ping_inactivate_threshold
parameter
ping_valid_reply_codes
parameter
ping_from
parameter
ping_socket
parameter
load_gws
usagenext_gw
usage from a route blocknext_gw
usage from a failure
route block
inactivate_gw
usagedefunct_gw
usagefrom_gw
usagefrom_gw
usageto_gw
usageto_gw
usagelcr.reload
RPC examplelcr.dump_gws
RPC examplelcr.dump_rules
RPC examplelcr.load_gws
RPC examplelcr.defunct_gw
RPC exampleTable of Contents
db_url
(string)
lcr_gw_table
(string)
id_column
(string)
lcr_id_column
(string)
gw_name_column
(string)
ip_addr_column
(string)
hostname_column
(string)
port_column
(string)
params_column
(string)
uri_scheme_column
(string)
transport_column
(string)
strip_column
(string)
tag_column
(string)
flags_column
(string)
defunct_column
(string)
lcr_rule_table
(string)
prefix_column
(string)
from_uri_column
(string)
mt_tvalue_column
(string)
request_uri_column
(string)
stopper_column
(string)
enabled_column
(string)
lcr_rule_target_table
(string)
rule_id_column
(string)
gw_id_column
(string)
priority_column
(string)
weight_column
(string)
lcr_count
(integer)
gw_uri_avp
(AVP string)
ruri_user_avp
(AVP string)
tag_avp
(AVP string)
flags_avp
(AVP string)
rule_id_avp
(AVP string)
mt_pv_values
(AVP string)
mtree
(string)
defunct_capability
(integer)
lcr_id_avp
(AVP string)
defunct_gw_avp
(AVP string)
lcr_rule_hash_size
(integer)
lcr_gw_count
(integer)
dont_strip_or_prefix_flag
(integer)
priority_ordering
(integer)
fetch_rows
(integer)
ping_interval
(integer)
ping_inactivate_threshold
(integer)
ping_valid_reply_codes
(string)
ping_from
(string)
ping_socket
(string)
The 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.
The LCR module supports many independent LCR instances (gateways and least cost rules). Each such instance has its own LCR instance identifier. Identifiers of normal LCR instances are positive integers. Gateways may belong to special LCR instance with identifier 0 meaning that such gateways belong to all normal LCR instances.
For the purpose of facilitating least cost routing of requests, each gateway of an LCR instance is associated with one or more <prefix, from uri pattern, from uri userpart, request uri pattern, priority, weight> tuples. A gateway matches a request if user part of Request-URI matches "prefix", caller URI matches "from_uri" pattern, caller URI userpart matches mtree with "mt_value", and callee URI matches "request_uri" pattern in a tuple that is associated with the gateway.
When the function load_gws() is called, matching gateways (that are not currently designated as defunct) are ordered for forwarding purposes as follows:
according to longest Request-URI user part match
according to tuple's priority
according to tuple's randomized weight
or, if priority_ordering parameter is set to value 1, as follows:
according to tuple's priority
according to tuple's randomized weight
A tuple can be marked as a "stopper" tuple. If a "stopper" tuple matches, then matching stops at it and all other tuples with shorter prefixes are not considered.
Prefix is a string of characters or NULL. From-URI pattern and Request-URI pattern are regular expressions (see 'man pcresyntax' for syntax), an empty string, or NULL. An empty or NULL From-URI pattern, Request-URI pattern or prefix matches anything. Smaller priority value means higher priority (highest priority value being 0 and lowest being 255).
Weight is an integer value from 1 to 254. Weight implementation is fast, but unfair favoring larger weight values at the expense smaller ones. For example, if two gateways have weights 1 and 2, probability that the gateway with weight 1 is tried first is 1/4, not 1/3. Two scripts are provided in lcr/utils directory that can be used to check the probabilities resulting from a given set of weight values. Same can be done with command 'kamctl eval_weights'.
The function next_gw() can then be used to select one gateway at a time for forwarding. Upon each call, unless "dont_strip_or_prefix_flag" flag is set, user part of the original Request-URI is first stripped by the number of characters as specified by the gateway's strip count and then prefixed by the gateway's prefix. Upon each call, if a gateway's hostname is NULL, Request-URI will be rewritten based on gateway's URI scheme, IP address, port, parameters, and transport protocol. If hostname is not NULL and IP address is NULL, Request-URI will be rewritten based on the gateway's URI scheme, hostname, port, parameters and transport protocol. If both hostname and IP address are not NULL, Request-URI will be rewritten based on gateway's URI scheme, hostname, and parameters, and destination URI is set based on gateway's URI scheme, IP address, port, and transport protocol.
Valid URI scheme values are NULL = sip, 1 = sip and 2 = sips. Currently valid transport protocol values are NULL and 0 = none, 1 = udp, 2 = tcp, 3 = tls, and 4 = sctp.
As a side effect of gateway selection, selected gateway's tag and flags (that may contain information about the gateway and its capabilities) are stored to tag_avp and flags_avp, respectively, if the corresponding module parameter has been defined. In the same way, rule_id_avp, if defined, contains the id of the rule that selected the gateway.
The following modules must be loaded before this module:
A database module like mysql, postgres or dbtext.
mtree module if mt_pv_values parameter is set.
URL of the database table to be used.
Default value is “mysql://kamailioro:kamailioro@localhost/kamailio”.
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 “lcr_gw”.
Name of the auto-increment, primary key column. Common to all lcr module tables.
Default value is “id”.
Name of the column holding the identifier of an LCR instance. Common to all lcr module tables. In lcr_rule and lcr_rule_target tables, value of the column is integer from 1 to lcr_count. In lcr_gw table, value of the column is from 0 to lcr_count.
Default value is “lcr_id”.
Example 1.4. Setting lcr_id_column
module
parameter
... modparam("lcr", "lcr_id_column", "lcr_identifier") ...
Name of the column holding gateway's name for documentation purpose.
Default value is “gw_name”.
Example 1.5. Setting gw_name_column
module parameter
... modparam("lcr", "gw_name_column", "name") ...
Name of the column holding the IPv4 or IPv6 address of the gateway.
Default value is “ip_addr”.
Example 1.6. Setting ip_addr_column
module
parameter
... modparam("lcr", "ip_addr_column", "ip") ...
Name of the column holding gateway's hostname that is used in Request-URI hostpart, when request is sent to the gateway.
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 gateway's parameters that is used in Request-URI, when request is sent to the gateway.
Default value is “params”.
Example 1.9. Setting params_column
module parameter
... modparam("lcr", "params_column", "parameters") ...
Name of the column holding the uri scheme of the gateway.
Default value is “uri_scheme”.
Example 1.10. Setting uri_scheme_column
module
parameter
... modparam("lcr", "uri_scheme_column", "uri_scheme") ...
Name of the column holding the transport protocol to be used for the gateway.
Default value is “transport”.
Example 1.11. Setting transport_column
module
parameter
... modparam("lcr", "transport_column", "trans") ...
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.12. Setting strip_column
module
parameter
... modparam("lcr", "strip_column", "strip_count") ...
Name of the column holding gateway specific tag string that is added to Request URI userpart after stripping.
Default value is “tag”.
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. If timestamp value is 4294967295 (= max UNIX timestamp value) or greater, gw is considered currently unused and is not loaded into memory at all.
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_rule”.
Example 1.16. Setting lcr_rule_table
module parameter
... modparam("lcr", "lcr_rule_table", "rules") ...
Name of the column in lcr_rule and lcr_gw tables holding prefix of Request-URI user part and prefix of gateway, respectively.
Default value is “prefix”.
Example 1.17. Setting prefix_column
module
parameter
... modparam("lcr", "prefix_column", "number_prefix") ...
Name of the column holding the From (caller's) URI.
Default value is “from_uri”.
Example 1.18. Setting from_uri_column
module parameter
... modparam("lcr", "from_uri_column", "caller_uri") ...
Name of the column holding mtree tvalue.
Default value is “mt_tvalue”.
Example 1.19. Setting from_uri_column
module parameter
... modparam("lcr", "mt_tvalue_column", "tree_value") ...
Name of the column holding the regular expression to match against the complete request URI (including the "sip:" prefix).
Default value is “request_uri”.
Example 1.20. Setting request_uri_column
module parameter
... modparam("lcr", "request_uri_column", "callee_uri") ...
Name of the column holding rule's stopper attribute.
Default value is “stopper”.
Example 1.21. Setting stopper_column
module
parameter
... modparam("lcr", "stopper_column", "stop") ...
Name of the column telling is the rule is currently enabled or disabled.
Default value is “enabled”.
Example 1.22. Setting enabled_column
module
parameter
... modparam("lcr", "enabled_column", "in_use") ...
Name of the table holding information about the LCR rule targets (gateways).
Default value is “lcr_rule_target”.
Example 1.23. Setting lcr_rule_target_table
module parameter
... modparam("lcr", "lcr_rule_target_table", "rules") ...
Name of lcr_rule_target_table column containing an id of lcr_rule table.
Default value is “rule_id”.
Example 1.24. Setting rule_id_column
module
parameter
... modparam("lcr", "rule_id_column", "rule") ...
Name of lcr_rule_target_table column containing an id of lcr_gw table.
Default value is “gw_id”.
Name of the column holding the priority of the rule target.
Default value is “priority”.
Example 1.26. Setting priority_column
module
parameter
... modparam("lcr", "priority_column", "priority") ...
Name of the column holding weight of rule target.
Default value is “weight”.
Example 1.27. Setting weight_column
module
parameter
... modparam("lcr","weight_column", "target_weight") ...
Maximum value of lcr_id.
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.29. Setting gw_uri_avp
module
parameter
... modparam("lcr", "gw_uri_avp", "$avp(lcr_gwuri)") ...
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.30. Setting ruri_user_avp
module parameter
... modparam("lcr", "ruri_user_avp", "$avp(lcr_ruri_user)") ...
If defined, an AVP where successful next_gw and from_gw functions store gateway's tag.
There is NO default value, i.e, if not defined, gateway's tag is not stored anywhere.
If defined, an AVP where successful next_gw and from_gw functions store gateway's flags.
There is NO default value, i.e, if not defined, gateway's flags are not stored anywhere.
Example 1.32. Setting flags_avp
module parameter
... modparam("lcr", "flags_avp", "$avp(lcr_flags)") ...
If defined, an AVP where successful next_gw and from_gw functions store matching rule's id.
There is NO default value, i.e, if not defined, matching rule's id is not stored anywhere.
Example 1.33. Setting rule_id_avp
module parameter
... modparam("lcr", "rule_id_avp", "$avp(lcr_ruleid)") ...
If defined and mt_value is given for a rule, load_gws() matches caller URI userpart to a mtree given as mtree parameter.
If defined, must have the same value as mtree module pv_values parameter.
There is NO default value.
Example 1.34. Setting tag_avp
module parameter
... modparam("lcr", "mt_pv_values", "$avp(lcr_mt_values)") ...
Name of mtree to which load_gws() matches caller URI userpart.
Default value is "lcr".
Tells if defunct capability of (non-responsive) gateways is supported. Non-zero value turns on defunct capability.
Default value is 0.
Example 1.36.
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.37. Setting lcr_id_avp
module
parameter
... modparam("lcr", "lcr_id_avp", "$avp(lcr_id)") ...
Internal AVP that next_gw() function uses to store internal index 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.38. Setting defunct_gw_avp
module
parameter
... modparam("lcr", "defunct_gw_avp", "$avp(lcr_defunct_gw)") ...
Defines the size of hash table used to store LCR rules. Hashing is done based on rule's prefix. Larger value means less collisions with other prefixes. Hash size value should be a power of 2.
Default value is 128.
Example 1.39.
Setting lcr_rule_hash_size
module
parameter
... modparam("lcr", "lcr_rule_hash_size", 1024) ...
Defines the maximum number of gateways in lcr_gw table.
Default value is 128.
Defines the flag number used to tell if stripping and tagging is done for the selected gateway.
Default value is -1 meaning that the flag is not defined.
Example 1.41.
Setting dont_strip_or_prefix_flag
module
parameter
... modparam("lcr", "dont_strip_or_prefix_flag", 10) ...
Defines how matching gateways are ordered (see Overview section).
Default value is 0.
Example 1.42.
Setting priority_ordering
module
parameter
... modparam("lcr", "priority_ordering", 1) ...
The number of the rows to be fetched at once from database when loading data from lcr_rule 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, the database driver must support fetch_result() capability.
Default value is “1024”.
Interval in seconds for sending OPTIONS ping requests
to gateways that, due to failures, have been marked
as inactive by inactivate_gw() function call.
If an inactive gateway later gives a valid response (see
ping_valid_reply_codes
) to a ping
request, it is marked again as active.
If value of this parameter is greater
than zero, tm module must have been loaded and
parameters lcr_id_avp
and
defunct_gw_avp
must have been defined.
Value “0” disables sending of OPTIONS ping
requests to failed gateways.
Default value is “0”.
Tells after how many failures (= inactivate_gw() function calls) a gateway is marked as inactive.
Default value is “1”, i.e., gateway is inactivated after first failure.
Example 1.45.
Set ping_inactivate_threshold
parameter
... modparam("lcr", "ping_inactivate_threshold", 3) ...
A comma separated list of SIP reply codes, which are accepted as valid replies to OPTIONS ping requests. Reply codes 2xx are by default accepted as valid replies and they don't need to be listed here.
Default value is “”, i.e., only 2xx replies are considered as valid replies.
Example 1.46.
Set ping_valid_reply_codes
parameter
... modparam("lcr", "ping_valid_reply_codes", "403,405,501") ...
Loads attributes of matching gateways to gw_uri_avp (see Overview section). Argument lcr_id specifies the used LCR instance. It can be a positive integer or a pseudo variable containing an integer value. If uri_user is given, it is used, instead of Request-URI user part, to look for matching gateways. Caller's URI may be given by caller_uri argument. If caller_uri argument is omitted, it defaults to empty string. Both uri_user and caller_uri argument may be a string or a pseudo variable containing a string value.
Returns 1 if at least one matching gateway was found, 2 if no matching gateways was found, 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 rules hash table of the LCR instance.
This function can be used from REQUEST_ROUTE.
Example 1.49. load_gws
usage
... if (!load_gws(1, $rU, $var(caller_uri))) { sl_send_reply("500", "Server Internal Error - Cannot load gateways"); exit; }; ...
Upon first call, fetches attribute values stored in first gw_uri_avp, destroys that AVP, and rewrites Request-URI and possibly also destination URI as described in the Overview section. Saves user part of Request-URI into ruri_user_avp for use in subsequent next_gw() calls.
Upon subsequent calls, does the same as in above, but takes user part of Request-URI from ruri_user_avp.
As a side effect, stores gateway's tag and flags to tag_avp and flags_avp, respectively, if the corresponding module parameter has been defined. In the same way, rule_id_avp, if defined, contains the id of the rule that selected the gateway.
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.50. next_gw
usage from a route block
... if (!next_gw()) { sl_send_reply("503", "Service not available - No gateways"); exit; }; ...
Example 1.51. next_gw
usage from a failure
route block
... if (!next_gw()) { t_reply("503", "Service not available - No more gateways"); exit; }; ...
Inactivates the gateway denoted by lcr_id_avp and defunct_gw_avp
(which were set by previous next_gw() call). Use of this
function requires that ping_interval
module
parameter has been set to a positive value allowing an
inactivated gateway to be automatically activated by a positive
response to OPTIONS ping request.
Returns 1 on success and -1 in case of error (see syslog).
This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
Example 1.52. inactivate_gw
usage
... failure_route [GW_FAILURE] { ... if (t_check_status("408|503")) { inactivate_gw(); }; ...
Defuncts gateway denoted by lcr_id_avp and defunct_gw_avp (which were set by previuos 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).
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE.
Checks if request comes from IP address, transport protocol and source port specified for a gateway in LCR instance lcr_id. Fails if the LCR instance includes one or more gateways without IP address. IP address, transport protocol and source port to be checked are either taken from source IP address and port of the request or (if present) from ip_addr, proto and src_port arguments.
lcr_id can be an integer constant or a pseudo variable holding an integer value. ip_addr can be a string or a pseudo variable holding a string value. proto can be an integer constant (0 = ANY, 1 = UDP, 2 = TCP, 3 = TLS, 4 = SCTP) or a pseudo variable holding such an integer value. src_port can be an integer or a pseudo variable holding such an integer value.
If request comes from a gateway, gateway's tag and flags are stored as a side effect to tag_avp and flags_avp, respectively, if the corresponding module parameter has been defined. In the same way, rule_id_avp, if defined, contains the id of the rule that selected the gateway.
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, transport protocol and source port specified for any gateway. Only LCR instances, where all gateways have IP address, are included in the test. IP address, transport protocol and source port to be checked are either taken from source IP address, transport protocol and source port of the request or (if present) from ip_addr, proto and src_port arguments. See from_gw() function for more info about the arguments.
If any gateway has the IP address, transport protocol and source port, function returns LCR identifier of the gateway. Returns -1 on error or if the request does not come from a gateway.
If request comes from a gateway, gateway's tag and flags are stored as a side effect to tag_avp and flags_avp, respectively, if the corresponding module parameter has been defined. In the same way, rule_id_avp, if defined, contains the id of the rule that selected the gateway.
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 IP address and transport protocol specified for a gateway in LCR instance lcr_id. Fails if LCR instance includes one or more gateways without IP address. IP address and transport protocol to be checked are either taken from Request-URI or (if present) from ip_addr and proto arguments. See from_gw() for more info regarding the arguments.
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 IP address and transport protocol of any gateway. Only LCR instances, where all gateways have IP address, are included in the test. IP address and transport protocol to be checked are either taken from Request-URI or (if present) from ip_addr and proto arguments. See from_gw() for more info regarding the arguments.
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 LCR tables into memory.
Name: lcr.reload
Parameters: none
Causes lcr module to dump the contents of its in-memory gw table.
Parameters: none
Causes lcr module to dump the contents of its in-memory lcr_rule and lcr_rule_target tables. Rules can be filtered by lcr_id or lcr_id and prefix. The filters are passed as optional parameters.
Parameters:
lcr_id filter rules based on lcr_id.
prefix filter rules based on prefix (prefixes shorter or equal to the give prefix) in addition to the previous lcr_id parameter.
Loads gateways and prints ids of matching ones in priority order.
Name: lcr.load_gws
Parameters: lcr_id uri_user [caller_uri request_uri]