modules: readme files regenerated - siptrace ... [skip ci]

src/modules/siptrace/README

@@ -16,6 +16,12 @@ Daniel-Constantin Mierla
 
    <[email protected]>
 
+Edited by
+
+Giacomo Vacca
+
+   <[email protected]>
+
    Copyright © 2010 asipto.com
 
    Copyright © 2006 voice-system.ro
@@ -51,10 +57,11 @@ Daniel-Constantin Mierla
               3.16. trace_delayed (integer)
               3.17. force_send_sock (str)
               3.18. trace_mode (integer)
+              3.19. auth_key (integer)
 
         4. Functions
 
-              4.1. sip_trace([address])
+              4.1. sip_trace([address][, correlation_id])
 
         5. RPC Commands
 
@@ -83,7 +90,8 @@ Daniel-Constantin Mierla
    1.16. Set trace_delayed parameter
    1.17. Set force_send_sock parameter
    1.18. Set trace_mode parameter
-   1.19. sip_trace() usage
+   1.19. Set auth_key parameter
+   1.20. sip_trace() usage
 
 Chapter 1. Admin Guide
 
@@ -115,10 +123,11 @@ Chapter 1. Admin Guide
         3.16. trace_delayed (integer)
         3.17. force_send_sock (str)
         3.18. trace_mode (integer)
+        3.19. auth_key (integer)
 
    4. Functions
 
-        4.1. sip_trace([address])
+        4.1. sip_trace([address][, correlation_id])
 
    5. RPC Commands
 
@@ -131,7 +140,7 @@ Chapter 1. Admin Guide
 
    The SIPtrace module offer a possibility to store incoming and outgoing
    SIP messages in a database and/or duplicate to the capturing server
-   (using HEP the Homer encapsulation protocol or plain SIP mode)
+   (using HEP, the Homer encapsulation protocol, or plain SIP mode)
 
    There are two ways of storing information:
      * by calling the sip_trace() method explicitely in the Kamailio
@@ -142,7 +151,7 @@ Chapter 1. Admin Guide
        on TM/SL callbacks, so only messages processed with the TM module
        or sent statelessly are logged.
 
-   The tracing can be turned on/off using Kamailio mi or RPC commands.
+   The tracing can be turned on/off using Kamailio RPC commands.
 
    kamctl fifo sip_trace on
 
@@ -155,8 +164,9 @@ Chapter 1. Admin Guide
 
 2.1. Kamailio Modules
 
-   The following modules must be loaded before this module:
-     * A database module - Mysql, Postgres, dbtext, unixODBC...
+   The following modules must be conditionally loaded before this module:
+     * A database module - Mysql, Postgres, dbtext, unixODBC... Optional,
+       if tracing to DB is enabled.
      * tm and sl modules - optional, only if you want to trace messages
        forwarded by these modules.
 
@@ -186,6 +196,7 @@ Chapter 1. Admin Guide
    3.16. trace_delayed (integer)
    3.17. force_send_sock (str)
    3.18. trace_mode (integer)
+   3.19. auth_key (integer)
 
 3.1. db_url (str)
 
@@ -251,8 +262,8 @@ modparam("siptrace", "traced_user_avp", "$avp(s:user)")
    The name of the AVP storing the name of the table where to store the
    SIP messages. If it is not set, the value of “table” 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 “sip_trace” table.
+   messages. The table must exist, and must have the same structure as the
+   “sip_trace” table.
 
    Default value is "NULL" (feature disabled).
 
@@ -370,21 +381,21 @@ modparam("siptrace", "hep_mode_on", 1)
 
 3.14. hep_version (integer)
 
-   The parameter indicate the version of the HEP protocol. Can be “1” or
-   “2”. In HEPv2 the timestamp and capture agent ID will be included to
-   HEP header.
+   The parameter indicate the version of the HEP protocol. Can be “1”, “2”
+   or “3”. In HEPv2 and HEPv3 the timestamp and capture agent ID will be
+   included in the HEP header.
 
    Default value is "1".
 
    Example 1.14. Set hep_version parameter
 ...
-modparam("siptrace", "hep_version", 2)
+modparam("siptrace", "hep_version", 3)
 ...
 
 3.15. hep_capture_id (integer)
 
-   The parameter indicate the capture agent ID for the HEPv2 protocol.
-   Limitation: 16-bit integer.
+   The parameter indicate the capture agent ID for the HEPv2 or HEPv3
+   protocol. Limitation: 16-bit integer for HEPv2, 32-bit for HEPv3.
 
    Default value is "1".
 
@@ -407,7 +418,7 @@ modparam("siptrace", "trace_delayed", 1)
 
 3.17. force_send_sock (str)
 
-   The local interface in the form of SIP uri from where to send the
+   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.
 
@@ -432,30 +443,45 @@ modparam("siptrace", "force_send_sock", "sip:10.1.1.2:5000")
 modparam("siptrace", "trace_mode", 1)
 ...
 
+3.19. auth_key (integer)
+
+   A string with an authorization key. Supported on HEPv3 only.
+
+   Default value is empty.
+
+   Example 1.19. Set auth_key parameter
+...
+modparam("siptrace", "auth_key", "spoihepuirthpeuia")
+...
+
 4. Functions
 
-   4.1. sip_trace([address])
+   4.1. sip_trace([address][, correlation_id])
 
-4.1.  sip_trace([address])
+4.1.  sip_trace([address][, correlation_id])
 
    Store or forward the current processed SIP message in database. It is
    stored in the form prior applying changes made to it.
 
    Meaning of the parameters is as follows:
-     * address - The address in form of SIP uri where to send a duplicate
+     * address - 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.
+       correlation_id - A string with a correlation ID to be added to the
+       HEP header when using HEPv3. It's possible to use PVs.
 
    This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
    ONREPLY_ROUTE, BRANCH_ROUTE.
    Default value is "NULL".
 
-   Example 1.19. sip_trace() usage
+   Example 1.20. sip_trace() usage
 ...
 sip_trace();
 ...
 sip_trace("sip:10.1.1.2:5085");
 ...
+sip_trace("sip:10.1.1.2:5085", "$ci-abc");
+...
 
 5. RPC Commands
 
@@ -466,7 +492,7 @@ sip_trace("sip:10.1.1.2:5085");
    Name: siptrace.status
 
    Parameters:
-     * on or off: turns on/off SIP message tracing.. Possible values are:
+     * on or off: turns on/off SIP message tracing. Possible values are:
           + on
           + off
      * “check” does not change siptrace status, just reports the current