ICMP6(4)

💖 icmp6 — Internet Control Message Protocol for IPv6 💖

okay bestie, so this is the icmp6(4) page from section 4 of the Kernel Interfaces Manual, and it's literally the whole vibe guide to ICMPv6 — the error-and-control-message protocol for IPv6. no cap, it's giving "networking's group chat for complaints and announcements" energy. let's get into it 🫶

---

✨ SYNOPSIS ✨

#include <sys/socket.h>
#include <netinet/in.h>
#include <netinet/icmp6.h>

int
socket(AF_INET6, SOCK_RAW, IPPROTO_ICMPV6);

---

🌸 DESCRIPTION 🌸

ICMPv6 is the error and control message protocol used by IPv6 and the whole IPv6 protocol family (peep ip6(4) and inet6(4) for the lore). you can slide into it through a "raw socket" if you're doing network monitoring and diagnostic functions. it's the main character of diagnostics, periodt. 👑

the proto parameter you pass to the socket(2) call to create an ICMPv6 socket? you can get it from getprotobyname(3). ICMPv6 sockets are connectionless, and they're normally used with sendto(2) and recvfrom(2) calls — though the connect(2) call can also be used to lock in the destination for future packets. and if you do that? then read(2) or recv(2), plus write(2) or send(2) system calls, are totally allowed too. choose your own adventure bestie ✨

outgoing packets automatically get an IPv6 header prepended to them (based on the destination address). incoming packets on the socket arrive with the IPv6 header and any extension headers already removed. so clean, so efficient, we love her 💅

🦋 Types 🦋

ICMPv6 messages get sorted by the type and code fields hanging out in the ICMPv6 header. the abbreviations for the types and codes can be used in rules in pf.conf(5) — iykyk. here are the types that are defined:

• 1 — unreach — Destination unreachable
• 2 — toobig — Packet too big
• 3 — timex — Time exceeded
• 4 — paramprob — Invalid IPv6 header
• 128 — echoreq — Echo service request
• 129 — echorep — Echo service reply
• 130 — groupqry — Group membership query
• 130 — listqry — Multicast listener query
• 131 — grouprep — Group membership report
• 131 — listenrep — Multicast listener report
• 132 — groupterm — Group membership termination
• 132 — listendone — Multicast listener done
• 133 — routersol — Router solicitation
• 134 — routeradv — Router advertisement
• 135 — neighbrsol — Neighbor solicitation
• 136 — neighbradv — Neighbor advertisement
• 137 — redir — Shorter route exists
• 138 — routrrenum — Route renumbering
• 139 — fqdnreq — FQDN query
• 139 — niqry — Node information query
• 139 — wrureq — Who-are-you request
• 140 — fqdnrep — FQDN reply
• 140 — nirep — Node information reply
• 140 — wrurep — Who-are-you reply
• 200 — mtraceresp — mtrace response
• 201 — mtrace — mtrace messages

and here are the codes that are defined (with their type, obvi):

