KEx Module

Daniel-Constantin Mierla

   asipto.com
   <miconda@gmail.com>

Ovidiu Sas

   VoIP Embedded, Inc.

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

Ovidiu Sas

   <osas@voipembedded.com.com>

   Copyright © 2009 Daniel-Constantin Mierla

   Copyright © 2014 VoIP Embedded, Inc.
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Functions

              3.1. setsflag(flag)
              3.2. issflagset(flag)
              3.3. resetsflag(flag)
              3.4. setbflag(flag [, branch])
              3.5. isbflagset(flag [, branch])
              3.6. resetbflag(flag [, branch])
              3.7. setdsturi(uri)
              3.8. resetdsturi()
              3.9. isdsturiset()
              3.10. pv_printf(var, str)
              3.11. is_myself(uri)
              3.12. is_myhost(uri)
              3.13. setdebug(level)
              3.14. resetdebug()
              3.15. km_append_branch([uri])

        4. RPC Commands

              4.1. core.aliases_list
              4.2. core.arg
              4.3. core.echo
              4.4. core.flags
              4.5. core.info
              4.6. core.runinfo
              4.7. core.kill
              4.8. core.printi
              4.9. core.prints
              4.10. core.ps
              4.11. core.psx
              4.12. core.pwd
              4.13. core.shmmem
              4.14. core.sockets_list
              4.15. core.tcp_info
              4.16. core.tcp_list
              4.17. core.tcp_options
              4.18. core.udp4_raw_info
              4.19. core.uptime
              4.20. core.version
              4.21. core.ppdefines
              4.22. core.modules
              4.23. modparam.getn
              4.24. modparam.gets
              4.25. modparam.setn
              4.26. modparam.list
              4.27. pkg.stats
              4.28. pkg.info
              4.29. stats.get_statistics
              4.30. stats.fetch
              4.31. stats.fetchn
              4.32. stats.reset_statistics
              4.33. stats.clear_statistics
              4.34. system.listMethods
              4.35. system.methodHelp
              4.36. system.methodSignature
              4.37. mod.mem_stats
              4.38. mod.stats
              4.39. mod.mem_statsx

   List of Examples

   1.1. setsflag usage
   1.2. issflagset usage
   1.3. resetsflag usage
   1.4. setbflag usage
   1.5. isbflagset usage
   1.6. resetbflag usage
   1.7. setdsturi usage
   1.8. resetdsturi usage
   1.9. isdsturiset usage
   1.10. pv_printf usage
   1.11. is_myself usage
   1.12. is_myhost usage
   1.13. setdebug usage
   1.14. resetdebug usage

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Functions

        3.1. setsflag(flag)
        3.2. issflagset(flag)
        3.3. resetsflag(flag)
        3.4. setbflag(flag [, branch])
        3.5. isbflagset(flag [, branch])
        3.6. resetbflag(flag [, branch])
        3.7. setdsturi(uri)
        3.8. resetdsturi()
        3.9. isdsturiset()
        3.10. pv_printf(var, str)
        3.11. is_myself(uri)
        3.12. is_myhost(uri)
        3.13. setdebug(level)
        3.14. resetdebug()
        3.15. km_append_branch([uri])

   4. RPC Commands

        4.1. core.aliases_list
        4.2. core.arg
        4.3. core.echo
        4.4. core.flags
        4.5. core.info
        4.6. core.runinfo
        4.7. core.kill
        4.8. core.printi
        4.9. core.prints
        4.10. core.ps
        4.11. core.psx
        4.12. core.pwd
        4.13. core.shmmem
        4.14. core.sockets_list
        4.15. core.tcp_info
        4.16. core.tcp_list
        4.17. core.tcp_options
        4.18. core.udp4_raw_info
        4.19. core.uptime
        4.20. core.version
        4.21. core.ppdefines
        4.22. core.modules
        4.23. modparam.getn
        4.24. modparam.gets
        4.25. modparam.setn
        4.26. modparam.list
        4.27. pkg.stats
        4.28. pkg.info
        4.29. stats.get_statistics
        4.30. stats.fetch
        4.31. stats.fetchn
        4.32. stats.reset_statistics
        4.33. stats.clear_statistics
        4.34. system.listMethods
        4.35. system.methodHelp
        4.36. system.methodSignature
        4.37. mod.mem_stats
        4.38. mod.stats
        4.39. mod.mem_statsx

