docs/howtos/HowToCreateACoreDump.mdwn

   1 [[!meta title="How to Get a Core Dump"]]
   2
   3 [[!toc levels=3 startlevel=2]]
   4
   5 Sometimes, a system **core dump** (also called post-mortem dump) is needed to track down a bug in the DragonFly BSD kernel.
   6
   7 **WARNING**: A core dump is obtained by triggering a *kernel panic*, which likes *directly cutting off the power*, therefore, unsaved data will be lost, recently saved data (still in the cache) might be lost, and filesystems mounted async might be destroyed.
   8
   9 **WARNING**: The saved core file (in `/var/crash`) contains *sensitive* data, e.g., passwords, certificates, decrypted private keys.  Therefore, do *not* upload it to somewhere that can be publicly accessed!
  10
  11
  12 ## Requirements
  13
  14 * A dump partition not smaller than the main (physical) memory.  Usually the swap partition is used as the dump partition.
  15
  16 * `/var/crash` must be on a filesystem with enough space to hold the dump (the size of main memory).
  17
  18 * "sync on panic" should be disabled in the kernel
  19
  20
  21 ## Configurations
  22
  23 ### Dump device
  24
  25 * If your swap partition is as large as main memory, it can be used as a dump device.
  26
  27 * If your swap partition is too small, you should use any partition that *doesn't* contain a filesystem.
  28
  29 * Add this to `/etc/rc.conf`:
  30
  31         dumpdev="/dev/<devicenode>"
  32
  33 * Please refer to [dumpon(8)](http://mdoc.su/d/dumpon) for details.
  34
  35 ### /var/crash
  36
  37 If `/var/crash` is residing on a filesystem without enough room to accommodate the core dump, you can move it to a different filesystem and use a symbolic link. For example:
  38
  39     # cpdup /var/crash /home/var.crash
  40     # rm -rf /var/crash
  41     # ln -s /home/var.crash /var/crash
  42
  43 ### Disable "sync on panic"
  44
  45 The `kern.sync_on_panic` controls whether to do a sync before rebooting from a panic, which is disabled by default as we required.  Otherwise, ddd this to `/etc/sysctl.conf`:
  46
  47     kern.sync_on_panic=0
  48
  49
  50 ## Get a Core Dump
  51
  52 Hit `<Ctrl-Alt-Esc>` at the desired moment, or execute `sysctl debug.panic=1`, then the system will break into the kernel debugger `db>`. Then type:
  53
  54     db> panic
  55
  56 The system will dump and reboot the machine automatically. Sometimes it might require a cold reset.
  57
  58 If the machine has dropped to a `db>` prompt by itself you can type the following to get a useful dump:
  59
  60     db> call dumpsys
  61
  62 Once the dump finished, type `reset` to reboot the machine:
  63
  64     db> reset
  65
  66 During the following startup, the dumped core will be automatically saved to `/var/crash`.
  67
  68
  69 ## Create a Core Dump Automatically on Panic
  70
  71 Set `debug.debugger_on_panic=0` or configure your kernel with options `DDB_UNATTENDED`, which will create a core dump automatically and reboot on system panic.
  72
  73 This configuration may be useful on a remote system.
  74
  75 See also [`ddb(4)`](http://www.dragonflybsd.org/cgi/web-man?command=ddb&section=4) for more details.
  76
  77 ## Tips
  78
  79 * You can have the settings described above take effect without rebooting using the following commands:
  80
  81         # dumpon /dev/<devicenode>
  82         # sysctl kern.sync_on_panic=0
  83
  84 * If a dump device is already configured but you want to change it without rebooting, then it is required to turn off the dump first by executing `dumpon off`, then use `dumpon /dev/<devicenode>` to set the new dump device.
  85
  86 * If the swap partition to be also used as the dump device is encrypted (e.g., using `dm-crypt`), the underlying swap device (e.g., `/dev/serno/xxxx`) should be used to specify the dump device, instead of using the mapped device name.
  87
  88 * Core files can get quite unwieldy with large amounts of main memory. In order to temporarily limit the amount of physical memory add a line similar to the following to `/boot/loader.conf` (and remove it again once you've produced the core dump):
  89
  90         hw.physmem="64M"
  91
  92 * On systems derived from DEVELOPMENT branch after 20 August 2005, you can get a panic directly by pressing `<Ctrl-Alt-Shift-Esc>` if you set `machdep.enable_panic_key=1` (which is disabled by default).