mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
552 lines
14 KiB
552 lines
14 KiB
dialplan Module
|
|
|
|
Andreea-Ancuta Onofrei
|
|
|
|
Voice Sistem SRL
|
|
|
|
Edited by
|
|
|
|
Andreea-Ancuta Onofrei
|
|
|
|
Edited by
|
|
|
|
Juha Heinanen
|
|
|
|
Edited by
|
|
|
|
Olle E. Johansson
|
|
|
|
Copyright © 2007-2008 Voice Sistem SRL
|
|
|
|
Copyright © 2008-2010 Juha Heinanen
|
|
|
|
Copyright © 2014 Olle E. Johansson, Edvina AB
|
|
__________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1. Overview
|
|
2. How it works
|
|
3. Dialplan use cases
|
|
4. Dependencies
|
|
|
|
4.1. Kamailio Modules
|
|
4.2. External Libraries or Applications
|
|
|
|
5. Parameters
|
|
|
|
5.1. db_url (string)
|
|
5.2. table_name (string)
|
|
5.3. dpid_col (string)
|
|
5.4. pr_col (string)
|
|
5.5. match_op_col (string)
|
|
5.6. match_exp_col (string)
|
|
5.7. match_len_col (string)
|
|
5.8. subst_exp_col (string)
|
|
5.9. repl_exp_col (string)
|
|
5.10. attrs_col (string)
|
|
5.11. attrs_pvar (string)
|
|
5.12. fetch_rows (int)
|
|
5.13. match_dynamic (int)
|
|
|
|
6. Functions
|
|
|
|
6.1. dp_translate(id, [src[/dest]])
|
|
|
|
7. MI Commands
|
|
|
|
7.1. dp_reload
|
|
7.2. dp_translate
|
|
|
|
8. Exported RPC Commands
|
|
|
|
8.1. dialplan.dump
|
|
8.2. dialplan.reload
|
|
8.3. dialplan.translate
|
|
|
|
9. Installation
|
|
|
|
2. Developer's Guide
|
|
|
|
List of Examples
|
|
|
|
1.1. Set db_url parameter
|
|
1.2. Set table_name parameter
|
|
1.3. Set dpid_col parameter
|
|
1.4. Set pr_col parameter
|
|
1.5. Set match_op_col parameter
|
|
1.6. Set match_exp_col parameter
|
|
1.7. Set pr_col parameter
|
|
1.8. Set pr_col parameter
|
|
1.9. Set repl_exp_col parameter
|
|
1.10. Set attrs_col parameter
|
|
1.11. Set attrs_pvar parameter
|
|
1.12. Set fetch_rows parameter
|
|
1.13. Set match_dynamic parameter
|
|
1.14. dp_translate usage
|
|
1.15. dp_translate usage
|
|
1.16. Example of rules
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
Table of Contents
|
|
|
|
1. Overview
|
|
2. How it works
|
|
3. Dialplan use cases
|
|
4. Dependencies
|
|
|
|
4.1. Kamailio Modules
|
|
4.2. External Libraries or Applications
|
|
|
|
5. Parameters
|
|
|
|
5.1. db_url (string)
|
|
5.2. table_name (string)
|
|
5.3. dpid_col (string)
|
|
5.4. pr_col (string)
|
|
5.5. match_op_col (string)
|
|
5.6. match_exp_col (string)
|
|
5.7. match_len_col (string)
|
|
5.8. subst_exp_col (string)
|
|
5.9. repl_exp_col (string)
|
|
5.10. attrs_col (string)
|
|
5.11. attrs_pvar (string)
|
|
5.12. fetch_rows (int)
|
|
5.13. match_dynamic (int)
|
|
|
|
6. Functions
|
|
|
|
6.1. dp_translate(id, [src[/dest]])
|
|
|
|
7. MI Commands
|
|
|
|
7.1. dp_reload
|
|
7.2. dp_translate
|
|
|
|
8. Exported RPC Commands
|
|
|
|
8.1. dialplan.dump
|
|
8.2. dialplan.reload
|
|
8.3. dialplan.translate
|
|
|
|
9. Installation
|
|
|
|
1. Overview
|
|
|
|
This module implements generic string translations based on matching
|
|
and replacement rules. It can be used to manipulate the request URI or
|
|
a PV and to translate it to a new format/value. Dialplan can also be
|
|
used to match a given URI and retrieve a set of attributes based on the
|
|
match. It is a very flexible module that can be used to handle call
|
|
routing, prefix rewrites and much more.
|
|
|
|
2. How it works
|
|
|
|
At startup the module will load a set of matching and transformation
|
|
rules from a database. Rules are grouped into dialplans. Every database
|
|
row will be stored in memory as a dialplan rule. Each rule will
|
|
describe how the matching will be made, how the input value will be
|
|
modified and which attributes that will be set for the matching
|
|
transformation.
|
|
|
|
The module expects an input value which will be matched against a rule
|
|
by using regular expressions (see 'man pcresyntax' for syntax), string
|
|
or fnmatch (see 'man fnmatch') matching. Overlapping matching
|
|
expressions can be controlled via priorities. One priority can have
|
|
multiple dialplan entries. Priorities need not be numbered with
|
|
consecutive numbers. The next higher priority will be used after trying
|
|
to match all entries in one priority.
|
|
|
|
Once a rule is matched, the defined transformation (if any) is applied
|
|
and the result is returned as output value. Also, if any string
|
|
attribute is associated to the rule, this will be returned to the
|
|
script along with the output value. This can be used to identify the
|
|
used rule.
|
|
|
|
The first matching rule will be processed.
|
|
|
|
3. Dialplan use cases
|
|
|
|
The module can be used to implement multiple dialplans - to do
|
|
auto-completion of dialed numbers (like national to international), to
|
|
convert generic numbers to specific numbers (like for emergency
|
|
numbers).
|
|
|
|
The module can also be used for detecting a range or sets of numbers
|
|
mapped on a service/case - the attribute string can be used to store
|
|
extra information about the service/case.
|
|
|
|
Non-SIP string translation can be implemented - like converting country
|
|
names from all possible formats to a canonical format: (UK, England,
|
|
United Kingdom) -> GB.
|
|
|
|
Any other string-base translation or detection for whatever other
|
|
purposes.
|
|
|
|
4. Dependencies
|
|
|
|
4.1. Kamailio Modules
|
|
4.2. External Libraries or Applications
|
|
|
|
4.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* A database module
|
|
|
|
4.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed before
|
|
running Kamailio with this module loaded:
|
|
* libpcre - the libraries of PCRE.
|
|
|
|
5. Parameters
|
|
|
|
5.1. db_url (string)
|
|
5.2. table_name (string)
|
|
5.3. dpid_col (string)
|
|
5.4. pr_col (string)
|
|
5.5. match_op_col (string)
|
|
5.6. match_exp_col (string)
|
|
5.7. match_len_col (string)
|
|
5.8. subst_exp_col (string)
|
|
5.9. repl_exp_col (string)
|
|
5.10. attrs_col (string)
|
|
5.11. attrs_pvar (string)
|
|
5.12. fetch_rows (int)
|
|
5.13. match_dynamic (int)
|
|
|
|
5.1. db_url (string)
|
|
|
|
The translation rules will be loaded using this database URL.
|
|
|
|
Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”.
|
|
|
|
Example 1.1. Set db_url parameter
|
|
...
|
|
modparam("dialplan", "db_url", "mysql://user:passwb@localhost/db")
|
|
...
|
|
|
|
5.2. table_name (string)
|
|
|
|
The name of the database table used to load the translation rules.
|
|
|
|
Default value is “dialplan”.
|
|
|
|
Example 1.2. Set table_name parameter
|
|
...
|
|
modparam("dialplan", "table_name", "my_table")
|
|
...
|
|
|
|
5.3. dpid_col (string)
|
|
|
|
The column name used to store the dialplan group ID.
|
|
|
|
Default value is “dpid”.
|
|
|
|
Example 1.3. Set dpid_col parameter
|
|
...
|
|
modparam("dialplan", "dpid_col", "column_name")
|
|
...
|
|
|
|
5.4. pr_col (string)
|
|
|
|
The column name used to store the priority of the corresponding rule
|
|
from the database row.
|
|
|
|
Default value is “pr”.
|
|
|
|
Example 1.4. Set pr_col parameter
|
|
...
|
|
modparam("dialplan", "pr_col", "column_name")
|
|
...
|
|
|
|
5.5. match_op_col (string)
|
|
|
|
The column name used to store the type of matching of the rule.
|
|
|
|
Default value is “match_op”.
|
|
|
|
Example 1.5. Set match_op_col parameter
|
|
...
|
|
modparam("dialplan", "match_op_col", "column_name")
|
|
...
|
|
|
|
5.6. match_exp_col (string)
|
|
|
|
The column name to store the rule match expression.
|
|
|
|
Default value is “match_exp”.
|
|
|
|
Example 1.6. Set match_exp_col parameter
|
|
...
|
|
modparam("dialplan", "match_exp_col", "column_name")
|
|
...
|
|
|
|
5.7. match_len_col (string)
|
|
|
|
The column name to store the length of a string matching the match
|
|
expression.
|
|
|
|
Default value is “match_len”.
|
|
|
|
Example 1.7. Set pr_col parameter
|
|
...
|
|
modparam("dialplan", "match_len_col", "column_name")
|
|
...
|
|
|
|
5.8. subst_exp_col (string)
|
|
|
|
The column name to store the rule's substitution expression.
|
|
|
|
Default value is “subst_exp”.
|
|
|
|
Example 1.8. Set pr_col parameter
|
|
...
|
|
modparam("dialplan", "subst_exp_col", "column_name")
|
|
...
|
|
|
|
5.9. repl_exp_col (string)
|
|
|
|
The column name to store the rule's replacement expression.
|
|
|
|
Default value is “repl_exp”.
|
|
|
|
Example 1.9. Set repl_exp_col parameter
|
|
...
|
|
modparam("dialplan", "repl_exp_col", "column_name")
|
|
...
|
|
|
|
5.10. attrs_col (string)
|
|
|
|
The column name to store the rule's attributes to be set after match
|
|
(see attrs_pvar )
|
|
|
|
Default value is “attrs”.
|
|
|
|
Example 1.10. Set attrs_col parameter
|
|
...
|
|
modparam("dialplan", "attrs_col", "column_name")
|
|
...
|
|
|
|
5.11. attrs_pvar (string)
|
|
|
|
The pseudovariable used to store the rule's attributes, after
|
|
translation (when dp_translate() succeeds). This parameter can be an
|
|
“AVP” or a script variable (“$var()”)..
|
|
|
|
Default value is “NULL”.
|
|
|
|
Example 1.11. Set attrs_pvar parameter
|
|
...
|
|
modparam("dialplan", "attrs_pvar", "$avp(s:dest)")
|
|
...
|
|
|
|
5.12. fetch_rows (int)
|
|
|
|
The number of rows to be fetched at once from database
|
|
|
|
Default value is “1000”.
|
|
|
|
Example 1.12. Set fetch_rows parameter
|
|
...
|
|
modparam("dialplan", "fetch_rows", 4000)
|
|
...
|
|
|
|
5.13. match_dynamic (int)
|
|
|
|
If set to 1, the match and substitution expressions can include script
|
|
variables and their values are evaluated at runtime.
|
|
|
|
During the loading process, the values that contain variables are no
|
|
longer pre-compiled to PCRE structure in memory, because the values
|
|
change at runtime, thus expect slightly slower performances. Values
|
|
without script variables are pre-compiled even if this parameter is
|
|
enabled.
|
|
|
|
Default value is “0” (disabled).
|
|
|
|
Example 1.13. Set match_dynamic parameter
|
|
...
|
|
modparam("dialplan", "match_dynamic", 1)
|
|
...
|
|
|
|
6. Functions
|
|
|
|
6.1. dp_translate(id, [src[/dest]])
|
|
|
|
6.1. dp_translate(id, [src[/dest]])
|
|
|
|
Will try to translate “src” into “dest” according to the translation
|
|
rules in the dialplan identified by “id” . If src/dest is missing the
|
|
default parameter “ruri.user/ruri.user” will be used, thus translating
|
|
the request URI user part. If only “dest” is missing, only matching and
|
|
storing of the matching rule's attributes is done.
|
|
|
|
Returns 1, if translation succeeded, -1 in case of some error occurred,
|
|
and -2 if dialplan with ID equal to id does not exist.
|
|
|
|
Meaning of the parameters is as follows:
|
|
* id -the dialplan id of the possible matching rules. This parameter
|
|
can have the following types:
|
|
+ integer- the dialplan id is statically assigned
|
|
+ avp var - the dialplan id is the value of an existing avp
|
|
variable
|
|
+ script var - the dialplan id is the value of an existing
|
|
script variable.
|
|
* src/dest - input and output of the function.
|
|
Input parameter src can be any pseudo variable. Output parameter
|
|
dest can be:
|
|
+ R-URI
|
|
- the string is the r-uri or r-uri user part
|
|
+ avp var
|
|
- At input the function will get the input string from an
|
|
existing avp variable. At output the function will add an avp
|
|
with the value of the output string.
|
|
+ script var
|
|
- At input the function will get the input string from an
|
|
existing script variable. At output the function will set an
|
|
script variable with the value of the output string.
|
|
|
|
This function can be used from ANY_ROUTE.
|
|
|
|
Example 1.14. dp_translate usage
|
|
...
|
|
dp_translate("240", "$ruri.user/$avp(s:dest)");
|
|
xlog("translated to var $avp(s:dest) \n");
|
|
...
|
|
|
|
Example 1.15. dp_translate usage
|
|
...
|
|
$avp(s:src) = $ruri.user;
|
|
dp_translate("$var(x)", "$avp(s:src)/$var(y)");
|
|
xlog("translated to var $var(y) \n");
|
|
...
|
|
|
|
7. MI Commands
|
|
|
|
7.1. dp_reload
|
|
7.2. dp_translate
|
|
|
|
7.1. dp_reload
|
|
|
|
Forces an update of the translation rules from the database.
|
|
|
|
Name: dp_reload
|
|
|
|
Parameters: none
|
|
|
|
MI DATAGRAM Command Format:
|
|
:dp_reload:
|
|
_empty_line_
|
|
|
|
7.2. dp_translate
|
|
|
|
Will apply a translation rule identified by a dialplan id and an input
|
|
string.
|
|
|
|
Name: dp_translate
|
|
|
|
Parameters: 2
|
|
* Dial plan ID
|
|
* Input String
|
|
|
|
MI DATAGRAM Command Format:
|
|
:dp_translate:
|
|
dpid
|
|
input
|
|
_empty_line_
|
|
|
|
8. Exported RPC Commands
|
|
|
|
8.1. dialplan.dump
|
|
8.2. dialplan.reload
|
|
8.3. dialplan.translate
|
|
|
|
8.1. dialplan.dump
|
|
|
|
Dumps the content of one dialplan ID
|
|
|
|
Name: dialplan.dump
|
|
|
|
Parameters: Dialplan ID
|
|
|
|
Example:
|
|
kamcmd dialplan.dump 100
|
|
|
|
8.2. dialplan.reload
|
|
|
|
Forces an update of the translation rules from the database.
|
|
|
|
Name: dialplan.reload
|
|
|
|
Parameters: none
|
|
|
|
Example:
|
|
kamcmd dialplan.reload
|
|
|
|
8.3. dialplan.translate
|
|
|
|
Will apply a translation rule identified by a dialplan id and an input
|
|
string.
|
|
|
|
Name: dialplan.translate
|
|
|
|
Parameters: 2
|
|
* Dial plan ID
|
|
* Input String
|
|
|
|
Example:
|
|
# kamcmd dp_translate dpid "input"
|
|
kamcmd dp_translate 1 "abcdxyz"
|
|
|
|
9. Installation
|
|
|
|
The modules requires one table in Kamailio database: dialplan. The SQL
|
|
syntax to create them can be found in dialplan-create.sql script in the
|
|
database directories in the kamailio/scripts folder. You can also find
|
|
the complete database documentation on the project webpage,
|
|
http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
|
|
|
|
Some sample records from a dialplan table are presented in the next
|
|
figure.
|
|
|
|
Example 1.16. Example of rules
|
|
...
|
|
dpid: 1
|
|
pr: 1
|
|
match_op: 1
|
|
match_exp: ^0[1-9][0-9]+$
|
|
match_len: 0
|
|
subst_exp: ^0([1-9][0-9]+)$
|
|
repl_exp: 0049\1
|
|
attrs: de
|
|
...
|
|
dpid: 1
|
|
pr: 2
|
|
match_op: 1
|
|
match_exp: ^0[1-9][0-9]+$
|
|
match_len: 0
|
|
subst_exp: ^0(.+)$
|
|
repl_exp: $var(prefix)\1
|
|
attrs: xyz
|
|
...
|
|
|
|
Note that you can use config variables in the replacement expression
|
|
(repl_exp) field. However, not all of config variables are safe to use
|
|
there - specifically the variables that have in their name other
|
|
variables (variables with dynamic name). References to SIP message,
|
|
private variables ($var(...)) and AVPs with static name are among those
|
|
that are safe to use in replacement expressions.
|
|
|
|
The match_op field specify matching operator, valid values:
|
|
* 0 - string comparison;
|
|
* 1 - regular expression matching (pcre);
|
|
* 2 - fnmatch (shell-like pattern) matching.
|
|
|
|
Chapter 2. Developer's Guide
|
|
|
|
The module does not provide any API to use in other Kamailio modules.
|