KEx Module

Daniel-Constantin Mierla

   asipto.com
   <miconda@gmail.com>

Ovidiu Sas

   VoIP Embedded, Inc.

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

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. setdebug(level)
              3.13. resetdebug()
              3.14. km_append_branch([uri])

        4. MI Commands

              4.1. arg
              4.2. kill
              4.3. pwd
              4.4. uptime
              4.5. version
              4.6. which
              4.7. get_statistics
              4.8. reset_statistics
              4.9. clear_statistics

        5. RPC Commands

              5.1. pkg.stats
              5.2. stats.get_statistics
              5.3. stats.reset_statistics
              5.4. stats.clear_statistics
              5.5. mod.stats module_name/all pkg/shm/all

   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. setdebug usage
   1.13. 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. setdebug(level)
        3.13. resetdebug()
        3.14. km_append_branch([uri])

   4. MI Commands

        4.1. arg
        4.2. kill
        4.3. pwd
        4.4. uptime
        4.5. version
        4.6. which
        4.7. get_statistics
        4.8. reset_statistics
        4.9. clear_statistics

   5. RPC Commands

        5.1. pkg.stats
        5.2. stats.get_statistics
        5.3. stats.reset_statistics
        5.4. stats.clear_statistics
        5.5. mod.stats module_name/all pkg/shm/all

1. Overview

   This module collects extensions from Kamailio core.

   Kamailio Core CookBook is available at: http://kamailio.org/dokuwiki/

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. setdebug(level)
   3.13. resetdebug()
   3.14. 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 of 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 of 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 assginment 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)

   Evalues 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).

   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. 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. 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.12. setdebug usage
...
setdebug("1");
...
$var(level) = 2;
setdebug("$var(level)");
...

3.13. 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.13. resetdebug usage
...
resetdebug();
...

3.14. km_append_branch([uri])

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

4. MI Commands

   4.1. arg
   4.2. kill
   4.3. pwd
   4.4. uptime
   4.5. version
   4.6. which
   4.7. get_statistics
   4.8. reset_statistics
   4.9. clear_statistics

4.1.  arg

   Print command line arguments.

   Name: arg

   Parameters: none.

   MI FIFO Command Format:
                :arg:_reply_fifo_file_
                _empty_line_

4.2.  kill

   Kill the application.

   Name: kill

   Parameters: none.

   MI FIFO Command Format:
                :kill:_reply_fifo_file_
                _empty_line_

4.3.  pwd

   Print working directory.

   Name: pwd

   Parameters: none.

   MI FIFO Command Format:
                :pwd:_reply_fifo_file_
                _empty_line_

4.4.  uptime

   Print uptime.

   Name: uptime

   Parameters: none.

   MI FIFO Command Format:
                :uptime:_reply_fifo_file_
                _empty_line_

4.5.  version

   Print version information.

   Name: version

   Parameters: none.

   MI FIFO Command Format:
                :version:_reply_fifo_file_
                _empty_line_

4.6.  which

   Print list of available MI commands.

   Name: which

   Parameters: none.

   MI FIFO Command Format:
                :which:_reply_fifo_file_
                _empty_line_

4.7.  get_statistics

   Print the list of available internal statistics.

   Name: get_statistics

   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.

   MI FIFO Command Format:
                :get_statistics:_reply_fifo_file_
                _statsid_
                _empty_line_

4.8.  reset_statistics

   Reset internal statistics.

   Name: reset_statistics

   Parameters: statsid - which statistics to be reset, give as name.

   MI FIFO Command Format:
                :reset_statistics:_reply_fifo_file_
                _statsid_
                _empty_line_

4.9.  clear_statistics

   Return statistics and reset their value in one command.

   Name: get_statistics

   Parameters: statsid - same as for get_statistics.

   MI FIFO Command Format:
                :clear_statistics:_reply_fifo_file_
                _statsid_
                _empty_line_

5. RPC Commands

   5.1. pkg.stats
   5.2. stats.get_statistics
   5.3. stats.reset_statistics
   5.4. stats.clear_statistics
   5.5. mod.stats module_name/all pkg/shm/all

5.1.  pkg.stats

   Print private memory (pkg) usage statistics per process. It can take
   optinally 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:
                kamcmd pkg.stats
                kamcmd pkg.stats pid 1234
                kamcmd pkg.stats rank 1
                kamcmd pkg.stats index 10

5.2.  stats.get_statistics

   Print the list of available internal statistics.

   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:
                kamcmd stats.get_statistics all
                kamcmd stats.get_statistics core:
                kamcmd stats.get_statistics unsupported_methods
                kamcmd stats.get_statistics shmem: fwd_requests fwd_replies

5.3.  stats.reset_statistics

   Reset internal statistics.

   Parameters: statsid - same as for get_statistics.

   Examples:
                kamcmd stats.reset_statistics all
                kamcmd stats.reset_statistics core:
                kamcmd stats.reset_statistics unsupported_methods
                kamcmd stats.reset_statistics shmem: fwd_requests fwd_replies

5.4.  stats.clear_statistics

   Return statistics and reset their value in one command.

   Parameters: statsid - same as for get_statistics.

   Examples:
                kamcmd stats.reset_statistics all
                kamcmd stats.reset_statistics core:
                kamcmd stats.reset_statistics unsupported_methods
                kamcmd stats.reset_statistics shmem: fwd_requests fwd_replies

5.5.  mod.stats module_name/all pkg/shm/all

   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 throug 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:
                kamcmd mod.stats core all
                kamcmd mod.stats userblacklist shm
                kamcmd mod.stats kex pkg
                kamcmd 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_mi_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
}