Protocol 9 of 81Layer 3FrameAssembly v3.1.2
llms-full.txt
icmpInternet Control Message Protocol v4 & Dual-Stack ICMPv6

Ping, Traceroute & Path MTU Blackholes (echorequest <-> echoreply)

Default Port / Protocol
IP Proto 1 (v4) / NextHdr 58 (v6)
Host Endpoint Rule
Dual-Stack Morphing (v4/v6)
Wireshark Display Filter
icmp || icmpv6
Standards & Specs
RFC 792, RFC 4443
Wire Stack:Ethernet II[802.1Q / QinQ / MPLS]IPv4 / IPv6ICMP / ICMPv6 (IP Proto 1 (v4) / NextHdr 58 (v6))

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.

icmp_quickstart.frasm7 lines
Open in 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 Header 58 (0x86dd) over IPv6 endpoints.
  • Translates echorequest (8 v4 / 128 v6), echoreply (0 v4 / 129 v6), destunreach (3 v4 / 1 v6), timeexceeded (11 v4 / 3 v6), and redirect (5 v4 / 137 v6).
  • Computes the RFC 1071 ones-complement checksum on IPv4 and the mandatory RFC 4443 40-byte IPv6 pseudo-header checksum on IPv6.
Multi-Frame Lab · Ready to Compile

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.

icmp_dualstack_pmtud.frasm18 lines
Open in Playground
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
}
Terminal Commands (FrameAssembly CLI v3.1.2)
# 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.frasm

All 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 / OptionAccepted ValueDefaultEffect on Packet
echorequest | echoreply | destunreach | timeexceeded | redirectNamed ICMP message shorthandechorequestMaps 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 integersDerived 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 integersid 1, seq 1Sets the 16-bit Echo Identifier and Echo Sequence Number in the 4-byte rest-of-header.
gateway <ipv4>IPv4 address literal0.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
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

Zero Underscores in ICMP Message Keywords

Avoid
a -> b icmp echo_request
Valid v3.1.2 Syntax
a -> b icmp echorequest

Write echorequest, echoreply, destunreach, and timeexceeded with zero underscores.

Both Endpoints Must Share the Same IP Address Family

Avoid
app_v4 -> edge_v6 icmp echorequest
Valid v3.1.2 Syntax
app_v6 -> edge_v6 icmp echorequest

Both 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.

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