Guide

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>/speed and /duplex) and read zero / unknown for virtual or down links, where the kernel does not report them. Outbound multicast, broadcast and unknown-protocol counts carry 0xFFFFFFFF, the unavailable-counter value: Linux does not expose these counters through rtnl_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 a NFNLGRP_CONNTRACK_DESTROY netlink 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 needs CAP_NET_ADMIN and the nf_conntrack_netlink module; 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_ADMIN and the kernel psample module. 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.