1. Overview

   This module collects extensions from Kamailio core.

   Kamailio Core Cookbook is available at:
   https://www.kamailio.org/wikidocs/

2. Dependencies

   2.1. Kamailio Modules
   2.2. External Libraries or Applications

2.1. Kamailio Modules

   The following modules must be loaded before this module:
     * No dependencies on other Kamailio modules.

2.2. External Libraries or Applications

   The following libraries or applications must be installed before
   running Kamailio with this module loaded:
     * None.

3. Functions

   3.1. setsflag(flag)
   3.2. issflagset(flag)
   3.3. resetsflag(flag)
   3.4. setbflag(flag [, branch])
   3.5. isbflagset(flag [, branch])
   3.6. resetbflag(flag [, branch])
   3.7. setdsturi(uri)
   3.8. resetdsturi()
   3.9. isdsturiset()
   3.10. pv_printf(var, str)
   3.11. is_myself(uri)
   3.12. is_myhost(uri)
   3.13. setdebug(level)
   3.14. resetdebug()
   3.15. km_append_branch([uri])

3.1. setsflag(flag)

   Set the script flag.

   Meaning of the parameters is as follows:
     * flag - the index of the script flag to be set. Can be integer or
       pseudo-variable with integer value.

   This function can be used from ANY_ROUTE.

   Example 1.1. setsflag usage
...
setsflag("1");
...
$var(flag) = 11;
setsflag("$var(flag)");
...

3.2. issflagset(flag)

   Return true if the script flag is set.

   Meaning of the parameters is as follows:
     * flag - the index of the script flag to be tested. Can be integer or
       pseudo-variable with integer value.

   This function can be used from ANY_ROUTE.

   Example 1.2. issflagset usage
...
if(issflagset("1"))
{
    ...
}
...

3.3. resetsflag(flag)

   Reset the script flag.

   Meaning of the parameters is as follows:
     * flag - the index of the script flag to be reset. Can be integer or
       pseudo-variable with integer value.

   This function can be used from ANY_ROUTE.

   Example 1.3. resetsflag usage
...
resetsflag("1");
...

3.4. setbflag(flag [, branch])

   Set the branch flag.

   Meaning of the parameters is as follows:
     * flag - the index of the branch flag to be set. Can be integer or
       pseudo-variable with integer value.
     * branch - the index of the branch whose flag to be set. Can be
       integer or pseudo-variable with integer value. If omitted, then
       branch 0 is used (R-URI).

   This function can be used from ANY_ROUTE.

   Example 1.4. setbflag usage
...
setbflag("1");
...
$var(flag) = 11;
setbflag("$var(flag)", "1");
...

3.5. isbflagset(flag [, branch])

   Return true if the branch flag is set.

   Meaning of the parameters is as follows:
     * flag - the index of the branch flag to be tested. Can be integer or
       pseudo-variable with integer value.
     * branch - the index of the branch whose flag to be set. Can be
       integer or pseudo-variable with integer value. If omitted, then
       branch 0 is used (R-URI).

   This function can be used from ANY_ROUTE.

   Example 1.5. isbflagset usage
...
if(isbflagset("1"))
{
    ...
}
...

3.6. resetbflag(flag [, branch])

   Reset the branch flag.

   Meaning of the parameters is as follows:
     * flag - the index of the branch flag to be reset. Can be integer or
       pseudo-variable with integer value.
     * branch - the index of the branch whose flag to be set. Can be
       integer or pseudo-variable with integer value. If omitted, then
       branch 0 is used (R-URI).

   This function can be used from ANY_ROUTE.

   Example 1.6. resetbflag usage
...
resetbflag("1");
...

3.7. setdsturi(uri)

   Set the destination address URI (outbound proxy address).

   Meaning of the parameters is as follows:
     * uri - Valid SIP URI representing the address where to send the
       request. It must be a static string, no variables are evaluated at
       runtime. If you need to set outbound proxy address via a variable,
       use assignment to $du.

   This function can be used from ANY_ROUTE.

   Example 1.7. setdsturi usage
...
setdsturi("sip:10.0.0.10");
...

3.8. resetdsturi()

   Reset the destination address URI (outbound proxy address).

   This function can be used from ANY_ROUTE.

   Example 1.8. resetdsturi usage
