Protocol 15 of 81Layer 3FrameAssembly v3.1.2
llms-full.txt
geneveGeneric Network Virtualization Encapsulation

Cloud SDN & Gateway Load-Balancer Overlays (geneve UDP 6081)

Default Port / Protocol
UDP 6081 (Proto 0x6558)
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
geneve
Standards & Specs
RFC 8926
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6GENEVE (UDP 6081 (Proto 0x6558))

What It Does on the Wire

VXLAN’s extensible cousin powering OVN, Cilium, and AWS Gateway Load Balancers on UDP 6081: geneve packs a 24-bit vni plus variable-length TLV option headers without manual optlen math.

Generic Network Virtualization Encapsulation (geneve, RFC 8926) is the extensible cloud and Kubernetes CNI overlay protocol (used by OVN-Kubernetes, Cilium, NSX-T, and AWS Gateway Load Balancer) running over UDP dstport 6081. Unlike fixed-header VXLAN, GENEVE includes a 6-bit OptLen field (4-byte multiples) allowing SDN controllers and cloud load balancers to attach variable-length Type-Length-Value (TLV) security metadata (optclass + opttype).

FrameAssembly generates the RFC 8926 base header (Protocol Type 0x6558 Transparent Ethernet Bridging by default), encodes optional 4-byte aligned TLV options when optclass or opttype is supplied, and updates OptLen automatically.

Kubernetes CNI (OVN / Cilium) Overlay Troubleshooting

Craft GENEVE packets carrying OVN (optclass 0x0102) or Cilium (optclass 0x0104) security identity TLVs across IPv4 and IPv6 cluster nodes.

AWS Gateway Load Balancer (GWLB) Appliance Inspection

Build geneve captures on UDP 6081 (optclass 0x0108 AWS GWLB metadata) to unit-test virtual firewall and IDS inspection appliances offline.

Hardware NIC Offload & Wireshark TLV Dissector Validation

Test GENEVE option parsing with both zero-option (OptLen=0) and TLV-populated (OptLen>=2) frames.

Minimal Quickstart (geneve_quickstart.frasm)

Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.

geneve_quickstart.frasm6 lines
Open in Playground
host k8s_worker1 { ip 10.240.0.11 }
host k8s_worker2 { ip 10.240.0.12 }
compile {
k8s_worker1 -> k8s_worker2 geneve vni 20200 optclass 0x0102 opttype 1
}

What the Compiler Calculates So You Don't Have To

  • Encapsulates over UDP dstport 6081 with computed IPv4/IPv6 and UDP pseudo-header checksums.
  • Writes the 8-byte RFC 8926 GENEVE base header (Ver=0, dynamic OptLen in 4-byte words, Protocol Type=0x6558 TEB, and 24-bit VNI).
  • When optclass or opttype is set, appends a 4-byte padded GENEVE TLV option header + value and sets OptLen so Wireshark dissects both the TLV and inner frame cleanly.
Multi-Frame Lab · Ready to Compile

Kubernetes OVN & Cilium GENEVE Overlay With Security Identity TLVs

Models pod-to-pod overlay packets carrying OVN (0x0102) and Cilium (0x0104) option classes, plus a Layer 3 IPv6 inner payload (protocoltype 0x86dd).

