flow export

Pre-Alpha. This page describes behavior that may change.

Experimental. Flow export is an experimental feature.

Ze exports interface counters and per-flow records to external collectors over UDP. The flow-export plugin is registered and loads only when a flow-export { } section is present in the config. Counter polling is driven by the interface rate tracker's snapshot callback; per-flow records come from packet sampling and from periodic conntrack table dumps.

Configuring flow-export { } automatically pulls in the interface plugin (a registered dependency), because counter export consumes the interface rate tracker. You do not need a separate interface { } section just to get counter datagrams flowing.

Protocols

Three export protocols are supported, selected per collector.

Protocol	Reference	Carries
sflow	sFlow v5	Interface counters, packet samples (flow samples)
netflow9	NetFlow v9 (RFC 3954)	Interface counters, per-flow records (template-based)
ipfix	IPFIX (RFC 7011)	Interface counters, per-flow records (template-based)

Per-flow records cover both IPv4 and IPv6, using separate templates.

Configuration

All flow export configuration lives under a single flow-export { } section.

Collectors

A collector is an export endpoint. Each collector names one protocol; you may configure several collectors at once (for example one sFlow and one IPFIX).

Field	Default	Description
name	-	Collector name (list key)
address	-	Collector IP address (mandatory)
port	6343	Collector UDP port
protocol	-	sflow, netflow9, or ipfix (mandatory)
polling-interval	20	Counter polling interval in seconds (1-3600)
template-refresh	600	Template refresh interval in seconds, NetFlow v9 / IPFIX (1-86400)
sub-agent-id	0	sFlow sub-agent identifier
observation-domain	0	IPFIX / NetFlow v9 observation domain ID
agent-address	-	sFlow agent address (the device's own stable IP, for example a loopback)
source-address	-	Local source IP for this collector's UDP socket. Left out, the kernel picks one from its route to the collector. It does not change the sFlow datagram header, which carries agent-address
max-datagram-size	464	Largest UDP payload sent to this collector in bytes, padding included (464-1400)

The default of 464 bytes keeps an IPv6 packet, with its IP and UDP headers, within 512 bytes, the size RFC 7011 recommends when the path MTU is unknown. Raise it only when you know the path MTU, and subtract every IP, UDP and tunnel header first. The encoders split batches, or cut sampled packet headers short, to stay within the bound, and a send that would still exceed it fails and counts as an error.

sFlow uses the expanded counter and flow sample formats for every interface, so interface indexes too large for the compact 24-bit form are kept whole. Compact and expanded formats are never mixed in one export.

An sFlow counter collector:

flow-export {
    collector edge-sflow {
        address 192.0.2.10;
        port 6343;
        protocol sflow;
        polling-interval 20;
        sub-agent-id 0;
        agent-address 198.51.100.1;
    }
}

A NetFlow v9 collector plus an IPFIX collector on the same device:

flow-export {
    collector nf9 {
        address 192.0.2.20;
        port 2055;
        protocol netflow9;
        polling-interval 30;
        template-refresh 600;
        observation-domain 1;
    }
    collector ipfix {
        address 192.0.2.21;
        port 4739;
        protocol ipfix;
        polling-interval 30;
        template-refresh 600;
        observation-domain 1;
    }
}

Sampling

Packet sampling uses the Linux tc sample action plus the kernel psample module and exports sampled packet headers as sFlow flow samples.

Field	Default	Description
name	-	Interface to sample (list key)
rate	-	Sampling rate, 1-in-N packets (1-1000000)
trunc-size	128	Bytes of each sampled packet header to capture (64-1500)
group	1	psample group ID (1-2147483647)

flow-export {
    sampling {
        interface eth0 {
            rate 1024;
            trunc-size 128;
            group 1;
        }
    }
}

Conntrack

Conntrack-based per-flow records are exported via NetFlow v9 and IPFIX. The exporter walks the conntrack table on a fixed interval and emits one record per tracked flow.

Field	Default	Description
enabled	false	Export per-flow records from the conntrack table
active-timeout	60	Seconds between conntrack table dumps (1-3600)

flow-export {
    conntrack {
        enabled true;
        active-timeout 60;
    }
}

Enrichment

Flow records can be enriched from the BGP RIB. With bgp true, the exporter consumes the RIB best-change event and attaches the next-hop for each flow's destination prefix, and the origin AS for each flow's source prefix.

The resolved origin AS also rides the internal observation feed as Observation.SrcAS, so another component (for example the traffic feature layer) reads it off the feed instead of querying the BGP RIB itself. SrcAS is 0, which RFC 7607 reserves, when enrichment is off or the RIB holds no matching prefix for the source address.

Field	Default	Description
bgp	false	Enrich flow records with the BGP next-hop

flow-export {
    enrichment {
        bgp true;
    }
}

Operational command

show flow-export [<collector>] reports per-collector export statistics. With no argument it lists every collector; with a collector name it returns that one collector, or an error if the name is not configured. When no flow-export section is configured the command returns {"status": "not-configured"}.

ze cli -c 'show flow-export'

[
  {
    "name": "edge-sflow",
    "address": "192.0.2.10",
    "port": 6343,
    "protocol": "sflow",
    "datagrams-sent": 1842,
    "bytes-sent": 1325760,
    "errors": 0,
    "sequence": 1842,
    "last-export-time": 1748430000
  }
]

Field	Description
name	Collector name
address	Collector IP address
port	Collector UDP port
protocol	Export protocol
datagrams-sent	UDP datagrams sent to this collector
bytes-sent	Total bytes sent to this collector
errors	Send errors
sequence	Sequence number shared by counter and flow export: data records sent for IPFIX, packets sent for NetFlow v9, datagrams generated for sFlow
last-export-time	Unix timestamp of the most recent successful counter poll (omitted before the first successful one)

The command produces JSON by default and supports the full set of pipe operators.

The datagram and byte totals include templates that were sent, and any packets that went out before a later error in the same batch. When a template fails to send, the data batch that needed it is not sent either, and export resumes once a later template send succeeds. A configuration reload starts a new transport session.

Prometheus metrics

The component registers the following metrics.

Metric	Type	Labels	Description
ze_flowexport_datagrams_total	counter	collector, protocol	Flow export datagrams sent
ze_flowexport_bytes_total	counter	collector, protocol	Flow export bytes sent
ze_flowexport_errors_total	counter	collector, protocol	Flow export send errors
ze_flowexport_samples_total	counter	interface	Packet samples received and exported
ze_flowexport_flows_total	counter	collector	Per-flow records exported
ze_flowexport_flows_active	gauge	-	Conntrack flows currently tracked for export

Limitations

• Packet sampling requires Linux with CAP_NET_ADMIN and the kernel psample module. On platforms without these, the sampling worker degrades and no flow samples are produced.
• sFlow counter samples carry 0xFFFFFFFF, the value sFlow uses for a counter that is not available, for outbound multicast, inbound and outbound broadcast, and inbound unknown-protocol packets. Linux does not expose these counters. IPFIX packet totals use the full 64-bit receive and transmit counts and are not affected.
• BGP enrichment looks up the source address and the destination address separately; a flow whose source or destination has no matching RIB prefix gets a zero value for that side only.

See also

• Monitoring
• Telemetry
• Firewall
• Interface

Adapted from main/docs/guide/flow-export.md.