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.

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.

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 }

Metrics

Network flow data is stored as journal records, not as traditional metrics. Use the Network Flows view in the Netdata dashboard to query and visualize flow data. For the full list of fields and the per-protocol availability matrix, see the Field Reference. For visualisation guidance see Sankey and Table, Time-Series, and Maps and Globe.

Alerts

There are no alerts configured by default for this integration.

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.