diff --git a/src/modules/lcr/README b/src/modules/lcr/README index 8fabc116ad3..0dd6fae04e0 100644 --- a/src/modules/lcr/README +++ b/src/modules/lcr/README @@ -57,21 +57,22 @@ Juha Heinanen 3.30. ruri_user_avp (AVP string) 3.31. tag_avp (AVP string) 3.32. flags_avp (AVP string) - 3.33. mt_pv_values (AVP string) - 3.34. mtree (string) - 3.35. defunct_capability (integer) - 3.36. lcr_id_avp (AVP string) - 3.37. defunct_gw_avp (AVP string) - 3.38. lcr_rule_hash_size (integer) - 3.39. lcr_gw_count (integer) - 3.40. dont_strip_or_prefix_flag (integer) - 3.41. priority_ordering (integer) - 3.42. fetch_rows (integer) - 3.43. ping_interval (integer) - 3.44. ping_inactivate_threshold (integer) - 3.45. ping_valid_reply_codes (string) - 3.46. ping_from (string) - 3.47. ping_socket (string) + 3.33. rule_id_avp (AVP string) + 3.34. mt_pv_values (AVP string) + 3.35. mtree (string) + 3.36. defunct_capability (integer) + 3.37. lcr_id_avp (AVP string) + 3.38. defunct_gw_avp (AVP string) + 3.39. lcr_rule_hash_size (integer) + 3.40. lcr_gw_count (integer) + 3.41. dont_strip_or_prefix_flag (integer) + 3.42. priority_ordering (integer) + 3.43. fetch_rows (integer) + 3.44. ping_interval (integer) + 3.45. ping_inactivate_threshold (integer) + 3.46. ping_valid_reply_codes (string) + 3.47. ping_from (string) + 3.48. ping_socket (string) 4. Functions @@ -128,35 +129,36 @@ Juha Heinanen 1.30. Setting ruri_user_avp module parameter 1.31. Setting tag_avp module parameter 1.32. Setting flags_avp module parameter - 1.33. Setting tag_avp module parameter - 1.34. Setting mtree module parameter - 1.35. Setting defunct_capability module parameter - 1.36. Setting lcr_id_avp module parameter - 1.37. Setting defunct_gw_avp module parameter - 1.38. Setting lcr_rule_hash_size module parameter - 1.39. Setting lcr_gw_count module parameter - 1.40. Setting dont_strip_or_prefix_flag module parameter - 1.41. Setting priority_ordering module parameter - 1.42. Set fetch_rows parameter - 1.43. Set ping_interval parameter - 1.44. Set ping_inactivate_threshold parameter - 1.45. Set ping_valid_reply_codes parameter - 1.46. Set ping_from parameter - 1.47. Set ping_socket parameter - 1.48. load_gws usage - 1.49. next_gw usage from a route block - 1.50. next_gw usage from a failure route block - 1.51. inactivate_gw usage - 1.52. defunct_gw usage - 1.53. from_gw usage + 1.33. Setting rule_id_avp module parameter + 1.34. Setting tag_avp module parameter + 1.35. Setting mtree module parameter + 1.36. Setting defunct_capability module parameter + 1.37. Setting lcr_id_avp module parameter + 1.38. Setting defunct_gw_avp module parameter + 1.39. Setting lcr_rule_hash_size module parameter + 1.40. Setting lcr_gw_count module parameter + 1.41. Setting dont_strip_or_prefix_flag module parameter + 1.42. Setting priority_ordering module parameter + 1.43. Set fetch_rows parameter + 1.44. Set ping_interval parameter + 1.45. Set ping_inactivate_threshold parameter + 1.46. Set ping_valid_reply_codes parameter + 1.47. Set ping_from parameter + 1.48. Set ping_socket parameter + 1.49. load_gws usage + 1.50. next_gw usage from a route block + 1.51. next_gw usage from a failure route block + 1.52. inactivate_gw usage + 1.53. defunct_gw usage 1.54. from_gw usage - 1.55. to_gw usage + 1.55. from_gw usage 1.56. to_gw usage - 1.57. lcr.reload RPC example - 1.58. lcr.dump_gws RPC example - 1.59. lcr.dump_rules RPC example - 1.60. lcr.load_gws RPC example - 1.61. lcr.defunct_gw RPC example + 1.57. to_gw usage + 1.58. lcr.reload RPC example + 1.59. lcr.dump_gws RPC example + 1.60. lcr.dump_rules RPC example + 1.61. lcr.load_gws RPC example + 1.62. lcr.defunct_gw RPC example Chapter 1. Admin Guide @@ -202,21 +204,22 @@ Chapter 1. Admin Guide 3.30. ruri_user_avp (AVP string) 3.31. tag_avp (AVP string) 3.32. flags_avp (AVP string) - 3.33. mt_pv_values (AVP string) - 3.34. mtree (string) - 3.35. defunct_capability (integer) - 3.36. lcr_id_avp (AVP string) - 3.37. defunct_gw_avp (AVP string) - 3.38. lcr_rule_hash_size (integer) - 3.39. lcr_gw_count (integer) - 3.40. dont_strip_or_prefix_flag (integer) - 3.41. priority_ordering (integer) - 3.42. fetch_rows (integer) - 3.43. ping_interval (integer) - 3.44. ping_inactivate_threshold (integer) - 3.45. ping_valid_reply_codes (string) - 3.46. ping_from (string) - 3.47. ping_socket (string) + 3.33. rule_id_avp (AVP string) + 3.34. mt_pv_values (AVP string) + 3.35. mtree (string) + 3.36. defunct_capability (integer) + 3.37. lcr_id_avp (AVP string) + 3.38. defunct_gw_avp (AVP string) + 3.39. lcr_rule_hash_size (integer) + 3.40. lcr_gw_count (integer) + 3.41. dont_strip_or_prefix_flag (integer) + 3.42. priority_ordering (integer) + 3.43. fetch_rows (integer) + 3.44. ping_interval (integer) + 3.45. ping_inactivate_threshold (integer) + 3.46. ping_valid_reply_codes (string) + 3.47. ping_from (string) + 3.48. ping_socket (string) 4. Functions @@ -312,7 +315,8 @@ Chapter 1. Admin Guide 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. + module parameter has been defined. In the same way, rule_id_avp, if + defined, contains the id of the rule that selected the gateway. 2. Dependencies @@ -365,21 +369,22 @@ Chapter 1. Admin Guide 3.30. ruri_user_avp (AVP string) 3.31. tag_avp (AVP string) 3.32. flags_avp (AVP string) - 3.33. mt_pv_values (AVP string) - 3.34. mtree (string) - 3.35. defunct_capability (integer) - 3.36. lcr_id_avp (AVP string) - 3.37. defunct_gw_avp (AVP string) - 3.38. lcr_rule_hash_size (integer) - 3.39. lcr_gw_count (integer) - 3.40. dont_strip_or_prefix_flag (integer) - 3.41. priority_ordering (integer) - 3.42. fetch_rows (integer) - 3.43. ping_interval (integer) - 3.44. ping_inactivate_threshold (integer) - 3.45. ping_valid_reply_codes (string) - 3.46. ping_from (string) - 3.47. ping_socket (string) + 3.33. rule_id_avp (AVP string) + 3.34. mt_pv_values (AVP string) + 3.35. mtree (string) + 3.36. defunct_capability (integer) + 3.37. lcr_id_avp (AVP string) + 3.38. defunct_gw_avp (AVP string) + 3.39. lcr_rule_hash_size (integer) + 3.40. lcr_gw_count (integer) + 3.41. dont_strip_or_prefix_flag (integer) + 3.42. priority_ordering (integer) + 3.43. fetch_rows (integer) + 3.44. ping_interval (integer) + 3.45. ping_inactivate_threshold (integer) + 3.46. ping_valid_reply_codes (string) + 3.47. ping_from (string) + 3.48. ping_socket (string) 3.1. db_url (string) @@ -758,7 +763,20 @@ modparam("lcr", "tag_avp", "$avp(lcr_tag)") modparam("lcr", "flags_avp", "$avp(i:712)") ... -3.33. mt_pv_values (AVP string) +3.33. rule_id_avp (AVP string) + + 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(i:712)") + ... + +3.34. mt_pv_values (AVP string) If defined and mt_value is given for a rule, load_gws() matches caller URI userpart to a mtree given as mtree parameter. @@ -768,35 +786,35 @@ modparam("lcr", "flags_avp", "$avp(i:712)") There is NO default value. - Example 1.33. Setting tag_avp module parameter + Example 1.34. Setting tag_avp module parameter ... modparam("lcr", "mt_pv_values", "$avp(mt_values)") ... -3.34. mtree (string) +3.35. mtree (string) Name of mtree to which load_gws() matches caller URI userpart. Default value is "lcr". - Example 1.34. Setting mtree module parameter + Example 1.35. Setting mtree module parameter ... modparam("lcr", "mtree", "caller_tree") ... -3.35. defunct_capability (integer) +3.36. 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.35. Setting defunct_capability module parameter + Example 1.36. Setting defunct_capability module parameter ... modparam("lcr", "defunct_capability", 1) ... -3.36. lcr_id_avp (AVP string) +3.37. 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 @@ -804,12 +822,12 @@ modparam("lcr", "defunct_capability", 1) There is NO default value. - Example 1.36. Setting lcr_id_avp module parameter + Example 1.37. Setting lcr_id_avp module parameter ... modparam("lcr", "lcr_id_avp", "$avp(s:lcr_id_avp)") ... -3.37. defunct_gw_avp (AVP string) +3.38. 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 @@ -817,12 +835,12 @@ modparam("lcr", "lcr_id_avp", "$avp(s:lcr_id_avp)") There is NO default value. - Example 1.37. Setting defunct_gw_avp module parameter + Example 1.38. Setting defunct_gw_avp module parameter ... modparam("lcr", "defunct_gw_avp", "$avp(s:defunct_gw_avp)") ... -3.38. lcr_rule_hash_size (integer) +3.39. 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 @@ -830,46 +848,46 @@ modparam("lcr", "defunct_gw_avp", "$avp(s:defunct_gw_avp)") Default value is 128. - Example 1.38. Setting lcr_rule_hash_size module parameter + Example 1.39. Setting lcr_rule_hash_size module parameter ... modparam("lcr", "lcr_rule_hash_size", 1024) ... -3.39. lcr_gw_count (integer) +3.40. lcr_gw_count (integer) Defines the maximum number of gateways in lcr_gw table. Default value is 128. - Example 1.39. Setting lcr_gw_count module parameter + Example 1.40. Setting lcr_gw_count module parameter ... modparam("lcr", "lcr_gw_count", 1024) ... -3.40. dont_strip_or_prefix_flag (integer) +3.41. dont_strip_or_prefix_flag (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.40. Setting dont_strip_or_prefix_flag module parameter + Example 1.41. Setting dont_strip_or_prefix_flag module parameter ... modparam("lcr", "dont_strip_or_prefix_flag", 10) ... -3.41. priority_ordering (integer) +3.42. priority_ordering (integer) Defines how matching gateways are ordered (see Overview section). Default value is 0. - Example 1.41. Setting priority_ordering module parameter + Example 1.42. Setting priority_ordering module parameter ... modparam("lcr", "priority_ordering", 1) ... -3.42. fetch_rows (integer) +3.43. 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 @@ -879,12 +897,12 @@ modparam("lcr", "priority_ordering", 1) Default value is “1024”. - Example 1.42. Set fetch_rows parameter + Example 1.43. Set fetch_rows parameter ... modparam("lcr", "fetch_rows", 3000) ... -3.43. ping_interval (integer) +3.44. ping_interval (integer) Interval in seconds for sending OPTIONS ping requests to gateways that, due to failures, have been marked as inactive by inactivate_gw() @@ -899,24 +917,24 @@ modparam("lcr", "fetch_rows", 3000) Default value is “0”. - Example 1.43. Set ping_interval parameter + Example 1.44. Set ping_interval parameter ... modparam("lcr", "ping_interval", 15) ... -3.44. ping_inactivate_threshold (integer) +3.45. ping_inactivate_threshold (integer) 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.44. Set ping_inactivate_threshold parameter + Example 1.45. Set ping_inactivate_threshold parameter ... modparam("lcr", "ping_inactivate_threshold", 3) ... -3.45. ping_valid_reply_codes (string) +3.46. ping_valid_reply_codes (string) A comma separated list of SIP reply codes, which are accepted as valid replies to OPTIONS ping requests. Reply codes 2xx are by default @@ -925,30 +943,30 @@ modparam("lcr", "ping_inactivate_threshold", 3) Default value is “”, i.e., only 2xx replies are considered as valid replies. - Example 1.45. Set ping_valid_reply_codes parameter + Example 1.46. Set ping_valid_reply_codes parameter ... modparam("lcr", "ping_valid_reply_codes", "403,405,501") ... -3.46. ping_from (string) +3.47. ping_from (string) From URI used in OPTIONS ping requests. Default value is “sip:pinger@localhost”. - Example 1.46. Set ping_from parameter + Example 1.47. Set ping_from parameter ... modparam("lcr", "ping_from", "sip:proxy.operator.com") ... -3.47. ping_socket (string) +3.48. ping_socket (string) Socket to be used for sending OPTIONS ping request. If not set or set to “”, default socket is used. Default value is “”. - Example 1.47. Set ping_socket parameter + Example 1.48. Set ping_socket parameter ... modparam("lcr", "ping_socket", "192.98.102.10:5060") ... @@ -984,7 +1002,7 @@ modparam("lcr", "ping_socket", "192.98.102.10:5060") This function can be used from REQUEST_ROUTE. - Example 1.48. load_gws usage + Example 1.49. load_gws usage ... if (!load_gws(1, $rU, $var(caller_uri))) { sl_send_reply("500", "Server Internal Error - Cannot load gateways"); @@ -1005,7 +1023,8 @@ if (!load_gws(1, $rU, $var(caller_uri))) { 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. + 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). @@ -1014,7 +1033,7 @@ if (!load_gws(1, $rU, $var(caller_uri))) { This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. - Example 1.49. next_gw usage from a route block + Example 1.50. next_gw usage from a route block ... if (!next_gw()) { sl_send_reply("503", "Service not available - No gateways"); @@ -1022,7 +1041,7 @@ if (!next_gw()) { }; ... - Example 1.50. next_gw usage from a failure route block + Example 1.51. next_gw usage from a failure route block ... if (!next_gw()) { t_reply("503", "Service not available - No more gateways"); @@ -1042,7 +1061,7 @@ if (!next_gw()) { This function can be used from REQUEST_ROUTE and FAILURE_ROUTE. - Example 1.51. inactivate_gw usage + Example 1.52. inactivate_gw usage ... failure_route [GW_FAILURE] { ... @@ -1063,7 +1082,7 @@ failure_route [GW_FAILURE] { This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. - Example 1.52. defunct_gw usage + Example 1.53. defunct_gw usage ... defunct_gw(60); ... @@ -1085,7 +1104,9 @@ defunct_gw(60); 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. + 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. @@ -1095,7 +1116,7 @@ defunct_gw(60); This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE. - Example 1.53. from_gw usage + Example 1.54. from_gw usage ... if (from_gw(1, $avp(s:real_source_addr), 2) { ... @@ -1117,7 +1138,9 @@ if (from_gw(1, $avp(s:real_source_addr), 2) { 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. + 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. @@ -1125,7 +1148,7 @@ if (from_gw(1, $avp(s:real_source_addr), 2) { This function can be used from REQUEST_ROUTE, FAILURE_ROUTE, ONREPLY_ROUTE. - Example 1.54. from_gw usage + Example 1.55. from_gw usage ... $var(lcr_id) = from_any_gw("192.168.1.1", 3); ... @@ -1146,7 +1169,7 @@ $var(lcr_id) = from_any_gw("192.168.1.1", 3); This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. - Example 1.55. to_gw usage + Example 1.56. to_gw usage ... if (to_gw("1")) { ... @@ -1172,7 +1195,7 @@ if (to_gw("1")) { This function can be used from REQUEST_ROUTE, FAILURE_ROUTE. - Example 1.56. to_gw usage + Example 1.57. to_gw usage ... if (to_any_gw("192.55.66.2", 1)) { ... @@ -1196,7 +1219,7 @@ if (to_any_gw("192.55.66.2", 1)) { Parameters: none - Example 1.57. lcr.reload RPC example + Example 1.58. lcr.reload RPC example $ kamcmd lcr.reload 5.2. lcr.dump_gws @@ -1205,7 +1228,7 @@ if (to_any_gw("192.55.66.2", 1)) { Parameters: none - Example 1.58. lcr.dump_gws RPC example + Example 1.59. lcr.dump_gws RPC example $ kamcmd lcr.dump_gws 5.3. lcr.dump_rules @@ -1215,7 +1238,7 @@ if (to_any_gw("192.55.66.2", 1)) { Parameters: none - Example 1.59. lcr.dump_rules RPC example + Example 1.60. lcr.dump_rules RPC example $ kamcmd lcr.dump_rules 5.4. lcr.load_gws @@ -1226,7 +1249,7 @@ if (to_any_gw("192.55.66.2", 1)) { Parameters: lcr_id uri_user [caller_uri request_uri] - Example 1.60. lcr.load_gws RPC example + Example 1.61. lcr.load_gws RPC example $ kamcmd lcr.load_gws 2 s:0447058050 5.5. lcr.defunct_gw @@ -1239,7 +1262,7 @@ if (to_any_gw("192.55.66.2", 1)) { Parameters: lcr_id gw_id period - Example 1.61. lcr.defunct_gw RPC example + Example 1.62. lcr.defunct_gw RPC example $ kamcmd lcr.defunct_gw 1 4 120 6. Known Limitations