• 0 — noroute-unr — type unreach — No route to destination
• 1 — admin-unr — type unreach — Administratively prohibited
• 2 — beyond-unr — type unreach — Beyond scope of source address
• 2 — notnbr-unr — type unreach — Not a neighbor (obsolete)
• 3 — addr-unr — type unreach — Address unreachable
• 4 — port-unr — type unreach — Port unreachable
• 0 — transit — type timex — Time exceeded in transit
• 1 — reassemb — type timex — Time exceeded in reassembly
• 0 — badhead — type paramprob — Erroneous header field
• 1 — nxthdr — type paramprob — Unrecognized next header
• 2 — (no abbrev, she's mysterious) — type redir — Unrecognized option
• 0 — redironlink — type redir — Redirection to on-link node
• 1 — redirrouter — type redir — Redirection to better router

🎀 Headers 🎀

all ICMPv6 messages get prefixed with an ICMPv6 header. this header matches the icmp6_hdr structure and it looks exactly like this, bestie:

struct icmp6_hdr {
        uint8_t  icmp6_type;    /* type field */
        uint8_t  icmp6_code;    /* code field */
        uint16_t icmp6_cksum;   /* checksum field */
        union {
                uint32_t icmp6_un_data32[1]; /* type-specific */
                uint16_t icmp6_un_data16[2]; /* type-specific */
                uint8_t  icmp6_un_data8[4];  /* type-specific */
        } icmp6_dataun;
} __packed;

#define icmp6_data32    icmp6_dataun.icmp6_un_data32
#define icmp6_data16    icmp6_dataun.icmp6_un_data16
#define icmp6_data8     icmp6_dataun.icmp6_un_data8
#define icmp6_pptr      icmp6_data32[0] /* parameter prob */
#define icmp6_mtu       icmp6_data32[0] /* packet too big */
#define icmp6_id        icmp6_data16[0] /* echo request/reply */
#define icmp6_seq       icmp6_data16[1] /* echo request/reply */
#define icmp6_maxdelay  icmp6_data16[0] /* mcast group membership*/

so icmp6_type describes the type of the message, and the suitable values are defined in ⟨netinet/icmp6.h⟩. icmp6_code describes the sub-type of the message and it depends on icmp6_type (they're a package deal, fr). icmp6_cksum holds the checksum for the message and it gets filled in by the kernel on outgoing messages — the kernel does that for you, no need to stress 💖. the other fields are used for type-specific purposes.

🌈 Filters 🌈

because ICMPv6 has so much extra functionality compared to ICMPv4, a larger number of messages may potentially be received on an ICMPv6 socket. so input filters are the move — they restrict input to a subset of the incoming ICMPv6 messages so that only the interesting ones get returned by the recv(2) family of calls to an application. vibe check: only the messages you asked for make it through.

the icmp6_filter structure can be used to refine the input message set according to the ICMPv6 type. by default, all message types are allowed on newly created raw ICMPv6 sockets. these macros are available to refine the input set:

• void ICMP6_FILTER_SETPASSALL(struct icmp6_filter *filterp) — allow all incoming messages. filterp is modified to allow all message types.
• void ICMP6_FILTER_SETBLOCKALL(struct icmp6_filter *filterp) — ignore all incoming messages. filterp is modified to ignore all message types.
• void ICMP6_FILTER_SETPASS(int type, struct icmp6_filter *filterp) — allow ICMPv6 messages with the given type. filterp is modified to allow such messages.
• void ICMP6_FILTER_SETBLOCK(int type, struct icmp6_filter *filterp) — ignore ICMPv6 messages with the given type. filterp is modified to ignore such messages.
• int ICMP6_FILTER_WILLPASS(int type, const struct icmp6_filter *filterp) — determine if the given filter will allow an ICMPv6 message of the given type.
• int ICMP6_FILTER_WILLBLOCK(int type, const struct icmp6_filter *filterp) — determine if the given filter will ignore an ICMPv6 message of the given type.

the getsockopt(2) and setsockopt(2) calls may be used to obtain and install the filter on ICMPv6 sockets — at option level IPPROTO_ICMPV6 and name ICMP6_FILTER, with a pointer to the icmp6_filter structure as the option value. that's the whole recipe, slay. ✨

---

👑 SEE ALSO 👑

• getsockopt(2)
• recv(2)
• send(2)
• setsockopt(2)
• socket(2)
• getprotobyname(3)
• inet6(4)
• ip6(4)
• netintro(4)

W. Stevens and M. Thomas, Advanced Sockets API for IPv6, RFC 2292, February 1998.

A. Conta and S. Deering, Internet Control Message Protocol (ICMPv6) for the Internet Protocol Version 6 (IPv6) Specification, RFC 2463, December 1998.

---

okay that's the whole page bestie, you ate it 💅 this one came from Debian, dated November 7, 2012, and it lives in the manual as ICMP6(4). go forth and diagnose, you iconic network gremlin 🦋💖