2017-11-27 10:42:54 -08:00
|
|
|
# VERMONT - VERsatile MONitoring Tool
|
2010-06-10 05:50:25 -07:00
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
[![Build Status](https://travis-ci.org/tumi8/vermont.svg?branch=master)](https://travis-ci.org/tumi8/vermont)
|
|
|
|
|
|
|
|
Vermont is an open-source software toolkit for the creation and processing of network flow data, based on monitored Internet packet data.
|
|
|
|
See the [Wiki](https://github.com/tumi8/vermont/wiki) for full details of all its features.
|
|
|
|
|
|
|
|
## REQUIREMENTS
|
2010-06-10 05:50:25 -07:00
|
|
|
|
|
|
|
VERMONT has been tested on Linux and FreeBSD systems.
|
|
|
|
|
|
|
|
For compilation, GNU C/C++ compiler and standard libraries are required,
|
|
|
|
as well as the following Ubuntu/Debian packages (or equivalent packages
|
|
|
|
of other Linux distributions):
|
|
|
|
- cmake
|
|
|
|
- libboost-filesystem-dev
|
|
|
|
- libboost-regex-dev
|
|
|
|
- libboost-test-dev
|
2014-07-01 07:28:36 -07:00
|
|
|
- libboost-thread-dev
|
2010-06-10 05:50:25 -07:00
|
|
|
- libxml2-dev
|
|
|
|
- libpcap-dev
|
|
|
|
- libsctp-dev (if not available, disable cmake option SUPPORT_SCTP)
|
|
|
|
|
|
|
|
The following packages are optional:
|
|
|
|
- cmake-curses-gui (ccmake, interactive user interface of cmake)
|
2014-07-31 04:55:23 -07:00
|
|
|
- libpq-dev (for PostgreSQL support)
|
|
|
|
==> cmake option SUPPORT_POSTGRESQL
|
2010-06-10 05:50:25 -07:00
|
|
|
- libmysqlclient-dev (for MySQL support)
|
|
|
|
==> cmake option SUPPORT_MYSQL
|
|
|
|
- libgsl-dev (for connection-based sampling with Bloom filters)
|
|
|
|
==> cmake option USE_GSL
|
2015-06-05 03:17:37 -07:00
|
|
|
- libczmq-dev (for receiving IPFIX reports over ZMQ)
|
|
|
|
==> cmake option SUPPORT_ZMQ
|
2010-06-10 05:50:25 -07:00
|
|
|
|
2017-06-19 07:02:23 -07:00
|
|
|
For DTLS support, OpenSSL 1.0.0 is required.
|
2010-06-10 05:50:25 -07:00
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
## BUILDING AND INSTALLATION
|
2010-06-10 05:50:25 -07:00
|
|
|
|
|
|
|
This project uses cmake for setting platform- and user-specific compile
|
|
|
|
options. In order to generate the Makefile for actual compilation, you
|
|
|
|
need to call in the root of the source directory:
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2010-06-10 05:50:25 -07:00
|
|
|
$ cmake .
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-06-10 05:50:25 -07:00
|
|
|
|
|
|
|
In order to change the default compile options, use:
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2010-06-10 05:50:25 -07:00
|
|
|
$ cmake -D OPTION1=value1 -D OPTION2=value2 ...
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-06-10 05:50:25 -07:00
|
|
|
|
|
|
|
To get a list of the most important options, call:
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2010-06-10 05:50:25 -07:00
|
|
|
$ cmake -LH
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
|
|
|
|
2010-07-08 09:18:26 -07:00
|
|
|
As a user-friendly alternative, you can use the interactive user interface.
|
|
|
|
Please note that this requires the package cmake-curses-gui, if you are using
|
2010-07-14 07:32:47 -07:00
|
|
|
Ubuntu/Debian.
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2010-06-10 05:50:25 -07:00
|
|
|
$ ccmake .
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-06-10 05:50:25 -07:00
|
|
|
|
|
|
|
If some libraries are installed in custom directories, use:
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2010-06-10 05:50:25 -07:00
|
|
|
$ cmake -D CMAKE_PREFIX_PATH=/custom/directory1:/custom/directory2
|
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
|
|
|
|
2010-06-10 05:50:25 -07:00
|
|
|
After successfully generating the Makefile with cmake, start the
|
|
|
|
compilation with:
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2010-06-10 05:50:25 -07:00
|
|
|
$ make
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-06-10 05:50:25 -07:00
|
|
|
|
|
|
|
Although not strictly necessary, VERMONT binaries and data files can be
|
|
|
|
copied to the usual install location by running:
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2010-06-10 05:50:25 -07:00
|
|
|
$ make install
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-06-10 05:50:25 -07:00
|
|
|
|
2010-07-08 09:18:26 -07:00
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
### BUILDING WITH DTLS-OVER-UDP SUPPORT
|
2010-07-08 09:18:26 -07:00
|
|
|
|
2017-06-19 07:02:23 -07:00
|
|
|
VERMONT's DTLS support is based on OpenSSL version 1.0.0. OpenSSL 1.1.0 is not currently supported.
|
2010-07-08 09:18:26 -07:00
|
|
|
|
2017-06-19 07:02:23 -07:00
|
|
|
In order to compile VERMONT with DTLS-over-UDP support set the following option:
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2017-06-19 07:02:23 -07:00
|
|
|
$ cmake -DSUPPORT_DTLS=YES
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-07-08 09:18:26 -07:00
|
|
|
|
2017-06-19 07:02:23 -07:00
|
|
|
If CMake does not find OPENSSL you can explicitly specify the include and library paths:
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2017-06-19 07:02:23 -07:00
|
|
|
cmake -DSUPPORT_DTLS=YES -DCMAKE_INCLUDE_PATH=/path/to/openssl/include -DCMAKE_LIBRARY_PATH=/path/to/openssl/lib
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-07-14 07:32:47 -07:00
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
### BUILDING WITH DTLS-OVER-SCTP SUPPORT
|
2010-07-14 07:32:47 -07:00
|
|
|
|
|
|
|
At the time of writing (July 2010), DTLS over SCTP can be used on FreeBSD only!
|
|
|
|
This is due to the fact that FreeBSD is currently the only OS which supports
|
|
|
|
the SCTP-AUTH extension (see RFC 4895) which is required by DTLS.
|
|
|
|
|
|
|
|
The current version of OpenSSL (1.0.0a) has no native support for SCTP. You
|
|
|
|
have to download additional patches from
|
2010-07-08 09:18:26 -07:00
|
|
|
|
|
|
|
http://sctp.fh-muenster.de/
|
|
|
|
|
2010-07-14 07:32:47 -07:00
|
|
|
and apply them to the OpenSSL sourcese before building OpenSSL. Make sure that
|
|
|
|
the patches fit to your local version of OpenSSL. Otherwise, you might need to
|
|
|
|
manually adapt the patch files.
|
2010-07-08 09:18:26 -07:00
|
|
|
|
|
|
|
Also, make sure to add the command line argument "sctp" when running OpenSSL's
|
|
|
|
./config to build SCTP support into OpenSSL.
|
|
|
|
|
2010-07-14 07:32:47 -07:00
|
|
|
In order to compile VERMONT with DTLS-over-SCTP support, you need to run cmake
|
|
|
|
with the following three options:
|
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
`-DSUPPORT_SCTP -DSUPPORT_DTLS -DSUPPORT_DTLS_OVER_SCTP`
|
2010-07-14 07:32:47 -07:00
|
|
|
|
|
|
|
In addition, you need to indicate the include and library paths to your patched
|
|
|
|
version of OpenSSL as explained for DTLS-over-UDP.
|
|
|
|
|
2010-06-10 05:50:25 -07:00
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
## USAGE AND CONFIGURATION
|
2010-06-10 05:50:25 -07:00
|
|
|
|
|
|
|
In order to run VERMONT, a configuration file is needed which specifies the
|
|
|
|
modules to be used and their parameters:
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2010-06-10 05:50:25 -07:00
|
|
|
$ ./vermont -f <config-file>
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-06-10 05:50:25 -07:00
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
Example configuration files can be found in [`configs/`](config).
|
|
|
|
Documentation of the available modules and their configuration parameters
|
|
|
|
can be found at https://github.com/tumi8/vermont/wiki/Moduleconfiguration
|
2010-06-10 05:50:25 -07:00
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
Use `Ctrl-C` to stop VERMONT. If VERMONT does not exit properly, enter Ctrl-C
|
2010-06-10 05:50:25 -07:00
|
|
|
for a second time.
|
|
|
|
|
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
## OPERATION AS COLLECTOR: TUNING SOCKET RECEIVE BUFFER
|
2010-06-10 05:50:25 -07:00
|
|
|
|
|
|
|
VERMONT can be used as an IPFIX/PSAMP and NetFlow.v9 collector. As the
|
|
|
|
incoming IPFIX/PSAMP/NetFlow messages usually arrive in bursts, losses
|
|
|
|
may occur due to insufficient buffer space.
|
|
|
|
|
|
|
|
As a solution, the socket receive buffer can be increased. To check the
|
|
|
|
current settings, use the following system calls on Linux systems with
|
2017-11-27 10:42:54 -08:00
|
|
|
`/proc` file system:
|
|
|
|
``` shell
|
2010-06-10 05:50:25 -07:00
|
|
|
$ cat /proc/sys/net/core/rmem_default
|
|
|
|
$ cat /proc/sys/net/core/rmem_max
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-06-10 05:50:25 -07:00
|
|
|
|
|
|
|
In order to configure a new value X (in bytes), call:
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2010-06-10 05:50:25 -07:00
|
|
|
$ sysctl -w net/core/rmem_default=X
|
|
|
|
$ sysctl -w net/core/rmem_max=X
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-06-10 05:50:25 -07:00
|
|
|
|
2014-09-04 07:43:17 -07:00
|
|
|
If you want Vermont to use a different buffer size than the default one,
|
2017-11-27 10:42:54 -08:00
|
|
|
you can specify it using the `<buffer>` directive in the `<listener>` section.
|
2014-09-04 07:43:17 -07:00
|
|
|
|
2010-06-10 05:50:25 -07:00
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
## OPTIMIZED PACKET CAPTURING WITH PCAP
|
2010-06-10 05:50:25 -07:00
|
|
|
|
|
|
|
To reduce the number of times packets need to be copied on their way from
|
|
|
|
the network interface card to the user space (i.e., VERMONT), we recommend
|
|
|
|
the utilization of pcap library 1.0.0 or higher.
|
|
|
|
|
|
|
|
For earlier versions of pcap, the pcap-mmap patch can be applied to
|
|
|
|
improve the performance: http://public.lanl.gov/cpw/
|
|
|
|
|
2010-06-23 07:40:52 -07:00
|
|
|
|
2017-11-27 10:42:54 -08:00
|
|
|
## EFFECTS OF RECEIVE OFFLOAD MECHANISMS
|
2010-06-23 07:40:52 -07:00
|
|
|
|
|
|
|
Several mechanisms have been implemented in modern network interface cards,
|
|
|
|
drivers, and kernels to offload common functions from the protocol stack and
|
|
|
|
the application. One particular focus is on TCP segmentation and reassembly.
|
|
|
|
|
|
|
|
Receive offload mechanisms aim at reassembling subsequent TCP segments into
|
|
|
|
a single large packet before passing it to the IP/TCP protocol stack and
|
|
|
|
finally to the application. In the Linux kernel, this is done by generic
|
|
|
|
receive offload (GRO) if the network interface card and the driver support
|
|
|
|
NAPI. Latest Intel 10GE controllers (e.g., 82599) support receive side
|
|
|
|
coalescing (RSC) which performs TCP reassembly in hardware.
|
|
|
|
|
|
|
|
If any receive offload mechanism is enabled, VERMONT (like any other
|
|
|
|
pcap-based application) does not observe the actually captured TCP packets
|
|
|
|
but the reassembled ones. One consequence is that packet counts of flows will
|
|
|
|
be smaller than the true number of packets.
|
|
|
|
|
|
|
|
In order to avoid such distortions, all receive offload mechanisms need to
|
|
|
|
be disabled. In the case of GRO (and the older LRO), this can be done with
|
|
|
|
ethtool. The following call returns a list of the current status of all
|
|
|
|
offload mechanisms for interface <dev>:
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2010-06-23 07:40:52 -07:00
|
|
|
$ ethtool -k <dev>
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-06-23 07:40:52 -07:00
|
|
|
|
|
|
|
If GRO is not shown, you probably need to install a newer version of ethtool.
|
|
|
|
To disable GRO (and LRO), execute:
|
2017-11-27 10:42:54 -08:00
|
|
|
``` shell
|
2010-06-23 07:40:52 -07:00
|
|
|
$ ethtool -K <dev> gro off
|
|
|
|
$ ethtool -K <dev> lro off
|
2017-11-27 10:42:54 -08:00
|
|
|
```
|
2010-06-23 07:40:52 -07:00
|
|
|
|
|
|
|
Hardware-based RSC can be deactivated at compile time of the driver as
|
|
|
|
explained here:
|
|
|
|
http://downloadmirror.intel.com/19004/eng/README-2.0.72.4.txt
|
|
|
|
|