|
|
@@ -11,16 +11,19 @@
|
|
|
<!-- Module User's Guide -->
|
|
|
|
|
|
<chapter>
|
|
|
-
|
|
|
+
|
|
|
<title>&adminguide;</title>
|
|
|
|
|
|
|
|
|
<section>
|
|
|
<title>Overview</title>
|
|
|
- <para>cpl-c modules implements a CPL (Call Processing Language)
|
|
|
- interpreter. Support for uploading/downloading/removing scripts via
|
|
|
+ <para>cpl-c modules implements a CPL (Call Processing Language)
|
|
|
+ interpreter. Support for uploading/downloading/removing scripts via
|
|
|
SIP REGISTER method is present.
|
|
|
</para>
|
|
|
+ <para>
|
|
|
+ CPL is an IETF specification detailed in RFC3880
|
|
|
+ (https://tools.ietf.org/html/rfc3880).
|
|
|
</section>
|
|
|
<section>
|
|
|
<title>Dependencies</title>
|
|
|
@@ -31,22 +34,22 @@
|
|
|
<itemizedlist>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>any DB module- a DB module for interfacing the DB
|
|
|
+ <emphasis>any DB module- a DB module for interfacing the DB
|
|
|
operations (modules like mysql, postgres, dbtext, etc)
|
|
|
</emphasis>
|
|
|
</para>
|
|
|
</listitem>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>TM (Transaction) module- used for proxying/forking
|
|
|
+ <emphasis>TM (Transaction) module- used for proxying/forking
|
|
|
requests
|
|
|
</emphasis>
|
|
|
</para>
|
|
|
</listitem>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>SL (StateLess) module - used for sending stateless
|
|
|
- reply when responding to REGISTER request or for sending back
|
|
|
+ <emphasis>SL (StateLess) module - used for sending stateless
|
|
|
+ reply when responding to REGISTER request or for sending back
|
|
|
error responses
|
|
|
</emphasis>
|
|
|
</para>
|
|
|
@@ -65,13 +68,13 @@
|
|
|
<section>
|
|
|
<title>External Libraries or Applications</title>
|
|
|
<para>
|
|
|
- The following libraries or applications must be installed
|
|
|
+ The following libraries or applications must be installed
|
|
|
before running &kamailio; with this module loaded:
|
|
|
<itemizedlist>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>libxml2 and libxml2-devel - on some SO, these to
|
|
|
- packages are merged into libxml2. This library contains an
|
|
|
+ <emphasis>libxml2 and libxml2-devel - on some SO, these to
|
|
|
+ packages are merged into libxml2. This library contains an
|
|
|
engine for XML parsing, DTD validation and
|
|
|
DOM manipulation.
|
|
|
</emphasis>
|
|
|
@@ -88,9 +91,9 @@
|
|
|
<section>
|
|
|
<title><varname>db_url</varname> (string)</title>
|
|
|
<para>
|
|
|
- A SQL URL have to be given to the module for knowing where the
|
|
|
- database containing the table with CPL scripts is locates. If
|
|
|
- required a user name and password can be specified for allowing
|
|
|
+ A SQL URL have to be given to the module for knowing where the
|
|
|
+ database containing the table with CPL scripts is locates. If
|
|
|
+ required a user name and password can be specified for allowing
|
|
|
the module to connect to the database server.
|
|
|
</para>
|
|
|
<para>
|
|
|
@@ -110,8 +113,8 @@ modparam("cpl-c","db_url","&exampledb;")
|
|
|
<section>
|
|
|
<title><varname>db_table</varname> (string)</title>
|
|
|
<para>
|
|
|
- Indicates the name of the table that store the CPL scripts.
|
|
|
- This table must be locate into the database specified by
|
|
|
+ Indicates the name of the table that store the CPL scripts.
|
|
|
+ This table must be locate into the database specified by
|
|
|
<quote>db_url</quote> parameter. For more about the format of the CPL
|
|
|
table please see the modules/cpl-c/init.mysql file.
|
|
|
</para>
|
|
|
@@ -170,7 +173,7 @@ modparam("cpl-c","domain_column","domain")
|
|
|
<section>
|
|
|
<title><varname>cpl_xml_column</varname> (string)</title>
|
|
|
<para>
|
|
|
- Indicates the name of the column used for storing the
|
|
|
+ Indicates the name of the column used for storing the
|
|
|
the XML version of the cpl script.
|
|
|
</para>
|
|
|
<para>
|
|
|
@@ -190,7 +193,7 @@ modparam("cpl-c","cpl_xml_column","cpl_xml")
|
|
|
<section>
|
|
|
<title><varname>cpl_bin_column</varname> (string)</title>
|
|
|
<para>
|
|
|
- Indicates the name of the column used for storing the
|
|
|
+ Indicates the name of the column used for storing the
|
|
|
the binary version of the cpl script (compiled version).
|
|
|
</para>
|
|
|
<para>
|
|
|
@@ -210,9 +213,9 @@ modparam("cpl-c","cpl_bin_column","cpl_bin")
|
|
|
<section>
|
|
|
<title><varname>cpl_dtd_file</varname> (string)</title>
|
|
|
<para>
|
|
|
- Points to the DTD file describing the CPL grammar. The file
|
|
|
- name may include also the path to the file. This path can be
|
|
|
- absolute or relative (be careful the path will be relative
|
|
|
+ Points to the DTD file describing the CPL grammar. The file
|
|
|
+ name may include also the path to the file. This path can be
|
|
|
+ absolute or relative (be careful the path will be relative
|
|
|
to the starting directory of &kamailio;).
|
|
|
</para>
|
|
|
<para>
|
|
|
@@ -232,13 +235,13 @@ modparam("cpl-c","cpl_dtd_file","/etc/kamailio/cpl-06.dtd")
|
|
|
<section>
|
|
|
<title><varname>log_dir</varname> (string)</title>
|
|
|
<para>
|
|
|
- Points to a directory where should be created all the log file
|
|
|
- generated by the LOG CPL node. A log file per user will be
|
|
|
+ Points to a directory where should be created all the log file
|
|
|
+ generated by the LOG CPL node. A log file per user will be
|
|
|
created (on demand) having the name username.log.
|
|
|
</para>
|
|
|
<para>
|
|
|
<emphasis>
|
|
|
- If this parameter is absent, the logging will be disabled
|
|
|
+ If this parameter is absent, the logging will be disabled
|
|
|
without generating error on execution.
|
|
|
</emphasis>
|
|
|
</para>
|
|
|
@@ -254,12 +257,12 @@ modparam("cpl-c","log_dir","/var/log/kamailio/cpl")
|
|
|
<section>
|
|
|
<title><varname>proxy_recurse</varname> (int)</title>
|
|
|
<para>
|
|
|
- Tells for how many time is allow to have recurse for PROXY CPL
|
|
|
- node If it has value 2, when doing proxy, only twice the proxy
|
|
|
- action will be re-triggered by a redirect response; the third
|
|
|
- time, the proxy execution will end by going on REDIRECTION
|
|
|
- branch. The recurse feature can be disable by setting this
|
|
|
- parameter to 0
|
|
|
+ Tells for how many time is allow to have recurse for PROXY CPL
|
|
|
+ node If it has value 2, when doing proxy, only twice the proxy
|
|
|
+ action will be re-triggered by a redirect response; the third
|
|
|
+ time, the proxy execution will end by going on REDIRECTION
|
|
|
+ branch. The recurse feature can be disable by setting this
|
|
|
+ parameter to 0
|
|
|
</para>
|
|
|
<para>
|
|
|
<emphasis>
|
|
|
@@ -299,7 +302,7 @@ modparam("cpl-c","proxy_route",1)
|
|
|
<section>
|
|
|
<title><varname>case_sensitive</varname> (int)</title>
|
|
|
<para>
|
|
|
- Tells if the username matching should be perform case
|
|
|
+ Tells if the username matching should be perform case
|
|
|
sensitive or not. Set it to a non zero value to force
|
|
|
a case sensitive handling of usernames.
|
|
|
</para>
|
|
|
@@ -320,7 +323,7 @@ modparam("cpl-c","case_sensitive",1)
|
|
|
<section>
|
|
|
<title><varname>realm_prefix</varname> (string)</title>
|
|
|
<para>
|
|
|
- Defines a prefix for the domain part which should be ignored
|
|
|
+ Defines a prefix for the domain part which should be ignored
|
|
|
in handling users and scripts.
|
|
|
</para>
|
|
|
<para>
|
|
|
@@ -340,8 +343,8 @@ modparam("cpl-c","realm_prefix","sip.")
|
|
|
<section>
|
|
|
<title><varname>timer_avp</varname> (string)</title>
|
|
|
<para>
|
|
|
- Full specification (ID, NAME, ALIAS) of the AVP to be used to
|
|
|
- set the value of the Final Response INVITE timeout - it's
|
|
|
+ Full specification (ID, NAME, ALIAS) of the AVP to be used to
|
|
|
+ set the value of the Final Response INVITE timeout - it's
|
|
|
used by the TIMEOUT attribute from the PROXY tag.
|
|
|
</para>
|
|
|
<para>
|
|
|
@@ -401,7 +404,7 @@ modparam("cpl-c","lookup_domain","location")
|
|
|
</emphasis>
|
|
|
</para>
|
|
|
<example>
|
|
|
- <title>Set <varname>lookup_append_branches</varname>
|
|
|
+ <title>Set <varname>lookup_append_branches</varname>
|
|
|
parameter</title>
|
|
|
<programlisting format="linespecific">
|
|
|
...
|
|
|
@@ -413,7 +416,7 @@ modparam("cpl-c","lookup_append_branches",1)
|
|
|
<section>
|
|
|
<title><varname>use_domain</varname> (integer)</title>
|
|
|
<para>
|
|
|
- Indicates if the domain part of the URI should be used in
|
|
|
+ Indicates if the domain part of the URI should be used in
|
|
|
user identification (otherwise only username part will be
|
|
|
used).
|
|
|
</para>
|
|
|
@@ -442,31 +445,31 @@ modparam("cpl-c","use_domain",1)
|
|
|
<function moreinfo="none">cpl_run_script(type,mode, [uri])</function>
|
|
|
</title>
|
|
|
<para>
|
|
|
- Starts the execution of the CPL script. The user name is
|
|
|
- fetched from new_uri or requested uri or from To header -in
|
|
|
- this order- (for incoming execution) or from FROM header (for
|
|
|
+ Starts the execution of the CPL script. The user name is
|
|
|
+ fetched from new_uri or requested uri or from To header -in
|
|
|
+ this order- (for incoming execution) or from FROM header (for
|
|
|
outgoing execution).
|
|
|
Regarding the stateful/stateless message processing, the
|
|
|
- function is very flexible, being able to run in different
|
|
|
+ function is very flexible, being able to run in different
|
|
|
modes (see below the"mode" parameter).
|
|
|
- Normally this function will end script execution. There is no
|
|
|
- guaranty that the CPL script interpretation ended when &kamailio;
|
|
|
- script ended also (for the same INVITE ;-)) - this can happen
|
|
|
- when the CPL script does a PROXY and the script interpretation
|
|
|
+ Normally this function will end script execution. There is no
|
|
|
+ guaranty that the CPL script interpretation ended when &kamailio;
|
|
|
+ script ended also (for the same INVITE ;-)) - this can happen
|
|
|
+ when the CPL script does a PROXY and the script interpretation
|
|
|
pause after proxying and it will be resume when some reply is
|
|
|
- received (this can happen in a different process of SER).
|
|
|
- If the function returns to script, the SIP server should
|
|
|
+ received (this can happen in a different process of SER).
|
|
|
+ If the function returns to script, the SIP server should
|
|
|
continue with the normal behavior as if no script existed.
|
|
|
- When some error is returned, the function itself haven't sent
|
|
|
+ When some error is returned, the function itself haven't sent
|
|
|
any SIP error reply (this can be done from script).
|
|
|
</para>
|
|
|
<para>Meaning of the parameters is as follows:</para>
|
|
|
<itemizedlist>
|
|
|
<listitem>
|
|
|
- <para><emphasis>type</emphasis> - which part of the script
|
|
|
- should be run; set it to "incoming" for having the incoming
|
|
|
- part of script executed (when an INVITE is received) or to
|
|
|
- "outgoing" for running the outgoing part of script (when a
|
|
|
+ <para><emphasis>type</emphasis> - which part of the script
|
|
|
+ should be run; set it to "incoming" for having the incoming
|
|
|
+ part of script executed (when an INVITE is received) or to
|
|
|
+ "outgoing" for running the outgoing part of script (when a
|
|
|
user is generating an INVITE - call).
|
|
|
</para>
|
|
|
</listitem>
|
|
|
@@ -477,16 +480,16 @@ modparam("cpl-c","use_domain",1)
|
|
|
<itemizedlist>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>IS_STATELESS</emphasis> - the current INVITE has
|
|
|
- no transaction created yet. All replies (redirection or
|
|
|
- deny) will be done is a stateless way. The execution will
|
|
|
- switch to stateful only when proxy is done. So, if the
|
|
|
+ <emphasis>IS_STATELESS</emphasis> - the current INVITE has
|
|
|
+ no transaction created yet. All replies (redirection or
|
|
|
+ deny) will be done is a stateless way. The execution will
|
|
|
+ switch to stateful only when proxy is done. So, if the
|
|
|
function returns, will be in stateless mode.
|
|
|
</para>
|
|
|
</listitem>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>IS_STATEFUL</emphasis> - the current INVITE has
|
|
|
+ <emphasis>IS_STATEFUL</emphasis> - the current INVITE has
|
|
|
already a transaction associated. All signaling operations
|
|
|
(replies or proxy) will be done in stateful way.So, if
|
|
|
the function returns, will be in stateful mode.
|
|
|
@@ -494,7 +497,7 @@ modparam("cpl-c","use_domain",1)
|
|
|
</listitem>
|
|
|
<listitem>
|
|
|
<para>
|
|
|
- <emphasis>FORCE_STATEFUL</emphasis> - the current INVITE
|
|
|
+ <emphasis>FORCE_STATEFUL</emphasis> - the current INVITE
|
|
|
has no transaction created yet. All signaling operations
|
|
|
will be done is a stateful way (on signaling, the
|
|
|
transaction will be created from within the interpreter).
|
|
|
@@ -503,7 +506,7 @@ modparam("cpl-c","use_domain",1)
|
|
|
</listitem>
|
|
|
</itemizedlist>
|
|
|
<para>
|
|
|
- <emphasis>HINT</emphasis>: is_stateful is very
|
|
|
+ <emphasis>HINT</emphasis>: is_stateful is very
|
|
|
difficult to manage from the routing script (script processing
|
|
|
can continue in stateful mode); is_stateless is the fastest and
|
|
|
less resources consumer (transaction is created only if
|
|
|
@@ -540,24 +543,24 @@ cpl_run_script("incoming","force_stateful");
|
|
|
<function moreinfo="none">cpl_process_register()</function>
|
|
|
</title>
|
|
|
<para>
|
|
|
- This function MUST be called only for REGISTER requests. It
|
|
|
- checks if the current REGISTER request is related or not with
|
|
|
- CPL script upload/download/ remove. If it is, all the needed
|
|
|
- operation will be done. For checking if the REGISTER is CPL
|
|
|
- related, the function looks fist to "Content-Type" header. If
|
|
|
- it exists and has a the mime type set to "application/cpl+xml"
|
|
|
- means this is a CPL script upload/remove operation. The
|
|
|
- distinction between to case is made by looking at
|
|
|
- "Content-Disposition" header; id its value is
|
|
|
- "script;action=store", means it's an upload; if it's
|
|
|
- "script;action=remove", means it's a remove operation; other
|
|
|
- values are considered to be errors. If no "Content-Type"
|
|
|
- header is present, the function looks to "Accept" header and
|
|
|
- if it contains the "*" or "application/cpl-xml" the request
|
|
|
+ This function MUST be called only for REGISTER requests. It
|
|
|
+ checks if the current REGISTER request is related or not with
|
|
|
+ CPL script upload/download/ remove. If it is, all the needed
|
|
|
+ operation will be done. For checking if the REGISTER is CPL
|
|
|
+ related, the function looks fist to "Content-Type" header. If
|
|
|
+ it exists and has a the mime type set to "application/cpl+xml"
|
|
|
+ means this is a CPL script upload/remove operation. The
|
|
|
+ distinction between to case is made by looking at
|
|
|
+ "Content-Disposition" header; id its value is
|
|
|
+ "script;action=store", means it's an upload; if it's
|
|
|
+ "script;action=remove", means it's a remove operation; other
|
|
|
+ values are considered to be errors. If no "Content-Type"
|
|
|
+ header is present, the function looks to "Accept" header and
|
|
|
+ if it contains the "*" or "application/cpl-xml" the request
|
|
|
it will be consider one for downloading CPL scripts.
|
|
|
- The functions returns to script only if the REGISTER is
|
|
|
- not related to CPL. In other case, the function will send by
|
|
|
- itself the necessary replies (stateless - using sl), including
|
|
|
+ The functions returns to script only if the REGISTER is
|
|
|
+ not related to CPL. In other case, the function will send by
|
|
|
+ itself the necessary replies (stateless - using sl), including
|
|
|
for errors.
|
|
|
</para>
|
|
|
<para>
|
|
|
@@ -580,12 +583,12 @@ if (method=="REGISTER") {
|
|
|
</function>
|
|
|
</title>
|
|
|
<para>
|
|
|
- Same as <quote>cpl_process_register</quote> without
|
|
|
+ Same as <quote>cpl_process_register</quote> without
|
|
|
internally generating the reply. All information (script) is
|
|
|
appended to the reply but without sending it out.
|
|
|
</para>
|
|
|
<para>
|
|
|
- Main purpose of this function is to allow integration
|
|
|
+ Main purpose of this function is to allow integration
|
|
|
between CPL and UserLocation services via same REGISTER
|
|
|
messages.
|
|
|
</para>
|
|
|
@@ -615,7 +618,7 @@ if (method=="REGISTER") {
|
|
|
<function moreinfo="none">LOAD_CPL</function>
|
|
|
</title>
|
|
|
<para>
|
|
|
- For the given user, loads the XML cpl file, compiles it into
|
|
|
+ For the given user, loads the XML cpl file, compiles it into
|
|
|
binary format and stores both format into database.
|
|
|
</para>
|
|
|
<para>
|
|
|
@@ -642,8 +645,8 @@ if (method=="REGISTER") {
|
|
|
<function moreinfo="none">REMOVE_CPL</function>
|
|
|
</title>
|
|
|
<para>
|
|
|
- For the given user, removes the entire database record
|
|
|
- (XML cpl and binary cpl); user with empty cpl scripts are not
|
|
|
+ For the given user, removes the entire database record
|
|
|
+ (XML cpl and binary cpl); user with empty cpl scripts are not
|
|
|
accepted.
|
|
|
</para>
|
|
|
<para>
|
|
|
@@ -651,7 +654,7 @@ if (method=="REGISTER") {
|
|
|
</para>
|
|
|
<para>Parameters:</para>
|
|
|
<itemizedlist>
|
|
|
- <listitem><para>username : name of the user</para></listitem>
|
|
|
+ <listitem><para>username : name of the user</para></listitem>
|
|
|
</itemizedlist>
|
|
|
<para>
|
|
|
MI FIFO Command format:
|
|
|
@@ -675,7 +678,7 @@ if (method=="REGISTER") {
|
|
|
</para>
|
|
|
<para>Parameters:</para>
|
|
|
<itemizedlist>
|
|
|
- <listitem><para>username : name of the user</para></listitem>
|
|
|
+ <listitem><para>username : name of the user</para></listitem>
|
|
|
</itemizedlist>
|
|
|
<para>
|
|
|
MI FIFO Command format:
|
|
|
@@ -694,13 +697,13 @@ if (method=="REGISTER") {
|
|
|
<title>Database setup</title>
|
|
|
<para>
|
|
|
Before running &kamailio; with cpl-c, you have to setup the database
|
|
|
- table where the module will store the CPL scripts. For that, if
|
|
|
+ table where the module will store the CPL scripts. For that, if
|
|
|
the table was not created by the installation script or you choose
|
|
|
to install everything by yourself you can use the cpc-create.sql
|
|
|
- <acronym>SQL</acronym> script in the database directories in the
|
|
|
- kamailio/scripts folder as template.
|
|
|
- Database and table name can be set with module parameters so they
|
|
|
- can be changed, but the name of the columns must be as they are
|
|
|
+ <acronym>SQL</acronym> script in the database directories in the
|
|
|
+ kamailio/scripts folder as template.
|
|
|
+ Database and table name can be set with module parameters so they
|
|
|
+ can be changed, but the name of the columns must be as they are
|
|
|
in the <acronym>SQL</acronym> script.
|
|
|
You can also find the complete database documentation on the
|
|
|
project webpage, &kamailiodbdocslink;.
|
Daniel-Constantin Mierla