diff --git a/src/modules/cplc/README b/src/modules/cplc/README index 139597f9cb0..45732f2eb20 100644 --- a/src/modules/cplc/README +++ b/src/modules/cplc/README @@ -1,2 +1,568 @@ +cplc Module +Bogdan-Andrei Iancu + Voice Sistem SRL + +Edited by + +Bogdan-Andrei Iancu + + Copyright © 2003 FhG FOKUS + __________________________________________________________________ + + Table of Contents + + 1. Admin Guide + + 1. Overview + 2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + + 3. Parameters + + 3.1. db_url (string) + 3.2. db_table (string) + 3.3. username_column (string) + 3.4. domain_column (string) + 3.5. cpl_xml_column (string) + 3.6. cpl_bin_column (string) + 3.7. cpl_dtd_file (string) + 3.8. log_dir (string) + 3.9. proxy_recurse (int) + 3.10. proxy_route (int) + 3.11. case_sensitive (int) + 3.12. realm_prefix (string) + 3.13. timer_avp (string) + 3.14. lookup_domain (string) + 3.15. lookup_append_branches (int) + 3.16. use_domain (integer) + + 4. Functions + + 4.1. cpl_run_script(type,mode, [uri]) + 4.2. cpl_process_register() + 4.3. cpl_process_register_norpl() + + 5. RPC Commands + + 5.1. cpl.load + 5.2. cpl.remove + 5.3. cpl.get + + 6. Installation and Running + + 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 + + Table of Contents + + 1. Overview + 2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + + 3. Parameters + + 3.1. db_url (string) + 3.2. db_table (string) + 3.3. username_column (string) + 3.4. domain_column (string) + 3.5. cpl_xml_column (string) + 3.6. cpl_bin_column (string) + 3.7. cpl_dtd_file (string) + 3.8. log_dir (string) + 3.9. proxy_recurse (int) + 3.10. proxy_route (int) + 3.11. case_sensitive (int) + 3.12. realm_prefix (string) + 3.13. timer_avp (string) + 3.14. lookup_domain (string) + 3.15. lookup_append_branches (int) + 3.16. use_domain (integer) + + 4. Functions + + 4.1. cpl_run_script(type,mode, [uri]) + 4.2. cpl_process_register() + 4.3. cpl_process_register_norpl() + + 5. RPC Commands + + 5.1. cpl.load + 5.2. cpl.remove + 5.3. cpl.get + + 6. Installation and Running + + 6.1. Database setup + +1. Overview + + cpl-c modules implements a CPL (Call Processing Language) interpreter. + Support for uploading/downloading/removing scripts via SIP REGISTER + method is present. + + CPL is an IETF specification detailed in RFC3880 + (https://tools.ietf.org/html/rfc3880). + +2. Dependencies + + 2.1. Kamailio Modules + 2.2. External Libraries or Applications + +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) + +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. + +3. Parameters + + 3.1. db_url (string) + 3.2. db_table (string) + 3.3. username_column (string) + 3.4. domain_column (string) + 3.5. cpl_xml_column (string) + 3.6. cpl_bin_column (string) + 3.7. cpl_dtd_file (string) + 3.8. log_dir (string) + 3.9. proxy_recurse (int) + 3.10. proxy_route (int) + 3.11. case_sensitive (int) + 3.12. realm_prefix (string) + 3.13. timer_avp (string) + 3.14. lookup_domain (string) + 3.15. lookup_append_branches (int) + 3.16. use_domain (integer) + +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://kamailio:kamailiorw@localhost/kamailio”. + + Example 1.1. Set db_url parameter +... +modparam("cpl-c","db_url","dbdriver://username:password@dbhost/dbname") +... + +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") +... + +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") +... + +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") +... + +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") +... + +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") +... + +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") +... + +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") +... + +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) +... + +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) +... + +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) +... + +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.") +... + +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)") +... + +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") +... + +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) +... + +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) +... + +4. Functions + + 4.1. cpl_run_script(type,mode, [uri]) + 4.2. cpl_process_register() + 4.3. cpl_process_register_norpl() + +4.1. cpl_run_script(type,mode, [uri]) + + 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) + * uri - optional - provide the SIP URI to be used for loading the CPL + script, instead of taking it from R-URI or headers. + + This function can be used from REQUEST_ROUTE. + + Example 1.17. cpl_run_script usage +... +cpl_run_script("incoming","force_stateful"); +... + +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(); +} +... + +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"); +} +... + +5. RPC Commands + + 5.1. cpl.load + 5.2. cpl.remove + 5.3. cpl.get + +5.1. cpl.load + + For the given user, loads the XML cpl file, compiles it into binary + format and stores both format into database. + + Name: cpl.load + + Parameters: + * username : name of the user + * cpl_filename: file name + + RPC Command format: +... +kamcmd cpl.load username cpl_filename +... + +5.2. cpl.remove + + For the given user, removes the entire database record (XML cpl and + binary cpl); user with empty cpl scripts are not accepted. + + Name: cpl.remove + + Parameters: + * username : name of the user + + RPC Command format: +... +kamcmd cpl.remove username +... + +5.3. cpl.get + + For the given user, returns the CPL script in XML format. + + Name: cpl.get + + Parameters: + * username : name of the user + + RPC Command format: +... +kamcmd cpl.get username +... + +6. Installation and Running + + 6.1. Database setup + +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.