IPFIX

Synopsis

Creates an IPFIX collector that accepts flow data over UDP connections. Supports high-volume collection with multiple worker processes. Also handles NetFlow v9 templates.

For details, see Appendix.

Schema

- id: <numeric>
  name: <string>
  description: <string>
  type: ipfix
  tags: <string[]>
  pipelines: <pipeline[]>
  status: <boolean>
  properties:
    address: <string>
    port: <numeric>
    protocol: <enum>
    framing: <enum>
    workers: <numeric>
    reuse: <boolean>

Configuration

The following fields are used to define the device:

Device

Field	Required	Default	Description
`id`	Y		Unique identifier
`name`	Y		Device name
`description`	N	-	Optional description
`type`	Y		Must be `ipfix`
`tags`	N	-	Optional tags
`pipelines`	N	-	Optional pre-processor pipelines
`status`	N	`true`	Enable/disable the device

Connection

Field	Required	Default	Description
`address`	N	`"0.0.0.0"`	Listen address
`protocol`	N	`udp`	Transport: `udp` or `tcp`. See Transport below
`framing`	N	`ipfix` over TCP	TCP message framing. See Transport below
`port`	N	`4739`	Listen port
`workers`	N	One per 8 CPU cores	Number of worker goroutines, never below 1 and reduced further on memory-constrained hosts. Forced to `1` when `reuse` is `false`.
`reuse`	N	`false`	Enable socket address reuse

Ingest Buffer

Field	Required	Default	Description
`max_buffer_size`	N	`128MB`	Ingest buffer admission cap. Also sets this listener's eager heap reservation

note

max_buffer_size is the ingest-buffer admission cap, and is distinct from any buffer_size field above, which sizes the network read buffer. Left unset it is 128MB, which commits 384 MiB of heap per listener worker before any data arrives — and with reuse: true a device runs one worker per listener. Size strings are binary, and 32MB and 32MiB are exact synonyms.

See Listener Memory Sizing for the arithmetic, the sizing table, and what happens when the cap is exhausted.

Details

Transport

The listener runs over UDP by default, which is how flow exporters almost always send. Setting protocol: tcp binds a TCP listener instead, for an exporter configured to use it or a path that needs the delivery guarantees.

Field	Required	Default	Description
`protocol`	N	`udp`	Transport to bind: `udp` or `tcp`. `network` is accepted as an alias and takes precedence when both are set
`framing`	N	`ipfix` over TCP	How message boundaries are found on a TCP stream: `delimiter`, `octet` or `ipfix`. Not used on UDP

Framing

A UDP datagram is one message, so nothing has to be framed. A TCP stream does, and the default framer looks for newlines — which never appear cleanly in a binary flow stream.

So over TCP the listener selects the ipfix framer automatically, reading the total length from bytes 2-3 of each message header as RFC 7011 §3.1 specifies. Setting framing explicitly overrides that choice.

note

The automatic selection applies to IPFIX and NetFlow v9 only, which share that header layout. sFlow over TCP would need a different framer and is not auto-selected — if you run it, set framing yourself.

TLS over TCP

TLS is available on the TCP transport, configured with the standard tls block. It has no effect on UDP.

TLS Fields

Field	Required	Default	Description
`tls.status`	N	`false`	Enable TLS encryption
`tls.cert_name`	Y*	`cert.pem`	TLS certificate
`tls.key_name`	Y*	`key.pem`	TLS private key
`tls.passphrase`	N	-	Passphrase for an encrypted private key
`tls.min_tls_version`	N	`tls1.2`	Minimum accepted TLS version (`tls1.0`, `tls1.1`, `tls1.2`, `tls1.3`)
`tls.max_tls_version`	N	-	Maximum accepted TLS version. When unset, the highest mutually supported version is negotiated.
`tls.client_ca_name`	N	-	CA bundle used to verify client certificates (mTLS)
`tls.client_auth_required`	N**	`false`	Require connecting clients to present a valid certificate. When `false`, a client certificate is verified only if one is presented.
`tls.insecure_skip_verify`	N	`false`	Skip peer certificate verification. Use only for testing.

