add new mirror in serbia, thanks to fourdots
[ikiwiki.git] / docs / howtos / HowToCreateACoreDump.mdwn
index 8950a31..3c67c1a 100644 (file)
@@ -1,73 +1,83 @@
-# Getting a system core dump 
-[[!toc levels=3 ]]�  A full system core dump (also called post-mortem dump) is sometimes needed to track down a bug in the DragonFlyBSD kernel.
+[[!meta title="How to Get a Core Dump"]]
+
+[[!toc levels=3 ]]
+
+Sometimes, a system **core dump** (also called post-mortem dump) is needed to track down a bug in the DragonFly BSD kernel.
+
+**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.
+
+**WARNING**: The saved core file (in `/var/crash`) contains *sensitive* data, e.g., passwords, certificates, decrypted private keys.  Therefore, do *not* upload it to public clouds/servers!
 
-Please note: A full core dump is obtained by triggering a kernel panic. Like when pulling the power plug from the wall socket, unsaved data will be lost, recently saved data might be lost, and filesystems mounted async might be destroyed.
 
 ## Requirements 
 
-* a dump partition at least as large as main memory (usually swap)
+* A dump partition not smaller than the main memory (usually swap)
 
 * `/var/crash` must be on a filesystem with enough space to hold the dump (the size of main memory).
 
-* sync on panic should be disabled in the kernel
+* "sync on panic" should be disabled in the kernel
 
-## Setup 
-### Setting up the dump device 
+
+## Configurations
+
+### Dump device 
 
 * If your swap partition is as large as main memory, it can be used as a dump device.
 
-* If your swap partition is too small, you use any partition that doesn't contain a filesystem.
+* If your swap partition is too small, you should use any partition that *doesn't* contain a filesystem.
 
 * Add this to `/etc/rc.conf`:
 
-    
-     dumpdev="/dev/<devicenode>"
+        dumpdev="/dev/<devicenode>"
 
+* Please refer to [dumpon(8)](http://mdoc.su/d/dumpon) for details.
 
-* Please refer to [dumpon(8)](http://leaf.dragonflybsd.org/cgi/web-man?command#dumpon&section8) (http://leaf.dragonflybsd.org/cgi/web-man?command=dumpon&section=8) for details.
+### /var/crash
 
-### Setting up /var/crash 
-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.
+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:
 
-    
     # cpdup /var/crash /home/var.crash
     # rm -rf /var/crash
     # ln -s /home/var.crash /var/crash
 
-### Disabling sync on panic 
-Add this to `/etc/sysctl.conf`
+### Disable "sync on panic"
+
+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`:
 
-    
     kern.sync_on_panic=0
 
-# Getting a core dump 
-Hit `<ctrl-alt-esc>` at the desired moment. This will break into the kernel debugger. Then type:
 
-    
+## Get a Core Dump
+
+Hit `<Ctrl-Alt-Esc>` at the desired moment. This will break into the kernel debugger. Then type:
+
     # panic
 
 The machine should reboot automatically. Sometimes it might require a cold reset.
 
-If the machine has dropped to a dbb> prompt by itself you can type the following to get a useful dump:
+If the machine has dropped to a `db>` prompt by itself you can type the following to get a useful dump:
 
-    
     # call dumpsys
 
 During the following startup the core dump will be automatically saved to `/var/crash`.
 
-# Useful hints 
 
-* You can have the settings described above take effect without rebooting using the following commands:
+## Create a Core Dump Automatically on Panic
+
+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.
 
-    
-    # dumpon /dev/<devicenode>
-    # sysctl kern.sync_on_panic=0
+This configuration may be useful on a remote system.
 
 
-* 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):
+## Tips
+
+* You can have the settings described above take effect without rebooting using the following commands:
+
+        # dumpon /dev/<devicenode>
+        # sysctl kern.sync_on_panic=0
 
-    
-    hw.physmem="64M"
+* 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):
 
+        hw.physmem="64M"
 
-* On systems derived from DEVELOPMENT (HEAD) after 20 August 2005, you can get a panic directly by pressing `<ctrl-alt-shift-esc>` if you set the `sysctl machdep.enable_panic_key to 1`.
+* 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).