Page MenuHomeFreeBSD

Update dumpon(8) to include sysctl variable information
AcceptedPublic

Authored by felix.the.red_gmail.com on Oct 24 2021, 5:06 AM.
Tags
None
Referenced Files
Unknown Object (File)
Sep 11 2025, 9:51 PM
Unknown Object (File)
Sep 8 2025, 12:57 AM
Unknown Object (File)
Aug 28 2025, 3:45 AM
Unknown Object (File)
Aug 1 2025, 6:04 PM
Unknown Object (File)
Jul 26 2025, 9:31 AM
Unknown Object (File)
Jul 21 2025, 4:17 PM
Unknown Object (File)
Jul 12 2025, 12:06 AM
Unknown Object (File)
Jul 11 2025, 3:37 AM

Details

Reviewers
gbe
ziaee
markj
Group Reviewers
manpages
Summary

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

Diff Detail

Repository
rG FreeBSD src repository
Lint
Lint Passed
Unit
No Test Coverage
Build Status
Buildable 62381
Build 59265: arc lint + arc unit

Event Timeline

gbe added a subscriber: gbe.

LGTM

This revision is now accepted and ready to land.Oct 24 2021, 7:03 AM
markj added inline comments.
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 requested changes to this revision.Feb 7 2025, 12:59 AM
ziaee added a reviewer: manpages.
ziaee added a subscriber: 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.

This revision now requires changes to proceed.Feb 7 2025, 12:59 AM

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

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

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

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.

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

PR: 259393

This revision is now accepted and ready to land.Feb 12 2025, 2:44 PM