ipfix

Documentation

Overview

Package ipfix decodes IPFIX (IP Flow Information eXport) messages per RFC 7011. IPFIX is the IETF standardization of NetFlow v9 (covered by `netflow_v9_decode`); the two protocols share the same template-based philosophy, IANA Information Element registry, and Data Set layout, but differ in three notable ways:

1. 16-byte header (vs NetFlow v9's 20) — drops the Source ID field in favour of an explicit Message Length and renames the per-exporter identifier to Observation Domain ID.
2. Enterprise-bit-extended Field Specifiers — the high bit of the Field Type signals presence of a 4-byte Enterprise Number after the (15-bit Field Type, Length) pair, opening the namespace to vendor-defined IEs.
3. Set IDs reserved 0-3: 2 = Template Set, 3 = Options Template Set, 256+ = Data Set; IPFIX drops NetFlow v9's FlowSet ID 0 / 1 distinction.

IPFIX is the export format used by Linux iptables / nftables flow exporters, Cisco ASR / NCS, Juniper modern routers, ntopng, akvorado, GoFlow2, pmacct, and every modern flow collector. Completes the flow-telemetry quartet alongside `netflow_v5_decode`, `netflow_v9_decode`, and `sflow_v5_decode`.

Wrap-vs-native judgement

Native. RFC 7011 is fully public; IPFIX has a tight
16-byte header followed by N Sets (each: 4-byte header
+ body). No crypto, no compression. Operators paste
IPFIX bytes (UDP destination port 4739 [IANA-assigned],
often also 2055 / 9555 / 9995 for legacy compatibility)
from a `tcpdump -X udp port 4739` line or a Wireshark
Follow-UDP-Stream view and get the documented header +
per-Set breakdown.

Like NetFlow v9, this decoder is stateless (single-
message), so Data Sets are surfaced as raw hex
annotated with their referencing Template ID.

What this package covers

• **16-byte header** (RFC 7011 §3.1):

• bytes 0-1: Version (uint16 BE; must be 10 / 0x000A).

• bytes 2-3: **Message Length** (uint16 BE; total length including header).

• bytes 4-7: Export Time (uint32 BE; epoch seconds).

• bytes 8-11: **Sequence Number** (uint32 BE; per- Observation Domain monotonic — gaps signal data loss).

• bytes 12-15: **Observation Domain ID** (uint32 BE; unique per exporter + observation point).

• **Set walker** — repeated 4-byte header (Set ID uint16 BE + Set Length uint16 BE; Length includes this 4-byte header) + body.

• **3-kind name table**: Set ID 2 Template Set / 3 Options Template Set / ≥ 256 Data Set (Set ID matches the Template ID of an earlier Template Set).

• **Template Set** (Set ID = 2; RFC 7011 §3.4.1):

• 2-byte Template ID (uint16 BE; ≥ 256).

• 2-byte Field Count.

• **Field Specifier × Field Count**, with format dispatched by the high bit of Field Type:

• **Standard IE** (high bit 0): 2-byte Field Type

• 2-byte Field Length.

• **Enterprise IE** (high bit 1): 2-byte Field Type (low 15 bits) + 2-byte Field Length + 4-byte Enterprise Number (IANA PEN).

• Field Type resolved via a **~45-entry name table** covering the most common IANA IPFIX Information Element IDs (shared with NetFlow v9).

• **Options Template Set** (Set ID = 3; RFC 7011 §3.4.2):

• 2-byte Template ID.

• 2-byte Field Count.

• 2-byte Scope Field Count.

• First `Scope Field Count` specifiers are scope fields (e.g. meteringProcessId), remaining are option fields (e.g. samplingProbability).

• **Data Set** (Set ID ≥ 256; RFC 7011 §3.4.3) — records back-to-back in the matching Template's field layout (no per-record header). Surfaced as raw hex annotated with the referencing Template ID.

What this package does NOT cover (deliberately out of scope)

• UDP / TCP / SCTP framing — feed IPFIX bytes after the transport header strip. IPFIX runs on UDP / TCP / SCTP destination port 4739 (IANA-assigned), often also 2055 / 9555 / 9995 for legacy compatibility.

• NetFlow v9 (use `netflow_v9_decode`); NetFlow v5 (use `netflow_v5_decode`); sFlow v5 (use `sflow_v5_decode`).

• Stateful template cache across messages — single- message decode only; Data Sets without an in-message template are surfaced as raw hex annotated with their referencing Template ID.

• Per-field type-aware decoding of Data Sets — would require a full IANA IE-id type table (~500 entries) plus per-IE decoder; deferred.

• Structured Data (RFC 6313 — basicList / subTemplate List / subTemplateMultiList) and Variable-Length Encoding — surfaced as raw hex within Data Sets.

Index

• type DataSetBody
• type FieldSpec
• type OptionTemplate
• type Result
  • func Decode(hexStr string) (*Result, error)
• type Set
• type Template

Types

type DataSetBody

type DataSetBody struct {
	ReferencedTemplateID int    `json:"referenced_template_id"`
	RecordsHex           string `json:"records_hex"`
	BodyBytes            int    `json:"body_bytes"`
}

DataSetBody is the decoded body of a Data Set.

type FieldSpec

type FieldSpec struct {
	Type             int    `json:"type"`
	TypeName         string `json:"type_name"`
	Length           int    `json:"length"`
	EnterpriseNumber uint32 `json:"enterprise_number,omitempty"`
	IsEnterprise     bool   `json:"is_enterprise,omitempty"`
}

FieldSpec is one Field Specifier from a Template's field list.

type OptionTemplate

type OptionTemplate struct {
	TemplateID      int         `json:"template_id"`
	FieldCount      int         `json:"field_count"`
	ScopeFieldCount int         `json:"scope_field_count"`
	ScopeFields     []FieldSpec `json:"scope_fields"`
	OptionFields    []FieldSpec `json:"option_fields"`
	RecordSize      int         `json:"record_size_bytes"`
}

OptionTemplate is one IPFIX Options Template definition.

type Result

type Result struct {
	Version             uint16   `json:"version"`
	MessageLength       uint16   `json:"message_length"`
	ExportTime          uint32   `json:"export_time"`
	ExportTimestampISO  string   `json:"export_timestamp_iso,omitempty"`
	SequenceNumber      uint32   `json:"sequence_number"`
	ObservationDomainID uint32   `json:"observation_domain_id"`
	Sets                []Set    `json:"sets"`
	TotalBytes          int      `json:"total_bytes"`
	Notes               []string `json:"notes,omitempty"`
}

Result is the top-level decoded view of an IPFIX message.

func Decode

func Decode(hexStr string) (*Result, error)

Decode parses a single IPFIX message from hex.

type Set

type Set struct {
	SetID   uint16 `json:"set_id"`
	Kind    string `json:"kind"`
	Length  uint16 `json:"length"`
	BodyHex string `json:"body_hex,omitempty"`

	// Decoded forms populated for known Set kinds.
	Templates       []Template       `json:"templates,omitempty"`
	OptionTemplates []OptionTemplate `json:"option_templates,omitempty"`
	DataSet         *DataSetBody     `json:"data,omitempty"`
}

Set is one (ID, Length, Body) record from the Set walker.

type Template

type Template struct {
	TemplateID int         `json:"template_id"`
	FieldCount int         `json:"field_count"`
	Fields     []FieldSpec `json:"fields"`
	RecordSize int         `json:"record_size_bytes"`
}

Template is one IPFIX Template definition.