greGeneric Routing Encapsulation (GRE, GRETAP & NVGRE)Classic Protocol-47 Tunnel Wrappers & ERSPAN Headers (gre)
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.
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
47and defaultsgreprototo0x0800(IPv4) with an inner probe header whenpayloadis omitted. - Dynamically toggles GRE header flag bits (
0x8000forchecksum,0x2000forgrekey/key,0x1000forgreseq) 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
checksumis present.
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.
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"}# 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.frasmAll 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 / Option | Accepted Value | Default | Effect on Packet |
|---|---|---|---|
| grekey <number> | key <number> | Whole number | Omitted (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 number | Omitted (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) | 0x0800 | Sets the 2-byte GRE Protocol Type (0x0800 IPv4, 0x86dd IPv6, 0x6558 TEB/GRETAP, 0x88be ERSPAN). |
| checksum | Bare boolean flag | Omitted (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
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
| 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). |
Gotchas & Quick Fixes
Use greseq (Not seq) for the GRE Sequence Number
a -> b gre seq 10a -> b gre greseq 10Bare 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)
a -> b gre dstport 4789a -> 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).