Add two tips: (1) change dump device; (2) encrypted swap as dump
[ikiwiki.git] / 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. This will break into the kernel debugger. Then type:
53
54     # panic
55
56 The machine should reboot 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     # call dumpsys
61
62 During the following startup the core dump will be automatically saved to `/var/crash`.
63
64
65 ## Create a Core Dump Automatically on Panic
66
67 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.
68
69 This configuration may be useful on a remote system.
70
71
72 ## Tips
73
74 * You can have the settings described above take effect without rebooting using the following commands:
75
76         # dumpon /dev/<devicenode>
77         # sysctl kern.sync_on_panic=0
78
79 * 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.
80
81 * 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.
82
83 * 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):
84
85         hw.physmem="64M"
86
87 * 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).