src/crates/netflow-plugin/integrations/netflow.md
Plugin: netflow-plugin Module: netflow
Collect network flow records from NetFlow v5, v7, and v9 exporters such as routers, switches, and firewalls. Each record exposes source and destination IP, ports, protocol, bytes, packets, ToS, TCP flags, and ingress/egress interface indices. Enrichment adds GeoIP country/city/ASN, static metadata, and classifier tags.
Cisco ASA NSEL over NetFlow v9 is recognized automatically. Event-5 interval updates become directional traffic rows; create, teardown, deny, malformed, and counterless events remain diagnostics and do not enter the flow database.
For full documentation including vendor configuration examples, sampling caveats, template handling and verification steps, see the Network Flows Overview.
The plugin listens on configurable UDP listener sockets for NetFlow datagrams. NetFlow v5 and v7 records are decoded directly. NetFlow v9 records are decoded using dynamic templates cached from the exporter and persisted across restarts. Validated Cisco ASA NSEL templates automatically activate event-aware directional decoding. Decoded records are enriched in-memory and appended to disk-backed journal tiers (raw, 1-minute, 5-minute, 1-hour rollups).
This integration is supported on all platforms.
This integration runs as a single instance per Netdata Agent.
The stock configuration enables the plugin and listens on the configured UDP ports.
Operational limits are driven by sustained flow records/s, exporter batching, cardinality, retention, storage speed, and enrichment. On modern hardware with fast storage, plan around 50k-100k sustained flow records/s per well-provisioned agent for the full raw + rollup pipeline, provided the underlying disks can sustain the required journal write activity; use distributed agents for larger deployments.
Disabled until exporters send traffic. Once active, CPU and disk I/O scale with flow-record rate, template volume, and cardinality; size retention and storage from observed flow records/s.
A router, switch, or firewall configured to export NetFlow v5, v7, or v9 datagrams to the Netdata agent's UDP listener.
The plugin is configured via netflow.yaml in the Netdata configuration directory.
| Option | Description | Default | Required |
|---|---|---|---|
| listener.listen | UDP listener endpoints for NetFlow/IPFIX and sFlow datagrams. YAML accepts either a scalar endpoint or a list of endpoints; CLI accepts repeated --netflow-listen flags or comma-delimited values. | 0.0.0.0:2055, 0.0.0.0:6343 | no |
| protocols.v5 | Enable NetFlow v5 decoding. | yes | no |
| protocols.v7 | Enable NetFlow v7 decoding. | yes | no |
| protocols.v9 | Enable NetFlow v9 decoding. | yes | no |
| protocols.v9_template_lifetime | Maximum age of a NetFlow v9 template since its last template refresh. Set to null to disable expiry; zero is invalid. | 90m | no |
| protocols.sampling_cache_max_entries | Maximum learned NetFlow v9/IPFIX sampling-rate entries across all exporter streams. Must be positive. | 100000 | no |
| protocols.sampling_cache_max_entries_per_stream | Maximum learned sampling-rate entries for one exporter stream. Must be positive; values above the global limit are clamped. | 65536 | no |
| journal.journal_dir | Directory for journal files (relative to NETDATA_CACHE_DIR). | flows | no |
| journal.tiers.<tier>.size_of_journal_files | Per-tier retained-artifact budget for journal data and finalized per-journal facet sidecars. Replace <tier> with raw, minute_1, minute_5, or hour_1. The protected active journal can temporarily exceed the budget. Set to null for time-only retention. | 10GB | no |
| journal.tiers.<tier>.duration_of_journal_files | Per-tier maximum age. Replace <tier> with raw, minute_1, minute_5, or hour_1. The default null disables time-based eviction; set a duration to add an age cap. | null | no |
The configuration file name for this integration is netflow.yaml.
You can edit the configuration file using the edit-config script from the
Netdata config directory.
cd /etc/netdata 2>/dev/null || cd /opt/netdata/etc/netdata
sudo ./edit-config netflow.yaml
Use Netdata's stock listener set for v5 and v9 records.
enabled: true
listener:
listen:
- "0.0.0.0:2055"
- "0.0.0.0:6343"
protocols:
v5: true
v9: true
Accept only v9 records, keep one day of raw data, and keep longer rollups.
<details open><summary>Config</summary>enabled: true
listener:
listen: "0.0.0.0:2055"
protocols:
v5: false
v7: false
v9: true
journal:
journal_dir: flows
tiers:
raw: { size_of_journal_files: 50GB, duration_of_journal_files: 24h }
minute_1: { size_of_journal_files: 10GB, duration_of_journal_files: 14d }
minute_5: { size_of_journal_files: 10GB, duration_of_journal_files: 30d }
hour_1: { size_of_journal_files: 10GB, duration_of_journal_files: 365d }
See Troubleshooting for the full diagnostic recipe -- including UDP path checks, template-error analysis, Cisco ASA NSEL event handling, and the "looks like a bug but isn't" section (doubling, mirroring, internal-IP geolocation). See also Validation and Data Quality and Anti-patterns.