<!--startmeta
custom_edit_url: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/integrations/netflow.md"
meta_yaml: "https://github.com/netdata/netdata/edit/master/src/crates/netflow-plugin/metadata.yaml"
sidebar_label: "NetFlow"
learn_status: "Published"
learn_rel_path: "Network Flows/Flow Protocols"
keywords: ['netflow', 'netflow v5', 'netflow v7', 'netflow v9', 'cisco', 'flows', 'network flows', 'flow collector']
message: "DO NOT EDIT THIS FILE DIRECTLY, IT IS GENERATED BY THE FLOWS' metadata.yaml FILE"
endmeta-->

<!-- markdownlint-disable-file -->

# NetFlow


<img src="https://netdata.cloud/img/network-wired.svg" width="150"/>


Plugin: netflow-plugin
Module: netflow

<img src="https://img.shields.io/badge/maintained%20by-Netdata-%2300ab44" />

## 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](https://learn.netdata.cloud/docs/network-flows/).


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.


<details open><summary>Config options</summary>



| 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.&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 |
| 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 |


</details>



#### via File

The configuration file name for this integration is `netflow.yaml`.


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
Netdata [config directory](https://github.com/netdata/netdata/blob/master/docs/netdata-agent/configuration/README.md#locate-your-config-directory).

```bash
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.

```yaml
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.

<details open><summary>Config</summary>

```yaml
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 }

```
</details>



### Verifying flow data is arriving and diagnosing failures

See [Troubleshooting](https://learn.netdata.cloud/docs/network-flows/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](https://learn.netdata.cloud/docs/network-flows/validation-and-data-quality)
and [Anti-patterns](https://learn.netdata.cloud/docs/network-flows/anti-patterns).



