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.
505 lines
16 KiB
505 lines
16 KiB
cpl-c Module
|
|
|
|
Bogdan-Andrei Iancu
|
|
|
|
voice-system.ro
|
|
|
|
Edited by
|
|
|
|
Bogdan-Andrei Iancu
|
|
|
|
Copyright © 2003 FhG FOKUS
|
|
Revision History
|
|
Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
|
|
(Mi, 06 Aug 2008) $
|
|
__________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
1. Admin Guide
|
|
|
|
1.1. Overview
|
|
1.2. Dependencies
|
|
|
|
1.2.1. Kamailio Modules
|
|
1.2.2. External Libraries or Applications
|
|
|
|
1.3. Exported Parameters
|
|
|
|
1.3.1. db_url (string)
|
|
1.3.2. db_table (string)
|
|
1.3.3. username_column (string)
|
|
1.3.4. domain_column (string)
|
|
1.3.5. cpl_xml_column (string)
|
|
1.3.6. cpl_bin_column (string)
|
|
1.3.7. cpl_dtd_file (string)
|
|
1.3.8. log_dir (string)
|
|
1.3.9. proxy_recurse (int)
|
|
1.3.10. proxy_route (int)
|
|
1.3.11. case_sensitive (int)
|
|
1.3.12. realm_prefix (string)
|
|
1.3.13. timer_avp (string)
|
|
1.3.14. lookup_domain (string)
|
|
1.3.15. lookup_append_branches (int)
|
|
1.3.16. use_domain (integer)
|
|
|
|
1.4. Exported Functions
|
|
|
|
1.4.1. cpl_run_script(type,mode)
|
|
1.4.2. cpl_process_register()
|
|
1.4.3. cpl_process_register_norpl()
|
|
|
|
1.5. Exported MI Functions
|
|
|
|
1.5.1. LOAD_CPL
|
|
1.5.2. REMOVE_CPL
|
|
1.5.3. GET_CPL
|
|
|
|
1.6. Installation and Running
|
|
|
|
1.6.1. Database setup
|
|
|
|
List of Examples
|
|
|
|
1.1. Set db_url parameter
|
|
1.2. Set db_table parameter
|
|
1.3. Set username_column parameter
|
|
1.4. Set domain_column parameter
|
|
1.5. Set cpl_xml_column parameter
|
|
1.6. Set cpl_bin_column parameter
|
|
1.7. Set cpl_dtd_file parameter
|
|
1.8. Set log_dir parameter
|
|
1.9. Set proxy_recurse parameter
|
|
1.10. Set proxy_route parameter
|
|
1.11. Set case_sensitive parameter
|
|
1.12. Set realm_prefix parameter
|
|
1.13. Set timer_avp parameter
|
|
1.14. Set lookup_domain parameter
|
|
1.15. Set lookup_append_branches parameter
|
|
1.16. Set use_domain parameter
|
|
1.17. cpl_run_script usage
|
|
1.18. cpl_process_register usage
|
|
1.19. cpl_process_register_norpl usage
|
|
|
|
Chapter 1. Admin Guide
|
|
|
|
1.1. Overview
|
|
|
|
cpl-c modules implements a CPL (Call Processing Language)
|
|
interpreter. Support for uploading/downloading/removing scripts
|
|
via SIP REGISTER method is present.
|
|
|
|
1.2. Dependencies
|
|
|
|
1.2.1. Kamailio Modules
|
|
|
|
The following modules must be loaded before this module:
|
|
* any DB module- a DB module for interfacing the DB
|
|
operations (modules like mysql, postgres, dbtext, etc)
|
|
* TM (Transaction) module- used for proxying/forking requests
|
|
* SL (StateLess) module - used for sending stateless reply
|
|
when responding to REGISTER request or for sending back
|
|
error responses
|
|
* USRLOC (User Location) module - used for implementing
|
|
lookup("registration") tag (adding into location set of the
|
|
users' contact)
|
|
|
|
1.2.2. External Libraries or Applications
|
|
|
|
The following libraries or applications must be installed
|
|
before running Kamailio with this module loaded:
|
|
* 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.
|
|
|
|
1.3. Exported Parameters
|
|
|
|
1.3.1. db_url (string)
|
|
|
|
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.
|
|
|
|
Default value is "mysql://openser:openserrw@localhost/openser".
|
|
|
|
Example 1.1. Set db_url parameter
|
|
...
|
|
modparam("cpl-c","db_url","dbdriver://username:password@dbhost/dbname")
|
|
...
|
|
|
|
1.3.2. db_table (string)
|
|
|
|
Indicates the name of the table that store the CPL scripts.
|
|
This table must be locate into the database specified by
|
|
"db_url" parameter. For more about the format of the CPL table
|
|
please see the modules/cpl-c/init.mysql file.
|
|
|
|
Default value is "cpl".
|
|
|
|
Example 1.2. Set db_table parameter
|
|
...
|
|
modparam("cpl-c","cpl_table","cpl")
|
|
...
|
|
|
|
1.3.3. username_column (string)
|
|
|
|
Indicates the name of the column used for storing the username.
|
|
|
|
Default value is "username".
|
|
|
|
Example 1.3. Set username_column parameter
|
|
...
|
|
modparam("cpl-c","username_column","username")
|
|
...
|
|
|
|
1.3.4. domain_column (string)
|
|
|
|
Indicates the name of the column used for storing the domain.
|
|
|
|
Default value is "domain".
|
|
|
|
Example 1.4. Set domain_column parameter
|
|
...
|
|
modparam("cpl-c","domain_column","domain")
|
|
...
|
|
|
|
1.3.5. cpl_xml_column (string)
|
|
|
|
Indicates the name of the column used for storing the the XML
|
|
version of the cpl script.
|
|
|
|
Default value is "cpl_xml".
|
|
|
|
Example 1.5. Set cpl_xml_column parameter
|
|
...
|
|
modparam("cpl-c","cpl_xml_column","cpl_xml")
|
|
...
|
|
|
|
1.3.6. cpl_bin_column (string)
|
|
|
|
Indicates the name of the column used for storing the the
|
|
binary version of the cpl script (compiled version).
|
|
|
|
Default value is "cpl_bin".
|
|
|
|
Example 1.6. Set cpl_bin_column parameter
|
|
...
|
|
modparam("cpl-c","cpl_bin_column","cpl_bin")
|
|
...
|
|
|
|
1.3.7. cpl_dtd_file (string)
|
|
|
|
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).
|
|
|
|
This parameter is MANDATORY!
|
|
|
|
Example 1.7. Set cpl_dtd_file parameter
|
|
...
|
|
modparam("cpl-c","cpl_dtd_file","/etc/kamailio/cpl-06.dtd")
|
|
...
|
|
|
|
1.3.8. log_dir (string)
|
|
|
|
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.
|
|
|
|
If this parameter is absent, the logging will be disabled
|
|
without generating error on execution.
|
|
|
|
Example 1.8. Set log_dir parameter
|
|
...
|
|
modparam("cpl-c","log_dir","/var/log/kamailio/cpl")
|
|
...
|
|
|
|
1.3.9. proxy_recurse (int)
|
|
|
|
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
|
|
|
|
Default value of this parameter is 0.
|
|
|
|
Example 1.9. Set proxy_recurse parameter
|
|
...
|
|
modparam("cpl-c","proxy_recurse",2)
|
|
...
|
|
|
|
1.3.10. proxy_route (int)
|
|
|
|
Before doing proxy (forward), a script route can be executed.
|
|
All modifications made by that route will be reflected only for
|
|
the current branch.
|
|
|
|
Default value of this parameter is 0 (none).
|
|
|
|
Example 1.10. Set proxy_route parameter
|
|
...
|
|
modparam("cpl-c","proxy_route",1)
|
|
...
|
|
|
|
1.3.11. case_sensitive (int)
|
|
|
|
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.
|
|
|
|
Default value of this parameter is 0.
|
|
|
|
Example 1.11. Set case_sensitive parameter
|
|
...
|
|
modparam("cpl-c","case_sensitive",1)
|
|
...
|
|
|
|
1.3.12. realm_prefix (string)
|
|
|
|
Defines a prefix for the domain part which should be ignored in
|
|
handling users and scripts.
|
|
|
|
Default value of this parameter is empty string.
|
|
|
|
Example 1.12. Set realm_prefix parameter
|
|
...
|
|
modparam("cpl-c","realm_prefix","sip.")
|
|
...
|
|
|
|
1.3.13. timer_avp (string)
|
|
|
|
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.
|
|
|
|
NOTE: take care and syncronize this value with the similar
|
|
parameters in TM module.
|
|
|
|
Default value of this parameter is NULL.
|
|
|
|
Example 1.13. Set timer_avp parameter
|
|
...
|
|
modparam("cpl-c","timer_avp","$avp(i:14)")
|
|
...
|
|
|
|
1.3.14. lookup_domain (string)
|
|
|
|
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.
|
|
|
|
If set to empty string, the lookup node will be disabled - no
|
|
user location will be performed.
|
|
|
|
Default value of this parameter is NULL.
|
|
|
|
Example 1.14. Set lookup_domain parameter
|
|
...
|
|
modparam("cpl-c","lookup_domain","location")
|
|
...
|
|
|
|
1.3.15. lookup_append_branches (int)
|
|
|
|
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.
|
|
|
|
Default value of this parameter is 0.
|
|
|
|
Example 1.15. Set lookup_append_branches parameter
|
|
...
|
|
modparam("cpl-c","lookup_append_branches",1)
|
|
...
|
|
|
|
1.3.16. use_domain (integer)
|
|
|
|
Indicates if the domain part of the URI should be used in user
|
|
identification (otherwise only username part will be used).
|
|
|
|
Default value is "0 (disabled)".
|
|
|
|
Example 1.16. Set use_domain parameter
|
|
...
|
|
modparam("cpl-c","use_domain",1)
|
|
...
|
|
|
|
1.4. Exported Functions
|
|
|
|
1.4.1. cpl_run_script(type,mode)
|
|
|
|
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).
|
|
|
|
Meaning of the parameters is as follows:
|
|
* type - 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).
|
|
* mode - sets the interpreter mode as stateless/stateful
|
|
behavior. The following modes are accepted:
|
|
+ IS_STATELESS - 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.
|
|
+ IS_STATEFUL - 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.
|
|
+ FORCE_STATEFUL - 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.
|
|
HINT: 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)
|
|
|
|
This function can be used from REQUEST_ROUTE.
|
|
|
|
Example 1.17. cpl_run_script usage
|
|
...
|
|
cpl_run_script("incoming","force_stateful");
|
|
...
|
|
|
|
1.4.2. cpl_process_register()
|
|
|
|
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.
|
|
|
|
This function can be used from REQUEST_ROUTE.
|
|
|
|
Example 1.18. cpl_process_register usage
|
|
...
|
|
if (method=="REGISTER") {
|
|
cpl_process_register();
|
|
}
|
|
...
|
|
|
|
1.4.3. cpl_process_register_norpl()
|
|
|
|
Same as "cpl_process_register" without internally generating
|
|
the reply. All information (script) is appended to the reply
|
|
but without sending it out.
|
|
|
|
Main purpose of this function is to allow integration between
|
|
CPL and UserLocation services via same REGISTER messages.
|
|
|
|
This function can be used from REQUEST_ROUTE.
|
|
|
|
Example 1.19. cpl_process_register_norpl usage
|
|
...
|
|
if (method=="REGISTER") {
|
|
cpl_process_register();
|
|
# continue with usrloc part
|
|
save("location");
|
|
}
|
|
...
|
|
|
|
1.5. Exported MI Functions
|
|
|
|
1.5.1. LOAD_CPL
|
|
|
|
For the given user, loads the XML cpl file, compiles it into
|
|
binary format and stores both format into database.
|
|
|
|
Name: LOAD_CPL
|
|
|
|
Parameters:
|
|
* username : name of the user
|
|
* cpl_filename: file name
|
|
|
|
MI FIFO Command format:
|
|
:LOAD_CPL:_reply_fifo_file_
|
|
username
|
|
cpl_filename
|
|
_empty_line_
|
|
|
|
1.5.2. REMOVE_CPL
|
|
|
|
For the given user, removes the entire database record (XML cpl
|
|
and binary cpl); user with empty cpl scripts are not accepted.
|
|
|
|
Name: REMOVE_CPL
|
|
|
|
Parameters:
|
|
* username : name of the user
|
|
|
|
MI FIFO Command format:
|
|
:REMOVE_CPL:_reply_fifo_file_
|
|
username
|
|
_empty_line_
|
|
|
|
1.5.3. GET_CPL
|
|
|
|
For the given user, returns the CPL script in XML format.
|
|
|
|
Name: GET_CPL
|
|
|
|
Parameters:
|
|
* username : name of the user
|
|
|
|
MI FIFO Command format:
|
|
:GET_CPL:_reply_fifo_file_
|
|
username
|
|
_empty_line_
|
|
|
|
1.6. Installation and Running
|
|
|
|
1.6.1. Database setup
|
|
|
|
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 SQL 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 SQL script.
|
|
You can also find the complete database documentation on the
|
|
project webpage,
|
|
http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
|