cfgt Module

Victor Seva

sipwise.com

Edited by

Victor Seva


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

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

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)

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

    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"]
    }