geneveGeneric Network Virtualization EncapsulationCloud SDN & Gateway Load-Balancer Overlays (geneve UDP 6081)
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.
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 6081with computed IPv4/IPv6 and UDP pseudo-header checksums. - Writes the 8-byte RFC 8926 GENEVE base header (
Ver=0, dynamicOptLenin 4-byte words,Protocol Type=0x6558TEB, and 24-bitVNI). - When
optclassoropttypeis set, appends a 4-byte padded GENEVE TLV option header + value and setsOptLenso Wireshark dissects both the TLV and inner frame cleanly.
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).
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}# 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.frasmAll 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 / Option | Accepted Value | Default | Effect on Packet |
|---|---|---|---|
| vni <0..16777215> | vnid <0..16777215> | 24-bit unsigned integer (0..16777215) | 1 | Sets 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 EtherType | 0x6558 (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
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
| Option | Range / Format | Default | Effect on Packet |
|---|---|---|---|
| wait <number><ns|us|ms|s|m> | Time gap (ns, us, ms, s, m) | 10ms | Advances 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) | Omitted | Appends 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 MAC | Host MAC / RFC multicast MAC | Overrides 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..1 | Untagged | Wraps 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..4095 | Untagged (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..255 | Unlabeled (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..3 | ttl 64, dscp 0, ecn 0 | Sets 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..8191 | ipid 1, flags 0, fragoffset 0 | Sets 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) | 0 | Sets 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..65535 | srcport 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
a -> b geneve opt_class 0x0102 opt_type 1 protocol_type 0x6558a -> b geneve optclass 0x0102 opttype 1 protocoltype 0x6558All GENEVE sub-keywords are strict lowercase alphanumeric tokens with zero underscores.
Critical Option Bit Semantics (opttype >= 0x80)
a -> b geneve vni 10 optclass 0x0102 opttype 0x81Setting 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.