@cryptotaxi247 / netdata
Code Commits Issues Pulls Sessions CI/CD
master
master
md 164 lines 5.37 KB
Rendered Raw
1 <!--startmeta
2 custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/integrations/netflow.md"
3 meta_yaml: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/metadata.yaml"
4 sidebar_label: "NetFlow"
5 learn_status: "Published"
6 learn_rel_path: "Network Flows/Flow Protocols"
7 keywords: ['netflow', 'netflow v5', 'netflow v7', 'netflow v9', 'cisco', 'flows', 'network flows', 'flow collector']
8 message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE FLOWS' metadata.yaml FILE"
9 endmeta-->
10
11 <!-- markdownlint-disable-file -->
12
13 # NetFlow
14
15
16 <img src="https://netdata.cloud/img/network-wired.svg" width="150"/>
17
18
19 Plugin: netflow-plugin
20 Module: netflow
21
22 <img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />
23
24 ## Overview
25
26 Collect network flow records from NetFlow v5, v7, and v9 exporters such as
27 routers, switches, and firewalls. Each record exposes source and destination IP,
28 ports, protocol, bytes, packets, ToS, TCP flags, and ingress/egress interface indices.
29 Enrichment adds GeoIP country/city/ASN, static metadata, and classifier tags.
30
31 For full documentation including vendor configuration examples, sampling caveats, template
32 handling and verification steps, see the [Network Flows Overview](https://learn.netdata.cloud/docs/network-flows/).
33
34
35 The plugin listens on a configurable UDP socket for NetFlow datagrams.
36 NetFlow v5 and v7 records are decoded directly. NetFlow v9 records are decoded using
37 dynamic templates cached from the exporter. Decoded records are enriched in-memory
38 and appended to disk-backed journal tiers (raw, 1-minute, 5-minute, 1-hour rollups).
39
40
41 This integration is only supported on the following platforms:
42
43 - Linux
44
45 This integration runs as a single instance per Netdata Agent.
46
47
48 ### Default Behavior
49
50 #### Auto-Detection
51
52 The plugin starts when enabled in netflow.yaml and listens on the configured UDP port.
53
54 #### Limits
55
56 Operational limits are driven by sustained flows/s, cardinality, retention, storage speed, and enrichment. Plan around 25k sustained flows/s per well-provisioned agent for the full raw + rollup pipeline; use distributed agents for larger deployments.
57
58 #### Performance Impact
59
60 Disabled until exporters send traffic. Once active, CPU and disk I/O scale with flow rate and cardinality; size retention and storage from observed flows/s.
61
62 ## Setup
63
64
65 ### Prerequisites
66
67 #### NetFlow-capable exporter
68
69 A router, switch, or firewall configured to export NetFlow v5, v7, or v9 datagrams to the
70 Netdata agent's UDP listener.
71
72
73
74 ### Configuration
75
76 #### Options
77
78 The plugin is configured via `netflow.yaml` in the Netdata configuration directory.
79
80
81 <details open><summary>Config options</summary>
82
83
84
85 | Option | Description | Default | Required |
86 |:-----|:------------|:--------|:---------:|
87 | listener.listen | UDP endpoint for NetFlow datagrams. | 0.0.0.0:2055 | no |
88 | protocols.v5 | Enable NetFlow v5 decoding. | yes | no |
89 | protocols.v7 | Enable NetFlow v7 decoding. | yes | no |
90 | protocols.v9 | Enable NetFlow v9 decoding. | yes | no |
91 | journal.journal_dir | Directory for journal files (relative to NETDATA_CACHE_DIR). | flows | no |
92 | journal.tiers.&lt;tier&gt;.size_of_journal_files | Per-tier hard size cap. Replace `<tier>` with `raw`, `minute_1`, `minute_5`, or `hour_1`. Set to `null` for time-only retention. | 10GB | no |
93 | journal.tiers.&lt;tier&gt;.duration_of_journal_files | Per-tier maximum age. Replace `<tier>` with `raw`, `minute_1`, `minute_5`, or `hour_1`. Set to `null` for size-only retention. | 7d | no |
94
95
96 </details>
97
98
99
100 #### via File
101
102 The configuration file name for this integration is `netflow.yaml`.
103
104
105 You can edit the configuration file using the [`edit-config`](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#edit-configuration-files) script from the
106 Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).
107
108 ```bash
109 cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
110 sudo ./edit-config netflow.yaml
111 ```
112
113 ##### Examples
114
115 ###### Basic NetFlow v5/v9 collection
116
117 Listen on Netdata's default flow listener port for v5 and v9 records.
118
119 ```yaml
120 enabled: true
121 listener:
122 listen: "0.0.0.0:2055"
123 protocols:
124 v5: true
125 v9: true
126
127 ```
128 ###### NetFlow v9 only with extended retention
129
130 Accept only v9 records, keep one day of raw data, and keep longer rollups.
131
132 <details open><summary>Config</summary>
133
134 ```yaml
135 enabled: true
136 listener:
137 listen: "0.0.0.0:2055"
138 protocols:
139 v5: false
140 v7: false
141 v9: true
142 journal:
143 journal_dir: flows
144 tiers:
145 raw: { size_of_journal_files: 50GB, duration_of_journal_files: 24h }
146 minute_1: { size_of_journal_files: 10GB, duration_of_journal_files: 14d }
147 minute_5: { size_of_journal_files: 10GB, duration_of_journal_files: 30d }
148 hour_1: { size_of_journal_files: 10GB, duration_of_journal_files: 365d }
149
150 ```
151 </details>
152
153
154
155 ### Verifying flow data is arriving and diagnosing failures
156
157 See [Troubleshooting](https://learn.netdata.cloud/docs/network-flows/troubleshooting) for
158 the full diagnostic recipe -- including UDP path checks, template-error analysis,
159 and the "looks like a bug but isn't" section (doubling, mirroring, internal-IP geolocation).
160 See also [Validation and Data Quality](https://learn.netdata.cloud/docs/network-flows/validation-and-data-quality)
161 and [Anti-patterns](https://learn.netdata.cloud/docs/network-flows/anti-patterns).
162
163
164