modules: readme files regenerated - drouting ... [skip ci]
[sip-router] / src / modules / drouting / README
1 Dynamic Routing Module
2
3    Voice Sistem SRL
4
5 Edited by
6
7 Ovidiu Sas
8
9 Edited by
10
11 Anca-Maria Vamanu
12
13    Copyright © 2005-2008 Voice Sistem SRL
14      __________________________________________________________________
15
16    Table of Contents
17
18    1. Admin Guide
19
20         1. Overview
21
22               1.1. Introduction
23               1.2. Features
24               1.3. Performance
25               1.4. Routing Rule Definition
26
27                     1.4.1. Gateway Addresses
28                     1.4.2. Destination/GW lists
29                     1.4.3. Routing Rules
30
31               1.5. Routing Rule Processing
32
33         2. Dependencies
34
35               2.1. Kamailio Modules
36               2.2. External Libraries or Applications
37
38         3. Parameters
39
40               3.1. db_url(str)
41               3.2. drd_table(str)
42               3.3. drr_table(str)
43               3.4. drg_table(str)
44               3.5. drl_table(str)
45               3.6. sort_order (int)
46               3.7. ruri_avp (str)
47               3.8. attrs_avp (str)
48               3.9. use_domain (int)
49               3.10. drg_user_col (str)
50               3.11. drg_domain_col (str)
51               3.12. drg_grpid_col (str)
52               3.13. fetch_rows (int)
53               3.14. force_dns (int)
54               3.15. enable_keepalive (int)
55
56         4. Functions
57
58               4.1. do_routing([groupID])
59               4.2. next_routing()
60               4.3. use_next_gw()
61               4.4. goes_to_gw([type])
62               4.5. is_from_gw([ type, [flag] ])
63
64         5. RPC Commands
65
66               5.1. drouting.reload
67
68         6. Installation
69
70    2. Developer Guide
71
72    List of Tables
73
74    1.1. Definition of table dr_gateways
75    1.2. Sample dr_gateways records
76    1.3. Definition of dr_rules table
77    1.4. Time recurrence attributes
78    1.5. Sample dr_rules records
79
80    List of Examples
81
82    1.1. Set db_url parameter
83    1.2. Set drd_table parameter
84    1.3. Set drr_table parameter
85    1.4. Set drg_table parameter
86    1.5. Set drl_table parameter
87    1.6. Set sort_order parameter
88    1.7. Set ruri_avp parameter
89    1.8. Set attrs_avp parameter
90    1.9. Set use_domain parameter
91    1.10. Set drg_user_col parameter
92    1.11. Set drg_domain_col parameter
93    1.12. Set drg_grpid_col parameter
94    1.13. Set fetch_rows parameter
95    1.14. Set force_dns parameter
96    1.15. Set enable_keepalive parameter
97    1.16. do_routing usage
98    1.17. next_routing usage
99    1.18. goes_to_gw usage
100    1.19. is_from_gw usage
101
102 Chapter 1. Admin Guide
103
104    Table of Contents
105
106    1. Overview
107
108         1.1. Introduction
109         1.2. Features
110         1.3. Performance
111         1.4. Routing Rule Definition
112
113               1.4.1. Gateway Addresses
114               1.4.2. Destination/GW lists
115               1.4.3. Routing Rules
116
117         1.5. Routing Rule Processing
118
119    2. Dependencies
120
121         2.1. Kamailio Modules
122         2.2. External Libraries or Applications
123
124    3. Parameters
125
126         3.1. db_url(str)
127         3.2. drd_table(str)
128         3.3. drr_table(str)
129         3.4. drg_table(str)
130         3.5. drl_table(str)
131         3.6. sort_order (int)
132         3.7. ruri_avp (str)
133         3.8. attrs_avp (str)
134         3.9. use_domain (int)
135         3.10. drg_user_col (str)
136         3.11. drg_domain_col (str)
137         3.12. drg_grpid_col (str)
138         3.13. fetch_rows (int)
139         3.14. force_dns (int)
140         3.15. enable_keepalive (int)
141
142    4. Functions
143
144         4.1. do_routing([groupID])
145         4.2. next_routing()
146         4.3. use_next_gw()
147         4.4. goes_to_gw([type])
148         4.5. is_from_gw([ type, [flag] ])
149
150    5. RPC Commands
151
152         5.1. drouting.reload
153
154    6. Installation
155
156 1. Overview
157
158    1.1. Introduction
159    1.2. Features
160    1.3. Performance
161    1.4. Routing Rule Definition
162
163         1.4.1. Gateway Addresses
164         1.4.2. Destination/GW lists
165         1.4.3. Routing Rules
166
167    1.5. Routing Rule Processing
168
169 1.1. Introduction
170
171    Dynamic Routing is a module for selecting (based on multiple criteria)
172    the the best gateway/destination to be used for delivering a certain
173    call. Least Cost Routing (LCR) is a special case of dynamic routing -
174    when the rules are ordered based on costs. Dynamic Routing comes with
175    many features regarding routing rule selection:
176      * prefix based
177      * caller/group based
178      * time based
179      * priority based
180
181    , processing :
182      * stripping and prefixing
183      * default rules
184      * inbound and outbound processing
185      * script route triggering
186
187    and failure handling:
188      * serial forking
189      * weight based GW selection
190      * random GW selection
191
192 1.2. Features
193
194    The dynamic routing implementation for Kamailio is designed with the
195    following properties:
196      * routing info (destinations, rules, groups) are stored in a database
197        and loaded into memory at start up time; reload at runtime via RPC
198        command
199      * load balancing or random selection of the destinations (from a
200        given set)
201      * able to handle large volume of routing info (300K of rules) with
202        minimal speed/time and memory consumption penalties
203      * script integration - Pseudo variables support in functions;
204        scripting route triggering when rules are matched
205      * bidirectional behavior - inbound and outbound processing (strip and
206        prefixing when sending and receiving from a destination/GW)
207
208 1.3. Performance
209
210    There were several tests performed regarding the performance of the
211    module when dealing with a large number of routing rules.
212
213    The tests were performed with a set of 383000 rules and to values were
214    measured:
215      * time to load from DB
216      * used shared memory
217
218    The time to load was varying between 4 seconds and 8 seconds, depending
219    of the caching of the DB client - the first load was the slowest (as
220    the DB query hits the disk drive); the following are faster as data is
221    already cached in the DB client. So technically speaking, the time to
222    load (without the time to query which is DB type dependent) is ~4
223    seconds
224
225    After loading the data into shared memory ~ 96M of memory were used
226    exclusively for the DR data.
227
228 1.4. Routing Rule Definition
229
230    Dynamic routing rules are stored in a database, in four tables:
231      * one for storing the gateway definitions
232      * one for storing the routing rule definitions
233      * one for storing the users mappings over groups
234      * one for storing a list of gateways, so you don't have to enter all
235        the elements every time you need it
236
237 1.4.1. Gateway Addresses
238
239    Default name for the table storing gateway addresses is “dr_gateways”.
240    Gateway addresses are stored in a separate table because of need to
241    access them independent of Dynamic Routing processing (e.g., adding/
242    removing gateway PRI prefix before/after performing other operation --
243    receiving/relaying to gateway).
244
245    Table 1.1. Definition of table dr_gateways
246    Column name     Type     Default value         Description
247    gwid        integer      auto increment unique identifier for GW
248    type        unsigned int 0              type/class of GW
249    address     varchar(128)                address of the gateway
250    strip       unsigned int 0              no of digits to strip
251    pri_prefix  varchar(255)                PRI prefix of the gateway
252    description varchar(128)                description of the gateway
253
254    Once a rule is matched, the STRIP number of digits are removed from the
255    username part of the RURI and then the PRI prefix has to be added to
256    the request URI before forwarding the call to the gateway.
257
258    Table 1.2. Sample dr_gateways records
259    gwid type     address      strip pri_prefix description
260    1    10   10.10.10.10:5080 0     2222       Gateway 1
261    2    10   10.10.10.10      2     3333       Gateway 2
262    3    20   10.10.10.11      0                Gateway 3
263
264 1.4.2. Destination/GW lists
265
266    For each rule, you can set a list of destinations to be used. The list
267    is comma or pipe separated enumeration of the destinations. The module
268    will use (one by one) each destination from the list (in the given
269    order).
270
271    Also the module allows the usage of groups in the destination lists. A
272    group of destinations is delimited by semi-colon char. inside the whole
273    destination list ( like: 2,4;5,78,23;4;7;2 ). The destinations from
274    within a group may be act differently (like load-balancing, random
275    selection, etc), depending of the “sort_order” module parameter - more
276    about this is available under the module paramters section.
277
278 1.4.3. Routing Rules
279
280    Default name for the table storing rule definitions is “dr_rules”.
281
282    Table 1.3. Definition of dr_rules table
283    Column name     Type     Default            Description
284    ruleid      integer      auto    UID of the rule
285    groupid     varchar(255)         list of routing group IDs
286    prefix      varchar(64)          destination prefix for this route
287    timerec     varchar(255)         time recurrence for this rule
288    priority    integer      0       priority of the rule
289    routeid     integer      0       route block to be execute
290    gwlist      varchar(255)         the list with GWs to be used
291    description varchar(128)         description of this rule
292
293     a. groupid column
294        Each user must be member of only one routing group. It must be
295        specified in user's profile.
296     b. prefix column
297        Destination URI must start with prefix value to match the rule. The
298        prefix value can contain only digits (0..9), '+', '*' or '#'.
299     c. time rec column
300        A date-time expression that defines the time recurrence to match
301        for current rule. Time recurrences are based closely on the
302        specification of recurring intervals of time in the Internet
303        Calendaring and Scheduling Core Object Specification (calendar
304        COS), RFC 2445. The set of attributes used in routing rule
305        specification is subset of time recurrence attributes used by Call
306        Processing Language (CPL). These attributes are (extracted from CPL
307        draft 09):
308        Table 1.4. Time recurrence attributes
309
310      Attribute                            Description
311      dastard    Start of interval (RFC 2445 DATE-TIME)
312      duration   Length of interval (RFC 2445 DURATION)
313      freq       Frequency of recurrence (secondly,minutely,hourly, daily,weekly,
314                 monthly, or yearly).
315      until      bound of recurrence (RFC 2445 DATE-TIME)
316      interval   How often the recurrence repeats
317      byday      List of days of the week
318      bymonthday List of days of the month
319      byyearday  List of days of the year
320      byweekno   List of weeks of the year
321      bymonth    List of months of the year
322        The value stored in database has the format of:
323        <dtstart>|<duration>|<freq>|<until>|<interval>|<byday>|<bymonthday>
324        |<byyearday>|<byweekno>|<bymonth>
325        When an attribute is not specified, the corresponding place must be
326        left empty, whenever another attribute that follows in the list has
327        to be specified.
328        Detailed description of time recurrence attributes:
329           + dtstart - specifies the beginning of the first period.
330           + duration - specifies the duration of the period. For a
331             recurring interval, the “duration” parameter MUST be small
332             enough such that subsequent intervals do not overlap. For
333             non-recurring intervals, durations of any positive length are
334             permitted, zero-length duration means “forever”.
335             Negative-length durations are not allowed. In the common case
336             of a duration less than one day, the value starts with 'PT'
337             followed by number of hours, minutes and seconds, e.g., a
338             duration of 8 hours and 30 minutes is written 'PT8H30M'. See
339             RFC 2445 DURATION specifications for full format.
340           + freq - takes one of the following values: “daily”, to specify
341             repeating periods based on an interval of a day or more;
342             “weekly”, to specify repeating periods based on an interval of
343             a week or more; “monthly”, to specify repeating periods based
344             on an interval of a month or more; and “yearly”, to specify
345             repeating periods based on an interval of a year or more.
346             These values are not case-sensitive.
347           + until - defines an iCalendar COS DATE or DATE-TIME value which
348             bounds the recurrence rule in an inclusive manner. If the
349             value specified by “until” is synchronized with the specified
350             recurrence, this date or date-time becomes the last instance
351             of the recurrence. If not present, the recurrence is
352             considered to repeat forever.
353           + interval - contains a positive integer representing how often
354             the recurrence rule repeats. The default value is “1”, meaning
355             every day for a “daily” rule, every week for a “weekly” rule,
356             every month for a “monthly” rule and every year for a “yearly”
357             rule.
358           + interval - contains a positive integer representing how often
359             the recurrence rule repeats. The default value is “1”, meaning
360             every day for a “daily” rule, every week for a “weekly” rule,
361             every month for a “monthly” rule and every year for a “yearly”
362             rule.
363           + byday - specifies a comma-separated list of days of the week.
364             “MO” indicates Monday; “TU” indicates Tuesday; “WE” indicates
365             Wednesday; “TH” indicates Thursday; “FR” indicates Friday;
366             “SA” indicates Saturday; “SU” indicates Sunday. These values
367             are not case-sensitive.
368             Each “byday” value can also be preceded by a positive (+n) or
369             negative (-n) integer. If present, this indicates the nth
370             occurrence of the specific day within the “monthly” or
371             “yearly” recurrence. For example, within a “monthly” rule,
372             +1MO (or simply 1MO) represents the first Monday within the
373             month, whereas -1MO represents the last Monday of the month.
374             If an integer modifier is not present, it means all days of
375             this type within the specified frequency. For example, within
376             a “monthly” rule, MO represents all Mondays within the month.
377           + bymonthday - parameter specifies a comma-separated list of
378             days of the month. Valid values are 1 to 31 or -31 to -1. For
379             example, -10 represents the tenth to the last day of the
380             month.
381           + byyearday - specifies a comma-separated list of days of the
382             year. Valid values are 1 to 366 or -366 to -1. For example, -1
383             represents the last day of the year (December 31st) and -306
384             represents the 306th to the last day of the year (March 1st).
385           + byweekno - specifies a comma-separated list of ordinals
386             specifying weeks of the year. Valid values are 1 to 53 or -53
387             to -1.
388           + bymonth - parameter specifies a comma-separated list of months
389             of the year. Valid values are 1 to 12.
390        A recurrence is specified by including the “freq” parameter, which
391        indicates the type of recurrence rule. Parameters other than
392        “dtstart” and “duration” SHOULD NOT be specified unless “freq” is
393        present.
394        If byxxx parameter values are found which are beyond the available
395        scope (ie, bymonthday=“30” in February), they are simply ignored.
396        Byxxx parameters modify the recurrence in some manner. Byxxx rule
397        parts for a period of time which is the same or greater than the
398        frequency generally reduce or limit the number of occurrences of
399        the recurrence generated. For example, freq=“daily” bymonth=“1”
400        reduces the number of recurrence instances from all days (if the
401        “bymonth” parameter is not present) to all days in January. Byxxx
402        parameters for a period of time less than the frequency generally
403        increase or expand the number of occurrences of the recurrence. For
404        example, freq=“yearly” bymonth=“1,2” increases the number of days
405        within the yearly recurrence set from 1 (if “bymonth” parameter is
406        not present) to 2.
407        If multiple Byxxx parameters are specified, then after evaluating
408        the specified “freq” and “interval” parameters, the Byxxx
409        parameters are applied to the current set of evaluated occurrences
410        in the following order: “bymonth”, “byweekno”, “byyearday”,
411        “bymonthday”, “byday”; then “until” is evaluated.
412        Here is an example of evaluating multiple Byxxx parameters.
413        dtstart=“19970105T083000” duration=“PT10M” freq=“yearly”
414        interval=“2” bymonth=“1” byday=“SU”
415        First, the interval=“2” would be applied to freq=“yearly” to arrive
416        at “every other year” . Then, bymonth=“1” would be applied to
417        arrive at “every January, every other year”. Then, byday=“SU” would
418        be applied to arrive at “every Sunday in January, every other year,
419        from 8:30 to 8:40 ”. The appropriate minutes and hours have been
420        retrieved from the “dtstart” and “duration” parameters.
421     d. priority column
422        If many rules are eligible, choose the one with highest priority.
423     e. routeid column
424        If different than 0, then execute the route with the specified ID.
425        That is, a route which can be used to perform custom operations on
426        message. At this route, no modification is performed at signaling
427        level.
428     f. gwlist column
429        A comma separated list of gateway identifiers corresponding to a
430        row in table “dr_gateways”. You can use a predefined list from the
431        table “dr_gw_lists” preceded by the character “#”. The first
432        gateway is tried first and if routing to it fails, then the second
433        one, and so one. If no gateway is left a negative response is sent
434        back to caller.
435     g. Routing Rules Examples
436        Table 1.5. Sample dr_rules records
437
438    ruleid group prefix timerec priority routeid gwlist description
439    1 6 0049 20040101T083000|10H|weekly|||MO,TU,WE,TH,FR 5 23 1,2 Rule 1
440    2 8 0049 20040101T083000 0 0 1,2 Rule 2
441    3 7,8,9 0049 20040101T083000 0 0 3 Rule 3
442        (The time recurrence for first rule is:
443        “20040101T083000|10H|weekly|||MO,TU,WE,TH,FR”)
444
445 1.5. Routing Rule Processing
446
447    The module can be used to find out which is the best gateway to use for
448    new calls terminated to PSTN. The algorithm to select the rule is as
449    follows:
450      * the module discovers the routing group of the originating user.
451        This step is skipped if a routing group is passed from the script
452        as parameter.
453      * once the group is known, in the subset of the rules for this group
454        the module looks for the one that matches the destination based on
455        "prefix" column. The set of rules with the longest prefix is
456        chosen. If no digit from the prefix matches, the default rules are
457        used (rules with no prefix)
458      * within the set of rules is applied the time criteria, and the rule
459        which has the highest priority and matches the time criteria is
460        selected to drive the routing.
461      * Once found the rule, it may contain a route ID to execute. If a
462        certain flag is set, then the processing is stopped after executing
463        the route block.
464      * The rule must contain a gateway chain. The module will execute
465        serial forking for each address in chain. The next address in chain
466        is used only if the previously has failed.
467      * With the right gateway address found, the prefix (PRI) of the
468        gateway is added to the request URI and then the request is
469        forwarded.
470
471    If no rule is found to match the selection criteria an default action
472    must be taken (e.g., error response sent back). If the gateway in the
473    chain has no prefix the request is forwarded without adding any prefix
474    to the request URI.
475
476 2. Dependencies
477
478    2.1. Kamailio Modules
479    2.2. External Libraries or Applications
480
481 2.1. Kamailio Modules
482
483    The following modules must be loaded before this module:
484      * a database module.
485
486 2.2. External Libraries or Applications
487
488      * none.
489
490 3. Parameters
491
492    3.1. db_url(str)
493    3.2. drd_table(str)
494    3.3. drr_table(str)
495    3.4. drg_table(str)
496    3.5. drl_table(str)
497    3.6. sort_order (int)
498    3.7. ruri_avp (str)
499    3.8. attrs_avp (str)
500    3.9. use_domain (int)
501    3.10. drg_user_col (str)
502    3.11. drg_domain_col (str)
503    3.12. drg_grpid_col (str)
504    3.13. fetch_rows (int)
505    3.14. force_dns (int)
506    3.15. enable_keepalive (int)
507
508 3.1. db_url(str)
509
510    The database url.
511
512    Default value is “NULL”.
513
514    Example 1.1. Set db_url parameter
515 ...
516 modparam("drouting", "db_url",
517         "mysql://kamailio:kamailiorw@localhost/kamailio")
518 ...
519
520 3.2. drd_table(str)
521
522    The name of the db table storing gateway addresses.
523
524    Default value is “dr_gateways”.
525
526    Example 1.2. Set drd_table parameter
527 ...
528 modparam("drouting", "drd_table", "dr_gateways")
529 ...
530
531 3.3. drr_table(str)
532
533    The name of the db table storing routing rules.
534
535    Default value is “dr_rules”.
536
537    Example 1.3. Set drr_table parameter
538 ...
539 modparam("drouting", "drr_table", "rules")
540 ...
541
542 3.4. drg_table(str)
543
544    The name of the db table storing groups.
545
546    Default value is “dr_groups”.
547
548    Example 1.4. Set drg_table parameter
549 ...
550 modparam("drouting", "drg_table", "groups")
551 ...
552
553 3.5. drl_table(str)
554
555    The name of the db table storing definitions of destination lists (to
556    be used directly by the routing rules). You will have a identifier to a
557    group of gateways instead of having all the members of the group as a
558    individual elements. Very useful to reuse a list of gateways in
559    different places.
560
561    Default value is “dr_gw_lists”.
562
563    Example 1.5. Set drl_table parameter
564 ...
565 modparam("drouting", "drl_table", "my_gw_lists")
566 ...
567
568 3.6. sort_order (int)
569
570    Defines how the destination list should be processed (ordering of the
571    elements). Possible modes are
572      * 0 - destination groups are ignored and all the destinations are
573        tried in the given order; Ex: list 1,2;3,4,5;6 will lead to usage
574        as 1,2,3,4,5,6
575      * 1 - the destinations from each group are randomly arranged (only
576        the two first elements are randomly selected); groups do maintain
577        their order (as given); the resulting list is used (with all the
578        defined destinations). Ex: 1,2;3,4,5;6 -> randomizer -> (A)
579        2,1;4,3,5;6 -> usage 2,1,4,3,5,6 (B) 1,2;3,5,4;6 -> usage
580        1,2,3,5,4,6
581      * 2 - from each destination group, only a single destination is
582        randomly selected; groups do maintain their order (as given);
583        Ex: 1,2;3,4,5;6 -> randomizer ->
584        (A) 2;4;6 -> usage 2,4,6
585        (B) 1;5;6 -> usage 1,5,6
586        It is ok to have repeating gateways in different groups. The module
587        will take care internally in case of failure not to choose a
588        gateway that was tried already.
589        Ex: 1,2,3; 1,2,3; 1,2,3 -> no gateway will be chosen twice. So in
590        case there are 2 failures, all the three gateways (1,2,3) will be
591        tried in a random order.
592
593    Default value is “0”.
594
595    Example 1.6. Set sort_order parameter
596 ...
597 modparam("drouting", "sort_order", 2)
598 ...
599
600 3.7. ruri_avp (str)
601
602    The name of the avp for storing Request URIs to be later used
603    (alternative destinations for the current one).
604
605    Default value is “NULL”.
606
607    Example 1.7. Set ruri_avp parameter
608 ...
609 modparam("drouting", "ruri_avp", '$avp(dr_ruri)')
610 modparam("drouting", "ruri_avp", '$avp(i:33)')
611 ...
612
613 3.8. attrs_avp (str)
614
615    The name of the avp for storing the attribute of the current selected
616    destination - once a new destination is selected (via the use_next_gw()
617    function), the AVP will be updated with the attrs of the new used
618    destination.
619
620    Default value is “NULL”.
621
622    Example 1.8. Set attrs_avp parameter
623 ...
624 modparam("drouting", "attrs_avp", '$avp(dr_attrs)')
625 modparam("drouting", "atrrs_avp", '$avp(i:67)')
626 ...
627
628 3.9. use_domain (int)
629
630    Flag to configure whether to use domain match when querying database
631    for user's routing group.
632
633    Default value is “1”.
634
635    Example 1.9. Set use_domain parameter
636 ...
637 modparam("drouting", "use_domain", 0)
638 ...
639
640 3.10. drg_user_col (str)
641
642    The name of the column in group db table where the username is stored.
643
644    Default value is “username”.
645
646    Example 1.10. Set drg_user_col parameter
647 ...
648 modparam("drouting", "drg_user_col", "user")
649 ...
650
651 3.11. drg_domain_col (str)
652
653    The name of the column in group db table where the domain is stored.
654
655    Default value is “domain”.
656
657    Example 1.11. Set drg_domain_col parameter
658 ...
659 modparam("drouting", "drg_domain_col", "host")
660 ...
661
662 3.12. drg_grpid_col (str)
663
664    The name of the column in group db table where the group id is stored.
665
666    Default value is “groupid”.
667
668    Example 1.12. Set drg_grpid_col parameter
669 ...
670 modparam("drouting", "drg_grpid_col", "grpid")
671 ...
672
673 3.13. fetch_rows (int)
674
675    The number of rows that should be fetched from the result of a query in
676    rules db table.
677
678    Default value is “2000”.
679
680    Example 1.13. Set fetch_rows parameter
681 ...
682 modparam("drouting", "fetch_rows", 1500)
683 ...
684
685 3.14. force_dns (int)
686
687    Force DNS resolving of GW/destination names (if not IPs) during
688    startup. If not enabled, the GW name will be blindly used during
689    routing.
690
691    Default value is “1 (enabled)”.
692
693    Example 1.14. Set force_dns parameter
694 ...
695 modparam("drouting", "force_dns", 0)
696 ...
697
698 3.15. enable_keepalive (int)
699
700    Enable monitoring of GW/destinations using keepalive module.
701    Destinations found unavailable will not be used on do_routing() call.
702
703    Default value is “0 (disabled)”.
704
705    Example 1.15. Set enable_keepalive parameter
706 ...
707 modparam("drouting", "enable_keepalive", 1)
708 ...
709
710 4. Functions
711
712    4.1. do_routing([groupID])
713    4.2. next_routing()
714    4.3. use_next_gw()
715    4.4. goes_to_gw([type])
716    4.5. is_from_gw([ type, [flag] ])
717
718 4.1.  do_routing([groupID])
719
720    Function to trigger routing of the message according to the rules in
721    the database table and the configured parameters.
722
723    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
724
725    The module can take one optional parameter: the routing group the
726    caller belongs to - this may be a static int value or a variable
727    holding an int. If none specified, the function will automatically try
728    to query the dr_group table to get the group id associated with the
729    user in From URI.
730
731    Example 1.16. do_routing usage
732 ...
733 do_routing();
734 ...
735 do_routing("0");
736 ...
737 do_routing("$avp(i:10)");
738
739 4.2.  next_routing()
740
741    The function takes the next available destination (set by do_routing,
742    as alternative destinations) and push it into RURI. Note that the
743    function just sets the RURI (nothing more).
744
745    If a new RURI is set, the used destination is removed from the pending
746    set of alternative destinations.
747
748    This function can be used from REQUEST_ROUTE and FAILURE_ROUTE.
749
750    The function returns true only if a new RURI was set. False is returned
751    is no other alternative destinations are found or in case of internal
752    processing error.
753
754    Example 1.17. next_routing usage
755 ...
756 if (next_routing()) {
757         t_relay();
758         exit;
759 }
760 ...
761
762 4.3.  use_next_gw()
763
764    Same as next_routing().
765
766 4.4.  goes_to_gw([type])
767
768    Function returns true if the destination of the current request
769    (destination URI or Request URI) points (as IP) to one of the gateways.
770    There is no DNS lookups done if the domain part of the URI is not an
771    IP.
772
773    This function does not change anything in the message.
774
775    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and
776    ONREPLY_ROUTE.
777
778    The function can take two optional parameters:
779      * type - GW/destination type to be checked
780
781    Example 1.18. goes_to_gw usage
782 ...
783 if (goes_to_gw("1")) {
784         sl_send_reply("403","Forbidden");
785         exit;
786 }
787 ...
788
789 4.5.  is_from_gw([ type, [flag] ])
790
791    The function checks if the sender of the message is a gateway from a
792    group in drouting rules.
793
794    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE and
795    ONREPLY_ROUTE.
796
797    The function can take two parameters:
798      * type (mandatory) - GW/destination type to be checked
799      * flags (optional) - if message is a request and the GW has a STRIP
800        defined, then apply it if GW is source.
801
802    Example 1.19. is_from_gw usage
803 ...
804 if (is_from_gw("1") {
805 }
806 ...
807 if (is_from_gw("3","1") {
808 }
809 ...
810
811 5. RPC Commands
812
813    5.1. drouting.reload
814
815 5.1.  drouting.reload
816
817    Command to reload routing rules from database.
818
819    It takes no parameter.
820
821    RPC Command Format:
822         kamcmd drouting.reload
823
824 6. Installation
825
826    The module requires 3 table in Kamailio database: dr_groups,
827    dr_gateways, dr_rules. The SQL syntax to create them can be found in
828    drouting-create.sql script in kamctl db directories. You can also find
829    the complete database documentation on the project webpage,
830    https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
831
832 Chapter 2. Developer Guide
833
834    The module provides no function to be used by other Kamailio modules.