Kdump is a standard Linux mechanism to dump machine memory content on kernel crash. Kdump is based on Kexec. Kdump utilizes two kernels: system kernel and dump capture kernel. System kernel is a normal kernel that is booted with special kdump-specific flags. We need to tell the system kernel to reserve some amount of physical memory where dump-capture kernel will be loaded. We need to load the dump capture kernel in advance because at the moment crash happens there is no way to read any data from disk because kernel is broken.
Once kernel crash happens the kernel crash handler uses Kexec mechanism to boot dump capture kernel. Please note that memory with system kernel is untouched and accessible from dump capture kernel as seen at the moment of crash. Once dump capture kernel is booted, the user can use the file
/proc/vmcore to get access to memory of crashed system kernel. The dump can be saved to disk or copied over network to some other machine for further investigation.
In real production environments system and dump capture kernel will be different - system kernel needs a lot of features and compiled with a many kernel flags/drivers. While dump capture kernel goal is to be minimalistic and take as small amount of memory as possible, e.g. dump capture kernel can be compiled without network support if we store memory dump to disk only. But in this article we will simplify things and use the same kernel both as system and dump capture one. It means we will load the same kernel code twice - one as normal system kernel, another one to reserved memory area.
System/dump capture kernel requires some configuration flags that may not be set by default. Please consult Kernel Compilation article for more information about compiling a custom kernel in Arch. Here we will emphasize on Kdump specific configuration. Current default Arch kernel builds seem to have these flags already set. You can verify if your running kernel has these set by looking in
To create a kernel you need to edit kernel
config.x86_64) file and enable following configuration options:
CONFIG_DEBUG_INFO=y CONFIG_CRASH_DUMP=y CONFIG_PROC_VMCORE=y
Also change package base name to something like linux-kdump to distinguish the kernel from the default Arch one. Compile kernel package and install it. Save ./src/linux-X.Y/vmlinux uncompressed system kernel binary - it contains debug symbols and you will need them later when analyzing the crash.
In case if you have a separate kernel for the system and dump capture then it is recommended to consult Kdump documentation. It has several recommendations how to make dump capture kernel smaller.
Prepare kdump initramfs
The kdump initramfs should contain tools for extraction of
/proc/vmcore information (see #Dump crashed kernel below). If you wish to save the artifacts to your root filesystem, it is easiest to modify your default initramfs. For example, if initramfs is built with mkinitcpio ( is required)
--- mkinitcpio.conf +++ mkinitcpio-kdump.conf @@ -11,12 +11,12 @@ # wish into the CPIO image. This is run last, so it may be used to # override the actual binaries included by a given hook # BINARIES are dependency parsed, so you may safely ignore libraries -BINARIES=() +BINARIES=(/usr/bin/makedumpfile) # FILES # This setting is similar to BINARIES above, however, files are added # as-is and are not parsed in any way. This is useful for config files. -FILES=() +FILES=(/etc/systemd/system/kdump-save.service) # HOOKS # This is the most important setting in this file. The HOOKS control the
and remember to update mkinitcpio preset file so that fresh initrd is rebuilt upon each kernel update.
Setup kdump kernel
First, you need to reserve memory for dump capture kernel. Edit your bootloader configuration and add
crashkernel=[size] kernel parameter.
64M of memory should be enough to handle crash dumps on machines with up to 12G of RAM. Some systems require more reserved memory. In case if dump capture kernel unable not load, try to increase the memory to 256M or even to 512M, but note that this memory is unavailable to system kernel.
Reboot into your system kernel. To make sure that the kernel is booted with correct options please check the
Next you need to tell Kexec that you want to use your dump capture kernel. Specify your kernel, initramfs file, root device and other parameters if needed:
# kexec -p [/boot/vmlinuz-linux-kdump] --initrd=[/boot/initramfs-linux-kdump.img] --append="root=[root-device] single irqpoll maxcpus=1 reset_devices"
It loads the kernel into the reserved area. Without the
-p flag kexec would boot the kernel right away, but in presence of the flag kernel will be loaded into reserved memory but boot postponed until a crash.
cat /sys/devices/system/cpu/onlineshows the active CPU cores. The
maxcpus=1kernel parameter should limit it to one. If it has no effect or your SMP-enabled kernel does not boot, try using
Instead of running kexec manually you might want to setup Systemd service that will run kexec on boot:
[Unit] Description=Load dump capture kernel After=local-fs.target [Service] ExecStart=/usr/bin/kexec -p [/boot/vmlinuz-linux-kdump] --initrd=[/boot/initramfs-linux-kdump.img] --append="root=[root-device] single irqpoll maxcpus=1 reset_devices" Type=oneshot [Install] WantedBy=multi-user.target
To check whether the crash kernel is already loaded please run following command:
$ cat /sys/kernel/kexec_crash_loaded
If you want to test crash then you can use sysrq for this.
# echo c > /proc/sysrq-trigger
Once crash happens kexec will load your dump capture kernel.
Dump crashed kernel
Once booted into dump capture kernel you can read
/proc/vmcore file. It is recommended to dump core to a file and analyze it later.
# cp /proc/vmcore /root/crash.dump
or optionally you can copy the crash to another machine. Once dump is saved you should reboot the machine into normal system kernel.
The crash dump can be quite big,can be used to create smaller dumps by ignoring some memory regions and using compression:
# makedumpfile -c -d 31 /proc/vmcore /root/crash.dump
The following systemd service can be used to automatically save crash dumps and reboot into the main kernel:
[Unit] Description=Create dump after kernel crash DefaultDependencies=no Wants=local-fs.target After=local-fs.target [Service] Type=idle ExecStart=/bin/sh -c 'mkdir -p /var/crash/ && /usr/bin/makedumpfile -c -d 31 /proc/vmcore "/var/crash/crashdump-$$(date +%%F-%%T)"' ExecStopPost=/usr/bin/systemctl reboot UMask=0077 StandardInput=tty-force StandardOutput=inherit StandardError=inherit
This can be invoked from the dump capture kernel command line:
[Unit] Description=Load dump capture kernel After=local-fs.target [Service] Type=oneshot RemainAfterExit=true ExecStart=/usr/bin/kexec -p [/boot/vmlinuz-linux-kdump] --initrd=[/boot/initramfs-linux-kdump.img] --append="root=[root-device] systemd.unit=kdump-save.service irqpoll maxcpus=1 reset_devices" # convenience ExecStartPost=/bin/sh -c 'mkdir -p /var/crash/ && /usr/bin/makedumpfile --dump-dmesg /proc/vmcore "/var/crash/crashdump-$$(date +%%F-%%T)".dmesg' ExecStop=/usr/bin/kexec -p -u [Install] WantedBy=multi-user.target
Note that, in the above, "single" has been removed from the kernel command line.
Analyzing core dump
You can use either gdb tool or special gdb extension called. Run crash as
$ crash vmlinux path/crash.dump
Where vmlinux previously saved kernel binary with debug symbols.
Follow man crash or  for more information about debugging practices.
- https://docs.kernel.org/admin-guide/kdump/kdump.html - Official kdump documentation
- https://www.dedoimedo.com/computers/www.dedoimedo.com-crash-book.pdf - The crash book
- https://crash-utility.github.io - The crash website