Tutorial: Tranalyzer2 and Plugins Configuration

Introduction

Tranalyzer2 and the plugins can be independently configured by editing various header files (typically pluginName/src/pluginName.h). Most flags are boolean, i.e., on or off. In this case, a 0 is used to indicate the feature is off, while a 1 means it is active. The available configuration flags and their default values are described in the documentation and in the header files.

There are several ways to change a value. The first one uses the t2conf script while the second one requires to edit the header file directly. Both methods are discussed below through two very simple examples, namely activating the alarm mode (Tranalyzer2 configuration) and activating the compression of the text output (plugin configuration).

Configuring Tranalyzer2

In the example below, we will activate the alarm mode of Tranalyzer2. This mode is controlled by the ALARM_MODE flag. Note that when changing a value in the core, it is recommended to recompile all the plugins as well (hence the t2build -R below!). While not always required, this helps to avoid incompatibility between the core and the plugins.

Using t2conf

  • To activate the alarm mode using t2conf, simply run the following command:

    $ t2conf tranalyzer2 -D ALARM_MODE=1
    $
  • To deactivate it, run the same command but with the value 0 instead of 1.

    $ t2conf tranalyzer2 -D ALARM_MODE=0
    $
  • Finally, do not forget to rebuild Tranalyzer2 and the plugins:

    $ t2build -R
    ...
    $
  • The current value of a flag can be checked with t2conf -G:

    $ t2conf tranalyzer2 -G ALARM_MODE
    ALARM_MODE = 0
    $
  • A list of the available configuration flags can be obtained with t2conf -I (note however that the list may not present all available options):

    $ t2conf tranalyzer2 -I
    ...
    ALARM_MODE
    ALARM_AND
    ...
    $

By Manually Editing the Value in the Header File

  1. First you need to identify the file in which the flag is defined:

    $ cd $T2HOME/tranalyzer2/src
    $ grep 'define ALARM_MODE' *.h
    tranalyzer.h:#define ALARM_MODE 0 // only flow output if an Alarm based plugin fires
    $
  2. Then you can edit its value directly in the header file:

    $ vi tranalyzer.h
    ....
    #define ALARM_MODE 1 // only flow output if an Alarm based plugin fires
    ...
    $
  3. Finally, do not forget to rebuild Tranalyzer2 and the plugins:

    $ t2build -R
    ...
    $

Configuring a Plugin

The same methods can be used to configure a plugin. In the example below, we will activate the compression of the text output in the txtSink plugin. The compression is controlled by the GZ_COMPRESS flag.

Using t2conf

There are several option to configure T2 and the plugins.

  • edit the .h files
  • t2conf command line
  • t2conf GUI

Editing the .h files is the most direct way, also suitable for developers. Nevertheless, often people are afraid to break something so t2conf is the way to go; either the command line or GUI.

In our tutorials we teach the 1. and 2. option, because they are faster in practice.

  • To activate the compression of the text output using t2conf, simply run the following command:

    $ t2conf txtSink -D GZ_COMPRESS=1
  • To deactivate it, run the same command but with the value 0 instead of 1.

    $ t2conf txtSink -D GZ_COMPRESS=0
  • Finally, do not forget to rebuild the plugin:

    $ t2build txtSink
    ...
    $
  • The current value of a flag can be checked with t2conf -G:

    $ t2conf txtSink -G GZ_COMPRESS
    GZ_COMPRESS = 0
    $
  • A list of the available configuration flags can be obtained with t2conf -I (note however that the list may not present all available options):

    $ t2conf txtSink -I
    TFS_SPLIT
    TFS_PRI_HDR
    TFS_HDR_FILE
    TFS_PRI_HDR_FW
    GZ_COMPRESS
    FLOWS_TXT_SUFFIX
    HEADER_SUFFIX
    $

By Manually Editing the Value in the Header File

  1. First you need to identify the file in which the flag is defined:

    $ cd $T2HOME/plugins/txtSink/src
    $ grep GZ_COMPRESS *.h
    #define GZ_COMPRESS    0 // Whether or not to compress the output (gzip)
    $

    Note that the grep command does not return the name of the file in which GZ_COMPRESS was found… This is simply because there is only a single .h file in the txtSink/src folder (the -H option of grep could be used to output the file name in which the text was found regardless of the number of .h files)

  2. Then you can edit the value of GZ_COMPRESS directly in the header file:

    $ vi txtSink.h
    ....
    #define GZ_COMPRESS    1 // Whether or not to compress the output (gzip)
    ...
    $
  3. Finally, do not forget to rebuild the plugin:

    $ t2build txtSink
    ...
    $

Special Cases

Some configuration flags, e.g., format of IPv4/6 addresses, are shared between Tranalyzer2 and the plugins and reside in the $T2HOME/utils folder.

Using t2conf

This is transparently handled by t2conf. Note however that t2conf -I may not report those flags. When modifying a shared configuration flag, it is recommended to rebuild Tranalyzer2 and the plugins using t2build -R.

By Manually Editing the Value in the Header File

If you want to manually edit the header files and your grep command does not return any result, it could be that the flag is actually defined in one of the header files in the utils folder. To handle those cases, modify your grep command to also search the utils folder. For example to locate the IP4_FORMAT, use the following command:

$ cd $T2HOME
$ grep -A4 'define IP4_FORMAT' tranalyzer2/src/*.h utils/*.h
utils/bin2txt.h:#define IP4_FORMAT             0 // IPv4 addresses representation:
utils/bin2txt.h-                                 //     0: normal
utils/bin2txt.h-                                 //     1: normalized (padded with zeros)
utils/bin2txt.h-                                 //     2: hexadecimal
utils/bin2txt.h-                                 //     3: uint32
$

Note that the -A4 option is used to display the four lines coming directly after the matched text and is included to show the different values accepted by IP4_FORMAT.

Finally, when modifying a shared configuration flag, it is recommended to rebuild Tranalyzer2 and the plugins using t2build -R.

t2conf GUI

Using t2conf GUI is straightforward and self explantory, just invoke:

$ t2conf

You will see the following screen, where you can select the plugins to be added with your mouse.

t2conf
t2conf

If you want to edit a configuration, use the arrow keys or your mouse and hit Configure

t2conf
t2conf

Set the constants by selecting it with the arrow keys and Configure. Don’t forget to save with OK and recompile with Build.

Getting Help with t2conf

$ t2conf --help
...
$