...
resetdsturi();
...

3.9. isdsturiset()

   Check if the destination address URI (outbound proxy address) is set.

   This function can be used from ANY_ROUTE.

   Example 1.9. isdsturiset usage
...
if(isdsturiset())
{
   ...
}
...

3.10. pv_printf(var, str)

   Evaluates the str and sets the resulting value to variable var. For
   backward compatibility reasons, the same function can be executed via
   'avp_printf(var, str)'.

   Meaning of the parameters is as follows:
     * var - name of a writable variable
     * str - string that may contain variables which will be evaluated at
       runtime.

   This function can be used from ANY_ROUTE.

   Example 1.10. pv_printf usage
...
pv_printf("$ru", "sip:$rU@$fd");
pv_printf("$avp(x)", "From: $fU - To: $tU");
...

3.11. is_myself(uri)

   Check if the parameter matches the 'myself' condition (i.e., is a local
   IP or domain). Note that if the port is missing in the URI, then no
   port matching is done (in other words, port matching is skipped -- it
   does not use default SIP ports 5060 or 5061 for matching).

   Meaning of the parameters is as follows:
     * uri - Valid SIP URI or IP address to check against the list of
       local IP addresses or domains, matching as well the port and
       protocol if they are provided. The parameter value can contain
       pseudo-variables.

   This function can be used from ANY_ROUTE.

   Example 1.11. is_myself usage
...
if(is_myself("$fu")) {
    ...
}
...

3.12. is_myhost(uri)

   Check if the host part of the parameter matches a local domain or IP
   address.

   Meaning of the parameters is as follows:
     * uri - Valid SIP URI, hostname of IP address to check against the
       list of local IP addresses or domains. If it is a SIP URI, the port
       and protocol are ignored. The parameter value can contain
       pseudo-variables.

   This function can be used from ANY_ROUTE.

   Example 1.12. is_myhost usage
...
if(is_myhost("$tu")) {
    ...
}
...

3.13. setdebug(level)

   Set the debug log level per process.

   Meaning of the parameters is as follows:
     * level - the debug log level to be set. Can be integer or
       pseudo-variable with integer value.

   This function can be used from ANY_ROUTE.

   Example 1.13. setdebug usage
...
setdebug("1");
...
$var(level) = 2;
setdebug("$var(level)");
...

3.14. resetdebug()

   Reset the local debug log level back to the value of core parameter
   'debug'.

   This function can be used from ANY_ROUTE.

   Example 1.14. resetdebug usage
...
resetdebug();
...

3.15. km_append_branch([uri])

   This function was replaced by append_branch() from corex module,
   starting with version 4.0.0.

4. RPC Commands

   4.1. core.aliases_list
   4.2. core.arg
   4.3. core.echo
   4.4. core.flags
   4.5. core.info
   4.6. core.runinfo
   4.7. core.kill
   4.8. core.printi
   4.9. core.prints
   4.10. core.ps
   4.11. core.psx
   4.12. core.pwd
   4.13. core.shmmem
   4.14. core.sockets_list
   4.15. core.tcp_info
   4.16. core.tcp_list
   4.17. core.tcp_options
   4.18. core.udp4_raw_info
   4.19. core.uptime
   4.20. core.version
   4.21. core.ppdefines
   4.22. core.modules
   4.23. modparam.getn
   4.24. modparam.gets
   4.25. modparam.setn
   4.26. modparam.list
   4.27. pkg.stats
   4.28. pkg.info
   4.29. stats.get_statistics
   4.30. stats.fetch
   4.31. stats.fetchn
   4.32. stats.reset_statistics
   4.33. stats.clear_statistics
   4.34. system.listMethods
   4.35. system.methodHelp
   4.36. system.methodSignature
   4.37. mod.mem_stats
   4.38. mod.stats
   4.39. mod.mem_statsx

4.1.  core.aliases_list

   Returns the list of local SIP server host aliases.

4.2.  core.arg

   Print command line arguments.

   Name: core.arg

   Parameters: none.

   RPC Command Format:
...
kamctl rpc core.arg
...

4.3.  core.echo

   Returns back its parameters.

4.4.  core.flags

   Returns the compile flags.

4.5.  core.info

   Verbose info, including version number, compile flags, compiler,
   repository, hash

4.6.  core.runinfo

   Runtime details like running version, uptime, ...

