Flow Export
Ze exports interface counters and per-flow records to external collectors over
UDP. The flowexport component is a registered component: it 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.
Because counter export consumes the interface rate tracker, configuring
flow-export { } automatically pulls in the interface plugin (a registered
dependency). You do not need to add a separate interface { } section just to
get counter datagrams flowing.
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) |
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 | Maximum time between two counter polls, in seconds (1-3600). Snapshots arrive once a second, so Ze polls from one second before the interval ends |
template-refresh |
600 | Template refresh interval in seconds, NetFlow v9 / IPFIX (1-86400) |
sub-agent-id |
0 | sFlow sub-agent identifier. Every sflow collector exports every interface, so all sflow collectors MUST name the same value |
observation-domain |
0 | IPFIX / NetFlow v9 observation domain ID |
agent-address |
- | sFlow agent address (the device's own stable IP, for example a loopback). Mandatory for sflow. 0.0.0.0 and :: are refused, and all sflow collectors MUST name the same address. Ze compares the parsed addresses, so are one address. Ze logs a warning when no interface holds the address, or when the router has more than one routed interface and the address is not on a loopback or dummy interface. 2001:db8::12001:DB8:0::1 |
source-address |
- | Local source IP for the collector's UDP socket |
max-datagram-size |
464 | Maximum UDP payload bytes, including protocol padding (464-1400) |
The default reserves IPv6 and UDP headers within a 512-byte packet when the path MTU is unknown. Raise it only when the path MTU is known, after subtracting all IP, UDP and tunnel headers. Encoders split batches or cap sampled headers to this bound. Oversized sends return an error.
sFlow uses expanded counter and flow samples for every interface, preserving full-width interface indexes without mixing compact and expanded formats.
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;
}
}
The agent address is how a collector tells this router from every other agent. sFlow v5 asks a router with several routed interfaces to use a loopback address, which does not go away when one interface goes down. When the plugin applies the config, it compares the address with the router's interfaces and logs a warning that names the fix:
flow-export: sflow agent-address 203.0.113.1 is on routed interface eth0, not on a loopback interface. ...
flow-export: sflow agent-address 198.51.100.1 is not configured on any interface. ...
A dummy interface counts as a loopback, so
create interface dummy name agent0 address 198.51.100.1/32 silences both.
The warning never refuses the config: the export runs either way.
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.
| Field | Default | Description |
|---|---|---|
bgp |
false | Enrich flow records with the BGP next-hop |
flow-export {
enrichment {
bgp true;
}
}
The BGP RIB is the bgp-rib plugin, which only a build with the ze_bgp tag
carries. Turning bgp true on starts it when the build has it, even with no
bgp {} block; with enrichment off, flow export never starts it. A build
without ze_bgp still runs flow export, and refuses bgp true at
ze config validate, at commit, at daemon start and at SIGHUP reload, before
any plugin starts. The refusal names the setting, says why, and gives the fix
on its own line. ze config validate prints:
configuration invalid: flow.conf
Errors:
config: "flow-export enrichment bgp true" needs plugin bgp-rib, and this build does not include it
flow-export cannot act on this setting without it, so ze refuses the config rather than run a setting that does nothing
fix: rebuild ze with build tag ze_bgp added to its -tags list, or remove "flow-export enrichment bgp true" from the config
Set bgp false (or leave the leaf out) to run flow export on that build.
Before this refusal existed, such a build accepted the setting and the exporter
silently received no RIB data.
Operational Command
show flow export [name <collector>] reports per-collector export statistics.
With no argument it lists every collector; with name <collector> 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 | json'
The | json pipe asks for that shape. Without it the answer is rendered in the
format environment cli format default names, whose registered value is text.
[
{
"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 |
Shared collector sequence: successful data records for IPFIX, successful packets for NetFlow v9, generated datagrams for sFlow |
last-export-time |
Unix timestamp of the most recent successful counter poll (omitted before the first successful poll) |
The command answers structured data, rendered in the format
environment cli format default names. The registered value is text. The full
set of pipe operators selects another one.
Datagram and byte totals include successfully sent templates and any packets sent before a later error in the same batch. A failed template blocks its data batch until a subsequent template attempt succeeds. Counter and flow exporters share the sequence; a configuration reload creates 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
- BGP enrichment attaches next-hop, origin AS, and the AS path from the RIB best-change event to flow records. Full-table replay events omit the AS data (the stored best-path record does not keep the AS-path handle); those entries are corrected by the next incremental best-path change.
- Extended sFlow
if_counters. ifType, ifIndex, status, octet/packet/ error/discard counters, promiscuous mode, ifSpeed, ifDirection (duplex), and inbound multicast packets are populated. ifSpeed and ifDirection come from sysfs (/sys/class/net/<if>/speedand/duplex) and read zero / unknown for virtual or down links, where the kernel does not report them. Outbound multicast, broadcast and unknown-protocol counts carry0xFFFFFFFF, the unavailable-counter value: Linux does not expose these counters throughrtnl_link_stats64. IPFIX packet totals use the original 64-bit receive and transmit counts, without the sFlow sentinels. - Conntrack export combines periodic dumps with destroy events. Records
are emitted on each table dump (
active-timeout), and aNFNLGRP_CONNTRACK_DESTROYnetlink listener exports each torn-down flow's residual counters immediately, so flows that begin and end between two dumps are not lost. The destroy listener needsCAP_NET_ADMINand thenf_conntrack_netlinkmodule; without them the worker logs that it is running in dump-only mode and continues with the periodic path alone. - Sampling requires Linux with
CAP_NET_ADMINand the kernelpsamplemodule. On platforms without these, the sampling worker degrades and no flow samples are produced.
Scale: conntrack vs sampling
Conntrack per-flow export gives exact per-flow accounting and suits edge /
moderate scale (up to low-thousands of new flows per second). Its cost scales
with flow churn: the delta tracker holds one entry per recently-seen flow,
the kernel table dump serializes every tracked flow over netlink each
active-timeout, and the destroy-event socket must keep up with the teardown
rate. A torn-down flow's tracking state is reclaimed within a few seconds of its
destroy event (or at 2 × active-timeout if the event is missed), so memory is
bounded by churn × residency. Raising active-timeout on a busy device
lengthens residency for any flow whose destroy event is missed, so keep it
modest under high churn.
For high-rate links (100G internet mix, tens of thousands to millions of new
flows per second), do not rely on conntrack per-flow export: the table dump,
the destroy-event rate, and the export bandwidth all become bottlenecks. Use
packet sampling instead (sampling { }, sFlow flow samples), whose cost is
independent of flow rate because it processes only 1-in-N packets. Sampling is
the scalable mechanism for line-rate flow visibility; conntrack export is for
exact accounting where flow rates are modest.
Security
The export protocols (sFlow, NetFlow v9, IPFIX) are unencrypted UDP and carry no authentication. Run flow export over a dedicated management VLAN, and keep the collector endpoints off any untrusted path.