mirror of https://github.com/sipwise/kamailio.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
474 lines
12 KiB
474 lines
12 KiB
SipTrace Module
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
<miconda@gmail.com>
|
|
|
|
Edited by
|
|
|
|
Alexandr Dubovikov
|
|
|
|
<alexandr.dubovikov@gmail.com>
|
|
|
|
Edited by
|
|
|
|
Daniel-Constantin Mierla
|
|
|
|
<miconda@gmail.com>
|
|
|
|
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)
|
|
|
|
4. Functions
|
|
|
|
4.1. sip_trace()
|
|
|
|
5. MI Commands
|
|
|
|
5.1. sip_trace
|
|
|
|
6. RPC Commands
|
|
|
|
6.1. siptrace.status param
|
|
|
|
7. Database setup
|
|
8. 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. sip_trace() usage
|
|
|
|
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)
|
|
|
|
4. Functions
|
|
|
|
4.1. sip_trace()
|
|
|
|
5. MI Commands
|
|
|
|
5.1. sip_trace
|
|
|
|
6. RPC Commands
|
|
|
|
6.1. siptrace.status param
|
|
|
|
7. Database setup
|
|
8. Known issues
|
|
|
|
1. Overview
|
|
|
|
Offer a possibility to store incoming and outgoing SIP messages in a
|
|
database and/or duplicate to the capturing server (using the Homer
|
|
encapsulation protocol or plain SIP mode)
|
|
|
|
There are two ways of storing information.
|
|
* by calling explicitely the sip_trace() method in Kamailio
|
|
configuration file. In this case the original message is processed.
|
|
* by setting the flag equal with the value of 'trace_flag' (e.g.,
|
|
setflag(__trace_flag__)) parameter of the module. In this case, the
|
|
message sent forward is processed. The logging mechanism is based
|
|
on TM/SL callbacks, so only messages processed with TM/SL are
|
|
logged.
|
|
|
|
The tracing can be turned on/off using Kamailio mi or 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 loaded before this module:
|
|
* database module - Mysql, Postgres, dbtext, unixODBC...
|
|
* 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.1. db_url (str)
|
|
|
|
Database URL.
|
|
|
|
Default value is "mysql://kamailio:kamailiorw@localhost/okamailio".
|
|
|
|
Example 1.1. Set db_url parameter
|
|
...
|
|
modparam("siptrace", "db_url", "mysql://user:passwd@host/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
|
|
|
|
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 '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 exists, and must have the same structure as
|
|
'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 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 local 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. Now SL module is able to run an event
|
|
route when such 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 to relay
|
|
the information over more then 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 HEP protocol. Can be 1 or 2. In
|
|
HEPv2 the timestamp and capture agent ID will be included to HEP
|
|
header.
|
|
|
|
Default value is "1".
|
|
|
|
Example 1.14. Set hep_version parameter
|
|
...
|
|
modparam("siptrace", "hep_version", 2)
|
|
...
|
|
|
|
3.15. hep_capture_id (integer)
|
|
|
|
The parameter indicate the capture agent ID for HEPv2 protocol.
|
|
Limitation: 16-bit integer.
|
|
|
|
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)
|
|
...
|
|
|
|
4. Functions
|
|
|
|
4.1. sip_trace()
|
|
|
|
4.1. sip_trace()
|
|
|
|
Store current processed SIP message in database. It is stored in the
|
|
form prior applying chages made to it.
|
|
|
|
This function can be used from REQUEST_ROUTE, FAILURE_ROUTE,
|
|
ONREPLY_ROUTE, BRANCH_ROUTE.
|
|
|
|
Example 1.17. sip_trace() usage
|
|
...
|
|
sip_trace();
|
|
...
|
|
|
|
5. MI Commands
|
|
|
|
5.1. sip_trace
|
|
|
|
5.1. sip_trace
|
|
|
|
Name: sip_trace
|
|
|
|
Parameters:
|
|
* trace_mode : turns on/off SIP message tracing. Possible values are:
|
|
+ on
|
|
+ off
|
|
The parameter is optional - if missing, the command will return the
|
|
status of the SIP message tracing (as string "on" or "off" )
|
|
without changing anything.
|
|
|
|
MI FIFO Command Format:
|
|
:sip_trace:_reply_fifo_file_
|
|
trace_mode
|
|
_empty_line_
|
|
|
|
6. RPC Commands
|
|
|
|
6.1. siptrace.status param
|
|
|
|
6.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.
|
|
|
|
7. 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, http://www.kamailio.org/docs/db-tables/kamailio-db-devel.html.
|
|
|
|
8. Known issues
|
|
|
|
Stateless forwarded messages (forward()) are not logged if you set the
|
|
flag, use sip_trace().
|