modules_k/siptrace/README
c0c67b7e
 SipTrace Module
 
 Daniel-Constantin Mierla
 
d34518a2
    <miconda@gmail.com>
 
c0c67b7e
 Edited by
 
 Daniel-Constantin Mierla
 
d34518a2
    <miconda@gmail.com>
 
c0c67b7e
    Copyright � 2006 voice-system.ro
d77df08a
    Revision History
0ded7f06
    Revision $Revision$ $Date: 2008-08-06 12:08:33 +0200
989206bd
                               (Mi, 06 Aug 2008) $
      __________________________________________________________
c0c67b7e
 
    Table of Contents
d77df08a
 
9fc784c6
    1. Admin Guide
c0c67b7e
 
         1.1. Overview
         1.2. Dependencies
 
37e4f522
               1.2.1. Kamailio Modules
c0c67b7e
               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)
90691771
               1.3.5. traced_user_avp (str)
               1.3.6. trace_table_avp (str)
               1.3.7. duplicate_uri (str)
               1.3.8. trace_local_ip (str)
c0c67b7e
 
         1.4. Exported Functions
 
989206bd
               1.4.1. sip_trace()
c0c67b7e
 
1061d103
         1.5. Exported MI Functions
 
989206bd
               1.5.1. sip_trace
1061d103
 
431b3a97
         1.6. Database setup
1061d103
         1.7. Known issues
c0c67b7e
 
    List of Examples
d77df08a
 
    1.1. Set db_url parameter
    1.2. Set sip_trace parameter
    1.3. Set trace_flag parameter
    1.4. Set trace_on parameter
0b4e4b59
    1.5. Set traced_user_avp parameter
    1.6. Set trace_table_avp parameter
d77df08a
    1.7. Set duplicate_uri parameter
    1.8. Set trace_local_ip parameter
    1.9. sip_trace() usage
c0c67b7e
 
9fc784c6
 Chapter 1. Admin Guide
c0c67b7e
 
 1.1. Overview
 
    Offer a possibility to store incoming/outgoing SIP messages in
    database.
 
    There are two ways of storing information.
9b64b9f3
      * by calling explicitely the sip_trace() method in Kamailio
c0c67b7e
        configuration file. In this case the original message is
        processed.
      * by setting the flag equal with the value of 'trace_flag'
989206bd
        (e.g., setflag(__trace_flag__)) parameter of the module. In
        this case, the\ message sent forward is processed. The
c0c67b7e
        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.
 
bb30e4a8
    kamctl fifo sip_trace on
c0c67b7e
 
bb30e4a8
    kamctl fifo sip_trace off
c0c67b7e
 
 1.2. Dependencies
 
37e4f522
 1.2.1. Kamailio Modules
c0c67b7e
 
    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
37e4f522
    before running Kamailio with this module loaded:
c0c67b7e
      * None.
 
 1.3. Exported Parameters
 
 1.3.1. db_url (str)
 
    Database URL.
 
989206bd
    Default value is "".
c0c67b7e
 
d77df08a
    Example 1.1. Set db_url parameter
c0c67b7e
 ...
 modparam("siptrace", "db_url", "mysql://user:passwd@host/dbname")
 ...
 
 1.3.2. table (str)
 
    Name of the table where to store the SIP messages.
 
989206bd
    Default value is "sip_trace".
c0c67b7e
 
d77df08a
    Example 1.2. Set sip_trace parameter
c0c67b7e
 ...
 modparam("siptrace", "table", "strace")
 ...
 
 1.3.3. trace_flag (integer)
 
    Which flag is used to mark messages to trace
 
989206bd
    Default value is "0".
c0c67b7e
 
d77df08a
    Example 1.3. Set trace_flag parameter
c0c67b7e
 ...
 modparam("siptrace", "trace_flag", 22)
 ...
 
 1.3.4. trace_on (integer)
 
    Parameter to enable/disable trace (on(1)/off(0))
 
989206bd
    Default value is "0".
c0c67b7e
 
d77df08a
    Example 1.4. Set trace_on parameter
c0c67b7e
 ...
 modparam("siptrace", "trace_on", 1)
 ...
 
90691771
 1.3.5. traced_user_avp (str)
030d88e7
 
90691771
    The name of the AVP storing the SIP URI of the traced user. If
030d88e7
    the AVP is set, messages are stored in database table and
    'traced_user' column is filled with AVP's value. You can store
989206bd
    the message many times for many users by having multiple values
    for this AVP.
030d88e7
 
989206bd
    Default value is "NULL" (feature disabled).
030d88e7
 
0b4e4b59
    Example 1.5. Set traced_user_avp parameter
030d88e7
 ...
4392d2e9
 modparam("siptrace", "traced_user_avp", "$avp(i:123)")
 modparam("siptrace", "traced_user_avp", "$avp(s:user)")
030d88e7
 ...
 
90691771
 1.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'
989206bd
    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.
90691771
 
989206bd
    Default value is "NULL" (feature disabled).
90691771
 
0b4e4b59
    Example 1.6. Set trace_table_avp parameter
90691771
 ...
4392d2e9
 modparam("siptrace", "trace_table_avp", "$avp(i:345)")
 modparam("siptrace", "trace_table_avp", "$avp(s:siptrace_table)")
90691771
 ...
 
 1.3.7. duplicate_uri (str)
c0c67b7e
 
    The address in form of SIP uri where to send a duplicate of
    traced message. It uses UDP all the time.
 
989206bd
    Default value is "NULL".
c0c67b7e
 
d77df08a
    Example 1.7. Set duplicate_uri parameter
c0c67b7e
 ...
 modparam("siptrace", "duplicate_uri", "sip:10.1.1.1:5888")
 ...
 
90691771
 1.3.8. trace_local_ip (str)
d1053847
 
    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.
 
989206bd
    Default value is "NULL".
d1053847
 
d77df08a
    Example 1.8. Set trace_local_ip parameter
d1053847
 ...
 modparam("siptrace", "trace_local_ip", "10.1.1.1:5064")
 ...
 
c0c67b7e
 1.4. Exported Functions
 
d77df08a
 1.4.1.  sip_trace()
c0c67b7e
 
    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.
 
d77df08a
    Example 1.9. sip_trace() usage
c0c67b7e
 ...
2be93baa
 sip_trace();
c0c67b7e
 ...
 
1061d103
 1.5. Exported MI Functions
 
d77df08a
 1.5.1.  sip_trace
1061d103
 
    Name: sip_trace
 
    Parameters:
      * trace_mode : turns on/off SIP message tracing. Possible
        values are:
           + on
           + off
24e12c20
        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.
1061d103
 
    MI FIFO Command Format:
                 :sip_trace:_reply_fifo_file_
                 trace_mode
                 _empty_line_
 
431b3a97
 1.6. Database setup
 
37e4f522
    Before running Kamailio with siptrace, you have to setup the
989206bd
    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.
c0c67b7e
 
1061d103
 1.7. Known issues
c0c67b7e
 
    Stateless forwarded messages (forward()) are not logged if you
    set the flag, use sip_trace().