1KEx Module
2
3Daniel-Constantin Mierla
4
5 asipto.com
6 <miconda@gmail.com>
7
8Ovidiu Sas
9
10 VoIP Embedded, Inc.
11
12Edited by
13
14Daniel-Constantin Mierla
15
16 <miconda@gmail.com>
17
18Ovidiu Sas
19
20 <osas@voipembedded.com.com>
21
22 Copyright © 2009 Daniel-Constantin Mierla
23
24 Copyright © 2014 VoIP Embedded, Inc.
25 __________________________________________________________________
26
27 Table of Contents
28
29 1. Admin Guide
30
31 1. Overview
32 2. Dependencies
33
34 2.1. Kamailio Modules
35 2.2. External Libraries or Applications
36
37 3. Functions
38
39 3.1. setsflag(flag)
40 3.2. issflagset(flag)
41 3.3. resetsflag(flag)
42 3.4. setbflag(flag [, branch])
43 3.5. isbflagset(flag [, branch])
44 3.6. resetbflag(flag [, branch])
45 3.7. setdsturi(uri)
46 3.8. resetdsturi()
47 3.9. isdsturiset()
48 3.10. pv_printf(var, str)
49 3.11. is_myself(uri)
50 3.12. setdebug(level)
51 3.13. resetdebug()
52 3.14. km_append_branch([uri])
53
54 4. RPC Commands
55
56 4.1. core.aliases_list
57 4.2. core.arg
58 4.3. core.echo
59 4.4. core.flags
60 4.5. core.info
61 4.6. core.kill
62 4.7. core.printi
63 4.8. core.prints
64 4.9. core.ps
65 4.10. core.psx
66 4.11. core.pwd
67 4.12. core.shmmem
68 4.13. core.sockets_list
69 4.14. core.tcp_info
70 4.15. core.tcp_list
71 4.16. core.tcp_options
72 4.17. core.udp4_raw_info
73 4.18. core.uptime
74 4.19. core.version
75 4.20. core.ppdefines
76 4.21. core.modules
77 4.22. pkg.stats
78 4.23. stats.get_statistics
79 4.24. stats.fetch
80 4.25. stats.fetchn
81 4.26. stats.reset_statistics
82 4.27. stats.clear_statistics
83 4.28. system.listMethods
84 4.29. system.methodHelp
85 4.30. system.methodSignature
86 4.31. mod.mem_stats
87 4.32. mod.stats
88 4.33. mod.mem_statsx
89
90 List of Examples
91
92 1.1. setsflag usage
93 1.2. issflagset usage
94 1.3. resetsflag usage
95 1.4. setbflag usage
96 1.5. isbflagset usage
97 1.6. resetbflag usage
98 1.7. setdsturi usage
99 1.8. resetdsturi usage
100 1.9. isdsturiset usage
101 1.10. pv_printf usage
102 1.11. is_myself usage
103 1.12. setdebug usage
104 1.13. resetdebug usage
105
106Chapter 1. Admin Guide
107
108 Table of Contents
109
110 1. Overview
111 2. Dependencies
112
113 2.1. Kamailio Modules
114 2.2. External Libraries or Applications
115
116 3. Functions
117
118 3.1. setsflag(flag)
119 3.2. issflagset(flag)
120 3.3. resetsflag(flag)
121 3.4. setbflag(flag [, branch])
122 3.5. isbflagset(flag [, branch])
123 3.6. resetbflag(flag [, branch])
124 3.7. setdsturi(uri)
125 3.8. resetdsturi()
126 3.9. isdsturiset()
127 3.10. pv_printf(var, str)
128 3.11. is_myself(uri)
129 3.12. setdebug(level)
130 3.13. resetdebug()
131 3.14. km_append_branch([uri])
132
133 4. RPC Commands
134
135 4.1. core.aliases_list
136 4.2. core.arg
137 4.3. core.echo
138 4.4. core.flags
139 4.5. core.info
140 4.6. core.kill
141 4.7. core.printi
142 4.8. core.prints
143 4.9. core.ps
144 4.10. core.psx
145 4.11. core.pwd
146 4.12. core.shmmem
147 4.13. core.sockets_list
148 4.14. core.tcp_info
149 4.15. core.tcp_list
150 4.16. core.tcp_options
151 4.17. core.udp4_raw_info
152 4.18. core.uptime
153 4.19. core.version
154 4.20. core.ppdefines
155 4.21. core.modules
156 4.22. pkg.stats
157 4.23. stats.get_statistics
158 4.24. stats.fetch
159 4.25. stats.fetchn
160 4.26. stats.reset_statistics
161 4.27. stats.clear_statistics
162 4.28. system.listMethods
163 4.29. system.methodHelp
164 4.30. system.methodSignature
165 4.31. mod.mem_stats
166 4.32. mod.stats
167 4.33. mod.mem_statsx
168
1691. Overview
170
171 This module collects extensions from Kamailio core.
172
173 Kamailio Core Cookbook is available at: https://www.kamailio.org/wiki/
174
1752. Dependencies
176
177 2.1. Kamailio Modules
178 2.2. External Libraries or Applications
179
1802.1. Kamailio Modules
181
182 The following modules must be loaded before this module:
183 * No dependencies on other Kamailio modules.
184
1852.2. External Libraries or Applications
186
187 The following libraries or applications must be installed before
188 running Kamailio with this module loaded:
189 * None.
190
1913. Functions
192
193 3.1. setsflag(flag)
194 3.2. issflagset(flag)
195 3.3. resetsflag(flag)
196 3.4. setbflag(flag [, branch])
197 3.5. isbflagset(flag [, branch])
198 3.6. resetbflag(flag [, branch])
199 3.7. setdsturi(uri)
200 3.8. resetdsturi()
201 3.9. isdsturiset()
202 3.10. pv_printf(var, str)
203 3.11. is_myself(uri)
204 3.12. setdebug(level)
205 3.13. resetdebug()
206 3.14. km_append_branch([uri])
207
2083.1. setsflag(flag)
209
210 Set the script flag.
211
212 Meaning of the parameters is as follows:
213 * flag - the index of the script flag to be set. Can be integer or
214 pseudo-variable with integer value.
215
216 This function can be used from ANY_ROUTE.
217
218 Example 1.1. setsflag usage
219...
220setsflag("1");
221...
222$var(flag) = 11;
223setsflag("$var(flag)");
224...
225
2263.2. issflagset(flag)
227
228 Return true of the script flag is set.
229
230 Meaning of the parameters is as follows:
231 * flag - the index of the script flag to be tested. Can be integer or
232 pseudo-variable with integer value.
233
234 This function can be used from ANY_ROUTE.
235
236 Example 1.2. issflagset usage
237...
238if(issflagset("1"))
239{
240 ...
241}
242...
243
2443.3. resetsflag(flag)
245
246 Reset the script flag.
247
248 Meaning of the parameters is as follows:
249 * flag - the index of the script flag to be reset. Can be integer or
250 pseudo-variable with integer value.
251
252 This function can be used from ANY_ROUTE.
253
254 Example 1.3. resetsflag usage
255...
256resetsflag("1");
257...
258
2593.4. setbflag(flag [, branch])
260
261 Set the branch flag.
262
263 Meaning of the parameters is as follows:
264 * flag - the index of the branch flag to be set. 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.4. setbflag usage
273...
274setbflag("1");
275...
276$var(flag) = 11;
277setbflag("$var(flag)", "1");
278...
279
2803.5. isbflagset(flag [, branch])
281
282 Return true of the branch flag is set.
283
284 Meaning of the parameters is as follows:
285 * flag - the index of the branch flag to be tested. Can be integer or
286 pseudo-variable with integer value.
287 * branch - the index of the branch whose flag to be set. Can be
288 integer or pseudo-variable with integer value. If omitted, then
289 branch 0 is used (R-URI).
290
291 This function can be used from ANY_ROUTE.
292
293 Example 1.5. isbflagset usage
294...
295if(isbflagset("1"))
296{
297 ...
298}
299...
300
3013.6. resetbflag(flag [, branch])
302
303 Reset the branch flag.
304
305 Meaning of the parameters is as follows:
306 * flag - the index of the branch flag to be reset. Can be integer or
307 pseudo-variable with integer value.
308 * branch - the index of the branch whose flag to be set. Can be
309 integer or pseudo-variable with integer value. If omitted, then
310 branch 0 is used (R-URI).
311
312 This function can be used from ANY_ROUTE.
313
314 Example 1.6. resetbflag usage
315...
316resetbflag("1");
317...
318
3193.7. setdsturi(uri)
320
321 Set the destination address URI (outbound proxy address).
322
323 Meaning of the parameters is as follows:
324 * uri - Valid SIP URI representing the address where to send the
325 request. It must be a static string, no variables are evaluated at
326 runtime. If you need to set outbound proxy address via a variable,
327 use assignment to $du.
328
329 This function can be used from ANY_ROUTE.
330
331 Example 1.7. setdsturi usage
332...
333setdsturi("sip:10.0.0.10");
334...
335
3363.8. resetdsturi()
337
338 Reset the destination address URI (outbound proxy address).
339
340 This function can be used from ANY_ROUTE.
341
342 Example 1.8. resetdsturi usage
343...
344resetdsturi();
345...
346
3473.9. isdsturiset()
348
349 Check if the destination address URI (outbound proxy address) is set.
350
351 This function can be used from ANY_ROUTE.
352
353 Example 1.9. isdsturiset usage
354...
355if(isdsturiset())
356{
357 ...
358}
359...
360
3613.10. pv_printf(var, str)
362
363 Evaluates the str and sets the resulting value to variable var. For
364 backward compatibility reasons, the same function can be executed via
365 'avp_printf(var, str)'.
366
367 Meaning of the parameters is as follows:
368 * var - name of a writable variable
369 * str - string that may contain variables which will be evaluated at
370 runtime.
371
372 This function can be used from ANY_ROUTE.
373
374 Example 1.10. pv_printf usage
375...
376pv_printf("$ru", "sip:$rU@$fd");
377pv_printf("$avp(x)", "From: $fU - To: $tU");
378...
379
3803.11. is_myself(uri)
381
382 Check if the parameter matches the 'myself' condition (i.e., is a local
383 IP or domain). Note that if the port is missing in the URI, then no
384 port matching is done (in other words, port matching is skipped -- it
385 does not use default SIP ports 5060 or 5061 for matching).
386
387 Meaning of the parameters is as follows:
388 * uri - Valid SIP URI or IP address to check against the list of
389 local IP addresses or domains. The parameter value can contain
390 pseudo-variables.
391
392 This function can be used from ANY_ROUTE.
393
394 Example 1.11. is_myself usage
395...
396if(is_myself("$fu")) {
397 ...
398}
399...
400
4013.12. setdebug(level)
402
403 Set the debug log level per process.
404
405 Meaning of the parameters is as follows:
406 * level - the debug log level to be set. Can be integer or
407 pseudo-variable with integer value.
408
409 This function can be used from ANY_ROUTE.
410
411 Example 1.12. setdebug usage
412...
413setdebug("1");
414...
415$var(level) = 2;
416setdebug("$var(level)");
417...
418
4193.13. resetdebug()
420
421 Reset the local debug log level back to the value of core parameter
422 'debug'.
423
424 This function can be used from ANY_ROUTE.
425
426 Example 1.13. resetdebug usage
427...
428resetdebug();
429...
430
4313.14. km_append_branch([uri])
432
433 This function was replaced by append_branch() from corex module,
434 starting with version 4.0.0.
435
4364. RPC Commands
437
438 4.1. core.aliases_list
439 4.2. core.arg
440 4.3. core.echo
441 4.4. core.flags
442 4.5. core.info
443 4.6. core.kill
444 4.7. core.printi
445 4.8. core.prints
446 4.9. core.ps
447 4.10. core.psx
448 4.11. core.pwd
449 4.12. core.shmmem
450 4.13. core.sockets_list
451 4.14. core.tcp_info
452 4.15. core.tcp_list
453 4.16. core.tcp_options
454 4.17. core.udp4_raw_info
455 4.18. core.uptime
456 4.19. core.version
457 4.20. core.ppdefines
458 4.21. core.modules
459 4.22. pkg.stats
460 4.23. stats.get_statistics
461 4.24. stats.fetch
462 4.25. stats.fetchn
463 4.26. stats.reset_statistics
464 4.27. stats.clear_statistics
465 4.28. system.listMethods
466 4.29. system.methodHelp
467 4.30. system.methodSignature
468 4.31. mod.mem_stats
469 4.32. mod.stats
470 4.33. mod.mem_statsx
471
4724.1. core.aliases_list
473
474 Returns the list of local SIP server host aliases.
475
4764.2. core.arg
477
478 Print command line arguments.
479
480 Name: core.arg
481
482 Parameters: none.
483
484 RPC Command Format:
485...
486kamcmd core.arg
487...
488
4894.3. core.echo
490
491 Returns back its parameters.
492
4934.4. core.flags
494
495 Returns the compile flags.
496
4974.5. core.info
498
499 Verbose info, including version number, compile flags, compiler,
500 repository, hash
501
5024.6. core.kill
503
504 Kill the application.
505
506 Name: core.kill
507
508 Parameters: none.
509
510 RPC Command Format:
511...
512kamcmd core.kill
513...
514
5154.7. core.printi
516
517 Returns the integers given as parameters.
518
5194.8. core.prints
520
521 Returns the strings given as parameters.
522
5234.9. core.ps
524
525 Returns the description of running processes.
526
5274.10. core.psx
528
529 Returns the detailed description of running processes.
530
5314.11. core.pwd
532
533 Print working directory.
534
535 Name: core.pwd
536
537 Parameters: none.
538
539 RPC Command Format:
540...
541kamcmd core.pwd
542...
543
5444.12. core.shmmem
545
546 Returns shared memory info. It has an optional parameter that specifies
547 the measuring unit: b - bytes (default), k or kb, m or mb, g or gb.
548 Note: when using something different from bytes, the value is
549 truncated.
550
5514.13. core.sockets_list
552
553 Returns the list of local SIP server listen sockets.
554
5554.14. core.tcp_info
556
557 Returns TCP related info.
558
5594.15. core.tcp_list
560
561 Returns TCP connections details.
562
5634.16. core.tcp_options
564
565 Returns active TCP options.
566
5674.17. core.udp4_raw_info
568
569 Returns udp4_raw mode related info.
570
5714.18. core.uptime
572
573 Print uptime.
574
575 Name: core.uptime
576
577 Parameters: none.
578
579 RPC Command Format:
580...
581kamcmd core.uptime
582...
583
5844.19. core.version
585
586 Print version information.
587
588 Name: core.version
589
590 Parameters: none.
591
592 RPC Command Format:
593...
594kamcmd core.version
595...
596
5974.20. core.ppdefines
598
599 List preprocessor defines enabled in config.
600
601 Name: core.ppdefines
602
603 Parameters: none.
604
605 RPC Command Format:
606...
607kamcmd core.ppdefines
608...
609
6104.21. core.modules
611
612 List loaded modules in config.
613
614 Name: core.modules
615
616 Parameters: none.
617
618 RPC Command Format:
619...
620kamcmd core.modules
621...
622
6234.22. pkg.stats
624
625 Print private memory (pkg) usage statistics per process. It can take
626 optionally a filter to print statistics only for a specific process or
627 set of processes. If no filter is given, it prints statistics for all
628 processes.
629
630 The filter can be:
631 * pid value - print statistics for specific process pid.
632 * rank value - print statistics for specific process rank.
633 * index value - print statistics for specific index in process table.
634
635 Examples:
636 kamcmd pkg.stats
637 kamcmd pkg.stats pid 1234
638 kamcmd pkg.stats rank 1
639 kamcmd pkg.stats index 10
640
6414.23. stats.get_statistics
642
643 Print the list of available internal statistics.
644
645 NOTE: the result is an array of strings that have the list of
646 statistics formated like "name = value", being propagated over the time
647 from the MI variant. Use "stats.fetch" or "stats.fetchn"commands to
648 have a more JSON-friendly output.
649
650 Parameters: statsid - which statistics to be printed. If set to 'all'
651 then all statistics are printed; if set to 'statsgroup:' then all
652 statistics in the group are printed; if set to 'statsname' then the
653 statistics identified by the name is printed.
654
655 Examples:
656 kamcmd stats.get_statistics all
657 kamcmd stats.get_statistics core:
658 kamcmd stats.get_statistics unsupported_methods
659 kamcmd stats.get_statistics shmem: fwd_requests fwd_replies
660
6614.24. stats.fetch
662
663 Print the list of available internal statistics with a more json
664 friendly output. Each printed statistic is a field in the output
665 structure: {"statsgroup.statsname" : "statsvalue"}. The value is
666 represented as string to accomodate large numbers.
667
668 Parameters: statsid - which statistics to be printed. If set to 'all'
669 then all statistics are printed; if set to 'statsgroup:' then all
670 statistics in the group are printed; if set to 'statsname' then the
671 statistics identified by the name is printed (can be also
672 'statsgroup.stastname' or 'statsgroup:statsname').
673
674 Examples:
675 kamcmd stats.fetch all
676 kamcmd stats.fetch core:
677 kamcmd stats.fetch unsupported_methods
678 kamcmd stats.fetch shmem.free_size
679 kamcmd stats.fetch shmem: fwd_requests fwd_replies
680
6814.25. stats.fetchn
682
683 Print the list of available internal statistics with a more json
684 friendly output. Each printed statistic is a field in the output
685 structure: {"statsgroup.statsname" : statsvalue}. The value is
686 represented as number.
687
688 Parameters: statsid - which statistics to be printed. If set to 'all'
689 then all statistics are printed; if set to 'statsgroup:' then all
690 statistics in the group are printed; if set to 'statsname' then the
691 statistics identified by the name is printed (can be also
692 'statsgroup.stastname' or 'statsgroup:statsname').
693
694 Examples:
695 kamcmd stats.fetchn all
696 kamcmd stats.fetchn core:
697 kamcmd stats.fetchn unsupported_methods
698 kamcmd stats.fetchn shmem.free_size
699 kamcmd stats.fetchn shmem: fwd_requests fwd_replies
700
7014.26. stats.reset_statistics
702
703 Reset internal statistics.
704
705 Parameters: statsid - same as for get_statistics.
706
707 Examples:
708 kamcmd stats.reset_statistics all
709 kamcmd stats.reset_statistics core:
710 kamcmd stats.reset_statistics unsupported_methods
711 kamcmd stats.reset_statistics shmem: fwd_requests fwd_replies
712
7134.27. stats.clear_statistics
714
715 Return statistics and reset their value in one command.
716
717 Parameters: statsid - same as for get_statistics.
718
719 Examples:
720 kamcmd stats.reset_statistics all
721 kamcmd stats.reset_statistics core:
722 kamcmd stats.reset_statistics unsupported_methods
723 kamcmd stats.reset_statistics shmem: fwd_requests fwd_replies
724
7254.28. system.listMethods
726
727 Print list of available RPC commands.
728
729 Name: system.listMethods
730
731 Parameters: none.
732
733 RPC Command Format:
734...
735kamcmd system.listMethods
736...
737
7384.29. system.methodHelp
739
740 Print the help string for given method.
741
7424.30. system.methodSignature
743
744 Returns signature of given method.
745
7464.31. mod.mem_stats
747
748 Print private(pkg) or shared(shm) memory currently allocated a given
749 module or by all modules.
750
751 NOTE: Processing is done only when the command is issued and involves
752 iterating through the list of memory fragments and printing details
753 about them.
754
755 NOTE: Only the module functions that directly calls shm_alloc or
756 pkg_alloc are taken into consideration.
757
758 The first parameter can be one of the following:
759 * module_name - print statistics for specific module. Either a module
760 name (like "usrloc") or "core" for the Kamailio core.
761 * all - print statistics for all modules that uses memory.
762
763 The second parameter can be:
764 * pkg - print private (process) memory statistics.
765 * shm - print shared memory statistics.
766 * all - print both private and shared memory statistics.
767
768 Examples:
769 kamcmd mod.stats core all
770 kamcmd mod.stats userblacklist shm
771 kamcmd mod.stats kex pkg
772 kamcmd mod.stats all all
773
774 Output:
775Module: kex
776{
777 // this is the pkg zone of the module
778 // function_name(line_where_pkg_malloc_was_called): size_alloc'ed_by_pkg_mal
779loc
780 init_rpc_uptime(74): 56
781 Total: 56
782}
783{
784 // this is the shm zone of the module
785 // function_name(line_where_shm_malloc_was_called): size_alloc'ed_by_shm_mal
786loc
787 pkg_proc_stats_init(79): 864
788 Total: 864
789}
790
7914.32. mod.stats
792
793 Same as RPC command "mod.mem_stats", this is an alias command to
794 preserve backward compatibility.
795
7964.33. mod.mem_statsx
797
798 Similar to RPC command "mod.mem_stats", but the output has an extended
799 format, printing info that includes the allocated size and the count of
800 allocated chunks in a combined string value. The parameters are the
801 same like for "mod.mem_stats".
802