4.7.  core.kill

   Kill the application.

   Name: core.kill

   Parameters: none.

   RPC Command Format:
...
kamctl rpc core.kill
...

4.8.  core.printi

   Returns the integers given as parameters.

4.9.  core.prints

   Returns the strings given as parameters.

4.10.  core.ps

   Returns the description of running processes.

4.11.  core.psx

   Returns the detailed description of running processes.

4.12.  core.pwd

   Print working directory.

   Name: core.pwd

   Parameters: none.

   RPC Command Format:
...
kamctl rpc core.pwd
...

4.13.  core.shmmem

   Returns shared memory info. It has an optional parameter that specifies
   the measuring unit: b - bytes (default), k or kb, m or mb, g or gb.
   Note: when using something different from bytes, the value is
   truncated.

4.14.  core.sockets_list

   Returns the list of local SIP server listen sockets.

4.15.  core.tcp_info

   Returns TCP related info.

4.16.  core.tcp_list

   Returns TCP connections details.

4.17.  core.tcp_options

   Returns active TCP options.

4.18.  core.udp4_raw_info

   Returns udp4_raw mode related info.

4.19.  core.uptime

   Print uptime.

   Name: core.uptime

   Parameters: none.

   RPC Command Format:
...
kamctl rpc core.uptime
...

4.20.  core.version

   Print version information.

   Name: core.version

   Parameters: none.

   RPC Command Format:
...
kamctl rpc core.version
...

4.21.  core.ppdefines

   List preprocessor defines enabled in config.

   Name: core.ppdefines

   Parameters: none.

   RPC Command Format:
...
kamctl rpc core.ppdefines
...

4.22.  core.modules

   List loaded modules in config.

   Name: core.modules

   Parameters: none.

   RPC Command Format:
...
kamctl rpc core.modules
...

4.23.  modparam.getn

   Get the value of a module parameter with integer value.

   Name: modparam.getn

   Parameters: module_name and parameter_name.

   RPC Command Format:
...
kamcli rpc modparam.getn tls keylog_mode
...

4.24.  modparam.gets

   Get the value of a module parameter with string value.

   Name: modparam.gets

   Parameters: module_name and parameter_name.

   RPC Command Format:
...
kamcli rpc modparam.gets tls config
...

4.25.  modparam.setn

   Set the value of a module parameter with integer value stored in shared
   memory.

   Name: modparam.setn

   Parameters: module_name, parameter_name and value.

   RPC Command Format:
...
kamcli rpc modparam.setn tls keylog_mode 15
...

4.26.  modparam.list

   List the parameters of the loaded modules.

   Name: modparam.list

   Parameters: module_name (optional).

   RPC Command Format:
...
kamcli rpc modparam.list
kamcli rpc modparam.list tls
...

4.27.  pkg.stats

   Print private memory (pkg) usage statistics per process. It can take
   optionally a filter to print statistics only for a specific process or
   set of processes. If no filter is given, it prints statistics for all
   processes.

   The filter can be:
     * pid value - print statistics for specific process pid.
     * rank value - print statistics for specific process rank.
     * index value - print statistics for specific index in process table.

   Examples:
                kamctl rpc pkg.stats
                kamctl rpc pkg.stats pid 1234
                kamctl rpc pkg.stats rank 1
                kamctl rpc pkg.stats index 10

4.28.  pkg.info

   Get pkg manager details.

   Example:
                kamcli rpc pkg.info

4.29.  stats.get_statistics

   Print the list of available internal statistics.

   NOTE: the result is an array of strings that have the list of
   statistics formatted like "name = value", being propagated over the
   time from the MI variant. Use "stats.fetch" or "stats.fetchn"commands
   to have a more JSON-friendly output.

   Parameters: statsid - which statistics to be printed. If set to 'all'
   then all statistics are printed; if set to 'statsgroup:' then all
   statistics in the group are printed; if set to 'statsname' then the
   statistics identified by the name is printed.

   Examples:
                kamctl rpc stats.get_statistics all
                kamctl rpc stats.get_statistics core:
                kamctl rpc stats.get_statistics unsupported_methods
                kamctl rpc stats.get_statistics shmem: fwd_requests fwd_replies

