# &adminguide;

## Overview

This module provides a report of the way &kamailioname; 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.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- pv.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- None.

## Parameters

### `basedir` (string)

Control where the config reports should be stored. The dir must exist and &kamailioname; must have permissions to write on it.

Default value is /tmp.

#### Set `cfgtrace` parameter

    ...
    modparam("cfgt", "basedir", "/run/kamailio/cfgtest")
    ...

### `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).

#### Set `mask` parameter

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

### `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).

#### Set `callid_prefix` parameter

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

### `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.

#### Set `skip_unknown` parameter

    ...
    modparam("cfgt", "skip_unknown", "1")
    ...

### `route_log` (int)

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

Default value is 0, false.

#### Set `route_log` parameter

    ...
    modparam("cfgt", "route_log", "1")
    ...

## RPC Commands

### `cfgt.mask`

Sets mask module parameter.

Name: cfgt.mask

Parameters:

- mask : int value

Example:

    ...
    &sercmd; cfgt.mask 32
    ...

### `cfgt.list`

Lists reports info in memory.

Name: cfgt.list

Example:

    ...
    &sercmd; cfgt.list
    {
            uuid: unknown
            msgid: 2
    }
    {
            uuid: whatever
            msgid: 1
    }
    200 ok
    ...

### `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:

    ...
    &sercmd; cfgt.clean unknown
    ...
    &sercmd; cfgt.clean all
    ...

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

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