kamailio/modules/lcr

LCR (Least Cost Routing) Module

Juha Heinanen

   <jh@tutpro.com>

Edited by

Juha Heinanen

   <jh@tutpro.com>

   Copyright © 2005-2010 Juha Heinanen
   Revision History
   Revision $Revision$ $Date$
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. SIP Router modules
              2.2. External libraries or applications

        3. Exported Parameters

              3.1. db_url (string)
              3.2. lcr_gw_table (string)
              3.3. id_column (string)
              3.4. lcr_id_column (string)
              3.5. gw_name_column (string)
              3.6. ip_addr_column (string)
              3.7. hostname_column (string)
              3.8. port_column (string)
              3.9. params_column (string)
              3.10. uri_scheme_column (string)
              3.11. transport_column (string)
              3.12. strip_column (string)
              3.13. tag_column (string)
              3.14. flags_column (string)
              3.15. defunct_column (string)
              3.16. lcr_rule_table (string)
              3.17. prefix_column (string)
              3.18. from_uri_column (string)
              3.19. stopper_column (string)
              3.20. enabled_column (string)
              3.21. lcr_rule_target_table (string)
              3.22. rule_id_column (string)
              3.23. gw_id_column (string)
              3.24. priority_column (string)
              3.25. weight_column (string)
              3.26. lcr_count (integer)
              3.27. gw_uri_avp (AVP string)
              3.28. ruri_user_avp (AVP string)
              3.29. flags_avp (AVP string)
              3.30. defunct_capability (integer)
              3.31. lcr_id_avp (AVP string)
              3.32. defunct_gw_avp (AVP string)
              3.33. lcr_rule_hash_size (integer)
              3.34. lcr_gw_count (integer)
              3.35. dont_strip_or_tag (integer)
              3.36. fetch_rows (integer)

        4. Exported Functions

              4.1. load_gws(lcr_id[, caller_uri])
              4.2. next_gw()
              4.3. defunct_gw(period)
              4.4. from_gw(lcr_id [, ip_addr])
              4.5. from_any_gw([ip_addr])
              4.6. to_gw(lcr_id [, ip_addr])
              4.7. to_any_gw([ip_addr])

        5. Exported RPC Commands

              5.1. lcr.reload
              5.2. lcr.dump_gws
              5.3. lcr.dump_rules

        6. Known Limitations

   List of Examples

   1.1. Setting db_url module parameter
   1.2. Setting gw_table module parameter
   1.3. Setting id_column module parameter
   1.4. Setting lcr_id_column module parameter
   1.5. Setting gw_name_column module parameter
   1.6. Setting ip_addr_column module parameter
   1.7. Setting hostname_column module parameter
   1.8. Setting port_column module parameter
   1.9. Setting params_column module parameter
   1.10. Setting uri_scheme_column module parameter
   1.11. Setting transport_column module parameter
   1.12. Setting strip_column module parameter
   1.13. Setting tag_column module parameter
   1.14. Setting flags_column module parameter
   1.15. Setting defunct_column module parameter
   1.16. Setting lcr_rule_table module parameter
   1.17. Setting prefix_column module parameter
   1.18. Setting from_uri_column module parameter
   1.19. Setting stopper_column module parameter
   1.20. Setting enabled_column module parameter
   1.21. Setting lcr_rule_target_table module parameter
   1.22. Setting rule_id_column module parameter
   1.23. Setting gw_id_column module parameter
   1.24. Setting priority_column module parameter
   1.25. Setting weight_column module parameter
   1.26. Setting lcr_count module parameter
   1.27. Setting gw_uri_avp module parameter
   1.28. Setting ruri_user_avp module parameter
   1.29. Setting flags_avp module parameter
   1.30. Setting defunct_capability module parameter
   1.31. Setting lcr_id_avp module parameter
   1.32. Setting defunct_gw_avp module parameter
   1.33. Setting lcr_rule_hash_size module parameter
   1.34. Setting lcr_gw_count module parameter
   1.35. Setting dont_strip_or_tag_flag module parameter
   1.36. Set fetch_rows parameter
   1.37. load_gws usage
   1.38. next_gw usage from a route block
   1.39. next_gw usage from a failure route block
   1.40. defunct_gw usage
   1.41. from_gw usage
   1.42. from_gw usage
   1.43. to_gw usage
   1.44. to_gw usage
   1.45. lcr.reload RPC example
   1.46. lcr.dump_gws RPC example
   1.47. lcr.dump_rules RPC example

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. SIP Router modules
        2.2. External libraries or applications

   3. Exported Parameters

        3.1. db_url (string)
        3.2. lcr_gw_table (string)
        3.3. id_column (string)
        3.4. lcr_id_column (string)
        3.5. gw_name_column (string)
        3.6. ip_addr_column (string)
        3.7. hostname_column (string)
        3.8. port_column (string)
        3.9. params_column (string)
        3.10. uri_scheme_column (string)
        3.11. transport_column (string)
        3.12. strip_column (string)
        3.13. tag_column (string)
        3.14. flags_column (string)
        3.15. defunct_column (string)
        3.16. lcr_rule_table (string)
        3.17. prefix_column (string)
        3.18. from_uri_column (string)
        3.19. stopper_column (string)
        3.20. enabled_column (string)
        3.21. lcr_rule_target_table (string)
        3.22. rule_id_column (string)
        3.23. gw_id_column (string)
        3.24. priority_column (string)
        3.25. weight_column (string)
        3.26. lcr_count (integer)
        3.27. gw_uri_avp (AVP string)
        3.28. ruri_user_avp (AVP string)
        3.29. flags_avp (AVP string)
        3.30. defunct_capability (integer)
        3.31. lcr_id_avp (AVP string)
        3.32. defunct_gw_avp (AVP string)
        3.33. lcr_rule_hash_size (integer)
        3.34. lcr_gw_count (integer)
        3.35. dont_strip_or_tag (integer)
        3.36. fetch_rows (integer)

   4. Exported Functions

        4.1. load_gws(lcr_id[, caller_uri])
        4.2. next_gw()
        4.3. defunct_gw(period)
        4.4. from_gw(lcr_id [, ip_addr])
        4.5. from_any_gw([ip_addr])
        4.6. to_gw(lcr_id [, ip_addr])
        4.7. to_any_gw([ip_addr])

   5. Exported RPC Commands

        5.1. lcr.reload
        5.2. lcr.dump_gws
        5.3. lcr.dump_rules

   6. Known Limitations

