<?xml version="1.0" encoding='ISO-8859-1'?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN"
"http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd" [

<!-- Include general documentation entities -->
<!ENTITY % docentities SYSTEM "../../../../doc/docbook/entities.xml">
%docentities;

]>

<!-- Module User's Guide -->

<chapter>

	<title>&adminguide;</title>

	<section>
	<title>Overview</title>
	<para>
		This module provides a report of the way &kamailioname; configuration
		has been executed as part of a unit test for different
		SIP scenarios.
	</para>
	<para>
		In order to identify different scenarios a prefix string should be
		used inside the Call-ID header.
	</para>
	</section>
	<section>
	<title>Dependencies</title>
	<section>
		<title>&kamailio; Modules</title>
		<para>
		The following modules must be loaded before this module:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>pv</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	<section>
		<title>External Libraries or Applications</title>
		<para>
		The following libraries or applications must be installed before running
		&kamailio; with this module loaded:
			<itemizedlist>
			<listitem>
			<para>
				<emphasis>None</emphasis>.
			</para>
			</listitem>
			</itemizedlist>
		</para>
	</section>
	</section>
	<section>
	<title>Parameters</title>
	<section id="cfg.p.basedir">
		<title><varname>basedir</varname> (string)</title>
		<para>
			Control where the config reports should be stored. The dir must
			exist and &kamailioname; must have permissions to write on it.
		</para>
		<para>
		<emphasis>
			Default value is <quote>/tmp</quote>.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>cfgtrace</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cfgt", "basedir", "/run/kamailio/cfgtest")
...
</programlisting>
		</example>
	</section>

	<section id="cfgt.p.mask">
		<title><varname>mask</varname> (int)</title>
		<itemizedlist>
			<para><emphasis>mask</emphasis> - Control the type of vars it should
			display in the report:
			</para>
			<itemizedlist>
			<listitem><para>
			  1 - dump null values
			</para></listitem>
			<listitem><para>
			  2 - dump avp vars
			</para></listitem>
			<listitem><para>
			  4 - dump script vars
			</para></listitem>
			<listitem><para>
			  8 - dump xavp vars
			</para></listitem>
			<listitem><para>
			  16 - dump DP_OTHER vars
			</para></listitem>
			<listitem><para>
			  32 - dump ALL vars
			</para></listitem>
			</itemizedlist>
		</itemizedlist>
		<para>
		<emphasis>
			Default value is <quote>32</quote> (ALL).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>mask</varname> parameter</title>
		<programlisting format="linespecific">
...
# dump xavp(8) and avp(4) vars
modparam("cfgt", "mask", 12)
...
</programlisting>
		</example>
	</section>

	<section id="cfgt.p.callid_prefix">
		<title><varname>callid_prefix</varname> (string)</title>
		<para>
			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 <quote>NGCP%</quote> and Call-ID <quote>NGCP%123%456</quote>
			the scenario identified will be <quote>123</quote>.
		</para>
		<para>
		<emphasis>
			Default value is <quote>NGCP%</quote>
			(using <quote>%</quote> as delimiter).
		</emphasis>
		</para>
		<example>
		<title>Set <varname>callid_prefix</varname> parameter</title>
		<programlisting format="linespecific">
...
# using '%' as delimiter
modparam("cfgt", "callid_prefix", "TEST-ID%")
...
</programlisting>
		</example>
	</section>
	<section id="cfg.p.skip_unknown">
		<title><varname>skip_unknown</varname> (int)</title>
		<para>
			If enabled, value different from 0, cfgt will not generate the report
			of any message that doesn't match the callid_prefix.
		</para>
		<para>
		<emphasis>
			Default value is <quote>0</quote>, false.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>skip_unknown</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cfgt", "skip_unknown", "1")
...
</programlisting>
		</example>
	</section>
	<section id="cfg.p.route_log">
		<title><varname>route_log</varname> (int)</title>
		<para>
			If enabled, value different from 0, cfgt will log (WARN) the execution time of routes.
		</para>
		<para>
		<emphasis>
			Default value is <quote>0</quote>, false.
		</emphasis>
		</para>
		<example>
		<title>Set <varname>route_log</varname> parameter</title>
		<programlisting format="linespecific">
...
modparam("cfgt", "route_log", "1")
...
</programlisting>
		</example>
	</section>

	</section>
	<section>
	<title>RPC Commands</title>
	<section id="cfgt.r.mask">
		<title>
		<function moreinfo="none">cfgt.mask</function>
		</title>
		<para>
		Sets <link linked="cfgt.p.mask">mask</link> module parameter.
		</para>
		<para>
		Name: <emphasis>cfgt.mask</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>mask : int value</para>
			</listitem>
		</itemizedlist>
		<para>
		Example:
		</para>
<programlisting  format="linespecific">
...
&sercmd; cfgt.mask 32
...
</programlisting>
    </section>

	<section id="cfgt.r.list">
		<title>
		<function moreinfo="none">cfgt.list</function>
		</title>
		<para>
		Lists reports info in memory.
		</para>
		<para>
		Name: <emphasis>cfgt.list</emphasis>
		</para>
		<para>
		Example:
		</para>
<programlisting  format="linespecific">
...
&sercmd; cfgt.list
{
        uuid: unknown
        msgid: 2
}
{
        uuid: whatever
        msgid: 1
}
200 ok
...
</programlisting>
    </section>

	<section id="cfgt.r.clean">
		<title>
		<function moreinfo="none">cfgt.clean</function>
		</title>
		<para>
		Removes reports from disk and cleans info in memory.
		</para>
		<para>
		Name: <emphasis>cfgt.clean</emphasis>
		</para>
		<para>Parameters:</para>
		<itemizedlist>
			<listitem><para>report : string value</para>
				<para>use 'all' to clean any report</para>
			</listitem>
		</itemizedlist>
		<para>
		Example:
		</para>
<programlisting  format="linespecific">
...
&sercmd; cfgt.clean unknown
...
&sercmd; cfgt.clean all
...
</programlisting>
    </section>

	</section>
	<section>
		<title>Usage</title>
		<para>
		This module is used by the <emphasis>debugger</emphasis> module, so it must be loaded
		first. To enable the generation of the reports, the <emphasis>debugger</emphasis> module
		must be configured by setting the <emphasis>cfgtest</emphasis> parameter to "1".
		</para>
		<para>
		Example of configuration:
		</para>
<programlisting  format="linespecific">
...
#!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
...
</programlisting>
	</section>
	<section>
		<title>Report format</title>
		<para>
		<emphasis>cfgt</emphasis> generates a json file per request processed.
		The files are created at &lt;basedir&gt;/&lt;prefix&gt;/&lt;message_id&gt;.json.
		The <quote>message_id</quote> is a sequence starting with 1 per scenario
		defined by <quote>prefix</quote> module parameter.
		</para>
		<para>
		The json report has three top members, <quote>flow</quote>,
		<quote>sip_in</quote> and <quote>sip_out</quote> describing, the flow of
		the configuration routes, the SIP message processed and the SIP messages
		sent during that process execution.
		</para>
		<para>
		The flow of the configuration routes is defined by an array of routes with
		the content of the variables controlled by <quote>mask</quote> module parameter.
		</para>
		<para>Each routename has a prefix as <quote>start|</quote>,
		<quote>return|</quote>,	when the route finish its execution and <quote>exit|</quote> or
		<quote>drop|</quote> if the route finish its execution with exit or drop.
		</para>
<programlisting format="linespecific">
{
 "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"]
}
</programlisting>
	</section>
</chapter>