geneve_cni_tlvs.frasm11 lines
Open in Playground
host node_az1 { ip 10.128.1.10 }
host node_az2 { ip 10.128.2.20 }
compile {
// 1. OVN-Kubernetes pod egress carrying Option Class 0x0102
node_az1 -> node_az2 geneve vni 4010 optclass 0x0102 opttype 1 srcport 55100 wait 1ms
// 2. Cilium return packet carrying Option Class 0x0104
node_az1 <- node_az2 geneve vni 4010 optclass 0x0104 opttype 2 srcport 59200 wait 2ms
// 3. Direct L3 IPv4 payload inside GENEVE (protocoltype 0x0800) for GWLB appliance test
node_az1 -> node_az2 geneve vni 100 optclass 0x0108 opttype 1 protocoltype 0x0800
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show geneve_cni_tlvs.frasm

# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly geneve_cni_tlvs.frasm geneve_cni_tlvs.pcap
frameassembly geneve_cni_tlvs.frasm geneve_cni_tlvs.pcapng

# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse geneve_cni_tlvs.pcap geneve_cni_tlvs_edited.frasm

All geneve Keywords & Header Options

Every sub-keyword and header option is lowercase [a-z0-9]+ with zero underscores — mix and match them in any order after geneve:

src_host -> dst_host geneve [vni|vnid <0..16777215>] [optclass <0..65535>] [opttype <0..255>] [protocoltype <0..65535>]
Keyword / OptionAccepted ValueDefaultEffect on Packet
vni <0..16777215> | vnid <0..16777215>24-bit unsigned integer (0..16777215)1Sets the 24-bit Virtual Network Identifier (vnid is an alias for vni).
optclass <0..65535>16-bit IANA Option Class (hex or decimal)Omitted (OptLen 0 unless set)Appends a GENEVE TLV Option with the given namespace (0x0102 OVN, 0x0104 Cilium, 0x0108 AWS) and increments OptLen.
opttype <0..255>8-bit Option Type (bit 7 = Critical bit)1 (when optclass set)Sets the 8-bit Option Type inside the GENEVE TLV (>= 0x80 marks a Critical option per RFC 8926 §3.5).
protocoltype <0..65535>16-bit IEEE EtherType0x6558 (Transparent Ethernet Bridging)Sets the inner encapsulated EtherType (0x6558 Ethernet L2 frame, 0x0800 raw IPv4, 0x86dd raw IPv6).

Cross-Layer Wrappers Valid with geneve

802.1Q VLAN / QinQ / MPLS tags, IPv4/IPv6 QoS & TTL fields, wait gaps, and transport overrides allowed on this protocol

10 options
OptionRange / FormatDefaultEffect on Packet
wait <number><ns|us|ms|s|m>Time gap (ns, us, ms, s, m)10msAdvances the packet timestamp clock after sending this packet and before the next packet (wait 0ns sends back-to-back).
payload "<text>" | hexpayload "<hex>"Quoted text or hex bytes (choose one)OmittedAppends or overrides raw payload bytes ("deadbeef" or "de:ad:be:ef") and updates packet lengths and checksums.
srcmac <mac> | dstmac <mac>Colon, hyphen, or Cisco dot MACHost MAC / RFC multicast MACOverrides the 14-byte Ethernet II source or destination MAC address for this single packet.
vlan <0..4095> [pcp <0..7>] [dei <0|1>]VLAN ID 0..4095, PCP 0..7, DEI 0..1UntaggedWraps the packet in an IEEE 802.1Q VLAN tag (0x8100) with optional 802.1p QoS priority.
qinq <0..4095> [innervlan <0..4095>]Outer S-VLAN 0..4095, Inner C-VLAN 0..4095Untagged (innervlan 1 when qinq is set)Double-tags the packet with outer IEEE 802.1ad S-Tag (0x88a8) plus inner IEEE 802.1Q C-Tag (0x8100).
mpls <0..1048575> [exp|tc <0..7>] [bos <0|1>] [mplsttl <0..255>]Label 0..1048575, exp/tc 0..7, bos 0..1, ttl 0..255Unlabeled (at most 1 mpls tag per packet)Inserts a 32-bit MPLS label header (0x8847) ahead of the Layer 3 header.
ttl <0..255> [dscp <0..63>] [ecn <0..3>]TTL/Hop Limit 0..255, DSCP 0..63, ECN 0..3ttl 64, dscp 0, ecn 0Sets IPv4 TTL or IPv6 Hop Limit plus DiffServ (DSCP) and ECN QoS markings.
ipid <0..65535> [df] [mf] [fragoffset <0..8191>]IPv4 ID, DF/MF flags, fragment offset 0..8191ipid 1, flags 0, fragoffset 0Sets IPv4 Identification, Do-Not-Fragment (df), More-Fragments (mf), and fragment offset (ignored over IPv6).
flowlabel <0..1048575>20-bit IPv6 Flow Label (0..1048575)0Sets the 20-bit IPv6 Flow Label for ECMP routing tests (ignored when running over IPv4 hosts).
srcport <0..65535> | dstport <0..65535>Port number 0..65535srcport 49152 (remembered), UDP 6081 (Proto 0x6558)Overrides source or destination port and remembers the port pair automatically on <- replies.

Gotchas & Quick Fixes

Spell optclass, opttype, and protocoltype Without Underscores

Avoid
a -> b geneve opt_class 0x0102 opt_type 1 protocol_type 0x6558
Valid v3.1.2 Syntax
a -> b geneve optclass 0x0102 opttype 1 protocoltype 0x6558

All GENEVE sub-keywords are strict lowercase alphanumeric tokens with zero underscores.

Critical Option Bit Semantics (opttype >= 0x80)

Valid v3.1.2 Syntax
a -> b geneve vni 10 optclass 0x0102 opttype 0x81

Setting bit 7 (0x80) in opttype sets the GENEVE header C (Critical Options Present) flag; tunnel endpoints that do not recognize a critical option must drop the packet.

Field Guide 05
VLANs, QinQ, MPLS, Tunnel Soup & Dual-Stack IPv6