1. Overview

   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 identifier.

   For the purpose of facilitating least cost routing of requests, each
   gateway of an LCR instance is associated with one or more <prefix, from
   pattern, priority, weight> tuples. A gateway matches a request if user
   part of the Request-URI matches a "prefix" and the caller's URI matches
   a "from" 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:

     * (1) according to longest user part match
     * (2) according to tuple's priority
     * (3) 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 pattern is a regular
   expression (see 'man pcresyntax' for syntax), an empty string, or NULL.
   An empty or NULL from 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_of_tag" 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 tag. 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 = none, 1 = udp, 2 = tcp, 3 =
   tls, and 4 = sctp.

   As a side effect of gateway selection, selected gateway's flags (that
   may contain information about capabilities of the gateway) are stored
   into an AVP.

2. Dependencies

   2.1. SIP Router modules
   2.2. External libraries or applications

2.1. SIP Router modules

   The following modules must be loaded before this module:
     * A database module like mysql, postgres or dbtext.

2.2. External libraries or applications

   The following libraries or applications must be installed before
   running SIP Router with this module:
     * libpcre

3. Exported Parameters

   3.1. db_url (string)
   3.2. lcr_gw_table (string)
   3.3. id_column (string)
   3.4. lcr_id_column (string)
   3.5. gw_name_column (string)
   3.6. ip_addr_column (string)
   3.7. hostname_column (string)
   3.8. port_column (string)
   3.9. params_column (string)
   3.10. uri_scheme_column (string)
   3.11. transport_column (string)
   3.12. strip_column (string)
   3.13. tag_column (string)
   3.14. flags_column (string)
   3.15. defunct_column (string)
   3.16. lcr_rule_table (string)
   3.17. prefix_column (string)
   3.18. from_uri_column (string)
   3.19. stopper_column (string)
   3.20. enabled_column (string)
   3.21. lcr_rule_target_table (string)
   3.22. rule_id_column (string)
   3.23. gw_id_column (string)
   3.24. priority_column (string)
   3.25. weight_column (string)
   3.26. lcr_count (integer)
   3.27. gw_uri_avp (AVP string)
   3.28. ruri_user_avp (AVP string)
   3.29. flags_avp (AVP string)
   3.30. defunct_capability (integer)
   3.31. lcr_id_avp (AVP string)
   3.32. defunct_gw_avp (AVP string)
   3.33. lcr_rule_hash_size (integer)
   3.34. lcr_gw_count (integer)
   3.35. dont_strip_or_tag (integer)
   3.36. fetch_rows (integer)

3.1. db_url (string)

   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")
...

