From ce96966593c9f7e12595b74c2a6bf50b248e64c8 Mon Sep 17 00:00:00 2001 From: Daniel-Constantin Mierla Date: Thu, 23 Nov 2017 00:07:04 +0100 Subject: [PATCH] drouting: updates to documentation --- src/modules/drouting/doc/drouting_admin.xml | 307 +++++++++----------- src/modules/drouting/drouting.c | 2 +- 2 files changed, 143 insertions(+), 166 deletions(-) diff --git a/src/modules/drouting/doc/drouting_admin.xml b/src/modules/drouting/doc/drouting_admin.xml index ecdfdc3b7c2..eb9c55a34d6 100644 --- a/src/modules/drouting/doc/drouting_admin.xml +++ b/src/modules/drouting/doc/drouting_admin.xml @@ -11,7 +11,7 @@ &adminguide; - +
Overview
@@ -20,7 +20,7 @@ Dynamic Routing is a module for selecting (based on multiple criteria) the the best gateway/destination to be used for delivering a certain call. Least Cost Routing (LCR) is a special case of dynamic - routing - when the rules are ordered based on costs. Dynamic Routing + routing - when the rules are ordered based on costs. Dynamic Routing comes with many features regarding routing rule selection: @@ -74,17 +74,17 @@ speed/time and memory consumption penalties - + script integration - Pseudo variables support in functions; scripting route triggering when rules are matched - + - bidirectional behavior - inbound and outbound processing (strip and + bidirectional behavior - inbound and outbound processing (strip and prefixing when sending and receiving from a destination/GW) @@ -108,13 +108,13 @@ The time to load was varying between 4 seconds and 8 seconds, depending of - the caching of the DB client - the first load was the slowest (as the DB - query hits the disk drive); the following are faster as data is already + the caching of the DB client - the first load was the slowest (as the DB + query hits the disk drive); the following are faster as data is already cached in the DB client. So technically speaking, the time to load (without the time to query which is DB type dependent) is ~4 seconds - After loading the data into shared memory ~ 96M of memory were used + After loading the data into shared memory ~ 96M of memory were used exclusively for the DR data.
@@ -147,7 +147,7 @@
Gateway Addresses - Default name for the table storing gateway addresses is + Default name for the table storing gateway addresses is dr_gateways. Gateway addresses are stored in a separate table because of need to access them independent of Dynamic Routing processing (e.g., adding/ @@ -205,13 +205,13 @@ - - + + Once a rule is matched, the STRIP number of digits are removed from the - username part of the RURI and then the PRI prefix has to be added to the - request URI before forwarding the call to the gateway. + username part of the RURI and then the PRI prefix has to be added to the + request URI before forwarding the call to the gateway. @@ -255,7 +255,7 @@ - +
@@ -270,10 +270,10 @@ Also the module allows the usage of groups in the destination lists. A group of destinations is delimited by semi-colon char. inside the whole - destination list ( like: 2,4;5,78,23;4;7;2 ). The destinations from - within a group may be act differently (like load-balancing, random - selection, etc), depending of the sort_order module - parameter - more about this is available under the module paramters + destination list ( like: 2,4;5,78,23;4;7;2 ). The destinations from + within a group may be act differently (like load-balancing, random + selection, etc), depending of the sort_order module + parameter - more about this is available under the module paramters section.
@@ -282,7 +282,7 @@
Routing Rules - Default name for the table storing rule definitions is + Default name for the table storing rule definitions is dr_rules. @@ -349,23 +349,23 @@ - + - groupid column + groupid column - Each user must be member of only one routing group. It must be + Each user must be member of only one routing group. It must be specified in user's profile. - prefix column + prefix column Destination URI must start with prefix value to match the rule. The prefix @@ -374,7 +374,7 @@ - time rec column + time rec column A date-time expression that defines the time recurrence to match for @@ -459,7 +459,7 @@ - dtstart - specifies the beginning of the first + dtstart - specifies the beginning of the first period. @@ -467,9 +467,9 @@ duration - specifies the duration of the period. For a recurring interval, the duration parameter MUST - be small enough such that subsequent intervals do not overlap. - For non-recurring intervals, durations of any positive length are - permitted, zero-length duration means forever. + be small enough such that subsequent intervals do not overlap. + For non-recurring intervals, durations of any positive length are + permitted, zero-length duration means forever. Negative-length durations are not allowed. In the common case of a duration less than one day, the value starts with 'PT' followed by number of hours, minutes and seconds, e.g., a duration of 8 hours @@ -479,12 +479,12 @@ - freq - takes one of the following values: + freq - takes one of the following values: daily, to specify repeating periods based on an interval of a day or more; - weekly, to specify repeating periods based on an - interval of a week or more; monthly, to specify - repeating periods based on an interval of a month or more; and + weekly, to specify repeating periods based on an + interval of a week or more; monthly, to specify + repeating periods based on an interval of a month or more; and yearly, to specify repeating periods based on an interval of a year or more. These values are not case-sensitive. @@ -493,16 +493,16 @@ until - defines an iCalendar COS DATE or DATE-TIME value which bounds the recurrence rule in an inclusive manner. If the - value specified by until is synchronized with the - specified - recurrence, this date or date-time becomes the last instance of the - recurrence. If not present, the recurrence is considered to repeat + value specified by until is synchronized with the + specified + recurrence, this date or date-time becomes the last instance of the + recurrence. If not present, the recurrence is considered to repeat forever. - interval - contains a positive integer + interval - contains a positive integer representing how often the recurrence rule repeats. The default value is 1, meaning every day for a daily rule, every week for a weekly @@ -512,55 +512,55 @@ - interval - contains a positive integer - representing how often the recurrence rule repeats. The default value + interval - contains a positive integer + representing how often the recurrence rule repeats. The default value is 1, meaning every day for a daily rule, every week for a weekly rule, every - month for a monthly rule and every year for a + month for a monthly rule and every year for a yearly rule. - byday - specifies a comma-separated list of days - of the week. MO indicates Monday; TU - indicates Tuesday; WE indicates Wednesday; - TH indicates Thursday; FR indicates - Friday; SA indicates Saturday; SU + byday - specifies a comma-separated list of days + of the week. MO indicates Monday; TU + indicates Tuesday; WE indicates Wednesday; + TH indicates Thursday; FR indicates + Friday; SA indicates Saturday; SU indicates Sunday. These values are not case-sensitive. - Each byday value can also be preceded by a positive - (+n) or negative (-n) integer. If present, this indicates the nth - occurrence of the specific day within the monthly or - yearly recurrence. For example, within a - monthly rule, +1MO (or simply 1MO) represents the first + Each byday value can also be preceded by a positive + (+n) or negative (-n) integer. If present, this indicates the nth + occurrence of the specific day within the monthly or + yearly recurrence. For example, within a + monthly rule, +1MO (or simply 1MO) represents the first Monday within the month, whereas -1MO represents the last Monday of the month. If an integer modifier is not present, it means all days - of this type within the specified frequency. For example, within a + of this type within the specified frequency. For example, within a monthly rule, MO represents all Mondays within the month. bymonthday - parameter specifies a comma-separated - list of days of the month. Valid values are 1 to 31 or -31 to -1. For + list of days of the month. Valid values are 1 to 31 or -31 to -1. For example, -10 represents the tenth to the last day of the month. - byyearday - specifies a comma-separated list of + byyearday - specifies a comma-separated list of days of the year. Valid values are 1 to 366 or -366 to -1. For example, - -1 represents the last day of the year (December 31st) and -306 + -1 represents the last day of the year (December 31st) and -306 represents the 306th to the last day of the year (March 1st). - byweekno - specifies a comma-separated list of - ordinals specifying weeks of the year. Valid values are 1 to 53 or + byweekno - specifies a comma-separated list of + ordinals specifying weeks of the year. Valid values are 1 to 53 or -53 to -1. @@ -576,41 +576,41 @@ - A recurrence is specified by including the freq - parameter, which indicates the type of recurrence rule. Parameters + A recurrence is specified by including the freq + parameter, which indicates the type of recurrence rule. Parameters other than dtstart - and duration SHOULD NOT be specified unless + and duration SHOULD NOT be specified unless freq is present. - If byxxx parameter values are found which are beyond the available + If byxxx parameter values are found which are beyond the available scope (ie, bymonthday=30 in February), they are simply - ignored. + ignored. - Byxxx parameters modify the recurrence in some manner. Byxxx rule - parts for a period of time which is the same or greater than the - frequency generally reduce or limit the number of occurrences of the - recurrence generated. For example, freq=daily + Byxxx parameters modify the recurrence in some manner. Byxxx rule + parts for a period of time which is the same or greater than the + frequency generally reduce or limit the number of occurrences of the + recurrence generated. For example, freq=daily bymonth=1 reduces the number of - recurrence instances from all days (if the bymonth - parameter is not present) to all days in January. Byxxx parameters for - a period of time less than the frequency generally increase or expand - the number of occurrences of the recurrence. For example, + recurrence instances from all days (if the bymonth + parameter is not present) to all days in January. Byxxx parameters for + a period of time less than the frequency generally increase or expand + the number of occurrences of the recurrence. For example, freq=yearly bymonth=1,2 - increases the number of days within the yearly recurrence set from 1 + increases the number of days within the yearly recurrence set from 1 (if bymonth parameter is not present) to 2. If multiple Byxxx parameters are specified, then after evaluating the specified freq and interval parameters, - the Byxxx parameters are + the Byxxx parameters are applied to the current set of evaluated occurrences in the following - order: bymonth, byweekno, - byyearday, bymonthday, + order: bymonth, byweekno, + byyearday, bymonthday, byday; then until is evaluated. @@ -618,24 +618,24 @@ dtstart=19970105T083000 duration=PT10M - freq=yearly interval=2 + freq=yearly interval=2 bymonth=1 byday=SU - First, the interval=2 would be applied to + First, the interval=2 would be applied to freq=yearly to arrive at every other year - . Then, bymonth=1 would be applied to arrive at + . Then, bymonth=1 would be applied to arrive at every January, every other year. Then, - byday=SU would be applied to arrive at every - Sunday in January, - every other year, from 8:30 to 8:40 . The appropriate minutes - and hours have been retrieved from the dtstart and + byday=SU would be applied to arrive at every + Sunday in January, + every other year, from 8:30 to 8:40 . The appropriate minutes + and hours have been retrieved from the dtstart and duration parameters. - priority column + priority column If many rules are eligible, choose the one with highest priority. @@ -643,7 +643,7 @@ - routeid column + routeid column If different than 0, then execute the route with the specified ID. @@ -654,22 +654,22 @@ - gwlist column + gwlist column - A comma separated list of gateway identifiers corresponding to a row in + A comma separated list of gateway identifiers corresponding to a row in table dr_gateways. You can use a predefined list from the table dr_gw_lists preceded by the character #. The first gateway is tried first and if routing to it - fails, then the second one, and so one. If no gateway is left a negative + fails, then the second one, and so one. If no gateway is left a negative response is sent back to caller. - Routing Rules Examples + Routing Rules Examples - + Sample dr_rules records @@ -741,15 +741,15 @@ - the module discovers the routing group of the originating user. This + the module discovers the routing group of the originating user. This step is skipped if a routing group is passed from the script as parameter. - once the group is known, in the subset of the rules for this group the + once the group is known, in the subset of the rules for this group the module looks for the one that matches the destination based on "prefix" - column. The set of rules with the longest prefix is chosen. If no digit + column. The set of rules with the longest prefix is chosen. If no digit from the prefix matches, the default rules are used (rules with no prefix) @@ -762,14 +762,14 @@ - Once found the rule, it may contain a route ID to execute. If a certain + Once found the rule, it may contain a route ID to execute. If a certain flag is set, then the processing is stopped after executing the route block. - The rule must contain a gateway chain. The module will execute serial + The rule must contain a gateway chain. The module will execute serial forking for each address in chain. The next address in chain is used only if the previously has failed. @@ -784,7 +784,7 @@ If no rule is found to match the selection criteria an default action must - be taken (e.g., error response sent back). If the gateway in the chain has + be taken (e.g., error response sent back). If the gateway in the chain has no prefix the request is forwarded without adding any prefix to the request URI. @@ -822,7 +822,7 @@ - +
Parameters
@@ -831,14 +831,14 @@ The database url. - Default value is NULL. + Default value is NULL. Set <varname>db_url</varname> parameter ... -modparam("drouting", "db_url", +modparam("drouting", "db_url", "&defaultdb;") ... @@ -903,7 +903,7 @@ modparam("drouting", "drg_table", "groups")
<varname>drl_table</varname>(str) - The name of the db table storing definitions of destination lists (to + The name of the db table storing definitions of destination lists (to be used directly by the routing rules). You will have a identifier to a group of gateways instead of having all the members of the group as a individual elements. @@ -931,20 +931,20 @@ modparam("drouting", "drl_table", "my_gw_lists") 0 - destination groups are ignored and all the - destinations are tried in the given order; - Ex: list 1,2;3,4,5;6 will lead to usage as 1,2,3,4,5,6 + destinations are tried in the given order; + Ex: list 1,2;3,4,5;6 will lead to usage as 1,2,3,4,5,6 1 - the destinations from each group are randomly arranged (only the two first elements are randomly selected); - groups do maintain their order (as given); the resulting list is + groups do maintain their order (as given); the resulting list is used (with all the defined destinations). - Ex: 1,2;3,4,5;6 -> randomizer -> + Ex: 1,2;3,4,5;6 -> randomizer -> (A) 2,1;4,3,5;6 -> usage 2,1,4,3,5,6 (B) 1,2;3,5,4;6 -> usage 1,2,3,5,4,6 - 2 - from each destination group, only a + 2 - from each destination group, only a single destination is randomly selected; groups do maintain their order (as given); @@ -985,7 +985,7 @@ modparam("drouting", "sort_order", 2)
<varname>ruri_avp</varname> (str) - The name of the avp for storing Request URIs to be later used + The name of the avp for storing Request URIs to be later used (alternative destinations for the current one). @@ -1007,7 +1007,7 @@ modparam("drouting", "ruri_avp", '$avp(i:33)') <varname>attrs_avp</varname> (str) The name of the avp for storing the attribute of the current selected - destination - once a new destination is selected (via the + destination - once a new destination is selected (via the use_next_gw() function), the AVP will be updated with the attrs of the new used destination. @@ -1125,8 +1125,8 @@ modparam("drouting", "fetch_rows", 1500)
<varname>force_dns</varname> (int) - Force DNS resolving of GW/destination names (if not IPs) during - startup. If not enabled, the GW name will be blindly used during + Force DNS resolving of GW/destination names (if not IPs) during + startup. If not enabled, the GW name will be blindly used during routing. @@ -1170,20 +1170,21 @@ modparam("drouting", "enable_keepalive", 1) Functions
- <function moreinfo="none">do_routing("[groupID]")</function> + <function moreinfo="none">do_routing([groupID])</function> - Function to trigger routing of the message according to the + Function to trigger routing of the message according to the rules in the database table and the configured parameters. This function can be used from REQUEST_ROUTE and FAILURE_ROUTE. - The module can take one optional parameter: the routing group the - caller belongs to - this may be a static numerical value or an AVP - specification. If none specified, the function will automatically - try to query the dr_group table to get this information. + The module can take one optional parameter: the routing group the + caller belongs to - this may be a static int value or a variable + holding an int. If none specified, the function will automatically + try to query the dr_group table to get the group id associated with + the user in From URI. <function>do_routing</function> usage @@ -1200,15 +1201,15 @@ do_routing("$avp(i:10)");
- <function moreinfo="none">use_next_gw()/next_routing()</function> + <function moreinfo="none">next_routing()</function> - The function takes the next available destination (set by do_routing, - as alternative destinations) and push it into RURI. Note that the + The function takes the next available destination (set by do_routing, + as alternative destinations) and push it into RURI. Note that the function just sets the RURI (nothing more). - If a new RURI is set, the used destination is removed from the + If a new RURI is set, the used destination is removed from the pending set of alternative destinations. @@ -1220,10 +1221,10 @@ do_routing("$avp(i:10)"); of internal processing error. - <function>use_next_gw</function> usage + <function>next_routing</function> usage ... -if (use_next_gw()) { +if (next_routing()) { t_relay(); exit; } @@ -1232,26 +1233,35 @@ if (use_next_gw()) {
+
+ + <function moreinfo="none">use_next_gw()</function> + + + Same as next_routing(). + +
<function moreinfo="none">goes_to_gw([type])</function> - Function returns true if the destination of the current request + Function returns true if the destination of the current request (destination URI or Request URI) points (as IP) to one of the gateways. - There no DNS lookups done if the domain part of the URI is not an IP. + There is no DNS lookups done if the domain part of the URI is not an IP. This function does not change anything in the message. - This function can be used from REQUEST_ROUTE and FAILURE_ROUTE. + This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and + ONREPLY_ROUTE. - The function can take one optional parameter: + The function can take two optional parameters: - type (optional) - GW/destination + type - GW/destination type to be checked @@ -1269,53 +1279,17 @@ if (goes_to_gw("1")) {
- -
- - <function moreinfo="none">is_from_gw([type])</function> - - - The function checks if the sender of the message is a gateway - from a certain group. - - - This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and - ONREPLY_ROUTE - - - The function can take one optional parameter: - - - type (optional) - GW/destination type - to be checked - - - flags - if message is a request and - the GW has a STRIP defined, then apply it if GW is source. - - - - - <function>is_from_gw</function> usage - -... -if (is_from_gw("1") { -} -... - - -
-
- <function moreinfo="none">is_from_gw( type, [flag])</function> + <function moreinfo="none">is_from_gw([ type, [flag] ])</function> The function checks if the sender of the message is a gateway - from a certain group. + from a group in drouting rules. - This function can be used from REQUEST_ROUTE and FAILURE_ROUTE. + This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and + ONREPLY_ROUTE. The function can take two parameters: @@ -1325,8 +1299,8 @@ if (is_from_gw("1") { type to be checked - flags (optional) - if message is a - request and the GW has a STRIP defined, then apply it + flags (optional) - if message is a + request and the GW has a STRIP defined, then apply it if GW is source. @@ -1335,6 +1309,9 @@ if (is_from_gw("1") { <function>is_from_gw</function> usage ... +if (is_from_gw("1") { +} +... if (is_from_gw("3","1") { } ... diff --git a/src/modules/drouting/drouting.c b/src/modules/drouting/drouting.c index e4ca15d4d01..f3e59991c0e 100644 --- a/src/modules/drouting/drouting.c +++ b/src/modules/drouting/drouting.c @@ -141,7 +141,7 @@ static cmd_export_t cmds[] = { {"is_from_gw", (cmd_function)is_from_gw_1, 1, fixup_igp_null, 0, REQUEST_ROUTE | FAILURE_ROUTE | ONREPLY_ROUTE}, {"is_from_gw", (cmd_function)is_from_gw_2, 2, fixup_igp_igp, 0, - REQUEST_ROUTE}, + REQUEST_ROUTE | FAILURE_ROUTE | ONREPLY_ROUTE}, {"goes_to_gw", (cmd_function)goes_to_gw_0, 0, 0, 0, REQUEST_ROUTE | FAILURE_ROUTE | ONREPLY_ROUTE}, {"goes_to_gw", (cmd_function)goes_to_gw_1, 1, fixup_igp_null, 0,