4. Geneve Frame Format

Geneve uses the UDP protocol [RFC768] as its transport. The Geneve packet is encapsulated in a UDP packet, which is itself encapsulated in an IP packet (IPv4 or IPv6).

The format of the Geneve packet is as follows:

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          Outer Ethernet Header (Optional)                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          Outer IP Header (IPv4 or IPv6)                       |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          Outer UDP Header                                     |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   | Ver |  Opt Len |O|C|    Rsvd.  |          Protocol Type        |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |        Virtual Network Identifier (VNI)       |    Reserved   |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   ~                    Variable Length Options                    ~
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   |             Inner Packet (Ethernet Frame, IP Packet, etc.)    |
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

4.1. Standard UDP Header

Geneve runs over UDP. The UDP header fields are set as follows:

Source Port: Implementation defined. It is RECOMMENDED that the source port be computed using a hash of the inner packet headers (e.g., 5-tuple) to support entropy for ECMP in the underlay.
Destination Port: The IANA-assigned port for Geneve is 6081.
Length: The length of the UDP packet, including the UDP header and the Geneve payload.
Checksum: The UDP checksum. It MAY be set to zero (see Section 4.6).

4.2. Tunnel Header Fields

The Geneve header is 8 bytes long, plus variable length options.

Ver (2 bits): Version. The current version is 0.
Opt Len (6 bits): Option Length. The length of the option fields, expressed in 4-byte multiples. If Options are not present, this field is 0. The maximum length is 63 * 4 = 252 bytes.
O (1 bit): Control packet. If set, the packet contains a control message (see Section 4.5). If clear, the packet contains data.
C (1 bit): Critical options present. If set, at least one option with the Critical bit set is present in the options list (see Section 4.4).
Rsvd. (6 bits): Reserved. MUST be zero on transmission and ignored on receipt.
Protocol Type (16 bits): The type of the inner protocol. For Ethernet frames, this is 0x6558 (Ethernet Bridging). Uses EtherType values.
VNI (24 bits): Virtual Network Identifier. Identifies the unique virtual network.
Reserved (8 bits): MUST be zero on transmission and ignored on receipt.

4.3. Tunnel Options

The variable length options follow the base header. Each option is a TLV (Type-Length-Value) field.

   0                   1                   2                   3
   0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |          Option Class         |      Type     |R|R|R| Length  |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
   |                                                               |
   ~                  Variable Option Data                         ~
   |                                                               |
   +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Option Class (16 bits): Namespace for the Option Type. Allows different organizations to define options independently. IANA registry manages Option Classes.
Type (8 bits): The type of option within the given Option Class. The most significant bit (bit 0) is the "Critical" bit.
R (3 bits): Reserved. MUST be zero on transmission and ignored on receipt.
Length (5 bits): Length of the option data, expressed in 4-byte multiples. Does not include the 4-byte option header. Length 0 means 4 bytes of header only (no data).
Variable Option Data: The content of the option.

4.3.1. Type

The Type field indicates the format of the data contained in the option. The high-order bit (0x80) is the "Critical" bit.

Critical Bit (Type & 0x80): If set, the option is Critical. Receivers MUST process this option or drop the packet if they do not recognize it. If clear, the option is non-critical, and receivers MAY ignore it if unrecognized.

4.4. Constraints on Options

Geneve options are designed to be flexible, but certain constraints apply:

Total Length: The total length of options is limited by the Opt Len field in the base header (max 252 bytes).
Processing: Endpoints MUST process options in the order they appear.

4.4.1. Option Processing Order

Options MUST be processed in the order they appear in the packet. This is important for options that may modify the processing of subsequent options.

4.5. Control Messages

If the 'O' bit in the base header is set, the packet is a control message. Control messages are used for OAM and signaling. The payload of a control message is determined by the Protocol Type field.

4.5.1. Loopback

One use of control messages is loopback for testing connectivity.

4.5.2. Ping

Ping messages can be used to verify path continuity.

4.6. UDP Checksum

The Outer UDP Checksum covers the outer IP pseudo-header, UDP header, Geneve header, and payload. It provides integrity protection for the encapsulated packet.

IPv4: The UDP checksum MAY be zero. IPv6: The UDP checksum SHOULD NOT be zero, but certain exceptions exist for tunnels (see [RFC6935] and [RFC768]). If the checksum is zero, the receiver MUST accept it.