# &adminguide;

## 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.

## Dependencies

### &kamailio; Modules

The following modules must be loaded before this module:

- none.

### External Libraries or Applications

The following libraries or applications must be installed before running &kamailio; with this module loaded:

- none

## Parameters

### `enable` (int)

Enable sipdump activity.

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

#### Set `enable` parameter

    ...
    modparam("sipdump", "enable", 1)
    ...

### `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).

#### Set `mode` parameter

    ...
    modparam("sipdump", "mode", 3)
    ...

### `wait` (int)

Wait time (microseconds) when no SIP traffic is received (for wait_time = 0).

Default value is 100.

#### Set `wait` parameter

    ...
    modparam("sipdump", "wait", 2000)
    ...

### `wait_mode` (int)

If set to 1, the module uses a pthread mutex and contion to signal when SIP messages are available to the writer process. It should use less CPU when idle (on no SIP traffic) than the default polling on timer, but be sure that the OS supports process-shared pthread mutexes and conditions (latest Linux distros have support for them).

Default value is 0.

#### Set `wait_mode` parameter

    ...
    modparam("sipdump", "wait_mode", 1)
    ...

### `rotate` (int)

Time interval in seconds to rotate files.

Default value is 7200 (2 hours).

#### Set `rotate` parameter

    ...
    modparam("sipdump", "rotate", 3600)
    ...

### `folder` (str)

Path to the folder where to save the files.

Default value is "/tmp".

#### Set `folder` parameter

    ...
    modparam("sipdump", "folder", "/run/kamailio")
    ...

### `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-".

#### Set `fprefix` parameter

    ...
    modparam("sipdump", "fprefix", "ksipdump-")
    ...

### `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).

#### Set `fage` parameter

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

### `fagex` (str)

Age as a time expression for the created files to be removed if they become older. It overwrites the 'fage' parameter. The value can be numbers followed by time units: d - days; h - hours; m - minutes; s - seconds.

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

#### Set `fagex` parameter

    ...
    # cleanup files older than 2 days
    modparam("sipdump", "fagex", "2d")

    # cleanup files older than 2 days, 6 hours, 40 minutes and 30 seconds
    modparam("sipdump", "fagex", "2d6h40m30s")
    ...

### `event_callback` (str)

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

Default value is not set.

#### 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
    ...

## Functions

### `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.

#### `sipdump_send` usage

    ...
    sipdump_send("cfg");
    ...

## RPC Commands

### `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.

#### `sipdump.enable` usage

    ...
    &kamctl; rpc sipdump.enable
    &kamctl; rpc sipdump.enable 1
    &kamctl; rpc sipdump.enable 0
    ...

## Event Routes

### `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");
    }
    ...

## 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 +2 -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.