3b89fbd7da4ad52aa4d162bdb99ed3b65490c016
[sip-router] / src / modules / dialplan / README
1 dialplan Module
2
3 Andreea-Ancuta Onofrei
4
5    Voice Sistem SRL
6
7 Edited by
8
9 Andreea-Ancuta Onofrei
10
11 Edited by
12
13 Juha Heinanen
14
15 Edited by
16
17 Olle E. Johansson
18
19 Edited by
20
21 Luis Martin
22
23    Copyright © 2007-2008 Voice Sistem SRL
24
25    Copyright © 2008-2010 Juha Heinanen
26
27    Copyright © 2014 Olle E. Johansson, Edvina AB
28      __________________________________________________________________
29
30    Table of Contents
31
32    1. Admin Guide
33
34         1. Overview
35         2. How it works
36         3. Dialplan use cases
37         4. Dependencies
38
39               4.1. Kamailio Modules
40               4.2. External Libraries or Applications
41
42         5. Parameters
43
44               5.1. db_url (string)
45               5.2. table_name (string)
46               5.3. dpid_col (string)
47               5.4. pr_col (string)
48               5.5. match_op_col (string)
49               5.6. match_exp_col (string)
50               5.7. match_len_col (string)
51               5.8. subst_exp_col (string)
52               5.9. repl_exp_col (string)
53               5.10. attrs_col (string)
54               5.11. attrs_pvar (string)
55               5.12. fetch_rows (int)
56               5.13. match_dynamic (int)
57               5.14. append_branch (int)
58               5.15. reload_delta (int)
59
60         6. Functions
61
62               6.1. dp_replace(dpid, inval, outvar)
63               6.2. dp_match(dpid, inval)
64               6.3. dp_translate(id, [src[/dest]])
65               6.4. dp_reload()
66
67         7. RPC Commands
68
69               7.1. dialplan.dump
70               7.2. dialplan.reload
71               7.3. dialplan.translate
72
73         8. Installation
74
75    2. Developer's Guide
76
77    List of Examples
78
79    1.1. Set db_url parameter
80    1.2. Set table_name parameter
81    1.3. Set dpid_col parameter
82    1.4. Set pr_col parameter
83    1.5. Set match_op_col parameter
84    1.6. Set match_exp_col parameter
85    1.7. Set pr_col parameter
86    1.8. Set pr_col parameter
87    1.9. Set repl_exp_col parameter
88    1.10. Set attrs_col parameter
89    1.11. Set attrs_pvar parameter
90    1.12. Set fetch_rows parameter
91    1.13. Set match_dynamic parameter
92    1.14. Set append_branch parameter
93    1.15. Set reload_delta parameter
94    1.16. dp_replace usage
95    1.17. dp_match usage
96    1.18. dp_translate usage
97    1.19. dp_translate usage
98    1.20. Example of rules
99
100 Chapter 1. Admin Guide
101
102    Table of Contents
103
104    1. Overview
105    2. How it works
106    3. Dialplan use cases
107    4. Dependencies
108
109         4.1. Kamailio Modules
110         4.2. External Libraries or Applications
111
112    5. Parameters
113
114         5.1. db_url (string)
115         5.2. table_name (string)
116         5.3. dpid_col (string)
117         5.4. pr_col (string)
118         5.5. match_op_col (string)
119         5.6. match_exp_col (string)
120         5.7. match_len_col (string)
121         5.8. subst_exp_col (string)
122         5.9. repl_exp_col (string)
123         5.10. attrs_col (string)
124         5.11. attrs_pvar (string)
125         5.12. fetch_rows (int)
126         5.13. match_dynamic (int)
127         5.14. append_branch (int)
128         5.15. reload_delta (int)
129
130    6. Functions
131
132         6.1. dp_replace(dpid, inval, outvar)
133         6.2. dp_match(dpid, inval)
134         6.3. dp_translate(id, [src[/dest]])
135         6.4. dp_reload()
136
137    7. RPC Commands
138
139         7.1. dialplan.dump
140         7.2. dialplan.reload
141         7.3. dialplan.translate
142
143    8. Installation
144
145 1. Overview
146
147    This module implements generic string translations based on matching
148    and replacement rules. It can be used to manipulate the request URI or
149    a PV and to translate it to a new format/value. Dialplan can also be
150    used to match a given URI and retrieve a set of attributes based on the
151    match. It is a very flexible module that can be used to handle call
152    routing, prefix rewrites and much more.
153
154 2. How it works
155
156    At startup the module will load a set of matching and transformation
157    rules from a database. Rules are grouped into dialplans. Every database
158    row will be stored in memory as a dialplan rule. Each rule will
159    describe how the matching will be made, how the input value will be
160    modified and which attributes that will be set for the matching
161    transformation.
162
163    The module expects an input value which will be matched against a rule
164    by using regular expressions (see 'man pcresyntax' for syntax), string
165    or fnmatch (see 'man fnmatch') matching. Overlapping matching
166    expressions can be controlled via priorities. One priority can have
167    multiple dialplan entries. Priorities need not be numbered with
168    consecutive numbers. The next higher priority will be used after trying
169    to match all entries in one priority.
170
171    Once a rule is matched, the defined transformation (if any) is applied
172    and the result is returned as output value. Also, if any string
173    attribute is associated to the rule, this will be returned to the
174    script along with the output value. This can be used to identify the
175    used rule.
176
177    The first matching rule will be processed.
178
179 3. Dialplan use cases
180
181    The module can be used to implement multiple dialplans - to do
182    auto-completion of dialed numbers (like national to international), to
183    convert generic numbers to specific numbers (like for emergency
184    numbers).
185
186    The module can also be used for detecting a range or sets of numbers
187    mapped on a service/case - the attribute string can be used to store
188    extra information about the service/case.
189
190    Non-SIP string translation can be implemented - like converting country
191    names from all possible formats to a canonical format: (UK, England,
192    United Kingdom) -> GB.
193
194    Any other string-base translation or detection for whatever other
195    purposes.
196
197 4. Dependencies
198
199    4.1. Kamailio Modules
200    4.2. External Libraries or Applications
201
202 4.1. Kamailio Modules
203
204    The following modules must be loaded before this module:
205      * A database module
206
207 4.2. External Libraries or Applications
208
209    The following libraries or applications must be installed before
210    running Kamailio with this module loaded:
211      * libpcre - the libraries of PCRE.
212
213 5. Parameters
214
215    5.1. db_url (string)
216    5.2. table_name (string)
217    5.3. dpid_col (string)
218    5.4. pr_col (string)
219    5.5. match_op_col (string)
220    5.6. match_exp_col (string)
221    5.7. match_len_col (string)
222    5.8. subst_exp_col (string)
223    5.9. repl_exp_col (string)
224    5.10. attrs_col (string)
225    5.11. attrs_pvar (string)
226    5.12. fetch_rows (int)
227    5.13. match_dynamic (int)
228    5.14. append_branch (int)
229    5.15. reload_delta (int)
230
231 5.1. db_url (string)
232
233    The translation rules will be loaded using this database URL.
234
235    Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
236
237    Example 1.1. Set db_url parameter
238 ...
239 modparam("dialplan", "db_url", "mysql://user:passwb@localhost/db")
240 ...
241
242 5.2. table_name (string)
243
244    The name of the database table used to load the translation rules.
245
246    Default value is “dialplan”.
247
248    Example 1.2. Set table_name parameter
249 ...
250 modparam("dialplan", "table_name", "my_table")
251 ...
252
253 5.3. dpid_col (string)
254
255    The column name used to store the dialplan group ID.
256
257    Default value is “dpid”.
258
259    Example 1.3. Set dpid_col parameter
260 ...
261 modparam("dialplan", "dpid_col", "column_name")
262 ...
263
264 5.4. pr_col (string)
265
266    The column name used to store the priority of the corresponding rule
267    from the database row.
268
269    Default value is “pr”.
270
271    Example 1.4. Set pr_col parameter
272 ...
273 modparam("dialplan", "pr_col", "column_name")
274 ...
275
276 5.5. match_op_col (string)
277
278    The column name used to store the type of matching of the rule.
279
280    Default value is “match_op”.
281
282    Example 1.5. Set match_op_col parameter
283 ...
284 modparam("dialplan", "match_op_col", "column_name")
285 ...
286
287 5.6. match_exp_col (string)
288
289    The column name to store the rule match expression.
290
291    Default value is “match_exp”.
292
293    Example 1.6. Set match_exp_col parameter
294 ...
295 modparam("dialplan", "match_exp_col", "column_name")
296 ...
297
298 5.7. match_len_col (string)
299
300    The column name to store the length of a string matching the match
301    expression.
302
303    Default value is “match_len”.
304
305    Example 1.7. Set pr_col parameter
306 ...
307 modparam("dialplan", "match_len_col", "column_name")
308 ...
309
310 5.8. subst_exp_col (string)
311
312    The column name to store the rule's substitution expression.
313
314    Default value is “subst_exp”.
315
316    Example 1.8. Set pr_col parameter
317 ...
318 modparam("dialplan", "subst_exp_col", "column_name")
319 ...
320
321 5.9. repl_exp_col (string)
322
323    The column name to store the rule's replacement expression.
324
325    Default value is “repl_exp”.
326
327    Example 1.9. Set repl_exp_col parameter
328 ...
329 modparam("dialplan", "repl_exp_col", "column_name")
330 ...
331
332 5.10. attrs_col (string)
333
334    The column name to store the rule's attributes to be set after match
335    (see attrs_pvar )
336
337    Default value is “attrs”.
338
339    Example 1.10. Set attrs_col parameter
340 ...
341 modparam("dialplan", "attrs_col", "column_name")
342 ...
343
344 5.11. attrs_pvar (string)
345
346    The pseudovariable used to store the rule's attributes, after
347    translation (when dp_translate() succeeds). This parameter can be an
348    “AVP” or a script variable (“$var()”)..
349
350    Default value is “NULL”.
351
352    Example 1.11. Set attrs_pvar parameter
353 ...
354 modparam("dialplan", "attrs_pvar", "$avp(s:dest)")
355 ...
356
357 5.12. fetch_rows (int)
358
359    The number of rows to be fetched at once from database
360
361    Default value is “1000”.
362
363    Example 1.12. Set fetch_rows parameter
364 ...
365 modparam("dialplan", "fetch_rows", 4000)
366 ...
367
368 5.13. match_dynamic (int)
369
370    If set to 1, the match and substitution expressions can include script
371    variables and their values are evaluated at runtime.
372
373    During the loading process, the values that contain variables are no
374    longer pre-compiled to PCRE structure in memory, because the values
375    change at runtime, thus expect slightly slower performances. Values
376    without script variables are pre-compiled even if this parameter is
377    enabled.
378
379    Default value is “0” (disabled).
380
381    Example 1.13. Set match_dynamic parameter
382 ...
383 modparam("dialplan", "match_dynamic", 1)
384 ...
385
386 5.14. append_branch (int)
387
388    If set to 1, the module appends a new outgoing branch when request URI
389    (r-uri) or its user part are changed by dp_translate() or dp_replace()
390    inside a failure_route block. Set it to 0 if the branch should not be
391    added.
392
393    Default value is “1”.
394
395    Example 1.14. Set append_branch parameter
396 ...
397 modparam("dialplan", "append_branch", 0)
398 ...
399
400 5.15. reload_delta (int)
401
402    The number of seconds that have to be waited before executing a new
403    reload of dialplan rules. By default there is a rate limiting of
404    maximum one reload in five seconds.
405
406    If set to 0, no rate limit is configured. Note carefully: use this
407    configuration only in tests environments because executing two dialplan
408    reloads at the same time can cause to kamailio to crash.
409
410    Default value is “5”.
411
412    Example 1.15. Set reload_delta parameter
413 ...
414 modparam("dialplan", "reload_delta", 1)
415 ...
416
417 6. Functions
418
419    6.1. dp_replace(dpid, inval, outvar)
420    6.2. dp_match(dpid, inval)
421    6.3. dp_translate(id, [src[/dest]])
422    6.4. dp_reload()
423
424 6.1.  dp_replace(dpid, inval, outvar)
425
426    The function translates the input value 'inval' using the rules with
427    dialplan id 'dpid', storing the value in the variable 'outvar'. If the
428    rule that was applied has attributes, they are stored in the variable
429    provided via the module parameter 'attrs_pvar'.
430
431    The behavior is same as dp_translate("dpid", "inval/outvar"), but the
432    parameters have a more flexible format.
433
434    Meaning of the parameters is as follows:
435      * dpid - the dialplan id to match the rules and apply the
436        transformations. It can be a static string or a config variable
437        holding an integer value.
438      * inval - input value. It can be a static or a dynamic string. The
439        dynamic string can contain config variables, combined or not with
440        static strings, that are evaluated at runtime.
441      * outvar - output variable name. The value resulted after applying
442        the matching rule is stored in this variable. The name must refer
443        to a writable variable.
444
445    This function can be used from ANY_ROUTE.
446
447    Example 1.16. dp_replace usage
448 ...
449 dp_replace("240", "$rU", "$var(newru)");
450 xlog("'$rU' was translated to '$var(newru)'\n");
451 dp_replace("240", "+49$rU", "$var(newval)");
452 ...
453
454 6.2.  dp_match(dpid, inval)
455
456    The function matches the input value 'inval' using the rules with
457    dialplan id 'dpid'. If the rule that was applied has attributes, they
458    are stored in the variable provided via the module parameter
459    'attrs_pvar'.
460
461    The behavior is same as dp_translate("dpid", "inval"), but the
462    parameters have a more flexible format.
463
464    Meaning of the parameters is as follows:
465      * dpid - the dialplan id to match the rules and apply the
466        transformations. It can be a static string or a config variable
467        holding an integer value.
468      * inval - input value. It can be a static or a dynamic string. The
469        dynamic string can contain config variables, combined or not with
470        static strings, that are evaluated at runtime.
471
472    This function can be used from ANY_ROUTE.
473
474    Example 1.17. dp_match usage
475 ...
476 dp_match("240", "+49$rU");
477 xlog("the attributes associated with '+49$rU' are '$var(attrs)'\n");
478 ...
479
480 6.3.  dp_translate(id, [src[/dest]])
481
482    Will try to translate “src” into “dest” according to the translation
483    rules in the dialplan identified by “id” . If src/dest is missing the
484    default parameter “ruri.user/ruri.user” will be used, thus translating
485    the request URI user part. If only “dest” is missing, only matching and
486    storing of the matching rule's attributes is done.
487
488    Returns 1, if translation succeeded, -1 in case of some error occurred,
489    and -2 if dialplan with ID equal to id does not exist.
490
491    Meaning of the parameters is as follows:
492      * id -the dialplan id of the possible matching rules. This parameter
493        can have the following types:
494           + integer- the dialplan id is statically assigned
495           + avp var - the dialplan id is the value of an existing avp
496             variable
497           + script var - the dialplan id is the value of an existing
498             script variable.
499      * src/dest - input and output of the function.
500        Input parameter src can be any pseudo variable. Output parameter
501        dest can be:
502           + R-URI
503             - the string is the r-uri or r-uri user part
504           + avp var
505             - At input the function will get the input string from an
506             existing avp variable. At output the function will add an avp
507             with the value of the output string.
508           + script var
509             - At input the function will get the input string from an
510             existing script variable. At output the function will set an
511             script variable with the value of the output string.
512
513    This function can be used from ANY_ROUTE.
514
515    Example 1.18. dp_translate usage
516 ...
517 dp_translate("240", "$ruri.user/$avp(s:dest)");
518 xlog("translated to var $avp(s:dest) \n");
519 ...
520
521    Example 1.19. dp_translate usage
522 ...
523 $avp(s:src) = $ruri.user;
524 dp_translate("$var(x)", "$avp(s:src)/$var(y)");
525 xlog("translated to var $var(y) \n");
526 ...
527
528 6.4.  dp_reload()
529
530    Reload the translation rules from the database. Note that there is a
531    rate limiting defined by 'reload_delta' paramenter. By default is
532    allowed maximum one reload in five seconds.
533
534    Name: dp_reload
535
536    Parameters: none
537
538    This function can be used from ANY_ROUTE.
539
540 7. RPC Commands
541
542    7.1. dialplan.dump
543    7.2. dialplan.reload
544    7.3. dialplan.translate
545
546 7.1. dialplan.dump
547
548    Dumps the content of one dialplan ID
549
550    Name: dialplan.dump
551
552    Parameters: Dialplan ID
553
554    Example:
555                 kamcmd dialplan.dump 100
556
557 7.2. dialplan.reload
558
559    Forces an update of the translation rules from the database.
560
561    Name: dialplan.reload
562
563    Parameters: none
564
565    Example:
566                 kamcmd dialplan.reload
567
568 7.3. dialplan.translate
569
570    Will apply a translation rule identified by a dialplan id and an input
571    string.
572
573    Name: dialplan.translate
574
575    Parameters: 2
576      * Dial plan ID (number)
577      * Input string (string) - it can be prefixed with 's:' to avoid
578        auto-conversion when the command is executed with CLI apps such as
579        kamcmd.
580
581    Example:
582                 kamcmd dialplan.translate 1 "abcdxyz"
583                 kamcmd dialplan.translate 1 s:123456789
584
585 8. Installation
586
587    The modules requires one table in Kamailio database: dialplan. The SQL
588    syntax to create them can be found in dialplan-create.sql script in the
589    database directories in the kamailio/scripts folder. You can also find
590    the complete database documentation on the project webpage,
591    https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
592
593    Some sample records from a dialplan table are presented in the next
594    figure.
595
596    Example 1.20. Example of rules
597 ...
598 dpid: 1
599 pr: 1
600 match_op: 1
601 match_exp: ^0[1-9][0-9]+$
602 match_len: 0
603 subst_exp: ^0([1-9][0-9]+)$
604 repl_exp: 0049\1
605 attrs: de
606 ...
607 dpid: 1
608 pr: 2
609 match_op: 1
610 match_exp: ^0[1-9][0-9]+$
611 match_len: 0
612 subst_exp: ^0(.+)$
613 repl_exp: $var(prefix)\1
614 attrs: xyz
615 ...
616
617    Note that you can use config variables in the replacement expression
618    (repl_exp) field. However, not all of config variables are safe to use
619    there - specifically the variables that have in their name other
620    variables (variables with dynamic name). References to SIP message,
621    private variables ($var(...)) and AVPs with static name are among those
622    that are safe to use in replacement expressions.
623
624    The match_op field specify matching operator, valid values:
625      * 0 - string comparison;
626      * 1 - regular expression matching (pcre);
627      * 2 - fnmatch (shell-like pattern) matching.
628
629 Chapter 2. Developer's Guide
630
631    The module does not provide any API to use in other Kamailio modules.