cfgt Module

Victor Seva

   sipwise.com

Edited by

Victor Seva

   <linuxmaniac@torreviejawireless.org>

   Copyright © 2015 Victor Seva (sipwise.com)
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. basedir (string)
              3.2. mask (int)
              3.3. callid_prefix (string)
              3.4. skip_unknown (int)
              3.5. route_log (int)

        4. RPC Commands

              4.1. cfgt.mask
              4.2. cfgt.list
              4.3. cfgt.clean

        5. Usage
        6. Report format

   List of Examples

   1.1. Set cfgtrace parameter
   1.2. Set mask parameter
   1.3. Set callid_prefix parameter
   1.4. Set skip_unknown parameter
   1.5. Set route_log parameter

Chapter 1. Admin Guide

   Table of Contents

   1. Overview
   2. Dependencies

        2.1. Kamailio Modules
        2.2. External Libraries or Applications

   3. Parameters

        3.1. basedir (string)
        3.2. mask (int)
        3.3. callid_prefix (string)
        3.4. skip_unknown (int)
        3.5. route_log (int)

   4. RPC Commands

        4.1. cfgt.mask
        4.2. cfgt.list
        4.3. cfgt.clean

   5. Usage
   6. Report format

1. Overview

   This module provides a report of the way Kamailio SIP Server Platform
   configuration has been executed as part of a unit test for different
   SIP scenarios.

   In order to identify different scenarios a prefix string should be used
   inside the Call-ID header.

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:
     * pv.

2.2. External Libraries or Applications

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

3. Parameters

   3.1. basedir (string)
   3.2. mask (int)
   3.3. callid_prefix (string)
   3.4. skip_unknown (int)
   3.5. route_log (int)

3.1. basedir (string)

   Control where the config reports should be stored. The dir must exist
   and Kamailio SIP Server Platform must have permissions to write on it.

   Default value is “/tmp”.

   Example 1.1. Set cfgtrace parameter
...
modparam("cfgt", "basedir", "/run/kamailio/cfgtest")
...

3.2. mask (int)

   mask - Control the type of vars it should display in the report:
     * 1 - dump null values
     * 2 - dump avp vars
     * 4 - dump script vars
     * 8 - dump xavp vars
     * 16 - dump DP_OTHER vars
     * 32 - dump ALL vars

   Default value is “32” (ALL).

   Example 1.2. Set mask parameter
...
# dump xavp(8) and avp(4) vars
modparam("cfgt", "mask", 12)
...

3.3. callid_prefix (string)

   Prefix used to identify test scenario messages. Last char of the string
   will be used as delimiter for the scenario ID. With parameter set to
   “NGCP%” and Call-ID “NGCP%123%456” the scenario identified will be
   “123”.

   Default value is “NGCP%” (using “%” as delimiter).

   Example 1.3. Set callid_prefix parameter
...
# using '%' as delimiter
modparam("cfgt", "callid_prefix", "TEST-ID%")
...

3.4. skip_unknown (int)

   If enabled, value different from 0, cfgt will not generate the report
   of any message that doesn't match the callid_prefix.

   Default value is “0”, false.

   Example 1.4. Set skip_unknown parameter
...
modparam("cfgt", "skip_unknown", "1")
...

3.5. route_log (int)

   If enabled, value different from 0, cfgt will log (WARN) the execution
   time of routes.

   Default value is “0”, false.

   Example 1.5. Set route_log parameter
...
modparam("cfgt", "route_log", "1")
...

4. RPC Commands

   4.1. cfgt.mask
   4.2. cfgt.list
   4.3. cfgt.clean

4.1.  cfgt.mask

   Sets mask module parameter.

   Name: cfgt.mask

   Parameters:
     * mask : int value

   Example:
...
kamcmd cfgt.mask 32
...

4.2.  cfgt.list

   Lists reports info in memory.

   Name: cfgt.list

   Example:
...
kamcmd cfgt.list
{
        uuid: unknown
        msgid: 2
}
{
        uuid: whatever
        msgid: 1
}
200 ok
...

4.3.  cfgt.clean

   Removes reports from disk and cleans info in memory.

   Name: cfgt.clean

   Parameters:
     * report : string value
       use 'all' to clean any report

   Example:
...
kamcmd cfgt.clean unknown
...
kamcmd cfgt.clean all
...

5. Usage

   This module is used by the debugger module, so it must be loaded first.
   To enable the generation of the reports, the debugger module must be
   configured by setting the cfgtest parameter to "1".

   Example of configuration:
...
#!ifdef WITH_DEBUG
loadmodule "cfgt.so"
loadmodule "debugger.so"
#!endif
...
#!ifdef WITH_DEBUG
# ----- cfgt params -----
modparam("cfgt", "basedir", "/tmp/kamailio/cfgtest")
modparam("cfgt", "callid_prefix", "TRACE-ID%")
modparam("cfgt", "mask", 32)

# ----- debugger params -----
modparam("debugger", "cfgtrace", 1)
modparam("debugger", "log_level_name", "exec")

modparam("debugger", "cfgtest", 1)
#!endif
...

6. Report format

   cfgt generates a json file per request processed. The files are created
   at <basedir>/<prefix>/<message_id>.json. The “message_id” is a sequence
   starting with 1 per scenario defined by “prefix” module parameter.

   The json report has three top members, “flow”, “sip_in” and “sip_out”
   describing, the flow of the configuration routes, the SIP message
   processed and the SIP messages sent during that process execution.

   The flow of the configuration routes is defined by an array of routes
   with the content of the variables controlled by “mask” module
   parameter.

   Each routename has a prefix as “start|”, “return|”, when the route
   finish its execution and “exit|” or “drop|” if the route finish its
   execution with exit or drop.
{
 "flow": [{
   "start|DEFAULT_ROUTE": {
    "$var(userprov_domain)": "spce.test",
    "$fU": "testuser1002",
    [...]},
   "start|ROUTE_NET_INFO": {[...]},
   "return|ROUTE_NET_INFO": {[...]},
   [...]
   "start|ROUTE_AUTH": {[...]},
   "exit|ROUTE_AUTH": {[...]},
   },
 "sip_in": ["INVITE sip:4311001@spce.test SIP/2.0\r\nRecord-Route: [...]\r\n"],
 "sip_out": ["SIP/2.0 100 Trying\r\nVia: SIP/2.0/UDP 127.0.0.1[...]\r\n", "SIP/2
.0 407 Proxy Authentication Required[...]\r\n"]
}
