Skip to content

Commit ebfdf4e

Browse files
Lukas955Lukas955
committed
README: add example configuration files and sample IPFIX data
1 parent 869707e commit ebfdf4e

File tree

7 files changed

+303
-14
lines changed

7 files changed

+303
-14
lines changed

‎doc/data/configs/multiOutput.xml‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
<!--
2+
Receive flow data over TCP and store them in a nfdump compatible format on
3+
a local drive and simultaneously send to a remote host as JSON.
4+
-->
5+
<ipfixcol2>
6+
<!-- Input plugins -->
7+
<inputPlugins>
8+
<input>
9+
<name>TCP collector</name>
10+
<plugin>tcp</plugin>
11+
<params>
12+
<!-- List on port 4739 -->
13+
<localPort>4739</localPort>
14+
<!-- Bind to all local adresses -->
15+
<localIPAddress></localIPAddress>
16+
</params>
17+
</input>
18+
</inputPlugins>
19+
20+
<!-- Output plugins -->
21+
<outputPlugins>
22+
<output>
23+
<name>LNF output</name>
24+
<plugin>lnfstore</plugin>
25+
<params>
26+
<storagePath>/tmp/ipfixcol/lnf/</storagePath> <!-- WARNING: the directory MUST exist before start -->
27+
<compress>yes</compress>
28+
<dumpInterval>
29+
<timeWindow>300</timeWindow>
30+
<align>yes</align>
31+
</dumpInterval>
32+
</params>
33+
</output>
34+
35+
<output>
36+
<name>JSON output</name>
37+
<plugin>json</plugin>
38+
<params>
39+
<tcpFlags>formatted</tcpFlags>
40+
<timestamp>formatted</timestamp>
41+
<protocol>formatted</protocol>
42+
<ignoreUnknown>true</ignoreUnknown>
43+
<ignoreOptions>false</ignoreOptions>
44+
<nonPrintableChar>true</nonPrintableChar>
45+
46+
<!-- Output methods -->
47+
<outputs>
48+
<!-- Send to a remove host on IP address 127.0.0.1:8000 -->
49+
<send>
50+
<name>Send to a remove host</name>
51+
<ip>127.0.0.1</ip>
52+
<port>8000</port>
53+
<protocol>tcp</protocol>
54+
<blocking>no</blocking>
55+
</send>
56+
</outputs>
57+
</params>
58+
</output>
59+
</outputPlugins>
60+
</ipfixcol2>

‎doc/data/configs/odidFilter.xml‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
<!--
2+
Receive flow data over UDP and store flows from different ODIDs to different
3+
locations (multiple instances of the same output plugin)
4+
-->
5+
<ipfixcol2>
6+
<!-- Input plugins -->
7+
<inputPlugins>
8+
<input>
9+
<name>UDP collector</name>
10+
<plugin>udp</plugin>
11+
<params>
12+
<!-- List on port 4739 -->
13+
<localPort>4739</localPort>
14+
<!-- Bind to all local adresses -->
15+
<localIPAddress></localIPAddress>
16+
</params>
17+
</input>
18+
</inputPlugins>
19+
20+
<!-- Output plugins -->
21+
<outputPlugins>
22+
<output>
23+
<name>JSON output (ODID 1)</name>
24+
<plugin>json</plugin>
25+
<odidOnly>1</odidOnly> <!-- Process only flows with ODID 1 -->
26+
<params>
27+
<outputs>
28+
<file>
29+
<name>Store to files</name>
30+
<path>/tmp/ipfixcol/odid1/%Y/%m/%d/</path>
31+
<prefix>json.</prefix>
32+
<timeWindow>300</timeWindow>
33+
<timeAlignment>yes</timeAlignment>
34+
</file>
35+
</outputs>
36+
</params>
37+
</output>
38+
39+
<output>
40+
<name>JSON output (ODID 2-5)</name>
41+
<plugin>json</plugin>
42+
<odidOnly>2-5</odidOnly> <!-- Process only flows with ODID 2 - 5 -->
43+
<params>
44+
<outputs>
45+
<file>
46+
<name>Store to files</name>
47+
<path>/tmp/ipfixcol/odid2-5/%Y/%m/%d/</path>
48+
<prefix>json.</prefix>
49+
<timeWindow>300</timeWindow>
50+
<timeAlignment>yes</timeAlignment>
51+
</file>
52+
</outputs>
53+
</params>
54+
</output>
55+
56+
<output>
57+
<name>JSON output (ODID others)</name>
58+
<plugin>json</plugin>
59+
<odidExcept>1-5</odidExcept> <!-- Process only flows with ODID different from 1 - 5 -->
60+
<params>
61+
<outputs>
62+
<file>
63+
<name>Store to files</name>
64+
<path>/tmp/ipfixcol/odidOthers/%Y/%m/%d/</path>
65+
<prefix>json.</prefix>
66+
<timeWindow>300</timeWindow>
67+
<timeAlignment>yes</timeAlignment>
68+
</file>
69+
</outputs>
70+
</params>
71+
</output>
72+
</outputPlugins>
73+
</ipfixcol2>

