Documentation
¶
Overview ¶
Package netflow9 decodes NetFlow v9 (RFC 3954) packets. NetFlow v9 is the template-based flow-export format that superseded NetFlow v5 (1996; covered by `netflow_v5_decode`) and bridged to IPFIX (RFC 7011); it's the dominant NetFlow version on modern (post-2010) Cisco / Juniper / Arista enterprise + carrier gear. NetFlow v9's killer feature is template-based extensibility: instead of a hardcoded 48-byte record like v5, exporters define Templates that name the fields and their widths, then send Data FlowSets that reference a Template ID and contain back-to-back records in that template's shape.
Wrap-vs-native judgement
Native. RFC 3954 is fully public; NetFlow v9 has a tight 20-byte header followed by N FlowSets (each: 4-byte header + body). No crypto, no compression. Operators paste NetFlow bytes (UDP destination port 2055 / 9555 / 9995) from a `tcpdump -X udp port 2055` line or a Wireshark Follow-UDP-Stream view and get the documented header + per-FlowSet breakdown. The template stateful-decode gap: this decoder is stateless (single-packet), so Data FlowSets are surfaced as raw hex annotated with their referencing Template ID. Operators correlate against the matching Template FlowSet (typically in the same packet, or in an earlier packet from the same exporter). A future iteration could maintain a template cache across calls.
What this package covers
**20-byte header** (RFC 3954 §5.1):
bytes 0-1: Version (uint16 BE; must be 9).
bytes 2-3: **Count** (uint16 BE; number of FlowSets in this packet).
bytes 4-7: SysUptime (uint32 BE; ms since exporter boot).
bytes 8-11: Unix Seconds (uint32 BE; epoch seconds of export).
bytes 12-15: **Sequence Number** (uint32 BE; per-source monotonic counter — gaps signal collector data loss).
bytes 16-19: **Source ID** (uint32 BE; unique exporter+observation-point identifier).
**FlowSet walker** — repeated 4-byte header (FlowSet ID uint16 BE + Length uint16 BE; Length includes this 4-byte header) + body.
**Template FlowSet** (FlowSet ID = 0; RFC 3954 §5.2):
2-byte Template ID (uint16 BE; ≥ 256 per RFC).
2-byte Field Count.
**Field Specifier × Field Count** (4 bytes each):
2-byte **Field Type** (uint16 BE) resolved via a ~30-entry name table covering the most common IANA NetFlow IPFIX Information Element IDs (IN_BYTES / IN_PKTS / FLOWS / PROTOCOL / TOS / TCP_FLAGS / L4_SRC_PORT / IPV4_SRC_ADDR / SRC_MASK / INPUT_SNMP / L4_DST_PORT / IPV4_DST_ADDR / DST_MASK / OUTPUT_SNMP / IPV4_NEXT_HOP / SRC_AS / DST_AS / BGP_NEXT_HOP / MUL_DST_PKTS / MUL_DST_BYTES / LAST_SWITCHED / FIRST_SWITCHED / IPV6_SRC_ADDR / IPV6_DST_ADDR / IPV6_SRC_MASK / IPV6_DST_MASK / FLOW_LABEL / ICMP_TYPE / IGMP_TYPE / SAMPLING_INTERVAL / SAMPLING_ALGORITHM / FLOW_ACTIVE_TIMEOUT / FLOW_INACTIVE_TIMEOUT / ENGINE_TYPE / ENGINE_ID / TOTAL_BYTES_EXP / TOTAL_PKTS_EXP / FLOW_END_ REASON).
2-byte **Field Length** (uint16 BE; bytes per field in the Data FlowSet record).
**Options Template FlowSet** (FlowSet ID = 1; RFC 3954 §6) — same shape as Template FlowSet plus scope and option distinction (surfaced structurally; option semantics deferred).
**Data FlowSet** (FlowSet ID ≥ 256; RFC 3954 §5.3) — the FlowSet ID matches the Template ID of an earlier Template FlowSet. Records are back-to-back in the template's field layout (no per-record header). Without the matching template the decoder surfaces the body as raw hex; with a same-packet template the bytes-per-record calculation is done implicitly but actual per-field decoding remains deferred (would require a typed-by-IE-id walker).
What this package does NOT cover (deliberately out of scope)
UDP framing — feed NetFlow bytes after the UDP header strip. NetFlow ships on UDP, conventionally to destination ports 2055 / 9555 / 9995.
NetFlow v5 (use `netflow_v5_decode`) and IPFIX (RFC 7011 — different envelope, warrants its own Spec).
sFlow (use `sflow_v5_decode`) — packet sampling, different model.
Stateful template cache across packets — single- packet decode only; Data FlowSets without an in- packet template are surfaced as raw hex annotated with their referencing Template ID.
Per-field type-aware decoding of Data FlowSets — would require a full IANA IE-id type table (~500 entries) plus per-IE decoder; deferred.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DataFlowSetBody ¶
type DataFlowSetBody struct {
ReferencedTemplateID int `json:"referenced_template_id"`
RecordsHex string `json:"records_hex"`
BodyBytes int `json:"body_bytes"`
}
DataFlowSetBody is the decoded body of a Data FlowSet (FlowSet ID ≥ 256). Records are surfaced as raw hex pending stateful template lookup.
type FieldSpec ¶
type FieldSpec struct {
Type int `json:"type"`
TypeName string `json:"type_name"`
Length int `json:"length"`
}
FieldSpec is one (Field Type, Field Length) pair from a Template's field list.
type FlowSet ¶
type FlowSet struct {
FlowSetID uint16 `json:"flowset_id"`
Kind string `json:"kind"`
Length uint16 `json:"length"`
BodyHex string `json:"body_hex,omitempty"`
// Decoded forms populated for known FlowSet kinds.
Templates []Template `json:"templates,omitempty"`
OptionTemplates []Template `json:"option_templates,omitempty"`
DataFlowSet *DataFlowSetBody `json:"data,omitempty"`
}
FlowSet is one (ID, Length, Body) record from the walker.
type Result ¶
type Result struct {
Version uint16 `json:"version"`
Count uint16 `json:"count"`
SysUptimeMs uint32 `json:"sys_uptime_ms"`
UnixSeconds uint32 `json:"unix_seconds"`
ExportTimestampISO string `json:"export_timestamp_iso,omitempty"`
SequenceNumber uint32 `json:"sequence_number"`
SourceID uint32 `json:"source_id"`
FlowSets []FlowSet `json:"flowsets"`
TotalBytes int `json:"total_bytes"`
Notes []string `json:"notes,omitempty"`
}
Result is the top-level decoded view of a NetFlow v9 packet.
Source Files