4.30.  stats.fetch

   Print the list of available internal statistics with a more json
   friendly output. Each printed statistic is a field in the output
   structure: {"statsgroup.statsname" : "statsvalue"}. The value is
   represented as string to accommodate large numbers.

   Parameters: statsid - which statistics to be printed. If set to 'all'
   then all statistics are printed; if set to 'statsgroup:' then all
   statistics in the group are printed; if set to 'statsname' then the
   statistics identified by the name is printed (can be also
   'statsgroup.stastname' or 'statsgroup:statsname').

   Examples:
                kamctl rpc stats.fetch all
                kamctl rpc stats.fetch core:
                kamctl rpc stats.fetch unsupported_methods
                kamctl rpc stats.fetch shmem.free_size
                kamctl rpc stats.fetch shmem: fwd_requests fwd_replies

4.31.  stats.fetchn

   Print the list of available internal statistics with a more json
   friendly output. Each printed statistic is a field in the output
   structure: {"statsgroup.statsname" : statsvalue}. The value is
   represented as number.

   Parameters: statsid - which statistics to be printed. If set to 'all'
   then all statistics are printed; if set to 'statsgroup:' then all
   statistics in the group are printed; if set to 'statsname' then the
   statistics identified by the name is printed (can be also
   'statsgroup.stastname' or 'statsgroup:statsname').

   Examples:
                kamctl rpc stats.fetchn all
                kamctl rpc stats.fetchn core:
                kamctl rpc stats.fetchn unsupported_methods
                kamctl rpc stats.fetchn shmem.free_size
                kamctl rpc stats.fetchn shmem: fwd_requests fwd_replies

4.32.  stats.reset_statistics

   Reset internal statistics.

   Parameters: statsid - same as for get_statistics.

   Examples:
                kamctl rpc stats.reset_statistics all
                kamctl rpc stats.reset_statistics core:
                kamctl rpc stats.reset_statistics unsupported_methods
                kamctl rpc stats.reset_statistics shmem: fwd_requests fwd_replie
s

4.33.  stats.clear_statistics

   Return statistics and reset their value in one command.

   Parameters: statsid - same as for get_statistics.

   Examples:
                kamctl rpc stats.reset_statistics all
                kamctl rpc stats.reset_statistics core:
                kamctl rpc stats.reset_statistics unsupported_methods
                kamctl rpc stats.reset_statistics shmem: fwd_requests fwd_replie
s

4.34.  system.listMethods

   Print list of available RPC commands.

   Name: system.listMethods

   Parameters: none.

   RPC Command Format:
...
kamctl rpc system.listMethods
...

4.35.  system.methodHelp

   Print the help string for given method.

4.36.  system.methodSignature

   Returns signature of given method.

4.37.  mod.mem_stats

   Print private(pkg) or shared(shm) memory currently allocated a given
   module or by all modules.

   NOTE: Processing is done only when the command is issued and involves
   iterating through the list of memory fragments and printing details
   about them.

   NOTE: Only the module functions that directly calls shm_alloc or
   pkg_alloc are taken into consideration.

   The first parameter can be one of the following:
     * module_name - print statistics for specific module. Either a module
       name (like "usrloc") or "core" for the Kamailio core.
     * all - print statistics for all modules that uses memory.

   The second parameter can be:
     * pkg - print private (process) memory statistics.
     * shm - print shared memory statistics.
     * all - print both private and shared memory statistics.

   Examples:
                kamctl rpc mod.stats core all
                kamctl rpc mod.stats tm shm
                kamctl rpc mod.stats kex pkg
                kamctl rpc mod.stats all all

   Output:
Module: kex
{
    // this is the pkg zone of the module
    // function_name(line_where_pkg_malloc_was_called): size_alloc'ed_by_pkg_mal
loc
    init_rpc_uptime(74): 56
    Total: 56
}
{
    // this is the shm zone of the module
    // function_name(line_where_shm_malloc_was_called): size_alloc'ed_by_shm_mal
loc
    pkg_proc_stats_init(79): 864
    Total: 864
}

4.38.  mod.stats

   Same as RPC command "mod.mem_stats", this is an alias command to
   preserve backward compatibility.

4.39.  mod.mem_statsx

   Similar to RPC command "mod.mem_stats", but the output has an extended
   format, printing info that includes the allocated size and the count of
   allocated chunks in a combined string value. The parameters are the
   same like for "mod.mem_stats".