‎doc/data/configs/tcp2anon2json.xml‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
<!--
2+
Receive flow data over TCP, anonymize them and store in JSON format
3+
on a local drive.
4+
-->
5+
<ipfixcol2>
6+
<!-- Input plugins -->
7+
<inputPlugins>
8+
<input>
9+
<name>TCP collector</name>
10+
<plugin>tcp</plugin>
11+
<params>
12+
<!-- List on port 4739 -->
13+
<localPort>4739</localPort>
14+
<!-- Bind to all local adresses -->
15+
<localIPAddress></localIPAddress>
16+
</params>
17+
</input>
18+
</inputPlugins>
19+
20+
<!-- Intermediate plugins -->
21+
<intermediatePlugins>
22+
<intermediate>
23+
<name>Flow anonymization</name>
24+
<plugin>anonymization</plugin>
25+
<params>
26+
<type>truncation</type>
27+
</params>
28+
</intermediate>
29+
</intermediatePlugins>
30+
31+
<!-- Output plugins -->
32+
<outputPlugins>
33+
<output>
34+
<name>JSON output</name>
35+
<plugin>json</plugin>
36+
<params>
37+
<tcpFlags>formatted</tcpFlags>
38+
<timestamp>formatted</timestamp>
39+
<protocol>formatted</protocol>
40+
<ignoreUnknown>true</ignoreUnknown>
41+
<ignoreOptions>false</ignoreOptions>
42+
<nonPrintableChar>true</nonPrintableChar>
43+
44+
<!-- Output methods -->
45+
<outputs>
46+
<!-- Store as files into /tmp/ipfixcol/... -->
47+
<file>
48+
<name>Store to files</name>
49+
<path>/tmp/ipfixcol/flow/%Y/%m/%d/</path>
50+
<prefix>json.</prefix>
51+
<timeWindow>300</timeWindow>
52+
<timeAlignment>yes</timeAlignment>
53+
</file>
54+
</outputs>
55+
</params>
56+
</output>
57+
</outputPlugins>
58+
</ipfixcol2>

‎doc/data/configs/tcpUdp2lnf.xml‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
<!--
2+
Receive flow data simultaneously over TCP and UDP and store them on a local
3+
drive in a nfdump compatible format (multiple instances of the same input
4+
plugin).
5+
-->
6+
<ipfixcol2>
7+
<!-- Input plugins -->
8+
<inputPlugins>
9+
<input>
10+
<name>TCP collector</name>
11+
<plugin>tcp</plugin>
12+
<params>
13+
<!-- List on port 4739 -->
14+
<localPort>4739</localPort>
15+
<!-- Bind to all local adresses -->
16+
<localIPAddress></localIPAddress>
17+
</params>
18+
</input>
19+
20+
<input>
21+
<name>UDP collector</name>
22+
<plugin>udp</plugin>
23+
<params>
24+
<!-- List on port 4739 -->
25+
<localPort>4739</localPort>
26+
<!-- Bind to all local adresses -->
27+
<localIPAddress></localIPAddress>
28+
</params>
29+
</input>
30+
</inputPlugins>
31+
32+
<!-- Output plugins -->
33+
<outputPlugins>
34+
<output>
35+
<name>LNF output</name>
36+
<plugin>lnfstore</plugin>
37+
<params>
38+
<storagePath>/tmp/ipfixcol/</storagePath> <!-- WARNING: the directory MUST exist before start -->
39+
<compress>yes</compress>
40+
<dumpInterval>
41+
<timeWindow>300</timeWindow>
42+
<align>yes</align>
43+
</dumpInterval>
44+
</params>
45+
</output>
46+
</outputPlugins>
47+
</ipfixcol2>

