Update dumpon(8) to include sysctl variable information

[felix.the.red_gmail.com]

Summary

Document debug.minidump, machdep.dump_retry_count, and kern.bootfile sysctl variables.

[gbe]

LGTM

[markj]

sbin/dumpon/dumpon.8

379

kern.bootfile really has nothing to do with dumpon, it is just mentioned in dumpon.8 as part of an example. Several debugging tools, such as kgdb and dtrace use it to find the kernel executable. I think dumpon.8 is not the right place to document it.

kern.bootfile is effectively set by loader(8), together with kern.module_path. I'm not sure where exactly they would best be documented, but IMO it should be grouped with boot loader documentation. We could certainly use better documentation of the handoff between loader and the kernel, I spent a lot of time last weekend trying to figure out how exactly loader(8) picks the kernel to boot (loader.conf variables which control this include kernel, kernel_path, module_path, bootfile, currdev, loaddev, and some are not meant to be set by users), and it's really not clear from our man pages.

[ziaee]

Let's get this one in the tree?
Please remove the 379,380.
Is 384 still accurate?

Also, please always add manpages as a reviewer if you are working on manual pages.

[emaste]

Please generate diffs with full context (e.g. git diff -U99999 or git show -U99999 <hash>) when uploading through the web UI

[felix.the.red_gmail.com]

Is the fix for this PR is to update the revision and remove the kern.bootfile section?

[ziaee]

To me, based on Markj's teaching, yes. I agree based on his reasoning that it needs to go into the manpages for loader. We also need to check if machdep.dump_retry_count has been implemented for arm64.

sbin/dumpon/dumpon.8

373

This should also be a colon :.

[markj]

In D32618#1116061, @felix.the.red_gmail.com wrote:

Is the fix for this PR is to update the revision and remove the kern.bootfile section?

I don't object to that. It makes some sense to document sysctls related to kernel dumps here.

Better would be to have a new kerneldump.4 man page, IMHO. Basically explaining:

• what is a kernel dump (a memory dump that can be opened by kgdb and used to debug kernel crashes)
• how does one ask the kernel to dump (DDB's dump command; automatic dump-on-panic via debug.debugger_on_panic=0)
• some explanation of the minidump format (the main file format used for kernel dumps; a custom file format that lets the kernel avoid dumping unused memory in order to save disk space)
• how do kernel dumps get saved (reference dumpon(8); can be saved to an unused region of a disk, typically a swap device, or over the network via netdump)
• how do kernel dumps get recovered (savecore(8) for disk dumps, netdumpd from ports for netdumps)
• how does one open a kernel dump using a debugger (explain that debug symbols, typically under /usr/lib/debug/boot/kernel, are required)
• what sysctls control kernel dump behaviour (e.g., debug.debugger_on_panic, machdep.dump_retry_count)

Of course, this is hard to write without some experience, but it's fairly easy to experiment with kernel dumps in a VM. The aim would be to document internals and technical details; the handbook has more user-facing documentation).

If anyone would like to take this on, I can review a draft and help flesh it out. Otherwise I'll add it to my todo list.

[felix.the.red_gmail.com]

Remove kern.bootfile, this needs to be documented elsewhere.

PR: 259393