Protocol 13 of 81Layer 3FrameAssembly v3.1.2
llms-full.txt
greGeneric Routing Encapsulation (GRE, GRETAP & NVGRE)

Classic Protocol-47 Tunnel Wrappers & ERSPAN Headers (gre)

Default Port / Protocol
IP Proto 47
Host Endpoint Rule
Dual-Stack IPv4/IPv6
Wireshark Display Filter
gre
Standards & Specs
RFC 2784, RFC 2890, RFC 7637
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6GRE / NVGRE (IP Proto 47)

What It Does on the Wire

Before everything became UDP overlays, engineers duct-taped continents together with IP Protocol 47. gre toggles RFC 2890 Key, Sequence, and Checksum bits automatically as you add fields.

Generic Routing Encapsulation (gre) tunnels arbitrary Layer 2 or Layer 3 payloads inside outer IPv4 or IPv6 packets using IP Protocol 47. The variable-length GRE header begins with a 16-bit Flags/Version word (C Checksum bit 15, K Key bit 13, S Sequence bit 12) and a 16-bit encapsulated EtherType (greproto, such as 0x0800 IPv4, 0x86dd IPv6, 0x6558 Transparent Ethernet Bridging, or 0x88be ERSPAN).

FrameAssembly automatically sets the exact C, K, and S flag bits based on which modifiers (checksum, grekey, greseq) you include, sizing the header between 4 and 16 bytes and computing the RFC 2784 GRE checksum when requested.

WAN GRE & GRE-over-IPsec Branch Tunnel Audits

Verify firewall ACLs permit IP Protocol 47 between branch and hub loopbacks and validate MTU/MSS clamping behavior.

NVGRE (greproto 0x6558) & ERSPAN (0x88be) Sensor Testing

Craft keyed greproto 0x6558 or 0x88be packets to test packet-broker decapsulation rules and Suricata/Zeek tunnel dissectors.

Sequence-Numbered GRE Reordering Diagnostics

Emit incrementing or out-of-order greseq values with checksum enabled to test tunnel endpoint sequence validation.

Minimal Quickstart (gre_quickstart.frasm)

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

gre_quickstart.frasm6 lines
Open in Playground
host branch_wan { ip 203.0.113.10 }
host hub_wan { ip 198.51.100.1 }
compile {
branch_wan -> hub_wan gre grekey 1001 greseq 1 checksum payload "gre-keepalive"
}

What the Compiler Calculates So You Don't Have To

  • Sets outer IPv4 Protocol or IPv6 Next Header to 47 and defaults greproto to 0x0800 (IPv4) with an inner probe header when payload is omitted.
  • Dynamically toggles GRE header flag bits (0x8000 for checksum, 0x2000 for grekey/key, 0x1000 for greseq) and inserts only the active 32-bit extension words in RFC 2890 order (Checksum+Reserved1, Key, Sequence).
  • Computes the 16-bit ones-complement RFC 2784 GRE checksum across the GRE header and payload whenever checksum is present.
Multi-Frame Lab · Ready to Compile

Keyed Dual-Stack GRE Tunnel Sequence & Transparent Ethernet Bridging (GRETAP)

Demonstrates an RFC 2890 keyed + checksummed GRE tunnel exchange over IPv4 followed by an IPv6 outer GRETAP (greproto 0x6558) overlay frame.

gre_overlay_lab.frasm14 lines
Open in Playground
host edge_a_v4 { ip 172.16.100.1 }
host edge_b_v4 { ip 172.16.100.2 }
host vtep_a_v6 { ip 2001:db8:47::1 }
host vtep_b_v6 { ip 2001:db8:47::2 }
compile {
// 1. Minimal 4-byte RFC 2784 GRE keepalive
edge_a_v4 -> edge_b_v4 gre payload "keepalive-1" wait 2ms
// 2. Full 16-byte GRE header (C=1, K=1, S=1) with tunnel key 5000
edge_a_v4 -> edge_b_v4 gre grekey 5000 greseq 10 checksum dscp 46 payload "wan-voice-tunnel" wait 2ms
edge_a_v4 <- edge_b_v4 gre grekey 5000 greseq 1 checksum dscp 46 payload "wan-voice-reply" wait 3ms
// 3. GRE over IPv6 carrying Transparent Ethernet Bridging (0x6558)
vtep_a_v6 -> vtep_b_v6 gre grekey 0x00102000 greproto 0x6558 hexpayload "ffffffffffff001b21aa00010806"
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show gre_overlay_lab.frasm

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

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

All gre 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 gre:

src_host -> dst_host gre [grekey|key <number>] [greseq <number>] [greproto <0..65535>] [checksum]
Keyword / OptionAccepted ValueDefaultEffect on Packet
grekey <number> | key <number>Whole numberOmitted (K=0)Sets Key Present bit (0x2000) and inserts the 4-byte RFC 2890 Tunnel Key (or 24-bit NVGRE VSID + 8-bit FlowID).
greseq <number>Whole numberOmitted (S=0)Sets Sequence Number Present bit (0x1000) and inserts the 4-byte GRE Sequence Number.
greproto <0..65535>16-bit EtherType (decimal or 0x hex)0x0800Sets the 2-byte GRE Protocol Type (0x0800 IPv4, 0x86dd IPv6, 0x6558 TEB/GRETAP, 0x88be ERSPAN).
checksumBare boolean flagOmitted (C=0)Sets Checksum Present bit (0x8000) and inserts the computed 2-byte GRE Checksum + 2-byte Reserved1 (0x0000).

Cross-Layer Wrappers Valid with gre

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

9 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).

Gotchas & Quick Fixes

Use greseq (Not seq) for the GRE Sequence Number

Avoid
a -> b gre seq 10
Valid v3.1.2 Syntax
a -> b gre greseq 10

Bare seq is the TCP sequence number modifier and is rejected on non-TCP protocols like gre. Always write greseq <number> for RFC 2890 GRE sequence numbers.

GRE Uses IP Protocol 47 (No L4 Ports)

Avoid
a -> b gre dstport 4789
Valid v3.1.2 Syntax
a -> b vxlan vni 100 (or gre grekey 100)

Standard GRE runs directly atop IP Protocol 47 without UDP/TCP headers. For UDP-encapsulated overlays, use vxlan (4789) or geneve (6081).

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