
SipTrace Module

Daniel-Constantin Mierla

   voice-system.ro

Edited by

Daniel-Constantin Mierla

   Copyright  2006 voice-system.ro
     _________________________________________________________

   Table of Contents
   1. User's Guide

        1.1. Overview
        1.2. Dependencies

              1.2.1. OpenSER Modules
              1.2.2. External Libraries or Applications

        1.3. Exported Parameters

              1.3.1. db_url (str)
              1.3.2. table (str)
              1.3.3. trace_flag (integer)
              1.3.4. trace_on (integer)
              1.3.5. traced_user_avp (integer)
              1.3.6. duplicate_uri (str)

        1.4. Exported Functions

              1.4.1. sip_trace()

        1.5. sip_trace table definition
        1.6. Known issues

   2. Developer's Guide
   3. Frequently Asked Questions

   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 trace_on parameter
   1-6. Set duplicate_uri parameter
   1-7. sip_trace() usage
   1-8. sip_trace sql
     _________________________________________________________

Chapter 1. User's Guide

1.1. Overview

   Offer a possibility to store incoming/outgoing SIP messages in
   database.

   There are two ways of storing information.

     * by calling explicitely the sip_trace() method in OpenSER
       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 fifo commad.

   openserctl fifo sip_trace on

   openserctl fifo sip_trace off
     _________________________________________________________

1.2. Dependencies

1.2.1. OpenSER Modules

   The following modules must be loaded before this module:

     * database module - mysql, postrgress, dbtext, unixodbc...
     * tm and sl modules - optional, only if you want to trace
       messages forwarded by these modules.
     _________________________________________________________

1.2.2. External Libraries or Applications

   The following libraries or applications must be installed
   before running OpenSER with this module loaded:

     * None.
     _________________________________________________________

1.3. Exported Parameters

1.3.1. db_url (str)

   Database URL.

   Default value is "". 

   Example 1-1. Set db_url parameter
...
modparam("siptrace", "db_url", "mysql://user:passwd@host/dbname")
...
     _________________________________________________________

1.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")
...
     _________________________________________________________

1.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)
...
     _________________________________________________________

1.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)
...
     _________________________________________________________

1.3.5. traced_user_avp (integer)

   The ID 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 "6843". 

   Example 1-5. Set trace_on parameter
...
modparam("siptrace", "traced_user_avp", 123)
...
     _________________________________________________________

1.3.6. 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-6. Set duplicate_uri parameter
...
modparam("siptrace", "duplicate_uri", "sip:10.1.1.1:5888")
...
     _________________________________________________________

1.4. Exported Functions

1.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-7. sip_trace() usage
...
sip_trace();
...
     _________________________________________________________

1.5. sip_trace table definition

   Next is presented the definition of sip_trace table

   Example 1-8. sip_trace sql
CREATE TABLE `sip_trace` (
  `id` bigint(20) NOT NULL auto_increment,
  `date` datetime NOT NULL default '0000-00-00 00:00:00',
  `callid` varchar(254) NOT NULL default '',
  `traced_user` varchar(128) NOT NULL default '',
  `msg` text NOT NULL,
  `method` varchar(50) NOT NULL default '',
  `status` varchar(254) NOT NULL default '',
  `fromip` varchar(50) NOT NULL default '',
  `toip` varchar(50) NOT NULL default '',
  `fromtag` varchar(64) NOT NULL default '',
  `direction` varchar(4) NOT NULL default '',
  PRIMARY KEY  (`id`),
  INDEX user_idx (traced_user),
  INDEX date_id (date),
  INDEX ip_idx (fromip),
  KEY `call_id` (`callid`)
);
     _________________________________________________________

1.6. Known issues

   Stateless forwarded messages (forward()) are not logged if you
   set the flag, use sip_trace().
     _________________________________________________________

Chapter 2. Developer's Guide

   The module does not provide any API to use in other OpenSER
   modules.
     _________________________________________________________

Chapter 3. Frequently Asked Questions

   3.1. Where can I find more about OpenSER?
   3.2. Where can I post a question about this module?
   3.3. How can I report a bug?

   3.1. Where can I find more about OpenSER?

   Take a look at http://openser.org/.

   3.2. Where can I post a question about this module?

   First at all check if your question was already answered on
   one of our mailing lists:

     * User Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/users
     * Developer Mailing List -
       http://openser.org/cgi-bin/mailman/listinfo/devel

   E-mails regarding any stable OpenSER release should be sent to
   <users@openser.org> and e-mails regarding development versions
   should be sent to <devel@openser.org>.

   If you want to keep the mail private, send it to
   <team@openser.org>.

   3.3. How can I report a bug?

   Please follow the guidelines provided at:
   http://sourceforge.net/tracker/?group_id=139143.