3.2. lcr_gw_table (string)

   Name of the table holding gateways definitions.

   Default value is “lcr_gw”.

   Example 1.2. Setting gw_table module parameter
...
modparam("lcr", "lcr_gw_table","gw")
...

3.3. id_column (string)

   Name of the auto-increment, primary key column. Common to all lcr
   module tables.

   Default value is “id”.

   Example 1.3. Setting id_column module parameter
...
modparam("lcr", "id_column", "row_id")
...

3.4. lcr_id_column (string)

   Name of the column holding the identifier of an LCR instance. Common to
   all lcr module tables.

   Default value is “lcr_id”.

   Example 1.4. Setting lcr_id_column module parameter
...
modparam("lcr", "lcr_id_column", "lcr_identifier")
...

3.5. gw_name_column (string)

   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")
...

3.6. ip_addr_column (string)

   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")
...

3.7. hostname_column (string)

   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")
...

3.8. port_column (string)

   Name of the column holding the port number of the gateway.

   Default value is “port”.

   Example 1.8. Setting port_column module parameter
...
modparam("lcr", "port_column", "port")
...

3.9. params_column (string)

   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")
...

3.10. uri_scheme_column (string)

   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")
...

3.11. transport_column (string)

   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")
...

3.12. strip_column (string)

   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")
...

3.13. tag_column (string)

   Name of the column holding gateway specific tag string that is added to
   Request URI userpart after stripping.

   Default value is “tag”.

   Example 1.13. Setting tag_column module parameter
...
modparam("lcr", "tag_column", "gw_tag")
...

3.14. flags_column (string)

   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")
...

3.15. defunct_column (string)

   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")
...

3.16. lcr_rule_table (string)

   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")
...

3.17. prefix_column (string)

   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", "number_prefix")
...

3.18. from_uri_column (string)

   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")
...

3.19. stopper_column (string)

   Name of the column holding rule's stopper attribute.

   Default value is “stopper”.

   Example 1.19. Setting stopper_column module parameter
...
modparam("lcr", "stopper_column", "stop")
...

3.20. enabled_column (string)

   Name of the column telling is the rule is currently enabled or
   disabled.

   Default value is “enabled”.

   Example 1.20. Setting enabled_column module parameter
...
modparam("lcr", "enabled_column", "in_use")
...

3.21. lcr_rule_target_table (string)

   Name of the table holding information about the LCR rule targets
   (gateways).

   Default value is “lcr_rule_target”.

   Example 1.21. Setting lcr_rule_target_table module parameter
...
modparam("lcr", "lcr_rule_target_table", "rules")
...

3.22. rule_id_column (string)

   Name of lcr_rule_target_table column containing an id of lcr_rule
   table.

   Default value is “rule_id”.

   Example 1.22. Setting rule_id_column module parameter
...
modparam("lcr", "rule_id_column", "rule")
...

3.23. gw_id_column (string)

   Name of lcr_rule_target_table column containing an id of lcr_gw table.

   Default value is “gw_id”.

   Example 1.23. Setting gw_id_column module parameter
...
modparam("lcr", "gw_id_column", "gw")
...

3.24. priority_column (string)

   Name of the column holding the priority of the rule target.

   Default value is “priority”.

   Example 1.24. Setting priority_column module parameter
...
modparam("lcr", "priority_column", "priority")
...

3.25. weight_column (string)

   Name of the column holding weight of rule target.

   Default value is “weight”.

   Example 1.25. Setting weight_column module parameter
...
modparam("lcr","weight_column", "target_weight")
...

3.26. lcr_count (integer)

   Number of LCR instances.

   Default value is 1.

   Example 1.26.  Setting lcr_count module parameter
...
modparam("lcr", "lcr_count", 10)
...

3.27. gw_uri_avp (AVP string)

   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.27. Setting gw_uri_avp module parameter
...
modparam("lcr", "gw_uri_avp", "$avp(i:709)")
...

3.28. ruri_user_avp (AVP string)

   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.28. Setting ruri_user_avp module parameter
...
modparam("lcr", "ruri_user_avp", "$avp(i:500)")
...

3.29. flags_avp (AVP string)

   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.29. Setting flags_avp module parameter
...
modparam("lcr", "flags_avp", "$avp(i:712)")
...

3.30. defunct_capability (integer)

   Tells if defunct capability of (non-responsive) gateways is supported.
   Non-zero value turns on defunct capability.

   Default value is 0.

   Example 1.30.  Setting defunct_capability module parameter
...
modparam("lcr", "defunct_capability", 1)
...

3.31. lcr_id_avp (AVP string)

   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.31. Setting lcr_id_avp module parameter
