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

src/modules/siptrace/README

@@ -1,2 +1,629 @@
+SipTrace Module
 
+Daniel-Constantin Mierla
 
+   <[email protected]>
+
+Edited by
+
+Alexandr Dubovikov
+
+   <[email protected]>
+
+Daniel-Constantin Mierla
+
+   <[email protected]>
+
+Giacomo Vacca
+
+   <[email protected]>
+
+Camille Oudot
+
+   <[email protected]>
+
+   Copyright © 2010 asipto.com
+
+   Copyright © 2006 voice-system.ro
+     __________________________________________________________________
+
+   Table of Contents
+
+   1. Admin Guide
+
+        1. Overview
+        2. Dependencies
+
+              2.1. Kamailio Modules
+              2.2. External Libraries or Applications
+
+        3. Parameters
+
+              3.1. db_url (str)
+              3.2. table (str)
+              3.3. trace_flag (integer)
+              3.4. trace_on (integer)
+              3.5. traced_user_avp (str)
+              3.6. trace_table_avp (str)
+              3.7. duplicate_uri (str)
+              3.8. trace_to_database (integer)
+              3.9. trace_local_ip (str)
+              3.10. trace_sl_acks (integer)
+              3.11. xheaders_write (integer)
+              3.12. xheaders_read (integer)
+              3.13. hep_mode_on (integer)
+              3.14. hep_version (integer)
+              3.15. hep_capture_id (integer)
+              3.16. trace_delayed (integer)
+              3.17. force_send_sock (str)
+              3.18. trace_init_mode (integer)
+              3.19. trace_mode (integer)
+              3.20. auth_key (integer)
+
+        4. Functions
+
+              4.1. sip_trace([address][,correlation_id][,mode])
+              4.2. sip_trace_mode(tmode)
+              4.3. hlog([correlation_id,] message)
+
+        5. RPC Commands
+
+              5.1. siptrace.status param
+
+        6. Database setup
+        7. Known issues
+
+   List of Examples
+
+   1.1. Set db_url parameter
+   1.2. Set table parameter
+   1.3. Set trace_flag parameter
+   1.4. Set trace_on parameter
+   1.5. Set traced_user_avp parameter
+   1.6. Set trace_table_avp parameter
+   1.7. Set duplicate_uri parameter
+   1.8. Set trace_to_database parameter
+   1.9. Set trace_local_ip parameter
+   1.10. Set trace_sl_acks parameter
+   1.11. Set xheaders_write parameter
+   1.12. Set xheaders_read parameter
+   1.13. Set hep_mode_on parameter
+   1.14. Set hep_version parameter
+   1.15. Set hep_capture_id parameter
+   1.16. Set trace_delayed parameter
+   1.17. Set force_send_sock parameter
+   1.18. Set trace_init_mode parameter
+   1.19. Set trace_mode parameter
+   1.20. Set auth_key parameter
+   1.21. sip_trace() usage
+   1.22. sip_trace_mode() usage
+   1.23. hlog() usage
+   1.24. Send relayed ACK message
+
+Chapter 1. Admin Guide
+
+   Table of Contents
+
+   1. Overview
+   2. Dependencies
+
+        2.1. Kamailio Modules
+        2.2. External Libraries or Applications
+
+   3. Parameters
+
+        3.1. db_url (str)
+        3.2. table (str)
+        3.3. trace_flag (integer)
+        3.4. trace_on (integer)
+        3.5. traced_user_avp (str)
+        3.6. trace_table_avp (str)
+        3.7. duplicate_uri (str)
+        3.8. trace_to_database (integer)
+        3.9. trace_local_ip (str)
+        3.10. trace_sl_acks (integer)
+        3.11. xheaders_write (integer)
+        3.12. xheaders_read (integer)
+        3.13. hep_mode_on (integer)
+        3.14. hep_version (integer)
+        3.15. hep_capture_id (integer)
+        3.16. trace_delayed (integer)
+        3.17. force_send_sock (str)
+        3.18. trace_init_mode (integer)
+        3.19. trace_mode (integer)
+        3.20. auth_key (integer)
+
+   4. Functions
+
+        4.1. sip_trace([address][,correlation_id][,mode])
+        4.2. sip_trace_mode(tmode)
+        4.3. hlog([correlation_id,] message)
+
+   5. RPC Commands
+
+        5.1. siptrace.status param
+
+   6. Database setup
+   7. Known issues
+
+1. Overview
+
+   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). Since
+   version 5.3.0 new levels of tracing are available. Transactions and
+   dialogs can be traced.
+
+   There are multiple ways of storing information:
+     * by calling the sip_trace() method explicitly in the Kamailio
+       configuration file. In this case the original message is processed
+       along with it's corresponding transaction/dialog if certain flags
+       are used.
+     * by setting “trace_mode” to mirror or store to db all traffic.
+
+   The tracing can be turned on/off using Kamailio RPC commands.
+
+   kamctl rpc siptrace.status on
+
+   kamctl rpc siptrace.status off
+
+2. Dependencies
+
+   2.1. Kamailio Modules
+   2.2. External Libraries or Applications
+
+2.1. Kamailio Modules
+
+   The following modules must be conditionally loaded before this module:
+     * A database module - Mysql, Postgres, dbtext, unixODBC... Optional,
+       if tracing to DB is enabled.
+     * dialog, tm and sl modules - optional, only if you want to trace
+       messages forwarded by these modules.
+
+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. db_url (str)
+   3.2. table (str)
+   3.3. trace_flag (integer)
+   3.4. trace_on (integer)
+   3.5. traced_user_avp (str)
+   3.6. trace_table_avp (str)
+   3.7. duplicate_uri (str)
+   3.8. trace_to_database (integer)
+   3.9. trace_local_ip (str)
+   3.10. trace_sl_acks (integer)
+   3.11. xheaders_write (integer)
+   3.12. xheaders_read (integer)
+   3.13. hep_mode_on (integer)
+   3.14. hep_version (integer)
+   3.15. hep_capture_id (integer)
+   3.16. trace_delayed (integer)
+   3.17. force_send_sock (str)
+   3.18. trace_init_mode (integer)
+   3.19. trace_mode (integer)
+   3.20. auth_key (integer)
+
+3.1. db_url (str)
+
+   Database URL.
+
+   Default value is "mysql://kamailio:kamailiorw@localhost/kamailio".
+
+   Example 1.1. Set db_url parameter
+...
+modparam("siptrace", "db_url", "dbdriver://username:password@dbhost/dbname")
+...
+
+3.2. table (str)
+
+   Name of the table where to store the SIP messages.
+
+   Default value is “sip_trace”.
+
+   Example 1.2. Set table parameter
+...
+modparam("siptrace", "table", "strace")
+...
+
+3.3. trace_flag (integer)
+
+   Which flag is used to mark messages to trace without traced user.
+
+   Default value is "0".
+
+   Example 1.3. Set trace_flag parameter
+...
+modparam("siptrace", "trace_flag", 22)
+...
+
+3.4. trace_on (integer)
+
+   Parameter to enable/disable trace (on(1)/off(0))
+
+   Default value is "0".
+
+   Example 1.4. Set trace_on parameter
+...
+modparam("siptrace", "trace_on", 1)
+...
+
+3.5. traced_user_avp (str)
+
+   The name of the AVP storing the SIP URI of the traced user. If the AVP
+   is set, messages are stored in database table and the “traced_user”
+   column is filled with AVP's value. You can store the message many times
+   for many users by having multiple values for this AVP.
+
+   Default value is "NULL" (feature disabled).
+
+   Example 1.5. Set traced_user_avp parameter
+...
+modparam("siptrace", "traced_user_avp", "$avp(user)")
+...
+
+3.6. trace_table_avp (str)
+
+   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 exist, and must have the same structure as the
+   “sip_trace” table.
+
+   Default value is "NULL" (feature disabled).
+
+   Example 1.6. Set trace_table_avp parameter
+...
+modparam("siptrace", "trace_table_avp", "$avp(i:345)")
+modparam("siptrace", "trace_table_avp", "$avp(s:siptrace_table)")
+...
+
+3.7. duplicate_uri (str)
+
+   The address in form of a SIP URI where to send a duplicate of traced
+   message.
+
+   Default value is "NULL".
+
+   Example 1.7. Set duplicate_uri parameter
+...
+modparam("siptrace", "duplicate_uri", "sip:10.1.1.1:5888")
+...
+
+3.8. trace_to_database (integer)
+
+   Parameter to enable/disable inserts to the database from this Kamailio.
+
+   In case we only want to send the SIP messages to the “duplicate_uri”
+   and not store the information to the local database we can set this to
+   "0".
+
+   Default value is "1".
+
+   Example 1.8. Set trace_to_database parameter
+...
+modparam("siptrace", "trace_to_database", 0)
+...
+
+3.9. trace_local_ip (str)
+
+   The address to be used in “fromip” field for locally generated
+   messages. If not set, the module sets it to the address of the socket
+   that will be used to send the message.
+
+   Default value is "NULL".
+
+   Example 1.9. Set trace_local_ip parameter
+...
+modparam("siptrace", "trace_local_ip", "10.1.1.1:5064")
+...
+
+3.10. trace_sl_acks (integer)
+
+   Parameter to enable/disable tracing of SL-filtered ACKs (on=1 / off=0).
+
+   By default all ACKs to replies generated by SL module are traced. There
+   is no way to select among them. The SL module is able to run an event
+   route when such an ACK arrives (event_route[sl:filtered-ack]). You can
+   set this parameter to 0 and then execute sip_trace() in the event
+   route, accompanied by config rules to decide which ACK to trace.
+
+   Default value is "1".
+
+   Example 1.10. Set trace_sl_acks parameter
+...
+modparam("siptrace", "trace_sl_acks", 0)
+...
+
+3.11. xheaders_write (integer)
+
+   Parameter to enable/disable writing of x-headers.
+
+   Stores “fromip”, “toip”, “method” and “direction” in “X-Siptrace-*”
+   headers. This allows to transmit them to a second Kamailio server using
+   the “duplicate_uri” feature. Because the headers are added after the
+   data is written to the database, the headers only show up in the
+   packets sent by duplicate_uri.
+
+   See xheaders_read, it should be used on the receiving side.
+
+   Note: The headers are first read, then written. This allows relaying
+   the information over more than two Kamailio servers by setting both
+   xheaders_write and xheaders_read to "1" on the servers in the middle.
+
+   Default value is "0".
+
+   Example 1.11. Set xheaders_write parameter
+...
+modparam("siptrace", "xheaders_write", 0)
+...
+
+3.12. xheaders_read (integer)
+
+   Parameter to enable/disable reading of x-headers.
+
+   Reads and removes the “X-Siptrace-*” headers. Packets not containing
+   the headers are neither stored to the database nor relayed
+   (duplicate_uri). See xheaders_write for further information.
+
+   Default value is "0".
+
+   Example 1.12. Set xheaders_read parameter
+...
+modparam("siptrace", "xheaders_read", 0)
+...
+
+3.13. hep_mode_on (integer)
+
+   Parameter to enable/disable Homer encapsulate mode (on(1)/off(0))
+
+   Default value is "0".
+
+   Example 1.13. Set hep_mode_on parameter
+...
+modparam("siptrace", "hep_mode_on", 1)
+...
+
+3.14. hep_version (integer)
+
+   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", 3)
+...
+
+3.15. hep_capture_id (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".
+
+   Example 1.15. Set hep_capture_id parameter
+...
+modparam("siptrace", "hep_capture_id", 234)
+...
+
+3.16. trace_delayed (integer)
+
+   Use “INSERT DELAYED” to store to database when it is available, instead
+   of “INSERT”.
+
+   Default value is 0 (off).
+
+   Example 1.16. Set trace_delayed parameter
+...
+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
+   duplicated traffic. In the absence of this parameter Kamailio
+   automatically picks an interface.
+
+   Example 1.17. Set force_send_sock parameter
+...
+modparam("siptrace", "force_send_sock", "sip:10.1.1.2:5000")
+...
+
+3.18. trace_init_mode (integer)
+
+   Control what tracing modes are initialized.
+
+   The value of the parameter can be a combination of next values:
+     * 0 - all modes are initialized.
+     * 1 - module initialized to do tracing only with core callback
+       functions (see also 'trace_mode' parameter).
+     * 2 - module initialized to do tracing only using config script flags
+       and functions.
+
+   Default value is 0.
+
+   Example 1.18. Set trace_init_mode parameter
+...
+modparam("siptrace", "trace_init_mode", 1)
+...
+
+3.19. trace_mode (integer)
+
+   If not set to 0, the module uses core events triggered when receiving
+   or sending SIP traffic to store it to database or mirror it to a SIP
+   capture server using HEP or UDP forwarding. It will automatically do
+   the handling of all SIP traffic. It is no longer needed to set the
+   siptrace flag per request or execute sip_trace(), if it is done, then
+   the storing and mirroring is duplicated.
+
+   The value of the parameter can be a combination of next values:
+     * 0 - no automatic mirroring or storing of SIP traffic.
+     * 1 (1st bit set) - mirror the traffic to HEP server.
+     * 2 (2nd bit set) - store the traffic to database server.
+     * 4 (3rd bit set) - mirro the traffic to the SIP URI specified by
+       duplicate_uri.
+
+   The trace_on parameter still has to be set, allowing also to control
+   this mode of mirroring via RPC commands.
+
+   Default value is 0.
+
+   Example 1.19. Set trace_mode parameter
+...
+modparam("siptrace", "trace_on", 1)
+modparam("siptrace", "trace_mode", 1)
+...
+modparam("siptrace", "trace_mode", 3)
+...
+
+3.20. auth_key (integer)
+
+   A string with an authorization key. Supported on HEPv3 only.
+
+   Default value is empty.
+
+   Example 1.20. Set auth_key parameter
+...
+modparam("siptrace", "auth_key", "spoihepuirthpeuia")
+...
+
+4. Functions
+
+   4.1. sip_trace([address][,correlation_id][,mode])
+   4.2. sip_trace_mode(tmode)
+   4.3. hlog([correlation_id,] message)
+
+4.1.  sip_trace([address][,correlation_id][,mode])
+
+   Store or forward the current processed SIP message/transaction/dialog
+   in database. It is stored in the form prior applying changes made to
+   it. Based on mode, one can trace the current message('m' - default),
+   the current transaction('t') or the current dialog('d').
+
+   Meaning of the parameters is as follows:
+     * 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.
+     * mode - SIP messages to be traced. One can trace the current message
+       (function can be called on either a reply or a request), the
+       current transaction(the route must belong to a request) or the
+       current dialog(the message has to be an invite).
+
+   This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
+   ONREPLY_ROUTE, BRANCH_ROUTE.
+   Default value is "NULL".
+
+   Example 1.21. sip_trace() usage
+...
+sip_trace();
+...
+sip_trace("sip:10.1.1.2:5085");
+...
+sip_trace("sip:10.1.1.2:5085", "$ci-abc");
+...
+/* trace current dialog; needs to be done on initial INVITE and dialog has to be
+ loaded */
+sip_trace("sip:10.1.1.2:5085", "$ci-abc", "d");
+...
+
+4.2.  sip_trace_mode(tmode)
+
+   Set the tracing mode: message, transaction or dialog. Only the first
+   character of the parameter matters: m or M for message; t or T for
+   transaction; d or D for dialog.
+
+   In message tracing mode only the current message is stored or mirrored.
+   In transaction tracing mode, all the messages of the current
+   transaction are stored or mirrored. In dialog tracing mode, all the
+   messages of the current dialog are stored or mirrored.
+
+   This function can be used in ANY_ROUTE.
+
+   Example 1.22. sip_trace_mode() usage
+...
+sip_trace_mode("t");
+...
+
+4.3.  hlog([correlation_id,] message)
+
+   Sends a log event as a HEP3 packet to the homer host configured in
+   duplicate_uri.
+
+   Meaning of the parameters is as follows:
+     * correlation_id (optional) - Homer correlation ID for this event. If
+       this parameter is not set, the current message's call-id will be
+       used. (This parameter may contain PVs)
+     * message - The text to send to Homer as log event. (This parameter
+       may contain PVs)
+
+   Example 1.23. hlog() usage
+...
+hlog("[cfg:$cfg(line)] This is a log from kamailio to Homer");
+...
+hlog("$hdr(P-MyID)", "Another one with a custom correlation ID");
+...
+
+5. RPC Commands
+
+   5.1. siptrace.status param
+
+5.1.  siptrace.status param
+
+   Name: siptrace.status
+
+   Parameters:
+     * on or off: turns on/off SIP message tracing. Possible values are:
+          + on
+          + off
+     * “check” does not change siptrace status, just reports the current
+       status.
+
+   RPC Command Format:
+...
+kamcmd siptrace.status on
+kamcmd siptrace.status off
+kamcmd siptrace.status check
+...
+
+6. Database setup
+
+   Before running Kamailio with siptrace, you have to setup the database
+   tables where the module will store the data. For that, if the table
+   were not created by the installation script or you choose to install
+   everything by yourself you can use the siptrace-create.sql SQL script
+   in the database directories in the kamailio/scripts folder as template.
+   You can also find the complete database documentation on the project
+   webpage,
+   https://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
+
+7. Known issues
+
+   Stateless forwarded messages (forward()) are not logged if you set the
+   flag, use sip_trace() inside onsend_route block.
+
+   If dialog level tracing is used internally generated BYE transaction(in
+   case of internal timeouts) won't be traced. At the moment kamailio
+   offers no posibility to trace those messages.
+
+   Trace_info xavp name is reserved by this module. Any use of xavp with
+   this name will result in overlapping internal avp used by the module
+   therefore causing unknown consequences.
+
+   Example 1.24. Send relayed ACK message
+...
+onsend_route {
+    if (is_method("ACK")) {
+        sip_trace();
+    }
+}
+...