NETDUMP(4)

💖 NETDUMP(4) 💖

okay bestie, gather round, because this is netdump(4) from the Kernel Interfaces Manual and it is literally the protocol that lets a dying kernel scream its last words into the network. no cap. 🫶

---

✨ NAME ✨

netdump — the protocol for transmitting kernel dumps to a remote server 👑

---

🌸 SYNOPSIS 🌸

so if you want netdump client support baked into your kernel, you drop this line into your kernel configuration file:

options NETDUMP

that's it. that's the whole ritual. 🕯️

---

🦋 DESCRIPTION 🦋

netdump is a UDP-based protocol for transmitting kernel dumps to a remote host. so like: a netdump client is a panicking kernel 😭 (yes, the one having the worst day of its life), and a netdump server is a host running the netdump daemon, which you can find in ports as ports/ftp/netdumpd. netdump clients get configured using the dumpon(8) utility. slay.

netdump client messages are built like a little sandwich: a fixed-size header followed by a variable-sized payload. the header carries:

• the message type
• a sequence number
• the offset of the payload data in the kernel dump
• the length of the payload data (not including the header)

the message types are HERALD, FINISHED, KDH, VMCORE, and EKCD_KEY. 💅

netdump server messages are fixed size and contain only the sequence number of the client message. they mean "yep, bestie, I successfully processed the client message with that exact sequence number." every single client message gets acknowledged this way. and server messages are always sent to port 20024 of the client.

to kick off a netdump, the client sends a HERALD message to the server at port 20023. the client may include a relative path in its payload — and if it does, the netdump server should attempt to save the dump at that path relative to its configured dump directory. the server acknowledges the HERALD using a random source port, and from then on the client must send all subsequent messages to that port. no takebacks. 🙈

the KDH, VMCORE, and EKCD_KEY message payloads contain the kernel dump header, the dump contents, and the dump encryption key respectively. the offset in the message header should be treated as a seek offset in the corresponding file. and there are no ordering requirements for these messages — chaotic, but valid. ✨

a netdump is completed by sending the FINISHED message to the server. goodbye forever. 🎀

the following network drivers support netdump: alc(4), bge(4), bnxt(4), bxe(4), cxgb(4), em(4), igb(4), ix(4), ixl(4), mlx4en(4), mlx5en(4), re(4), vtnet(4). the whole squad. 🔥

---

⭐ SYSCTL VARIABLES ⭐

these little cuties are available as both sysctl(8) variables and loader(8) variables. double threat energy:

• net.netdump.debug — controls debug message verbosity. debug messages are disabled by default, but they're genuinely useful when you're troubleshooting or when you're developing driver support. turn them on when things get weird. 👀
• net.netdump.path — specifies a path relative to the server's dump directory in which to store the dump. for example, if the netdump server is configured to store dumps in /var/crash, a path of “foo” will cause the server to attempt to store dumps from the client in /var/crash/foo. > ⚠️ heads up bestie: the server will not automatically create the relative directory. you gotta make it yourself.
• net.netdump.polls — the client will poll the configured network interface while waiting for acknowledgements. this parameter controls the maximum number of poll attempts before giving up, which typically results in a re-transmit. each poll attempt takes 0.5ms. so like, do the math before you set it too low. 😭
• net.netdump.retries — the number of times the client will re-transmit a packet before aborting a dump due to a lack of acknowledgement. ngl, the default may be too small in environments with lots of packet loss. 🫠
• net.netdump.arp_retries — the number of times the client will attempt to learn the MAC address of the configured gateway or server before giving up and aborting the dump. it's giving "one more try then I'm leaving." 💀

---

🌈 SEE ALSO 🌈

decryptcore(8), dumpon(8), savecore(8)

---

👑 HISTORY 👑

netdump client support first appeared in FreeBSD 12.0. a legend from birth, fr fr.

---

💜 BUGS 💜

• Only IPv4 is supported. that's the whole IPv4-only situation, sorry to the v6 girlies. 😭
• netdump may only be used after the kernel has panicked. yes, really. it's the emergency protocol. it's giving "main character energy but only in the final act." 💅

---

and that's the whole page, bestie!! this one's from the Debian manual set, dated August 25, 2020 — go forth and dump those kernels responsibly. mwah 💖✨🎀🦋