...
modparam("lcr", "lcr_id_avp", "$avp(s:lcr_id_avp)")
...

3.32. defunct_gw_avp (AVP string)

   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.32. Setting defunct_gw_avp module parameter
...
modparam("lcr", "defunct_gw_avp", "$avp(s:defunct_gw_avp)")
...

3.33. lcr_rule_hash_size (integer)

   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.33.  Setting lcr_rule_hash_size module parameter
...
modparam("lcr", "lcr_rule_hash_size", 1024)
...

3.34. lcr_gw_count (integer)

   Defines the maximum number of gateways in lcr_gw table.

   Default value is 128.

   Example 1.34.  Setting lcr_gw_count module parameter
...
modparam("lcr", "lcr_gw_count", 1024)
...

3.35. dont_strip_or_tag (integer)

   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.35.  Setting dont_strip_or_tag_flag module parameter
...
modparam("lcr", "dont_strip_or_tag_flag", 10)
...

3.36. fetch_rows (integer)

   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”.

   Example 1.36. Set fetch_rows parameter
...
modparam("lcr", "fetch_rows", 3000)
...

4. Exported Functions

   4.1. load_gws(lcr_id[, caller_uri])
   4.2. next_gw()
   4.3. defunct_gw(period)
   4.4. from_gw(lcr_id [, ip_addr])
   4.5. from_any_gw([ip_addr])
   4.6. to_gw(lcr_id [, ip_addr])
   4.7. to_any_gw([ip_addr])

4.1.  load_gws(lcr_id[, caller_uri])

   Loads attributes 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. If
   caller_uri argument is omitted, it defaults to empty string.

   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.37. load_gws usage
...
if (!load_gws("1", "$var(caller_uri)")) {
        sl_send_reply("500", "Server Internal Error - Cannot load gateways");
        exit;
};
...

4.2.  next_gw()

   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 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.38. next_gw usage from a route block
...
if (!next_gw()) {
        sl_send_reply("503", "Service not available - No gateways");
        exit;
};
...

   Example 1.39. next_gw usage from a failure route block
...
if (!next_gw()) {
        t_reply("503", "Service not available - No more gateways");
        exit;
};
...

4.3.  defunct_gw(period)

   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.

   Example 1.40. defunct_gw usage
...
defunct_gw("60");
...

4.4.  from_gw(lcr_id [, ip_addr])

   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. Fails if LCR instance includes one
   or more gateways without IP address. 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.

   Example 1.41. from_gw usage
...
if (from_gw("1", "$avp(s:real_source_addr)") {
        ...
};
...

4.5.  from_any_gw([ip_addr])

   Checks if request comes from IP address and port of any gateway. Only
   LCR instances, where all gateways have IP address, are included in the
   test. 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 the request does not come from a
   gateway.

   If request comes from a gateway, the 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.

   Example 1.42. from_gw usage
...
$var(lcr_id) = from_any_gw();
...

4.6.  to_gw(lcr_id [, ip_addr])

   Checks if in-dialog request goes to IP address and port of a gateway in
   LCR instance specified by lcr_id argument. Fails if LCR instance
   includes one or more gateways without IP address. 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.

   Example 1.43. to_gw usage
...
if (to_gw("1")) {
        ...
        exit;
};
...

4.7.  to_any_gw([ip_addr])

   Checks if in-dialog request goes to any gateway. Only LCR instances,
   where all gateways have IP address, are included in the test. 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.

   Example 1.44. to_gw usage
...
if (to_any_gw()) {
        ...
        exit;
};
...

5. Exported RPC Commands

   5.1. lcr.reload
   5.2. lcr.dump_gws
   5.3. lcr.dump_rules

5.1. lcr.reload

   Causes lcr module to re-read the contents of LCR tables into memory.

   Name: lcr.reload

   Parameters: none

   Example 1.45. lcr.reload RPC example
                $ sercmd lcr.reload

5.2. lcr.dump_gws

   Causes lcr module to dump the contents of its in-memory gw table.

   Parameters: none

   Example 1.46. lcr.dump_gws RPC example
                $ sercmd lcr.dump_gws

5.3. lcr.dump_rules

   Causes lcr module to dump the contents of its in-memory lcr_rule and
   lcr_rule_target tables.

   Parameters: none

   Example 1.47. lcr.dump_rules RPC example
                $ sercmd lcr.dump_rules

6. Known Limitations

   In-memory LCR rules and gw tables are switched by two consecutive
   machine instructions. If lcr reload process is interrupted after the
   first one, in-memory gateway table does not match in-memory rule table
   until execution of lcr reload process is resumed.