Debian Codegraph @

src/modules/cplc/README

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