NetFlow

Plugin: netflow-plugin Module: netflow

Overview

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.

For full documentation including vendor configuration examples, sampling caveats, template handling and verification steps, see the Network Flows Overview.

The plugin listens on a configurable UDP socket for NetFlow datagrams. NetFlow v5 and v7 records are decoded directly. NetFlow v9 records are decoded using dynamic templates cached from the exporter. Decoded records are enriched in-memory and appended to disk-backed journal tiers (raw, 1-minute, 5-minute, 1-hour rollups).

This integration is only supported on the following platforms:

• Linux

This integration runs as a single instance per Netdata Agent.

Default Behavior

Auto-Detection

The plugin starts when enabled in netflow.yaml and listens on the configured UDP port.

Limits

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.

Performance Impact

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.

Setup

Prerequisites

NetFlow-capable exporter

A router, switch, or firewall configured to export NetFlow v5, v7, or v9 datagrams to the Netdata agent's UDP listener.

Configuration

Options

The plugin is configured via netflow.yaml in the Netdata configuration directory.

Config options

Option	Description	Default	Required
listener.listen	UDP endpoint for NetFlow datagrams.	0.0.0.0:2055	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
journal.journal_dir	Directory for journal files (relative to NETDATA_CACHE_DIR).	flows	no
journal.tiers.<tier>.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
journal.tiers.<tier>.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

via File

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

Examples

Basic NetFlow v5/v9 collection

Listen on Netdata's default flow listener port for v5 and v9 records.

enabled: true
listener:
  listen: "0.0.0.0:2055"
protocols:
  v5: true
  v9: true

NetFlow v9 only with extended retention

Accept only v9 records, keep one day of raw data, and keep longer rollups.

Config

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 }

Verifying flow data is arriving and diagnosing failures

See Troubleshooting for the full diagnostic recipe -- including UDP path checks, template-error analysis, and the "looks like a bug but isn't" section (doubling, mirroring, internal-IP geolocation). See also Validation and Data Quality and Anti-patterns.