Debian Codegraph @

src/modules/dialplan/README

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