‎doc/data/configs/udp2json.xml‎

Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
<!--
2+
Receive flow data over UDP, convert them into JSON and provide them as
3+
a server on local port
4+
-->
5+
<ipfixcol2>
6+
<!-- Input plugins -->
7+
<inputPlugins>
8+
<input>
9+
<name>UDP collector</name>
10+
<plugin>udp</plugin>
11+
<params>
12+
<!-- List on port 4739 -->
13+
<localPort>4739</localPort>
14+
<!-- Bind to all local adresses -->
15+
<localIPAddress></localIPAddress>
16+
</params>
17+
</input>
18+
</inputPlugins>
19+
20+
<!-- Output plugins -->
21+
<outputPlugins>
22+
<output>
23+
<name>JSON output</name>
24+
<plugin>json</plugin>
25+
<params>
26+
<!-- JSON format paramters -->
27+
<tcpFlags>formatted</tcpFlags>
28+
<timestamp>formatted</timestamp>
29+
<protocol>formatted</protocol>
30+
<ignoreUnknown>false</ignoreUnknown>
31+
<ignoreOptions>true</ignoreOptions>
32+
<nonPrintableChar>true</nonPrintableChar>
33+
34+
<!-- Output methods -->
35+
<outputs>
36+
<!-- Create a local server on port 8000 -->
37+
<server>
38+
<name>Local server</name>
39+
<port>8000</port>
40+
<blocking>no</blocking>
41+
</server>
42+
</outputs>
43+
</params>
44+
</output>
45+
</outputPlugins>
46+
</ipfixcol2>

‎doc/data/ipfix/example_flows.ipfix‎

195 KB
Binary file not shown.

‎doc/sphinx/configuration.rst‎

Lines changed: 19 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -167,17 +167,17 @@ Example configuration files
167167
In this section you can see various example configuration files that demonstrate possibilities
168168
of IPFIXcol. Always keep in mind that you should modify a configuration to fit you needs.
169169

170-
:`udp2json <TODO>`_:
170+
:`udp2json <../data/configs/udp2json.xml>`_:
171171
Receive flow data over UDP, convert them into JSON and provide them as a server on local port.
172-
:`tcp2anon2json <TODO>`_:
172+
:`tcp2anon2json <../data/configs/tcp2anon2json.xml>`_:
173173
Receive flow data over TCP, anonymize them and store in JSON format on a local drive.
174-
:`tcpUdp2lnf <TODO>`_:
174+
:`tcpUdp2lnf <../data/configs/tcpUdp2lnf.xml>`_:
175175
Receive flow data simultaneously over TCP and UDP and store them on a local drive in
176-
a nfdump compatible format (multiple instances of the same input plugin).
177-
:`odidFilter <TODO>`_:
178-
Receive flow data over TCP and store flows from different ODIDs to different locations
176+
a nfdump compatible format (multiple instances of input plugins).
177+
:`odidFilter <../data/configs/odidFilter.xml>`_:
178+
Receive flow data over UDP and store flows from different ODIDs to different locations
179179
(multiple instances of the same output plugin).
180-
:`multiOutput <TODO>`_:
180+
:`multiOutput <../data/configs/multiOutput.xml>`_:
181181
Receive flow data over TCP and store them in a nfdump compatible format on a local drive
182182
and simultaneously send to a remote host as JSON.
183183

@@ -198,10 +198,11 @@ increasing verbosity level to see also warning messages (parameter "``-v``") dur
198198
Note: Receiving flow data from an exporter *over UDP transport
199199
protocol* may lead due to IPFIX protocol structure to a situation when the collector
200200
is unable to interpret data immediately after start.
201-
For more information, see documentation of `UDP <TODO>`_ plugin.
201+
For more information, see documentation of `UDP <../../src/plugins/input/udp>`_ plugin.
202202

203203
We prepared a file with few anonymized IPFIX flows, so you can try your configurations,
204-
even without running a flow exporter. Just download the `file <TODO>`_ and use ``ipfixsend2`` tool
204+
even without running a flow exporter. Just download the `file <../data/ipfix/example_flows.ipfix>`_
205+
and use ``ipfixsend2`` tool
205206
(distributed and installed together with IPFIXcol). For example, to send flow records over UDP
206207
protocol with real-time simulation use:
207208

@@ -254,8 +255,12 @@ shown below. The same approach applies to other types of instances too.
254255
255256
Available verbosity levels:
256257

257-
:none: Hide all messages
258-
:error: Show only error messages (i.e. something went really wrong)
259-
:warning: Show error and warning messages (i.e. something is not right, but an action can continue)
260-
:info: Show all previous types of messages and informational (status) messages
261-
:debug: Show all types of messages (i.e. include messages interesting only for developers)
258+
=========== =========================================================================================
259+
Verbosity Description
260+
=========== =========================================================================================
261+
``none`` Hide all messages
262+
``error`` Show only error messages (i.e. something went really wrong)
263+
``warning`` Show error and warning messages (i.e. something is not right, but an action can continue)
264+
``info`` Show all previous types of messages and informational (status) messages
265+
``debug`` Show all types of messages (i.e. include messages interesting only for developers)
266+
=========== =========================================================================================

0 commit comments

Comments
 (0)