KEx Module

Daniel-Constantin Mierla

asipto.com

Ovidiu Sas

VoIP Embedded, Inc.

Edited by

Daniel-Constantin Mierla

Ovidiu Sas

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. 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. pkg.stats
4.24. pkg.info
4.25. stats.get_statistics
4.26. stats.fetch
4.27. stats.fetchn
4.28. stats.reset_statistics
4.29. stats.clear_statistics
4.30. system.listMethods
4.31. system.methodHelp
4.32. system.methodSignature
4.33. mod.mem_stats
4.34. mod.stats
4.35. 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. 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. 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. pkg.stats
4.24. pkg.info
4.25. stats.get_statistics
4.26. stats.fetch
4.27. stats.fetchn
4.28. stats.reset_statistics
4.29. stats.clear_statistics
4.30. system.listMethods
4.31. system.methodHelp
4.32. system.methodSignature
4.33. mod.mem_stats
4.34. mod.stats
4.35. mod.mem_statsx

1. Overview

This module collects extensions from Kamailio core.

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

2. Dependencies

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)

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 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. 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. RPC Commands

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: 

...
kamcmd 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: 

...
kamcmd 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: 

...
kamcmd 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: 

...
kamcmd core.uptime
...

4.20.  core.version

Print version information.

Name: core.version

Parameters: none.

RPC Command Format: 

...
kamcmd core.version
...

4.21.  core.ppdefines

List preprocessor defines enabled in config.

Name: core.ppdefines

Parameters: none.

RPC Command Format: 

...
kamcmd core.ppdefines
...

4.22.  core.modules

List loaded modules in config.

Name: core.modules

Parameters: none.

RPC Command Format: 

...
kamcmd core.modules
...

4.23.  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: 

		kamcmd pkg.stats
		kamcmd pkg.stats pid 1234
		kamcmd pkg.stats rank 1
		kamcmd pkg.stats index 10

4.24.  pkg.info

Get pkg manager details.

Example: 

		kamcli rpc pkg.info

4.25.  stats.get_statistics

Print the list of available internal statistics.

NOTE: the result is an array of strings that have the list of statistics formated 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:

		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

4.26.  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 accomodate 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:

		kamcmd stats.fetch all
		kamcmd stats.fetch core:
		kamcmd stats.fetch unsupported_methods
		kamcmd stats.fetch shmem.free_size
		kamcmd stats.fetch shmem: fwd_requests fwd_replies

4.27.  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:

		kamcmd stats.fetchn all
		kamcmd stats.fetchn core:
		kamcmd stats.fetchn unsupported_methods
		kamcmd stats.fetchn shmem.free_size
		kamcmd stats.fetchn shmem: fwd_requests fwd_replies

4.28.  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

4.29.  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

4.30.  system.listMethods

Print list of available RPC commands.

Name: system.listMethods

Parameters: none.

RPC Command Format: 

...
kamcmd system.listMethods
...

4.31.  system.methodHelp

Print the help string for given method.

4.32.  system.methodSignature

Returns signature of given method.

4.33.  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: 

		kamcmd mod.stats core all
		kamcmd mod.stats tm 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_malloc
    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_malloc
    pkg_proc_stats_init(79): 864
    Total: 864
}

4.34.  mod.stats

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

4.35.  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".