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.
705 lines
20 KiB
705 lines
20 KiB
<?xml version="1.0" encoding='ISO-8859-1'?>
|
|
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [
|
|
|
|
<!-- Include general documentation entities -->
|
|
<!ENTITY % docentities SYSTEM "../../../docbook/entities.xml">
|
|
%docentities;
|
|
|
|
]>
|
|
|
|
<!-- 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
|
|
SIP REGISTER method is present.
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>Dependencies</title>
|
|
<section>
|
|
<title>&kamailio; Modules</title>
|
|
<para>
|
|
The following modules must be loaded before this module:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<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
|
|
requests
|
|
</emphasis>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>SL (StateLess) module - used for sending stateless
|
|
reply when responding to REGISTER request or for sending back
|
|
error responses
|
|
</emphasis>
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>USRLOC (User Location) module - used for implementing
|
|
lookup("registration") tag (adding into location set of the
|
|
users' contact)
|
|
</emphasis>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
<section>
|
|
<title>External Libraries or Applications</title>
|
|
<para>
|
|
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
|
|
engine for XML parsing, DTD validation and
|
|
DOM manipulation.
|
|
</emphasis>
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>Exported Parameters</title>
|
|
<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
|
|
the module to connect to the database server.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>&defaultdb;</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_url</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","db_url","&exampledb;")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<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
|
|
<quote>db_url</quote> parameter. For more about the format of the CPL
|
|
table please see the modules/cpl-c/init.mysql file.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>cpl</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>db_table</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","cpl_table","cpl")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>username_column</varname> (string)</title>
|
|
<para>
|
|
Indicates the name of the column used for storing the username.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>username</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>username_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","username_column","username")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>domain_column</varname> (string)</title>
|
|
<para>
|
|
Indicates the name of the column used for storing the domain.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>domain</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>domain_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","domain_column","domain")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>cpl_xml_column</varname> (string)</title>
|
|
<para>
|
|
Indicates the name of the column used for storing the
|
|
the XML version of the cpl script.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>cpl_xml</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>cpl_xml_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","cpl_xml_column","cpl_xml")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>cpl_bin_column</varname> (string)</title>
|
|
<para>
|
|
Indicates the name of the column used for storing the
|
|
the binary version of the cpl script (compiled version).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>cpl_bin</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>cpl_bin_column</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","cpl_bin_column","cpl_bin")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<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
|
|
to the starting directory of &kamailio;).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
This parameter is MANDATORY!
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>cpl_dtd_file</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","cpl_dtd_file","/etc/kamailio/cpl-06.dtd")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<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
|
|
created (on demand) having the name username.log.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
If this parameter is absent, the logging will be disabled
|
|
without generating error on execution.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>log_dir</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","log_dir","/var/log/kamailio/cpl")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<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
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value of this parameter is 0.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>proxy_recurse</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","proxy_recurse",2)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>proxy_route</varname> (int)</title>
|
|
<para>
|
|
Before doing proxy (forward), a script route can be executed.
|
|
All modifications made by that route will be reflected only for
|
|
the current branch.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value of this parameter is 0 (none).
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>proxy_route</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","proxy_route",1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>case_sensitive</varname> (int)</title>
|
|
<para>
|
|
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>
|
|
<para>
|
|
<emphasis>
|
|
Default value of this parameter is 0.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>case_sensitive</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","case_sensitive",1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>realm_prefix</varname> (string)</title>
|
|
<para>
|
|
Defines a prefix for the domain part which should be ignored
|
|
in handling users and scripts.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value of this parameter is empty string.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>realm_prefix</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","realm_prefix","sip.")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<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
|
|
used by the TIMEOUT attribute from the PROXY tag.
|
|
</para>
|
|
<para>
|
|
NOTE: take care and syncronize this value with the similar
|
|
parameters in TM module.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value of this parameter is NULL.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>timer_avp</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","timer_avp","$avp(i:14)")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>lookup_domain</varname> (string)</title>
|
|
<para>
|
|
Used by lookup tag to indicate where to perform user location.
|
|
Basically this is the name of the usrloc domain (table) where
|
|
the user registrations are kept.
|
|
</para>
|
|
<para>
|
|
If set to empty string, the lookup node will be disabled - no
|
|
user location will be performed.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value of this parameter is NULL.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>lookup_domain</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","lookup_domain","location")
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>lookup_append_branches</varname> (int)</title>
|
|
<para>
|
|
Tells if the lookup tag should append branches (to do parallel
|
|
forking) if user_location lookup returns more than one contact.
|
|
Set it to a non zero value to enable parallel forking for
|
|
location lookup tag.
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value of this parameter is 0.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>lookup_append_branches</varname>
|
|
parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","lookup_append_branches",1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title><varname>use_domain</varname> (integer)</title>
|
|
<para>
|
|
Indicates if the domain part of the URI should be used in
|
|
user identification (otherwise only username part will be
|
|
used).
|
|
</para>
|
|
<para>
|
|
<emphasis>
|
|
Default value is <quote>0 (disabled)</quote>.
|
|
</emphasis>
|
|
</para>
|
|
<example>
|
|
<title>Set <varname>use_domain</varname> parameter</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
modparam("cpl-c","use_domain",1)
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
|
|
<section>
|
|
<title>Exported Functions</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">cpl_run_script(type,mode)</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
|
|
outgoing execution).
|
|
Regarding the stateful/stateless message processing, the
|
|
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
|
|
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
|
|
continue with the normal behavior as if no script existed.
|
|
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
|
|
user is generating an INVITE - call).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para><emphasis>mode</emphasis> - sets the interpreter mode as
|
|
stateless/stateful behavior. The following modes are accepted:
|
|
</para>
|
|
<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
|
|
function returns, will be in stateless mode.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<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.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
<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).
|
|
So, if the function returns, will be in stateless mode.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
<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
|
|
proxying is done), but there is minimal protection against
|
|
retransmissions (since replies are send stateless);
|
|
force_stateful is a good compromise - all signaling is done
|
|
stateful (retransmission protection) and in the same time, if
|
|
returning to script, it will be in stateless mode (easy to
|
|
continue the routing script execution)
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>cpl_run_script</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
cpl_run_script("incoming","force_stateful");
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<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
|
|
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
|
|
for errors.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>cpl_process_register</function> usage</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (method=="REGISTER") {
|
|
cpl_process_register();
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">cpl_process_register_norpl()
|
|
</function>
|
|
</title>
|
|
<para>
|
|
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
|
|
between CPL and UserLocation services via same REGISTER
|
|
messages.
|
|
</para>
|
|
<para>
|
|
This function can be used from REQUEST_ROUTE.
|
|
</para>
|
|
<example>
|
|
<title><function>cpl_process_register_norpl</function> usage
|
|
</title>
|
|
<programlisting format="linespecific">
|
|
...
|
|
if (method=="REGISTER") {
|
|
cpl_process_register();
|
|
# continue with usrloc part
|
|
save("location");
|
|
}
|
|
...
|
|
</programlisting>
|
|
</example>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Exported MI Functions</title>
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">LOAD_CPL</function>
|
|
</title>
|
|
<para>
|
|
For the given user, loads the XML cpl file, compiles it into
|
|
binary format and stores both format into database.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>LOAD_CPL</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>username : name of the user</para></listitem>
|
|
<listitem><para>cpl_filename: file name </para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
MI FIFO Command format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:LOAD_CPL:_reply_fifo_file_
|
|
username
|
|
cpl_filename
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<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
|
|
accepted.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>REMOVE_CPL</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>username : name of the user</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
MI FIFO Command format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:REMOVE_CPL:_reply_fifo_file_
|
|
username
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>
|
|
<function moreinfo="none">GET_CPL</function>
|
|
</title>
|
|
<para>
|
|
For the given user, returns the CPL script in XML format.
|
|
</para>
|
|
<para>
|
|
Name: <emphasis>GET_CPL</emphasis>
|
|
</para>
|
|
<para>Parameters:</para>
|
|
<itemizedlist>
|
|
<listitem><para>username : name of the user</para></listitem>
|
|
</itemizedlist>
|
|
<para>
|
|
MI FIFO Command format:
|
|
</para>
|
|
<programlisting format="linespecific">
|
|
:GET_CPL:_reply_fifo_file_
|
|
username
|
|
_empty_line_
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Installation and Running</title>
|
|
<section>
|
|
<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
|
|
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
|
|
in the <acronym>SQL</acronym> script.
|
|
You can also find the complete database documentation on the
|
|
project webpage, &kamailiodbdocslink;.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
|