f005f7e66f2445fbee4f9ba6bfe6aacc2ae22a3e
[sip-router] / src / modules / kex / README
1 KEx Module
2
3 Daniel-Constantin Mierla
4
5    asipto.com
6    <miconda@gmail.com>
7
8 Ovidiu Sas
9
10    VoIP Embedded, Inc.
11
12 Edited by
13
14 Daniel-Constantin Mierla
15
16    <miconda@gmail.com>
17
18 Edited by
19
20 Ovidiu Sas
21
22    <osas@voipembedded.com.com>
23
24    Copyright © 2009 Daniel-Constantin Mierla
25
26    Copyright © 2014 VoIP Embedded, Inc.
27      __________________________________________________________________
28
29    Table of Contents
30
31    1. Admin Guide
32
33         1. Overview
34         2. Dependencies
35
36               2.1. Kamailio Modules
37               2.2. External Libraries or Applications
38
39         3. Functions
40
41               3.1. setsflag(flag)
42               3.2. issflagset(flag)
43               3.3. resetsflag(flag)
44               3.4. setbflag(flag [, branch])
45               3.5. isbflagset(flag [, branch])
46               3.6. resetbflag(flag [, branch])
47               3.7. setdsturi(uri)
48               3.8. resetdsturi()
49               3.9. isdsturiset()
50               3.10. pv_printf(var, str)
51               3.11. is_myself(uri)
52               3.12. setdebug(level)
53               3.13. resetdebug()
54               3.14. km_append_branch([uri])
55
56         4. RPC Commands
57
58               4.1. core.arg
59               4.2. core.kill
60               4.3. core.pwd
61               4.4. core.uptime
62               4.5. version
63               4.6. system.listMethods
64               4.7. pkg.stats
65               4.8. stats.get_statistics
66               4.9. stats.reset_statistics
67               4.10. stats.clear_statistics
68               4.11. mod.stats module_name/all pkg/shm/all
69
70    List of Examples
71
72    1.1. setsflag usage
73    1.2. issflagset usage
74    1.3. resetsflag usage
75    1.4. setbflag usage
76    1.5. isbflagset usage
77    1.6. resetbflag usage
78    1.7. setdsturi usage
79    1.8. resetdsturi usage
80    1.9. isdsturiset usage
81    1.10. pv_printf usage
82    1.11. is_myself usage
83    1.12. setdebug usage
84    1.13. resetdebug usage
85
86 Chapter 1. Admin Guide
87
88    Table of Contents
89
90    1. Overview
91    2. Dependencies
92
93         2.1. Kamailio Modules
94         2.2. External Libraries or Applications
95
96    3. Functions
97
98         3.1. setsflag(flag)
99         3.2. issflagset(flag)
100         3.3. resetsflag(flag)
101         3.4. setbflag(flag [, branch])
102         3.5. isbflagset(flag [, branch])
103         3.6. resetbflag(flag [, branch])
104         3.7. setdsturi(uri)
105         3.8. resetdsturi()
106         3.9. isdsturiset()
107         3.10. pv_printf(var, str)
108         3.11. is_myself(uri)
109         3.12. setdebug(level)
110         3.13. resetdebug()
111         3.14. km_append_branch([uri])
112
113    4. RPC Commands
114
115         4.1. core.arg
116         4.2. core.kill
117         4.3. core.pwd
118         4.4. core.uptime
119         4.5. version
120         4.6. system.listMethods
121         4.7. pkg.stats
122         4.8. stats.get_statistics
123         4.9. stats.reset_statistics
124         4.10. stats.clear_statistics
125         4.11. mod.stats module_name/all pkg/shm/all
126
127 1. Overview
128
129    This module collects extensions from Kamailio core.
130
131    Kamailio Core CookBook is available at: http://kamailio.org/dokuwiki/
132
133 2. Dependencies
134
135    2.1. Kamailio Modules
136    2.2. External Libraries or Applications
137
138 2.1. Kamailio Modules
139
140    The following modules must be loaded before this module:
141      * No dependencies on other Kamailio modules.
142
143 2.2. External Libraries or Applications
144
145    The following libraries or applications must be installed before
146    running Kamailio with this module loaded:
147      * None.
148
149 3. Functions
150
151    3.1. setsflag(flag)
152    3.2. issflagset(flag)
153    3.3. resetsflag(flag)
154    3.4. setbflag(flag [, branch])
155    3.5. isbflagset(flag [, branch])
156    3.6. resetbflag(flag [, branch])
157    3.7. setdsturi(uri)
158    3.8. resetdsturi()
159    3.9. isdsturiset()
160    3.10. pv_printf(var, str)
161    3.11. is_myself(uri)
162    3.12. setdebug(level)
163    3.13. resetdebug()
164    3.14. km_append_branch([uri])
165
166 3.1. setsflag(flag)
167
168    Set the script flag.
169
170    Meaning of the parameters is as follows:
171      * flag - the index of the script flag to be set. Can be integer or
172        pseudo-variable with integer value.
173
174    This function can be used from ANY_ROUTE.
175
176    Example 1.1. setsflag usage
177 ...
178 setsflag("1");
179 ...
180 $var(flag) = 11;
181 setsflag("$var(flag)");
182 ...
183
184 3.2. issflagset(flag)
185
186    Return true of the script flag is set.
187
188    Meaning of the parameters is as follows:
189      * flag - the index of the script flag to be tested. Can be integer or
190        pseudo-variable with integer value.
191
192    This function can be used from ANY_ROUTE.
193
194    Example 1.2. issflagset usage
195 ...
196 if(issflagset("1"))
197 {
198     ...
199 }
200 ...
201
202 3.3. resetsflag(flag)
203
204    Reset the script flag.
205
206    Meaning of the parameters is as follows:
207      * flag - the index of the script flag to be reset. Can be integer or
208        pseudo-variable with integer value.
209
210    This function can be used from ANY_ROUTE.
211
212    Example 1.3. resetsflag usage
213 ...
214 resetsflag("1");
215 ...
216
217 3.4. setbflag(flag [, branch])
218
219    Set the branch flag.
220
221    Meaning of the parameters is as follows:
222      * flag - the index of the branch flag to be set. Can be integer or
223        pseudo-variable with integer value.
224      * branch - the index of the branch whose flag to be set. Can be
225        integer or pseudo-variable with integer value. If omitted, then
226        branch 0 is used (R-URI).
227
228    This function can be used from ANY_ROUTE.
229
230    Example 1.4. setbflag usage
231 ...
232 setbflag("1");
233 ...
234 $var(flag) = 11;
235 setbflag("$var(flag)", "1");
236 ...
237
238 3.5. isbflagset(flag [, branch])
239
240    Return true of the branch flag is set.
241
242    Meaning of the parameters is as follows:
243      * flag - the index of the branch flag to be tested. Can be integer or
244        pseudo-variable with integer value.
245      * branch - the index of the branch whose flag to be set. Can be
246        integer or pseudo-variable with integer value. If omitted, then
247        branch 0 is used (R-URI).
248
249    This function can be used from ANY_ROUTE.
250
251    Example 1.5. isbflagset usage
252 ...
253 if(isbflagset("1"))
254 {
255     ...
256 }
257 ...
258
259 3.6. resetbflag(flag [, branch])
260
261    Reset the branch flag.
262
263    Meaning of the parameters is as follows:
264      * flag - the index of the branch flag to be reset. Can be integer or
265        pseudo-variable with integer value.
266      * branch - the index of the branch whose flag to be set. Can be
267        integer or pseudo-variable with integer value. If omitted, then
268        branch 0 is used (R-URI).
269
270    This function can be used from ANY_ROUTE.
271
272    Example 1.6. resetbflag usage
273 ...
274 resetbflag("1");
275 ...
276
277 3.7. setdsturi(uri)
278
279    Set the destination address URI (outbound proxy address).
280
281    Meaning of the parameters is as follows:
282      * uri - Valid SIP URI representing the address where to send the
283        request. It must be a static string, no variables are evaluated at
284        runtime. If you need to set outbound proxy address via a variable,
285        use assginment to $du.
286
287    This function can be used from ANY_ROUTE.
288
289    Example 1.7. setdsturi usage
290 ...
291 setdsturi("sip:10.0.0.10");
292 ...
293
294 3.8. resetdsturi()
295
296    Reset the destination address URI (outbound proxy address).
297
298    This function can be used from ANY_ROUTE.
299
300    Example 1.8. resetdsturi usage
301 ...
302 resetdsturi();
303 ...
304
305 3.9. isdsturiset()
306
307    Check if the destination address URI (outbound proxy address) is set.
308
309    This function can be used from ANY_ROUTE.
310
311    Example 1.9. isdsturiset usage
312 ...
313 if(isdsturiset())
314 {
315    ...
316 }
317 ...
318
319 3.10. pv_printf(var, str)
320
321    Evalues the str and sets the resulting value to variable var. For
322    backward compatibility reasons, the same function can be executed via
323    'avp_printf(var, str)'.
324
325    Meaning of the parameters is as follows:
326      * var - name of a writable variable
327      * str - string that may contain variables which will be evaluated at
328        runtime.
329
330    This function can be used from ANY_ROUTE.
331
332    Example 1.10. pv_printf usage
333 ...
334 pv_printf("$ru", "sip:$rU@$fd");
335 pv_printf("$avp(x)", "From: $fU - To: $tU");
336 ...
337
338 3.11. is_myself(uri)
339
340    Check if the parameter matches the 'myself' condition (i.e., is a local
341    IP or domain).
342
343    Meaning of the parameters is as follows:
344      * uri - Valid SIP URI or IP address to check against the list of
345        local IP addresses or domains. The parameter value can contain
346        pseudo-variables.
347
348    This function can be used from ANY_ROUTE.
349
350    Example 1.11. is_myself usage
351 ...
352 if(is_myself("$fu")) {
353     ...
354 }
355 ...
356
357 3.12. setdebug(level)
358
359    Set the debug log level per process.
360
361    Meaning of the parameters is as follows:
362      * level - the debug log level to be set. Can be integer or
363        pseudo-variable with integer value.
364
365    This function can be used from ANY_ROUTE.
366
367    Example 1.12. setdebug usage
368 ...
369 setdebug("1");
370 ...
371 $var(level) = 2;
372 setdebug("$var(level)");
373 ...
374
375 3.13. resetdebug()
376
377    Reset the local debug log level back to the value of core parameter
378    'debug'.
379
380    This function can be used from ANY_ROUTE.
381
382    Example 1.13. resetdebug usage
383 ...
384 resetdebug();
385 ...
386
387 3.14. km_append_branch([uri])
388
389    This function was replaced by append_branch() from corex module,
390    starting with version 4.0.0.
391
392 4. RPC Commands
393
394    4.1. core.arg
395    4.2. core.kill
396    4.3. core.pwd
397    4.4. core.uptime
398    4.5. version
399    4.6. system.listMethods
400    4.7. pkg.stats
401    4.8. stats.get_statistics
402    4.9. stats.reset_statistics
403    4.10. stats.clear_statistics
404    4.11. mod.stats module_name/all pkg/shm/all
405
406 4.1.  core.arg
407
408    Print command line arguments.
409
410    Name: core.arg
411
412    Parameters: none.
413
414    RPC Command Format:
415 ...
416 kamcmd core.arg
417 ...
418
419 4.2.  core.kill
420
421    Kill the application.
422
423    Name: core.kill
424
425    Parameters: none.
426
427    RPC Command Format:
428 ...
429 kamcmd core.kill
430 ...
431
432 4.3.  core.pwd
433
434    Print working directory.
435
436    Name: core.pwd
437
438    Parameters: none.
439
440    RPC Command Format:
441 ...
442 kamcmd core.pwd
443 ...
444
445 4.4.  core.uptime
446
447    Print uptime.
448
449    Name: core.uptime
450
451    Parameters: none.
452
453    RPC Command Format:
454 ...
455 kamcmd core.uptime
456 ...
457
458 4.5.  version
459
460    Print version information.
461
462    Name: core.version
463
464    Parameters: none.
465
466    RPC Command Format:
467 ...
468 kamcmd core.version
469 ...
470
471 4.6.  system.listMethods
472
473    Print list of available RPC commands.
474
475    Name: system.listMethods
476
477    Parameters: none.
478
479    RPC Command Format:
480 ...
481 kamcmd system.listMethods
482 ...
483
484 4.7.  pkg.stats
485
486    Print private memory (pkg) usage statistics per process. It can take
487    optinally a filter to print statistics only for a specific process or
488    set of processes. If no filter is given, it prints statistics for all
489    processes.
490
491    The filter can be:
492      * pid value - print statistics for specific process pid.
493      * rank value - print statistics for specific process rank.
494      * index value - print statistics for specific index in process table.
495
496    Examples:
497                 kamcmd pkg.stats
498                 kamcmd pkg.stats pid 1234
499                 kamcmd pkg.stats rank 1
500                 kamcmd pkg.stats index 10
501
502 4.8.  stats.get_statistics
503
504    Print the list of available internal statistics.
505
506    Parameters: statsid - which statistics to be printed. If set to 'all'
507    then all statistics are printed; if set to 'statsgroup:' then all
508    statistics in the group are printed; if set to 'statsname' then the
509    statistics identified by the name is printed.
510
511    Examples:
512                 kamcmd stats.get_statistics all
513                 kamcmd stats.get_statistics core:
514                 kamcmd stats.get_statistics unsupported_methods
515                 kamcmd stats.get_statistics shmem: fwd_requests fwd_replies
516
517 4.9.  stats.reset_statistics
518
519    Reset internal statistics.
520
521    Parameters: statsid - same as for get_statistics.
522
523    Examples:
524                 kamcmd stats.reset_statistics all
525                 kamcmd stats.reset_statistics core:
526                 kamcmd stats.reset_statistics unsupported_methods
527                 kamcmd stats.reset_statistics shmem: fwd_requests fwd_replies
528
529 4.10.  stats.clear_statistics
530
531    Return statistics and reset their value in one command.
532
533    Parameters: statsid - same as for get_statistics.
534
535    Examples:
536                 kamcmd stats.reset_statistics all
537                 kamcmd stats.reset_statistics core:
538                 kamcmd stats.reset_statistics unsupported_methods
539                 kamcmd stats.reset_statistics shmem: fwd_requests fwd_replies
540
541 4.11.  mod.stats module_name/all pkg/shm/all
542
543    Print private(pkg) or shared(shm) memory currently allocated a given
544    module or by all modules.
545
546    NOTE: Processing is done only when the command is issued and involves
547    iterating throug the list of memory fragments and printing details
548    about them.
549
550    NOTE: Only the module functions that directly calls shm_alloc or
551    pkg_alloc are taken into consideration.
552
553    The first parameter can be one of the following:
554      * module_name - print statistics for specific module. Either a module
555        name (like "usrloc") or "core" for the Kamailio core.
556      * all - print statistics for all modules that uses memory.
557
558    The second parameter can be:
559      * pkg - print private (process) memory statistics.
560      * shm - print shared memory statistics.
561      * all - print both private and shared memory statistics.
562
563    Examples:
564                 kamcmd mod.stats core all
565                 kamcmd mod.stats userblacklist shm
566                 kamcmd mod.stats kex pkg
567                 kamcmd mod.stats all all
568
569    Output:
570 Module: kex
571 {
572     // this is the pkg zone of the module
573     // function_name(line_where_pkg_malloc_was_called): size_alloc'ed_by_pkg_mal
574 loc
575     init_rpc_uptime(74): 56
576     Total: 56
577 }
578 {
579     // this is the shm zone of the module
580     // function_name(line_where_shm_malloc_was_called): size_alloc'ed_by_shm_mal
581 loc
582     pkg_proc_stats_init(79): 864
583     Total: 864
584 }