forked from tumi8/vermont
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathREADME
271 lines (187 loc) · 9.41 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
This is VERMONT - VERsatile MONitoring Tool.
Released under GPL2
Project website: http://vermont.berlios.de
------------
REQUIREMENTS
------------
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
- 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)
- libpq-dev (for PostGreSQL support)
==> cmake option SUPPORT_PGSQL
- libmysqlclient-dev (for MySQL support)
==> cmake option SUPPORT_MYSQL
- libgsl-dev (for connection-based sampling with Bloom filters)
==> cmake option USE_GSL
For DTLS support, OpenSSL 1.0.0 or higher is required. It is recommended
to build OpenSSL based on the latest CVS revision. See DTLS instructions below.
-------------------------
BUILDING AND INSTALLATION
-------------------------
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:
$ cmake .
In order to change the default compile options, use:
$ cmake -D OPTION1=value1 -D OPTION2=value2 ...
To get a list of the most important options, call:
$ cmake -LH
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
Ubuntu/Debian.
$ ccmake .
If some libraries are installed in custom directories, use:
$ cmake -D CMAKE_PREFIX_PATH=/custom/directory1:/custom/directory2
After successfully generating the Makefile with cmake, start the
compilation with:
$ make
Although not strictly necessary, VERMONT binaries and data files can be
copied to the usual install location by running:
$ make install
-----------------------------------
BUILDING WITH DTLS-OVER-UDP SUPPORT
-----------------------------------
VERMONT's DTLS support is based on OpenSSL version 1.0.0 (and maybe higher).
Since the DTLS implementation in OpenSSL is fairly new and not as mature as
the TLS/SSL implementation, you should use the latest version of OpenSSL which
you can get from
http://openssl.org/source/
At the time of writing (July 2010), the latest version is 1.0.0a.
$ wget http://openssl.org/source/openssl-1.0.0a.tar.gz
$ tar xzf openssl-1.0.0a.tar.gz
$ cd openssl-1.0.0a/
If you want to profit from the most recent bugfixes, you can check out the
sources from the OpenSSL CVS repository instead:
$ cvs -z9 -d [email protected]:/openssl-cvs co openssl
$ cd openssl/
In order to avoid incompatibilities with other packages of your distribution,
you probably do not want the new version of OpenSSL to become the default
OpenSSL library on your system. Therefore, it is recommended to install the
new version in a local directory by using the --prefix option of the config
script.
To build OpenSSL and install it into a built/ subdirectory within the OpenSSL
source directory, call the following commands:
$ ./config -d no-dso no-shared --prefix=`pwd`/built
$ make
$ make install
The configure option "no-dso" turns off the use of shared-library methods which
avoids linking problems related to libdl on the Linux platform.
With the option "no-shared", only static libraries are built which makes it
easier to link VERMONT to the correct version of OpenSSL.
In order to compile VERMONT with DTLS-over-UDP support, change into the root
of VERMONT's source directory and execute cmake with the OpenSSL include and
library paths (replace "/path/to/openssl" by your OpenSSL source directory):
$ cmake -DSUPPORT_DTLS=YES -DCMAKE_INCLUDE_PATH=/path/to/openssl/built/include -DCMAKE_LIBRARY_PATH=/path/to/openssl/built/lib
On 64 bit platforms, the library path might be different (mind the "64" at the
very end!):
$ cmake -DSUPPORT_DTLS=YES -DCMAKE_INCLUDE_PATH=/path/to/openssl/built/include -DCMAKE_LIBRARY_PATH=/path/to/openssl/built/lib64
If you have previously built VERMONT with OpenSSL located in another
directory, you might need to manually remove the file CMakeCache.txt before
calling cmake.
After cmake has finished, you should be able to build VERMONT with
DTLS-over-UDP support by calling
$ make
Please read the next section if you require support for DTLS over SCTP as well.
------------------------------------
BUILDING WITH DTLS-OVER-SCTP SUPPORT
------------------------------------
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
http://sctp.fh-muenster.de/
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.
Also, make sure to add the command line argument "sctp" when running OpenSSL's
./config to build SCTP support into OpenSSL.
In order to compile VERMONT with DTLS-over-SCTP support, you need to run cmake
with the following three options:
-DSUPPORT_SCTP
-DSUPPORT_DTLS
-DSUPPORT_DTLS_OVER_SCTP
In addition, you need to indicate the include and library paths to your patched
version of OpenSSL as explained for DTLS-over-UDP.
-----------------------
USAGE AND CONFIGURATION
-----------------------
In order to run VERMONT, a configuration file is needed which specifies the
modules to be used and their parameters:
$ ./vermont -f <config-file>
Example configuration files can be found in configs/.
A documentation of the available modules and their configuration parameters
can be found at http://vermont.berlios.de/vermont_module_configuration .
A snapshot of this file is located at docs/config/.
Use Ctrl-C to stop VERMONT. If VERMONT does not exit properly, enter Ctrl-C
for a second time.
--------------------------------------
TRAFFIC CAPTURING AT VLAN MIRROR PORTS
--------------------------------------
VERMONT can be used to capture traffic at a mirror port of a switch. If
the mirror port is configured for VLAN traffic, the Ethernet frames will
usually include a VLAN tag in the Ethernet header, increasing the header
length from 14 to 18 bytes.
In order to capture such traffic correctly, you need to set the cmake
option IP_HEADER_OFFSET to 18. Furthermore, make sure that the observer
is configured with <pap_filter> parameter set to "vlan and ip".
----------------------------------------------------
OPERATION AS COLLECTOR: TUNING SOCKET RECEIVE BUFFER
----------------------------------------------------
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
/proc file system:
$ cat /proc/sys/net/core/rmem_default
$ cat /proc/sys/net/core/rmem_max
In order to configure a new value X (in bytes), call:
$ sysctl -w net/core/rmem_default=X
$ sysctl -w net/core/rmem_max=X
------------------------------------
OPTIMIZED PACKET CAPTURING WITH PCAP
------------------------------------
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/
-------------------------------------
EFFECTS OF RECEIVE OFFLOAD MECHANISMS
-------------------------------------
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>:
$ ethtool -k <dev>
If GRO is not shown, you probably need to install a newer version of ethtool.
To disable GRO (and LRO), execute:
$ ethtool -K <dev> gro off
$ ethtool -K <dev> lro off
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