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
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
121 at the same time one might want to build a custom dump capture kernel
125 dump-capture kernels for enabling kdump support.
127 System kernel config options
128 ----------------------------
139 2) Enable "sysfs file system support" in "Filesystem" -> "Pseudo
146    is not enabled in "General Setup." In this case, check the .config file
149 	grep 'CONFIG_SYSFS' .config
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 --------------------------------------------------------------------
190    command line when loading the dump-capture kernel because one
212    kexec boot loader will load it in memory region reserved for dump-capture
217    start of memory region reserved for dump-capture kernel.
224 Dump-capture kernel config options (Arch Dependent, ppc64)
225 ----------------------------------------------------------
237 Dump-capture kernel config options (Arch Dependent, arm)
238 ----------------------------------------------------------
240 -   To use a relocatable kernel,
245 Dump-capture kernel config options (Arch Dependent, arm64)
246 ----------------------------------------------------------
248 - Please note that kvm of the dump-capture kernel will not be enabled
249   on non-VHE systems even if it is configured. This is because the CPU
256    Here 'size' specifies how much memory to reserve for the dump-capture kernel
259    starting at physical address 0x01000000 (16MB) for the dump-capture kernel.
280    on the value of System RAM -- that's mostly for distributors that pre-setup
287        range=start-[end]
291        crashkernel=512M-2G:64M,2G-:128M
319 -----------------------
342 Load the Dump-capture Kernel
345 After booting to the system kernel, dump-capture kernel needs to be
350 of dump-capture kernel. Following is the summary.
354 	- Use bzImage/vmlinuz if kernel is relocatable.
355 	- Use vmlinux if kernel is not relocatable.
359 	- Use vmlinux
363 	- Use image or bzImage
367 	- Use zImage
371 	- Use vmlinux or Image
374 to load dump-capture kernel::
376    kexec -p <dump-capture-kernel-vmlinux-image> \
377    --initrd=<initrd-for-dump-capture-kernel> --args-linux \
378    --append="root=<root-dev> <arch-specific-options>"
381 to load dump-capture kernel::
383    kexec -p <dump-capture-kernel-bzImage> \
384    --initrd=<initrd-for-dump-capture-kernel> \
385    --append="root=<root-dev> <arch-specific-options>"
388 to load dump-capture kernel::
390    kexec --type zImage -p <dump-capture-kernel-bzImage> \
391    --initrd=<initrd-for-dump-capture-kernel> \
392    --dtb=<dtb-for-dump-capture-kernel> \
393    --append="root=<root-dev> <arch-specific-options>"
396 to load dump-capture kernel::
398    kexec -p <dump-capture-kernel-Image> \
399    --initrd=<initrd-for-dump-capture-kernel> \
400    --append="root=<root-dev> <arch-specific-options>"
403 loading dump-capture kernel.
425 Notes on loading the dump-capture kernel:
430   So, on non-PAE systems, ELF32 is always used.
432   The --elf32-core-headers option can be used to force the generation of ELF32
434   with ELF64 headers on 32-bit systems.
437   due to shared interrupts in the dump-capture kernel.
439 * You must specify <root-dev> in the format corresponding to the root
440   device name in the output of mount command.
442 * Boot parameter "1" boots the dump-capture kernel into single-user
446   dump. Hence generally it is useful either to build a UP dump-capture
447   kernel or specify maxcpus=1 option while loading dump-capture kernel.
451 * You should enable multi-cpu support in dump-capture kernel if you intend
452   to use multi-thread programs with it, such as parallel dump feature of
453   makedumpfile. Otherwise, the multi-thread program may have a great
454   performance degradation. To enable multi-cpu support, you should bring up an
455   SMP dump-capture kernel and specify maxcpus/nr_cpus options while loading it.
474 After successfully loading the dump-capture kernel as previously
475 described, the system will reboot into the dump-capture kernel if a
477 die(), die_nmi() and in the sysrq handler (ALT-SysRq-c).
482 will boot into the dump-capture kernel ( die_nmi() ).
486 the system will boot into the dump-capture kernel.
488 On powerpc systems when a soft-reset is generated, die() is called by all cpus
489 and the system will boot into the dump-capture kernel.
491 For testing purposes, you can trigger a crash by using "ALT-SysRq-c",
492 "echo c > /proc/sysrq-trigger" or write a module to force the panic.
497 After the dump-capture kernel is booted, write out the dump file with
500    cp /proc/vmcore <dump-file>
504    scp /proc/vmcore remote_username@remote_ip:<dump-file>
509    makedumpfile -l --message-level 1 -d 31 /proc/vmcore <dump-file>
517 /proc/vmcore. Use the debug vmlinux built with -g and run the following
520    gdb vmlinux <dump-file>
527 ELF32-format headers using the --elf32-core-headers kernel option on the
533    https://github.com/crash-utility/crash
536    https://crash-utility.github.io/
552 This will cause a kdump to occur at the add_taint()->panic() call.
557 - kexec@lists.infradead.org