siptrace: update doc with support for HEPv3

src/modules/siptrace/doc/siptrace_admin.xml

@@ -17,8 +17,8 @@
 	<title>Overview</title>
 	<para>
 		The SIPtrace module offer a possibility to store incoming and outgoing SIP
-		messages in a database and/or duplicate to the capturing server (using <acronym>HEP</acronym>
-		the Homer encapsulation protocol or plain SIP mode)
+		messages in a database and/or duplicate to the capturing server (using <acronym>HEP</acronym>,
+		the Homer encapsulation protocol, or plain SIP mode)
 	</para>
 	<para>
 		There are two ways of storing information:
@@ -42,8 +42,7 @@
 	</para>
 
 	<para>
-	The tracing can be turned on/off using Kamailio <acronym>mi</acronym> or <acronym>RPC</acronym>
-	commands.
+	The tracing can be turned on/off using Kamailio <acronym>RPC</acronym> commands.
 	</para>
 	<para>
 	&ctltool; fifo sip_trace on
@@ -57,12 +56,12 @@
 	<section>
 		<title>&kamailio; Modules</title>
 		<para>
-		The following modules must be loaded before this module:
+		The following modules must be conditionally loaded before this module:
 			<itemizedlist>
 			<listitem>
 			<para>
 				<emphasis>A database module</emphasis> - Mysql, Postgres,
-				dbtext, unixODBC...
+				dbtext, unixODBC... Optional, if tracing to DB is enabled.
 			</para>
 			</listitem>
 			<listitem>
@@ -199,7 +198,7 @@ modparam("siptrace", "traced_user_avp", "$avp(s:user)")
 		store the SIP messages. If it is not set, the value of
 		<quote>table</quote> parameter is used. In this way one can select
 		dynamically where to store the traced messages. The table
-		must exists, and must have the same structure as the <quote>sip_trace</quote>
+		must exist, and must have the same structure as the <quote>sip_trace</quote>
 		table.
 		</para>
 		<para>
@@ -395,8 +394,9 @@ modparam("siptrace", "hep_mode_on", 1)
                 <title><varname>hep_version</varname> (integer)</title>
                 <para>
                 The parameter indicate the version of the HEP protocol.
-                Can be <quote>1</quote> or <quote>2</quote>. In HEPv2 the timestamp and capture agent ID
-                will be included to HEP header.
+                Can be <quote>1</quote>, <quote>2</quote> or <quote>3</quote>.
+                In HEPv2 and HEPv3 the timestamp and capture agent ID will be
+                included in the HEP header.
                 </para>
                 <para>
                 <emphasis>
@@ -407,7 +407,7 @@ modparam("siptrace", "hep_mode_on", 1)
                 <title>Set <varname>hep_version</varname> parameter</title>
                 <programlisting format="linespecific">
 ...
-modparam("siptrace", "hep_version", 2)
+modparam("siptrace", "hep_version", 3)
 ...
 </programlisting>
                 </example>
@@ -416,8 +416,8 @@ modparam("siptrace", "hep_version", 2)
                 <title><varname>hep_capture_id</varname> (integer)</title>
                 <para>
                 The parameter indicate the capture agent ID for the <acronym>HEPv2</acronym>
-                protocol.
-                Limitation: 16-bit integer.
+                or <acronym>HEPv3</acronym> protocol.
+                Limitation: 16-bit integer for HEPv2, 32-bit for HEPv3.
                 </para>
                 <para>
                 <emphasis>
@@ -425,8 +425,7 @@ modparam("siptrace", "hep_version", 2)
                 </emphasis>
                 </para>
                 <example>
-                <title>Set <varname>hep_capture_id</varname>
-                parameter</title>
+                <title>Set <varname>hep_capture_id</varname> parameter</title>
                 <programlisting format="linespecific">
 ...
 modparam("siptrace", "hep_capture_id", 234)
@@ -456,7 +455,7 @@ modparam("siptrace", "trace_delayed", 1)
 	<section id="siptrace.p.force_send_sock">
                 <title><varname>force_send_sock</varname> (str)</title>
                 <para>
-			The local interface in the form of SIP uri from where to send
+			The local interface in the form of SIP URI from where to send
 			the duplicated traffic. In the absence of this parameter
 			&kamailio; automatically picks an interface.
                 </para>
@@ -490,6 +489,25 @@ modparam("siptrace", "force_send_sock", "sip:10.1.1.2:5000")
 ...
 modparam("siptrace", "trace_mode", 1)
 ...
+</programlisting>
+                </example>
+        </section>
+	<section id="siptrace.p.auth_key">
+                <title><varname>auth_key</varname> (integer)</title>
+                <para>
+A string with an authorization key.
+Supported on HEPv3 only.
+                </para>
+                <para>
+                Default value is empty.
+                </para>
+                <example>
+                <title>Set <varname>auth_key</varname>
+                parameter</title>
+                <programlisting format="linespecific">
+...
+modparam("siptrace", "auth_key", "spoihepuirthpeuia")
+...
 </programlisting>
                 </example>
         </section>
@@ -499,7 +517,7 @@ modparam("siptrace", "trace_mode", 1)
 	<title>Functions</title>
 	<section id="siptrace.f.sip_trace">
 		<title>
-		<function moreinfo="none">sip_trace([address])</function>
+		<function moreinfo="none">sip_trace([address][, correlation_id])</function>
 		</title>
 		<para>
 		Store or forward the current processed SIP message in database. It is stored in the
@@ -508,10 +526,14 @@ modparam("siptrace", "trace_mode", 1)
 		<para>Meaning of the parameters is as follows:</para>
 		<itemizedlist>
 		<listitem>
-		<para><emphasis>address</emphasis> - The address in form of SIP uri
+		<para><emphasis>address</emphasis> - The address in form of SIP URI
 		where to send a duplicate of traced message. This parameter trumps
 		duplicate_uri and allows tracing to more than one server.
 		</para>
+		<para><emphasis>correlation_id</emphasis> - A string with a correlation ID
+		to be added to the HEP header when using HEPv3.
+		It's possible to use PVs.
+		</para>
 		</listitem>
 		</itemizedlist>
 		<para>
@@ -529,6 +551,8 @@ sip_trace();
 ...
 sip_trace("sip:10.1.1.2:5085");
 ...
+sip_trace("sip:10.1.1.2:5085", "$ci-abc");
+...
 </programlisting>
 		</example>
 	</section>
@@ -549,7 +573,7 @@ sip_trace("sip:10.1.1.2:5085");
 		</para>
 		<para>Parameters: </para>
 		<itemizedlist>
-			<listitem><para>on or off: turns on/off SIP message tracing..
+			<listitem><para>on or off: turns on/off SIP message tracing.
 			Possible values are:</para>
 			<itemizedlist>
 				<listitem><para>on</para></listitem>