icmpInternet Control Message Protocol v4 & Dual-Stack ICMPv6Ping, Traceroute & Path MTU Blackholes (echorequest <-> echoreply)
What It Does on the Wire
The humble ping (a -> b icmp echorequest and a <- b icmp echoreply) automatically emits ICMPv4 over IPv4 hosts or ICMPv6 with full pseudo-header checksums over IPv6 hosts.
Internet Control Message Protocol (icmp) handles network reachability diagnostics, Path MTU Discovery signaling, and hop-limit expiration feedback. In FrameAssembly v3.1.2, icmp is dual-stack morphing: when invoked between IPv4 hosts, it emits IPv4 Protocol 1 with an RFC 1071 header checksum; when invoked between IPv6 hosts, the exact same syntax automatically morphs into ICMPv6 (Next Header 58) with a full RFC 4443 IPv6 pseudo-header checksum.
Named shorthands (echorequest, echoreply, destunreach, timeexceeded, redirect) map transparently to their respective v4 (8, 0, 3, 11, 5) and v6 (128, 129, 1, 3, 137) wire Type codes.
Path MTU Discovery (PMTUD) Blackhole Debugging
Synthesize df-flagged probes alongside icmp destunreach code 4 (Fragmentation Needed, IPv4) or ICMPv6 Packet Too Big (type 2 code 0) to test firewall ICMP filtering.
Traceroute Hop-Limit Expiration Simulation
Emit sequences of ttl 1, ttl 2, and icmp timeexceeded router replies to verify observability and MTR/traceroute parsers.
Dual-Stack Reachability & Ping Flood IDS Rules
Run a single flow ping_pair(a, b) over both IPv4 and IPv6 endpoints to generate matching Suricata/Zeek baseline test fixtures.
Minimal Quickstart (icmp_quickstart.frasm)
Hit Preview Packets to compile in-browser and eyeball timestamps + wire byte lengths, or ship it straight to the Playground.
host client { ip 10.0.0.10 }host router { ip 10.0.0.1 }compile { client -> router icmp echorequest wait 2ms client <- router icmp echoreply}What the Compiler Calculates So You Don't Have To
- Automatically selects IPv4 Protocol
1(0x0800) over IPv4 endpoints or ICMPv6 Next Header58(0x86dd) over IPv6 endpoints. - Translates
echorequest(8v4 /128v6),echoreply(0v4 /129v6),destunreach(3v4 /1v6),timeexceeded(11v4 /3v6), andredirect(5v4 /137v6). - Computes the RFC 1071 ones-complement checksum on IPv4 and the mandatory RFC 4443 40-byte IPv6 pseudo-header checksum on IPv6.
Dual-Stack Echo Flow Plus IPv4 Fragmentation-Needed & Traceroute TTL Expiry
Reuses a ping_test(src, dst) flow across IPv4 and IPv6 hosts, then sends a router Time Exceeded (ttl 1) and Fragmentation Needed (destunreach code 4) reply.
host app_v4 { ip 10.10.0.25 }host edge_v4 { ip 10.10.0.1 }host app_v6 { ip 2001:db8:10::25 }host edge_v6 { ip 2001:db8:10::1 }flow ping_test(src, dst) { src -> dst icmp echorequest id 0x2026 seq 1 payload "healthcheck-probe" wait 1ms src <- dst icmp echoreply id 0x2026 seq 1 payload "healthcheck-probe" wait 2ms}compile { ping_test(app_v4, edge_v4) ping_test(app_v6, edge_v6) // Traceroute hop 1 expiry + PMTUD Fragmentation Needed (Type 3, Code 4) app_v4 -> edge_v4 icmp echorequest id 0x2026 seq 2 ttl 1 df wait 1ms app_v4 <- edge_v4 icmp timeexceeded code 0 wait 2ms app_v4 <- edge_v4 icmp destunreach code 4}# 1. Eyeball relative timestamps, ports & wire lengths in your terminal
frameassembly show icmp_dualstack_pmtud.frasm
# 2. Compile .frasm -> classic .pcap (tcpdump/tcpreplay/Suricata) or nanosecond .pcapng
frameassembly icmp_dualstack_pmtud.frasm icmp_dualstack_pmtud.pcap
frameassembly icmp_dualstack_pmtud.frasm icmp_dualstack_pmtud.pcapng
# 3. Round-trip .pcap <-> .frasm whenever you want to scrub or tweak an existing capture
frameassembly reverse icmp_dualstack_pmtud.pcap icmp_dualstack_pmtud_edited.frasmAll icmp 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 icmp:
src_host -> dst_host icmp [echorequest | echoreply | destunreach | timeexceeded | redirect] [type <0..255>] [code <0..255>] [id <0..65535>] [seq <0..65535>] [gateway <ipv4>]| Keyword / Option | Accepted Value | Default | Effect on Packet |
|---|---|---|---|
| echorequest | echoreply | destunreach | timeexceeded | redirect | Named ICMP message shorthand | echorequest | Maps to IPv4/ICMPv6 Type codes: 8/128 (echorequest), 0/129 (echoreply), 3/1 (destunreach), 11/3 (timeexceeded), 5/137 (redirect). |
| type <0..255> | code <0..255> | 8-bit unsigned integers | Derived from shorthand (code 0) | Explicitly overrides the 1-byte ICMP/ICMPv6 Type and Code fields (e.g., type 2 code 0 for ICMPv6 Packet Too Big). |
| id <0..65535> | seq <0..65535> | 16-bit unsigned integers | id 1, seq 1 | Sets the 16-bit Echo Identifier and Echo Sequence Number in the 4-byte rest-of-header. |
| gateway <ipv4> | IPv4 address literal | 0.0.0.0 (or source router IPv4) | Sets the 4-byte Redirect Gateway Internet Address on IPv4 icmp redirect messages. |
Cross-Layer Wrappers Valid with icmp
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 icmp
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
Zero Underscores in ICMP Message Keywords
a -> b icmp echo_requesta -> b icmp echorequestWrite echorequest, echoreply, destunreach, and timeexceeded with zero underscores.
Both Endpoints Must Share the Same IP Address Family
app_v4 -> edge_v6 icmp echorequestapp_v6 -> edge_v6 icmp echorequestBoth hosts on a single packet line must use IPv4 or both must use IPv6—you cannot send a packet directly from an IPv4 host to an IPv6 host.