* = Required when tls.status is true.

** = Requires tls.client_ca_name. If tls.client_auth_required is true or tls.client_ca_name is set and the named CA cannot be loaded, the configuration is rejected and the device fails to start.

note

tls.min_version is a deprecated alias for tls.min_tls_version, honored only when tls.min_tls_version is unset. Use tls.min_tls_version in new configurations.

note

TLS material fields (cert_name, key_name, ca_name, client_ca_name) accept any of the following:

File name — resolved relative to the service root directory. Nested paths such as certs/prod/server.pem are supported.
Absolute path — honored only if it resolves inside the service root. Any path that escapes the root is refused.
Inline PEM content — used verbatim when the value contains -----BEGIN.
Environment variable — ${ENV_VAR}.
Vault reference — $secret{id=...} or $secret{store=...,ref=...}.

NetFlow, sFlow, and IPFIX devices share a common flow collection backend (backend/module/listener/flow/). The thin per-protocol controller sets the flow type and default port.

When reuse is enabled, the collector scales to one worker per 8 CPU cores. Each worker maintains its own UDP listener, processes flows independently, and writes to a dedicated queue file.

The collector supports template management for NetFlow v9 and IPFIX, application identification, port-based protocol mapping, flow state tracking, and statistical aggregation.

Examples

The following are commonly used configuration types.

Basic

Creating a simple IPFIX collector on the default port...

devices:
  - id: 1
    name: basic_ipfix
    type: ipfix
    properties:
      port: 4739

High-Volume

Optimizing for high flow volumes using multiple workers...

devices:
  - id: 2
    name: performant_ipfix
    type: ipfix
    properties:
      address: "0.0.0.0"
      port: 4739
      reuse: true
      workers: 4

note

When reuse is enabled, the collector scales to one worker per 8 CPU cores. Without reuse the count is forced to 1, since the workers share the listening socket through SO_REUSEPORT.

Application Protocols

The collector supports application-based identification, TCP port mapping, and UDP port mapping. The definition files for these respectively are placed in three locations under <vm_root>:

/user/definitions/app-definitions-{device-id}.csv (device-specific)
/user/definitions/app-definitions.csv (user-defined)
/package/definitions/app-definitions.csv (system defaults)
/user/definitions/tcp-definitions-{device-id}.csv (device-specific)
/user/definitions/tcp-definitions.csv (user-defined)
/package/definitions/tcp-definitions.csv (system defaults)
/user/definitions/udp-definitions-{device-id}.csv (device-specific)
/user/definitions/udp-definitions.csv (user-defined)
/package/definitions/udp-definitions.csv (system defaults):::warning

Definition files must be in CSV format with exactly two columns per row. :::

The contents of these files are:

app-definitions.csv:

SSH,Secure Shell
RDP,Remote Desktop
HTTP,Web Browsing
HTTPS,Secure Web

tcp-definitions.csv:

22,SSH
3389,RDP
80,HTTP
443,HTTPS

udp-definitions.csv:

53,DNS
67,DHCP
123,NTP
161,SNMP

note

The collector will fall back on the system defaults if the custom definition files are not found.

IPFIX collector with application identification enabled...

devices:
  - id: 3
    name: app_aware_ipfix
    type: ipfix
    properties:
      port: 4739
      reuse: true

Synopsis​

Schema​

Configuration​

Device​

Connection​

Ingest Buffer​

Details​

Transport​

Framing​

TLS over TCP​

TLS Fields​

Examples​

Basic​

High-Volume​

Application Protocols​

Synopsis

Schema

Configuration

Device

Connection

Ingest Buffer

Details

Transport

Framing

TLS over TCP

TLS Fields

Examples

Basic

High-Volume

Application Protocols