<!--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 Performance Monitoring/Network Flows/Flow Protocols"
keywords: ['netflow', 'netflow v5', 'netflow v7', 'netflow v9', 'cisco', 'cisco asa', 'nsel', 'firewall', '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.

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](https://github.com/netdata/netdata/blob/master/docs/npm/network-flows/README.md).


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.


### Default Behavior

#### Auto-Detection

The stock configuration enables the plugin and listens on the configured UDP ports.

#### Limits

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.

#### Performance Impact

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.

## 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 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.&lt;tier&gt;.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.&lt;tier&gt;.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 |


</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

Use Netdata's stock listener set for v5 and v9 records.

```yaml
enabled: true
listener:
  listen:
    - "0.0.0.0:2055"
    - "0.0.0.0:6343"
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://github.com/netdata/netdata/blob/master/docs/npm/network-flows/troubleshooting.md) 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](https://github.com/netdata/netdata/blob/master/docs/npm/network-flows/validation.md)
and [Anti-patterns](https://github.com/netdata/netdata/blob/master/docs/npm/network-flows/anti-patterns.md).
