1cplc Module 2 3Bogdan-Andrei Iancu 4 5 Voice Sistem SRL 6 7Edited by 8 9Bogdan-Andrei Iancu 10 11 Copyright © 2003 FhG FOKUS 12 __________________________________________________________________ 13 14 Table of Contents 15 16 1. Admin Guide 17 18 1. Overview 19 2. Dependencies 20 21 2.1. Kamailio Modules 22 2.2. External Libraries or Applications 23 24 3. Parameters 25 26 3.1. db_url (string) 27 3.2. db_table (string) 28 3.3. username_column (string) 29 3.4. domain_column (string) 30 3.5. cpl_xml_column (string) 31 3.6. cpl_bin_column (string) 32 3.7. cpl_dtd_file (string) 33 3.8. log_dir (string) 34 3.9. proxy_recurse (int) 35 3.10. proxy_route (string) 36 3.11. case_sensitive (int) 37 3.12. realm_prefix (string) 38 3.13. timer_avp (string) 39 3.14. lookup_domain (string) 40 3.15. lookup_append_branches (int) 41 3.16. use_domain (integer) 42 43 4. Functions 44 45 4.1. cpl_run_script(type,mode, [uri]) 46 4.2. cpl_process_register() 47 4.3. cpl_process_register_norpl() 48 49 5. RPC Commands 50 51 5.1. cpl.load 52 5.2. cpl.remove 53 5.3. cpl.get 54 55 6. Installation and Running 56 57 6.1. Database setup 58 59 List of Examples 60 61 1.1. Set db_url parameter 62 1.2. Set db_table parameter 63 1.3. Set username_column parameter 64 1.4. Set domain_column parameter 65 1.5. Set cpl_xml_column parameter 66 1.6. Set cpl_bin_column parameter 67 1.7. Set cpl_dtd_file parameter 68 1.8. Set log_dir parameter 69 1.9. Set proxy_recurse parameter 70 1.10. Set proxy_route parameter 71 1.11. Set case_sensitive parameter 72 1.12. Set realm_prefix parameter 73 1.13. Set timer_avp parameter 74 1.14. Set lookup_domain parameter 75 1.15. Set lookup_append_branches parameter 76 1.16. Set use_domain parameter 77 1.17. cpl_run_script usage 78 1.18. cpl_process_register usage 79 1.19. cpl_process_register_norpl usage 80 81Chapter 1. Admin Guide 82 83 Table of Contents 84 85 1. Overview 86 2. Dependencies 87 88 2.1. Kamailio Modules 89 2.2. External Libraries or Applications 90 91 3. Parameters 92 93 3.1. db_url (string) 94 3.2. db_table (string) 95 3.3. username_column (string) 96 3.4. domain_column (string) 97 3.5. cpl_xml_column (string) 98 3.6. cpl_bin_column (string) 99 3.7. cpl_dtd_file (string) 100 3.8. log_dir (string) 101 3.9. proxy_recurse (int) 102 3.10. proxy_route (string) 103 3.11. case_sensitive (int) 104 3.12. realm_prefix (string) 105 3.13. timer_avp (string) 106 3.14. lookup_domain (string) 107 3.15. lookup_append_branches (int) 108 3.16. use_domain (integer) 109 110 4. Functions 111 112 4.1. cpl_run_script(type,mode, [uri]) 113 4.2. cpl_process_register() 114 4.3. cpl_process_register_norpl() 115 116 5. RPC Commands 117 118 5.1. cpl.load 119 5.2. cpl.remove 120 5.3. cpl.get 121 122 6. Installation and Running 123 124 6.1. Database setup 125 1261. Overview 127 128 cpl-c modules implements a CPL (Call Processing Language) interpreter. 129 Support for uploading/downloading/removing scripts via SIP REGISTER 130 method is present. 131 132 CPL is an IETF specification detailed in RFC3880 133 (https://tools.ietf.org/html/rfc3880). 134 1352. Dependencies 136 137 2.1. Kamailio Modules 138 2.2. External Libraries or Applications 139 1402.1. Kamailio Modules 141 142 The following modules must be loaded before this module: 143 * any DB module- a DB module for interfacing the DB operations 144 (modules like mysql, postgres, dbtext, etc) 145 * TM (Transaction) module- used for proxying/forking requests 146 * SL (StateLess) module - used for sending stateless reply when 147 responding to REGISTER request or for sending back error responses 148 * USRLOC (User Location) module - used for implementing 149 lookup("registration") tag (adding into location set of the users' 150 contact) 151 1522.2. External Libraries or Applications 153 154 The following libraries or applications must be installed before 155 running Kamailio with this module loaded: 156 * libxml2 and libxml2-devel - on some SO, these to packages are 157 merged into libxml2. This library contains an engine for XML 158 parsing, DTD validation and DOM manipulation. 159 1603. Parameters 161 162 3.1. db_url (string) 163 3.2. db_table (string) 164 3.3. username_column (string) 165 3.4. domain_column (string) 166 3.5. cpl_xml_column (string) 167 3.6. cpl_bin_column (string) 168 3.7. cpl_dtd_file (string) 169 3.8. log_dir (string) 170 3.9. proxy_recurse (int) 171 3.10. proxy_route (string) 172 3.11. case_sensitive (int) 173 3.12. realm_prefix (string) 174 3.13. timer_avp (string) 175 3.14. lookup_domain (string) 176 3.15. lookup_append_branches (int) 177 3.16. use_domain (integer) 178 1793.1. db_url (string) 180 181 A SQL URL have to be given to the module for knowing where the database 182 containing the table with CPL scripts is locates. If required a user 183 name and password can be specified for allowing the module to connect 184 to the database server. 185 186 Default value is “mysql://kamailio:kamailiorw@localhost/kamailio”. 187 188 Example 1.1. Set db_url parameter 189... 190modparam("cpl-c","db_url","dbdriver://username:password@dbhost/dbname") 191... 192 1933.2. db_table (string) 194 195 Indicates the name of the table that store the CPL scripts. This table 196 must be locate into the database specified by “db_url” parameter. For 197 more about the format of the CPL table please see the 198 modules/cpl-c/init.mysql file. 199 200 Default value is “cpl”. 201 202 Example 1.2. Set db_table parameter 203... 204modparam("cpl-c","cpl_table","cpl") 205... 206 2073.3. username_column (string) 208 209 Indicates the name of the column used for storing the username. 210 211 Default value is “username”. 212 213 Example 1.3. Set username_column parameter 214... 215modparam("cpl-c","username_column","username") 216... 217 2183.4. domain_column (string) 219 220 Indicates the name of the column used for storing the domain. 221 222 Default value is “domain”. 223 224 Example 1.4. Set domain_column parameter 225... 226modparam("cpl-c","domain_column","domain") 227... 228 2293.5. cpl_xml_column (string) 230 231 Indicates the name of the column used for storing the XML version of 232 the cpl script. 233 234 Default value is “cpl_xml”. 235 236 Example 1.5. Set cpl_xml_column parameter 237... 238modparam("cpl-c","cpl_xml_column","cpl_xml") 239... 240 2413.6. cpl_bin_column (string) 242 243 Indicates the name of the column used for storing the binary version of 244 the cpl script (compiled version). 245 246 Default value is “cpl_bin”. 247 248 Example 1.6. Set cpl_bin_column parameter 249... 250modparam("cpl-c","cpl_bin_column","cpl_bin") 251... 252 2533.7. cpl_dtd_file (string) 254 255 Points to the DTD file describing the CPL grammar. The file name may 256 include also the path to the file. This path can be absolute or 257 relative (be careful the path will be relative to the starting 258 directory of Kamailio). 259 260 This parameter is MANDATORY! 261 262 Example 1.7. Set cpl_dtd_file parameter 263... 264modparam("cpl-c","cpl_dtd_file","/etc/kamailio/cpl-06.dtd") 265... 266 2673.8. log_dir (string) 268 269 Points to a directory where should be created all the log file 270 generated by the LOG CPL node. A log file per user will be created (on 271 demand) having the name username.log. 272 273 If this parameter is absent, the logging will be disabled without 274 generating error on execution. 275 276 Example 1.8. Set log_dir parameter 277... 278modparam("cpl-c","log_dir","/var/log/kamailio/cpl") 279... 280 2813.9. proxy_recurse (int) 282 283 Tells for how many time is allow to have recurse for PROXY CPL node If 284 it has value 2, when doing proxy, only twice the proxy action will be 285 re-triggered by a redirect response; the third time, the proxy 286 execution will end by going on REDIRECTION branch. The recurse feature 287 can be disable by setting this parameter to 0 288 289 Default value of this parameter is 0. 290 291 Example 1.9. Set proxy_recurse parameter 292... 293modparam("cpl-c","proxy_recurse",2) 294... 295 2963.10. proxy_route (string) 297 298 Before doing proxy (forward), a script route can be executed. All 299 modifications made by that route will be reflected only for the current 300 branch. 301 302 Default value of this parameter is NULL (none). 303 304 Example 1.10. Set proxy_route parameter 305... 306modparam("cpl-c","proxy_route","1") 307... 308 3093.11. case_sensitive (int) 310 311 Tells if the username matching should be perform case sensitive or not. 312 Set it to a non zero value to force a case sensitive handling of 313 usernames. 314 315 Default value of this parameter is 0. 316 317 Example 1.11. Set case_sensitive parameter 318... 319modparam("cpl-c","case_sensitive",1) 320... 321 3223.12. realm_prefix (string) 323 324 Defines a prefix for the domain part which should be ignored in 325 handling users and scripts. 326 327 Default value of this parameter is empty string. 328 329 Example 1.12. Set realm_prefix parameter 330... 331modparam("cpl-c","realm_prefix","sip.") 332... 333 3343.13. timer_avp (string) 335 336 Full specification (ID, NAME, ALIAS) of the AVP to be used to set the 337 value of the Final Response INVITE timeout - it's used by the TIMEOUT 338 attribute from the PROXY tag. 339 340 NOTE: take care and synchronize this value with the similar parameters 341 in TM module. 342 343 Default value of this parameter is NULL. 344 345 Example 1.13. Set timer_avp parameter 346... 347modparam("cpl-c","timer_avp","$avp(i:14)") 348... 349 3503.14. lookup_domain (string) 351 352 Used by lookup tag to indicate where to perform user location. 353 Basically this is the name of the usrloc domain (table) where the user 354 registrations are kept. 355 356 If set to empty string, the lookup node will be disabled - no user 357 location will be performed. 358 359 Default value of this parameter is NULL. 360 361 Example 1.14. Set lookup_domain parameter 362... 363modparam("cpl-c","lookup_domain","location") 364... 365 3663.15. lookup_append_branches (int) 367 368 Tells if the lookup tag should append branches (to do parallel forking) 369 if user_location lookup returns more than one contact. Set it to a non 370 zero value to enable parallel forking for location lookup tag. 371 372 Default value of this parameter is 0. 373 374 Example 1.15. Set lookup_append_branches parameter 375... 376modparam("cpl-c","lookup_append_branches",1) 377... 378 3793.16. use_domain (integer) 380 381 Indicates if the domain part of the URI should be used in user 382 identification (otherwise only username part will be used). 383 384 Default value is “0 (disabled)”. 385 386 Example 1.16. Set use_domain parameter 387... 388modparam("cpl-c","use_domain",1) 389... 390 3914. Functions 392 393 4.1. cpl_run_script(type,mode, [uri]) 394 4.2. cpl_process_register() 395 4.3. cpl_process_register_norpl() 396 3974.1. cpl_run_script(type,mode, [uri]) 398 399 Starts the execution of the CPL script. The user name is fetched from 400 new_uri or requested uri or from To header -in this order- (for 401 incoming execution) or from FROM header (for outgoing execution). 402 Regarding the stateful/stateless message processing, the function is 403 very flexible, being able to run in different modes (see below 404 the"mode" parameter). Normally this function will end script execution. 405 There is no guaranty that the CPL script interpretation ended when 406 Kamailio script ended also (for the same INVITE ;-)) - this can happen 407 when the CPL script does a PROXY and the script interpretation pause 408 after proxying and it will be resume when some reply is received (this 409 can happen in a different process of SER). If the function returns to 410 script, the SIP server should continue with the normal behavior as if 411 no script existed. When some error is returned, the function itself 412 haven't sent any SIP error reply (this can be done from script). 413 414 Meaning of the parameters is as follows: 415 * type - which part of the script should be run; set it to "incoming" 416 for having the incoming part of script executed (when an INVITE is 417 received) or to "outgoing" for running the outgoing part of script 418 (when a user is generating an INVITE - call). 419 * mode - sets the interpreter mode as stateless/stateful behavior. 420 The following modes are accepted: 421 + IS_STATELESS - the current INVITE has no transaction created 422 yet. All replies (redirection or deny) will be done is a 423 stateless way. The execution will switch to stateful only when 424 proxy is done. So, if the function returns, will be in 425 stateless mode. 426 + IS_STATEFUL - the current INVITE has already a transaction 427 associated. All signaling operations (replies or proxy) will 428 be done in stateful way.So, if the function returns, will be 429 in stateful mode. 430 + FORCE_STATEFUL - the current INVITE has no transaction created 431 yet. All signaling operations will be done is a stateful way 432 (on signaling, the transaction will be created from within the 433 interpreter). So, if the function returns, will be in 434 stateless mode. 435 HINT: is_stateful is very difficult to manage from the routing 436 script (script processing can continue in stateful mode); 437 is_stateless is the fastest and less resources consumer 438 (transaction is created only if proxying is done), but there is 439 minimal protection against retransmissions (since replies are send 440 stateless); force_stateful is a good compromise - all signaling is 441 done stateful (retransmission protection) and in the same time, if 442 returning to script, it will be in stateless mode (easy to continue 443 the routing script execution) 444 * uri - optional - provide the SIP URI to be used for loading the CPL 445 script, instead of taking it from R-URI or headers. 446 447 This function can be used from REQUEST_ROUTE. 448 449 Example 1.17. cpl_run_script usage 450... 451cpl_run_script("incoming","force_stateful"); 452... 453 4544.2. cpl_process_register() 455 456 This function MUST be called only for REGISTER requests. It checks if 457 the current REGISTER request is related or not with CPL script 458 upload/download/ remove. If it is, all the needed operation will be 459 done. For checking if the REGISTER is CPL related, the function looks 460 fist to "Content-Type" header. If it exists and has a the mime type set 461 to "application/cpl+xml" means this is a CPL script upload/remove 462 operation. The distinction between to case is made by looking at 463 "Content-Disposition" header; id its value is "script;action=store", 464 means it's an upload; if it's "script;action=remove", means it's a 465 remove operation; other values are considered to be errors. If no 466 "Content-Type" header is present, the function looks to "Accept" header 467 and if it contains the "*" or "application/cpl-xml" the request it will 468 be consider one for downloading CPL scripts. The functions returns to 469 script only if the REGISTER is not related to CPL. In other case, the 470 function will send by itself the necessary replies (stateless - using 471 sl), including for errors. 472 473 This function can be used from REQUEST_ROUTE. 474 475 Example 1.18. cpl_process_register usage 476... 477if (method=="REGISTER") { 478 cpl_process_register(); 479} 480... 481 4824.3. cpl_process_register_norpl() 483 484 Same as “cpl_process_register” without internally generating the reply. 485 All information (script) is appended to the reply but without sending 486 it out. 487 488 Main purpose of this function is to allow integration between CPL and 489 UserLocation services via same REGISTER messages. 490 491 This function can be used from REQUEST_ROUTE. 492 493 Example 1.19. cpl_process_register_norpl usage 494... 495if (method=="REGISTER") { 496 cpl_process_register(); 497 # continue with usrloc part 498 save("location"); 499} 500... 501 5025. RPC Commands 503 504 5.1. cpl.load 505 5.2. cpl.remove 506 5.3. cpl.get 507 5085.1. cpl.load 509 510 For the given user, loads the XML cpl file, compiles it into binary 511 format and stores both format into database. 512 513 Name: cpl.load 514 515 Parameters: 516 * username : name of the user 517 * cpl_filename: file name 518 519 RPC Command format: 520... 521kamcmd cpl.load username cpl_filename 522... 523 5245.2. cpl.remove 525 526 For the given user, removes the entire database record (XML cpl and 527 binary cpl); user with empty cpl scripts are not accepted. 528 529 Name: cpl.remove 530 531 Parameters: 532 * username : name of the user 533 534 RPC Command format: 535... 536kamcmd cpl.remove username 537... 538 5395.3. cpl.get 540 541 For the given user, returns the CPL script in XML format. 542 543 Name: cpl.get 544 545 Parameters: 546 * username : name of the user 547 548 RPC Command format: 549... 550kamcmd cpl.get username 551... 552 5536. Installation and Running 554 555 6.1. Database setup 556 5576.1. Database setup 558 559 Before running Kamailio with cpl-c, you have to setup the database 560 table where the module will store the CPL scripts. For that, if the 561 table was not created by the installation script or you choose to 562 install everything by yourself you can use the cpc-create.sql SQL 563 script in the database directories in the kamailio/scripts folder as 564 template. Database and table name can be set with module parameters so 565 they can be changed, but the name of the columns must be as they are in 566 the SQL script. You can also find the complete database documentation 567 on the project webpage, 568 https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html. 569