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