igmp

Overview ¶

Package igmp decodes Internet Group Management Protocol packets per RFC 3376 (IGMPv3) and RFC 2236 (IGMPv2). IGMPv1 (RFC 1112) is recognised as a degenerate v2 form. MLD (the IPv6 equivalent, RFC 3810) is not covered here.

Wrap-vs-native judgement

Native. Both RFCs are fully public; IGMP wire format is
a tight 8-byte fixed header for v2 (or a slightly larger
header for v3 with the QRV/QQIC byte + Number of Sources
+ Source Addresses tail) and a per-record list for
IGMPv3 Membership Reports. No crypto, no compression,
no varints (apart from the exp+mantissa Max Resp Code
encoding documented in RFC 3376 §4.1.1). Operators paste
IGMP bytes (IP protocol number 2, multicast to 224.0.0.1
for General Queries or 224.0.0.22 for IGMPv3 Reports)
from a `tcpdump -X proto 2` line, a Wireshark Follow-IP-
Stream view, or any IGMP-speaking router's tcpdump and
get the documented header + per-version body breakdown.

What this package covers

• **Version auto-detection**: Type 0x11 with body length 8 = IGMPv1/v2 General Query; Type 0x11 with body length ≥12 = IGMPv3 Membership Query; Type 0x22 = IGMPv3 Membership Report; Type 0x16 = IGMPv2 Membership Report; Type 0x17 = IGMPv2 Leave Group; Type 0x12 = IGMPv1 Membership Report (legacy).

• **IGMPv2 fixed 8-byte header** (RFC 2236 §2):

• byte 0: **Type** with **5-entry name table**: 0x11 Membership Query, 0x12 IGMPv1 Membership Report, 0x16 IGMPv2 Membership Report, 0x17 Leave Group, 0x22 IGMPv3 Membership Report (dispatched separately).

• byte 1: Max Resp Time (1/10 seconds for v2; encoded Max Resp Code for v3 Query — see §4.1.1).

• bytes 2-3: Checksum (uint16 BE, hex-formatted).

• bytes 4-7: Group Address (4 bytes IPv4; 0.0.0.0 for General Query).

• **IGMPv3 Query body extension** (RFC 3376 §4.1):

• byte 8: 4-bit Resv + 1-bit **S** (Suppress Router- Side processing flag) + 3-bit **QRV** (Querier's Robustness Variable; default 2)

• byte 9: **QQIC** (Querier's Query Interval Code — same exp+mantissa encoding as Max Resp Code)

• bytes 10-11: Number of Sources (uint16 BE)

• N × 4 bytes: Source Addresses

• **IGMPv3 Membership Report body** (RFC 3376 §4.2):

• bytes 4-5: Reserved

• bytes 6-7: Number of Group Records (uint16 BE)

• Group Records (variable; each is 8-byte fixed header + N source addresses + Aux Data):

• byte 0: **Record Type** with **6-entry name table**: 1 MODE_IS_INCLUDE, 2 MODE_IS_EXCLUDE, 3 CHANGE_TO_INCLUDE_MODE, 4 CHANGE_TO_EXCLUDE_ MODE, 5 ALLOW_NEW_SOURCES, 6 BLOCK_OLD_SOURCES.

• byte 1: Aux Data Len (in 4-byte words; should be 0 per RFC 3376).

• bytes 2-3: Number of Sources (uint16 BE).

• bytes 4-7: Multicast Address (IPv4).

• N × 4 bytes: Source Addresses.

• Aux Data Len × 4 bytes: Auxiliary Data (deprecated; surfaced as raw hex).

• **Max Resp Code exp+mantissa encoding** (RFC 3376 §4.1.1) — when the byte value is < 128 it's the direct centisecond count; when ≥ 128 it's split as 0x80 | (exp<<4) | mant → (mant | 0x10) << (exp + 3). Surfaced both as the encoded byte and the decoded value in centiseconds + milliseconds.

What this package does NOT cover (deliberately out of scope)

• IP framing — feed IGMP bytes after the IPv4 header strip. IGMP runs over IP protocol 2.

• MLD (Multicast Listener Discovery, RFC 3810) — the IPv6 equivalent of IGMP; uses ICMPv6 type 130-132 and 143 (already partially decoded by `icmp_packet_decode`); a future Spec would walk MLDv2.

• IGMP Router-Side state machine — Query intervals, Robustness Variable retries, group-membership timeout reasoning — that's higher-level analysis.

• IP Router Alert option (RFC 2113) — IGMP packets should have it; checked at the IP layer.