diff --git a/src/modules/siptrace/README b/src/modules/siptrace/README index 139597f9cb0..749c89ea650 100644 --- a/src/modules/siptrace/README +++ b/src/modules/siptrace/README @@ -1,2 +1,596 @@ +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 sip_trace 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 all traffic. + + The tracing can be turned on/off using Kamailio RPC commands. + + kamctl fifo sip_trace on + + kamctl fifo sip_trace 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 sip_trace 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(i:123)") +modparam("siptrace", "traced_user_avp", "$avp(s: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. It uses UDP all the time. + + 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 set to 1, the module uses core events triggered when receiving or + sending SIP traffic to mirror traffic to a SIP capture server using + HEP. It will automatically do the mirroring 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 there mirroring is duplicated. + + If set to 0, no automatic mirroring of SIP traffic via HEP. + + Default value is 0. + + Example 1.18. Set trace_mode parameter +... +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][,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(); + } +} +...