diff --git a/src/modules/siptrace/README b/src/modules/siptrace/README index ea4eae3b19d..139597f9cb0 100644 --- a/src/modules/siptrace/README +++ b/src/modules/siptrace/README @@ -1,607 +1,2 @@ -SipTrace Module -Daniel-Constantin Mierla - - -Edited by - -Alexandr Dubovikov - - - -Daniel-Constantin Mierla - - - -Giacomo Vacca - - - -Camille Oudot - - - - 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(); - } -} -...