admin-guide/kdump/kdump.rst

2 Documentation for Kdump - The kexec-based Crash Dumping Solution
11 Kdump uses kexec to quickly boot to a dump-capture kernel whenever a
14 the reboot and is accessible to the dump-capture kernel.
24 the dump-capture kernel. This ensures that ongoing Direct Memory Access
25 (DMA) from the system kernel does not corrupt the dump-capture kernel.
26 The kexec -p command loads the dump-capture kernel into this reserved
31 low 1M is reserved to avoid any later kernel or device driver writing
45 encoded in the ELF format, and stored in a reserved area of memory
47 passed to the dump-capture kernel through the elfcorehdr= boot
51 With the dump-capture kernel, you can access the memory image through
52 /proc/vmcore. This exports the dump as an ELF-format file that you can
55 options, e.g with '-d 31' it will only write out kernel data. Further,
63 Install kexec-tools
64 -------------------
68 2) Download the kexec-tools user-space package from the following URL:
70 http://kernel.org/pub/linux/utils/kernel/kexec/kexec-tools.tar.gz
74 The latest kexec-tools git tree is available at:
76 - git://git.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
77 - http://www.kernel.org/pub/scm/utils/kernel/kexec/kexec-tools.git
80 http://www.kernel.org/git/?p=utils/kernel/kexec/kexec-tools.git
82 More information about kexec-tools can be found at
87 	tar xvpzf kexec-tools.tar.gz
89 4) Change to the kexec-tools directory, as follows::
91 	cd kexec-tools-VERSION
106 Build the system and dump-capture kernels
107 -----------------------------------------
110 1) Build a separate custom dump-capture kernel for capturing the
113 2) Or use the system kernel binary itself as dump-capture kernel and there is
114    no need to build a separate dump-capture kernel. This is possible
125 dump-capture kernels for enabling kdump support.
128 ----------------------------
139 2) Enable "sysfs file system support" in "Filesystem" -> "Pseudo
159 Dump-capture kernel config options (Arch Independent)
160 -----------------------------------------------------
171 2) Enable "/proc/vmcore support" under "Filesystems" -> "Pseudo filesystems"::
177 Dump-capture kernel config options (Arch Dependent, i386 and x86_64)
178 --------------------------------------------------------------------
186    command line when loading the dump-capture kernel because one
208    kexec boot loader will load it in memory region reserved for dump-capture
211    Otherwise it should be the start of memory region reserved for
213    start of memory region reserved for dump-capture kernel.
220 Dump-capture kernel config options (Arch Dependent, ppc64)
221 ----------------------------------------------------------
233 Dump-capture kernel config options (Arch Dependent, arm)
234 ----------------------------------------------------------
236 -   To use a relocatable kernel,
241 Dump-capture kernel config options (Arch Dependent, arm64)
242 ----------------------------------------------------------
244 - Please note that kvm of the dump-capture kernel will not be enabled
245   on non-VHE systems even if it is configured. This is because the CPU
252    Here 'size' specifies how much memory to reserve for the dump-capture kernel
253    and 'offset' specifies the beginning of this reserved memory. For example,
255    starting at physical address 0x01000000 (16MB) for the dump-capture kernel.
275    configurations, sometimes it's handy to have the reserved memory dependent
276    on the value of System RAM -- that's mostly for distributors that pre-setup
283        range=start-[end]
287        crashkernel=512M-2G:64M,2G-:128M
315 -----------------------
338 Load the Dump-capture Kernel
341 After booting to the system kernel, dump-capture kernel needs to be
345 can choose to load the uncompressed vmlinux or compressed bzImage/vmlinuz
346 of dump-capture kernel. Following is the summary.
350 	- Use bzImage/vmlinuz if kernel is relocatable.
351 	- Use vmlinux if kernel is not relocatable.
355 	- Use vmlinux
359 	- Use image or bzImage
363 	- Use zImage
367 	- Use vmlinux or Image
370 to load dump-capture kernel::
372    kexec -p <dump-capture-kernel-vmlinux-image> \
373    --initrd=<initrd-for-dump-capture-kernel> --args-linux \
374    --append="root=<root-dev> <arch-specific-options>"
377 to load dump-capture kernel::
379    kexec -p <dump-capture-kernel-bzImage> \
380    --initrd=<initrd-for-dump-capture-kernel> \
381    --append="root=<root-dev> <arch-specific-options>"
384 to load dump-capture kernel::
386    kexec --type zImage -p <dump-capture-kernel-bzImage> \
387    --initrd=<initrd-for-dump-capture-kernel> \
388    --dtb=<dtb-for-dump-capture-kernel> \
389    --append="root=<root-dev> <arch-specific-options>"
392 to load dump-capture kernel::
394    kexec -p <dump-capture-kernel-Image> \
395    --initrd=<initrd-for-dump-capture-kernel> \
396    --append="root=<root-dev> <arch-specific-options>"
399 loading dump-capture kernel.
421 Notes on loading the dump-capture kernel:
426   So, on non-PAE systems, ELF32 is always used.
428   The --elf32-core-headers option can be used to force the generation of ELF32
430   with ELF64 headers on 32-bit systems.
433   due to shared interrupts in the dump-capture kernel.
435 * You must specify <root-dev> in the format corresponding to the root
438 * Boot parameter "1" boots the dump-capture kernel into single-user
442   dump. Hence generally it is useful either to build a UP dump-capture
443   kernel or specify maxcpus=1 option while loading dump-capture kernel.
447 * You should enable multi-cpu support in dump-capture kernel if you intend
448   to use multi-thread programs with it, such as parallel dump feature of
449   makedumpfile. Otherwise, the multi-thread program may have a great
450   performance degradation. To enable multi-cpu support, you should bring up an
451   SMP dump-capture kernel and specify maxcpus/nr_cpus options while loading it.
470 After successfully loading the dump-capture kernel as previously
471 described, the system will reboot into the dump-capture kernel if a
473 die(), die_nmi() and in the sysrq handler (ALT-SysRq-c).
478 will boot into the dump-capture kernel ( die_nmi() ).
482 the system will boot into the dump-capture kernel.
484 On powerpc systems when a soft-reset is generated, die() is called by all cpus
485 and the system will boot into the dump-capture kernel.
487 For testing purposes, you can trigger a crash by using "ALT-SysRq-c",
488 "echo c > /proc/sysrq-trigger" or write a module to force the panic.
493 After the dump-capture kernel is booted, write out the dump file with
496    cp /proc/vmcore <dump-file>
500    scp /proc/vmcore remote_username@remote_ip:<dump-file>
505    makedumpfile -l --message-level 1 -d 31 /proc/vmcore <dump-file>
513 /proc/vmcore. Use the debug vmlinux built with -g and run the following
516    gdb vmlinux <dump-file>
523 ELF32-format headers using the --elf32-core-headers kernel option on the
529    https://github.com/crash-utility/crash
532    https://crash-utility.github.io/
548 This will cause a kdump to occur at the add_taint()->panic() call.
553 - kexec@lists.infradead.org