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

src/modules/siptrace/README

@@ -1,607 +1,2 @@
-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_mode (integer)
-              3.19. 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_mode parameter
-   1.19. Set auth_key parameter
-   1.20. sip_trace() usage
-   1.21. sip_trace_mode() usage
-   1.22. hlog() usage
-   1.23. 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_mode (integer)
-        3.19. 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_mode (integer)
-   3.19. 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_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.18. Set trace_mode parameter
-...
-modparam("siptrace", "trace_on", 1)
-modparam("siptrace", "trace_mode", 1)
-...
-modparam("siptrace", "trace_mode", 3)
-...
-
-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][,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.20. 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.21. 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.22. 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.23. Send relayed ACK message
-...
-onsend_route {
-    if (is_method("ACK")) {
-        sip_trace();
-    }
-}
-...