SIPDUMP Module

Daniel-Constantin Mierla

   <miconda@gmail.com>

Edited by

Daniel-Constantin Mierla

   <miconda@gmail.com>

   Copyright © 2017 asipto.com
     __________________________________________________________________

   Table of Contents

   1. Admin Guide

        1. Overview
        2. Dependencies

              2.1. Kamailio Modules
              2.2. External Libraries or Applications

        3. Parameters

              3.1. enable (int)
              3.2. mode (int)
              3.3. wait (int)
              3.4. rotate (int)
              3.5. folder (str)
              3.6. fprefix (str)
              3.7. fage (int)
              3.8. event_callback (str)

        4. Functions

              4.1. sipdump_send(tag)

        5. RPC Commands

              5.1. sipdump.enable

        6. Event Routes

              6.1. sipdump:msg

        7. Usage Remarks

   List of Examples

   1.1. Set enable parameter
   1.2. Set mode parameter
   1.3. Set wait parameter
   1.4. Set rotate parameter
   1.5. Set folder parameter
   1.6. Set fprefix parameter
   1.7. Set fage parameter
   1.8. Set event_callback parameter
   1.9. sipdump_send usage
   1.10. sipdump.enable 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. enable (int)
        3.2. mode (int)
        3.3. wait (int)
        3.4. rotate (int)
        3.5. folder (str)
        3.6. fprefix (str)
        3.7. fage (int)
        3.8. event_callback (str)

   4. Functions

        4.1. sipdump_send(tag)

   5. RPC Commands

        5.1. sipdump.enable

   6. Event Routes

        6.1. sipdump:msg

   7. Usage Remarks

1. Overview

   This module writes SIP traffic and some associated details into local
   files. It intercepts automatically all the SIP traffic received or sent
   by Kamailio and provides a function to trigger storage from
   configuration file.

   Received traffic has the tag 'rcv' and the one to be sent has the tag
   'snd'. The tag value is provided as parameter for the config function.

   Besides the SIP packets, the module aims to save details related to
   Kamailio runtime environment that are useful for troubleshooting, like
   process id, child rank, a.s.o.

   The module should be useful for troubleshooting during development or
   testing of new deployments, especially when dealing with traffic over
   TLS with forward privacy, when other tools such as wireshark cannot
   decrypt. For production environments with a lot of SIP traffic, look at
   siptrace and sipcapture modules for a scalable alternative to capture
   all the SIP traffic and then search using Homer Sipcapture web toolkit.

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:
     * none.

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. enable (int)
   3.2. mode (int)
   3.3. wait (int)
   3.4. rotate (int)
   3.5. folder (str)
   3.6. fprefix (str)
   3.7. fage (int)
   3.8. event_callback (str)

3.1. enable (int)

   Enable sipdump activity.

   Default value is 0 (0 - off; 1 - on).

   Example 1.1. Set enable parameter
...
modparam("sipdump", "enable", 1)
...

3.2. mode (int)

   Set the type of activity done by the module, the value can be set based
   on flags index: 0 (value 1) - write to text files; 1 (value 2) -
   execute event route; 2 (value 4) - write to pcap files; 3 (value 8) -
   insert the P-KSR-SIPDump header with meta data inside the SIP message
   written in pcap file.

   To enable several activity modes, set the parameter to the sum of
   corresponding values.

   Default value is 1 (write to text files).

   Example 1.2. Set mode parameter
...
modparam("sipdump", "mode", 3)
...

3.3. wait (int)

   Wait time (microseconds) when no SIP traffic is received.

   Default value is 100.

   Example 1.3. Set wait parameter
...
modparam("sipdump", "wait", 2000)
...

3.4. rotate (int)

   Time interval in seconds to rotate files.

   Default value is 7200 (2 hours).

   Example 1.4. Set rotate parameter
...
modparam("sipdump", "rotate", 3600)
...

3.5. folder (str)

   Path to the folder where to save the files.

   Default value is "/tmp".

   Example 1.5. Set folder parameter
...
modparam("sipdump", "folder", "/run/kamailio")
...

3.6. fprefix (str)

   File name prefix. The date is appended to this prefix in the format
   yyyy-mm-dd--hh-mm-ss. The extension of the text file is ".data", of the
   meta file is ".meta" and of the pcap file is ".pcap".

   Default value is "kamailio-sipdump-".

   Example 1.6. Set fprefix parameter
...
modparam("sipdump", "fprefix", "ksipdump-")
...

3.7. fage (int)

   Age of created files (in seconds) to be removed if they become older.
   Cleanup is done on a timer routine running every 600 seconds.

   Default value is 0 (no cleanup of created files).

   Example 1.7. Set fage parameter
...
# cleanup files older than two days
modparam("sipdump", "fage", 172800)
...

3.8. event_callback (str)

   Name of the KEMI function to be executed instead of the event route.

   Default value is not set.

   Example 1.8. Set event_callback parameter
...
modparam("sipdump", "event_callback", "ksr_sipdump_event")
...
-- event callback function implemented in Lua
function ksr_sipdump_event(evname)
        KSR.info("===== sipdump module triggered event: " .. evname .. "\n");
        return 1;
end
...

4. Functions

   4.1. sipdump_send(tag)

4.1.  sipdump_send(tag)

   Send the details of the current SIP message to the writer process and
   get it stored in the file.

   The parameter "tag" can be any string, it is going to be written in the
   tag attribute inside the storage file.

   This function can be used from ANY_ROUTE.

   Example 1.9. sipdump_send usage
...
sipdump_send("cfg");
...

5. RPC Commands

   5.1. sipdump.enable

5.1.  sipdump.enable

   Control the value for "enable" parameter.

   If no value is provided to this command, the value of "enable"
   parameter is returned.

   This function can be used from ANY_ROUTE.

   Example 1.10. sipdump.enable usage
...
kamcmd sipdump.enable
kamcmd sipdump.enable 1
kamcmd sipdump.enable 0
...

6. Event Routes

   6.1. sipdump:msg

6.1.  sipdump:msg

   Executed when sipdump handles messages and mode parameter has flag 2
   set. The variable $sipdump(...) is available inside the event route.

   If drop() is used in event_route, then writing to file is no longer
   done when mode parameter has also the flag 1 set.
...
event_route[sipdump:msg] {
    xinfo("[$sipdump(tag)] [[$sipdump(buf)]]\n");
}
...

7. Usage Remarks

   Note that the files with the SIP traffic and metadata are not deleted
   by the module itself. They have to be deleted explicitely by other
   means, such as cron.d job, or using rtimer and exec modules. Next
   examples shows how to delete the files older than 2 days using Kamailio
   modules.
...
loadmodule "rtimer.so"
loadmodule "exec.so"
...
modparam("rtimer", "timer", "name=tjobs;interval=300;mode=1;")
modparam("rtimer", "exec", "timer=tjobs;route=TCLEAN")
...
route[TCLEAN] {
    exec_cmd("find /tmp -type f -name kamailio-sipdump-* -mtime +1 -delete &");
}
...

   If operational mode is set to write the pcap files, note that packets
   in the pcap file are generated always with transport UDP, no matter the
   SIP traffic was over another transport layer like TCP, TLS, SCTP or
   WSS. The headers of the SIP message (e.g., Via, Route) should provide
   hints about what the SIP transport layer.