Tranalyzer2 and plugins configuration

configuration t2conf

Introduction
Configuring Tranalyzer2
- Using t2conf
- By manually editing the value in the header file
Configuring a plugin
Resetting tranalyzer2 or a plugin configuration
Special cases
- Using t2conf
- By manually editing the value in the header file
t2conf GUI
Getting help with t2conf

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
...
```
The configuration of tranalyzer2 can be reset to its default value with t2conf --reset option:

t2conf tranalyzer2 --reset
The configuration of tranalyzer2 can be saved with t2conf -g option:

t2conf tranalyzer2 -g
```
Successfully generated configuration file '/home/user/tranalyzer2-0.9.1/tranalyzer2/tranalyzer2.config'
```
Alternatively a different filename can be chosen:

t2conf tranalyzer2 -g /home/user/.tranalyzer/tranalyzer2.config
```
Successfully generated configuration file '/home/user/.tranalyzer/tranalyzer2.config'
```
A saved configuration can be loaded with t2conf -C option:

t2conf tranalyzer2 -C /home/user/.tranalyzer/tranalyzer2.config

Alternatively if the default filename was chosen:

t2conf tranalyzer2 -C auto

By manually editing the value in the header file

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

cd $T2HOME/tranalyzer2/

grep -HF 'define ALARM_MODE' src/*.h
```
src/tranalyzer.h:#define ALARM_MODE 0 // only flow output if an Alarm based plugin fires
```

Then you can edit its value directly in the header file:

vi src/tranalyzer.h

...
#define ALARM_MODE 1 // only flow output if an Alarm based plugin fires
...

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 TFS_GZ_COMPRESS flag.

Using t2conf

There are several options to configure T2 and the plugins.

Edit the .h files
t2conf command line
t2conf GUI
Use environment variables

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 TFS_GZ_COMPRESS=1
To deactivate it, run the same command but with the value 0 instead of 1.

t2conf txtSink -D TFS_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 TFS_GZ_COMPRESS
```
TFS_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
TFS_GZ_COMPRESS
TFS_FLOWS_TXT_SUFFIX
TFS_HEADER_SUFFIX
...
```
The configuration of a plugins can be reset to its default value with t2conf --reset option:

t2conf txtSink --reset

The configuration of a plugin can be saved with t2conf -g option:

t2conf txtSink -g


Successfully generated configuration file '/home/user/tranalyzer2-0.9.1/plugins/txtSink/txtSink.config'

Alternatively a different filename can be chosen:

t2conf txtSink -g /home/user/.tranalyzer/txtSink.config


Successfully generated configuration file '/home/user/.tranalyzer/plugins/txtSink.config'

A saved configuration can be loaded with t2conf -C option:

t2conf txtSink -C /home/user/.tranalyzer/txtSink.config

Alternatively if the default filename was chosen:

t2conf txtSink -C auto

By manually editing the value in the header file

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

cd $T2HOME/plugins/txtSink

grep -HF 'define TFS_GZ_COMPRESS' src/*.h
```
src/txtSink.h:#define TFS_GZ_COMPRESS    0 // Whether or not to compress the output (gzip)
```

Then you can edit the value of TFS_GZ_COMPRESS directly in the header file:

vi src/txtSink.h

...
#define TFS_GZ_COMPRESS    1 // Whether or not to compress the output (gzip)
...

Finally, do not forget to rebuild the plugin:

t2build txtSink

Using environment variables

A list of the available environment configuration flags can be obtained with t2conf -E:

t2conf txtSink -E
```
TFS_FLOWS_TXT_SUFFIX
TFS_HEADER_SUFFIX
```
A list of the environment configuration flags currently set can be obtained with t2conf -e:

t2conf txtSink -e
```
TFS_HEADER_SUFFIX = _new_suffix.txt
```
To edit a configuration flag using environment variables, simply run the following command:

export TFS_HEADER_SUFFIX="_new_suffix.txt"

Your next call to t2 in the same terminal will use the exported values (note that you do not need to rebuild the plugins).
An alternative is to configure the variables at the same time as your call to t2:

TFS_HEADER_SUFFIX="_new_suffix.txt" t2 -r file.pcap

Once again, rebuilding the plugin is not necessary.
To reset an environment variable, run:

unset TFS_HEADER_SUFFIX

Resetting tranalyzer2 or a plugin configuration

The configuration of tranalyzer2 and/or the plugins can be reset to its default value with the following command:

t2conf --reset tranalyzer2

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 explanatory, just invoke:

t2conf --gui

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

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

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

Tranalyzer2 and plugins configuration

Contents

Introduction

Configuring Tranalyzer2

Using t2conf

By manually editing the value in the header file

Configuring a plugin

Using t2conf

By manually editing the value in the header file

Using environment variables

Resetting tranalyzer2 or a plugin configuration

Special cases

Using t2conf

By manually editing the value in the header file

t2conf GUI

Getting help with t2conf