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