docs/howtos/HowToCreateACoreDump.mdwn

   1 [[!meta title="How to Get a Core Dump"]]
   2
   3 [[!toc levels=3 ]]
   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 ## Requirements
  10
  11 * A dump partition not smaller than the main memory (usually swap)
  12
  13 * `/var/crash` must be on a filesystem with enough space to hold the dump (the size of main memory).
  14
  15 * "sync on panic" should be disabled in the kernel
  16
  17
  18 ## Configurations
  19
  20 ### Dump device
  21
  22 * If your swap partition is as large as main memory, it can be used as a dump device.
  23
  24 * If your swap partition is too small, you should use any partition that *doesn't* contain a filesystem.
  25
  26 * Add this to `/etc/rc.conf`:
  27
  28         dumpdev="/dev/<devicenode>"
  29
  30 * Please refer to [dumpon(8)](http://mdoc.su/d/dumpon) for details.
  31
  32 ### /var/crash
  33
  34 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:
  35
  36     # cpdup /var/crash /home/var.crash
  37     # rm -rf /var/crash
  38     # ln -s /home/var.crash /var/crash
  39
  40 ### Disable "sync on panic"
  41
  42 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`:
  43
  44     kern.sync_on_panic=0
  45
  46
  47 ## Get a Core Dump
  48
  49 Hit `<Ctrl-Alt-Esc>` at the desired moment. This will break into the kernel debugger. Then type:
  50
  51     # panic
  52
  53 The machine should reboot automatically. Sometimes it might require a cold reset.
  54
  55 If the machine has dropped to a `db>` prompt by itself you can type the following to get a useful dump:
  56
  57     # call dumpsys
  58
  59 During the following startup the core dump will be automatically saved to `/var/crash`.
  60
  61
  62 ## Create a Core Dump Automatically on Panic
  63
  64 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.
  65
  66 This configuration may be useful on a remote system.
  67
  68
  69 ## Tips
  70
  71 * You can have the settings described above take effect without rebooting using the following commands:
  72
  73         # dumpon /dev/<devicenode>
  74         # sysctl kern.sync_on_panic=0
  75
  76 * 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):
  77
  78         hw.physmem="64M"
  79
  80 * 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).