KDUMP.CONF(5)

📦

version 1.0.61 · 3 versions

1.0.61 · centos-stream 10, fedora 43, fedora 44 (latest)
2.0.29 · centos-stream 9
1.0.56 · fedora 43

, in centos-stream 10, fedora 43, fedora 44

💖 NAME 💖

okay so bestie, this is kdump.conf(5) from the File Formats Manual — and the name of the game is literally kdump.conf: the configuration file for kdump kernel. 💅

✨ DESCRIPTION ✨

kdump.conf is the configuration file for the kdump kernel crash collection service. It's giving "crash dump settings, but make it initrd." 🦋

It provides post-kexec instructions to the kdump kernel. It is stored in the initrd file managed by the kdump service. If you change this file and do not want to reboot in order for the changes to take effect, restart the kdump service to rebuild the initrd. periodt.

For most configurations, you can simply review the examples provided in the stock /etc/kdump.conf. No cap, the stock file is lowkey the tutorial.

NOTE: For filesystem dumps the dump target must be mounted before building kdump initramfs. Do not skip this, bestie, it will not slay.

kdump.conf only affects the behavior of the initramfs. Please read the kdump operational flow section of kexec-kdump-howto.txt in the docs to better understand how this configuration file affects the behavior of kdump. iykyk. 💜

👑 OPTIONS 👑

Now the main character energy: every option, every detail, zero skips. Let's go. 🎀

auto_reset_crashkernel <yes|no> — determines whether to reset kernel crashkernel parameter to the default value or not when kdump-utils is updated or a new kernel is installed. The default crashkernel values are different for different architectures and also take the following factors into consideration:
- AMD Secure Memory Encryption (SME) and Secure Encrypted Virtualization (SEV)
- Mellanox 5th generation network driver
- aarch64 64k kernel
- Firmware-assisted dump (FADump)

Since the kernel crasherkernel parameter will be only reset when kdump-utils is updated or a new kernel is installed, you need to call kdumpctl reset-crashkernel [--kernel=path_to_kernel] if you want to use the default value set after having enabled features like SME/SEV for a specific kernel. And you should also reboot the system for the new crashkernel value to take effect. Also see kdumpctl(8).

raw <partition> — Will dd /proc/vmcore into <partition>. Use persistent device names for partition devices, such as /dev/vg/<devname>.
nfs <nfs mount> — Will mount nfs to <mnt>, and copy /proc/vmcore to <mnt>/<path>/%HOST-%DATE/, supports DNS. Note that a fqdn should be used as the server name in the mount point.
ssh <user@server> — Will save /proc/vmcore through ssh pipe to <user@server>:<path>/%HOST-%DATE/, supports DNS. NOTE: make sure user has necessary write permissions on server and that a fqdn is used as the server name.
sshkey <path> — Specify the path of the ssh key to use when dumping via ssh. The default value is /root/.ssh/kdump_id_rsa.
<fs type> <partition> — Will mount -t <fs type> <partition> <mnt>, and copy /proc/vmcore to <mnt>/<path>/%HOST_IP-%DATE/. NOTE: <partition> can be a device node, label or uuid. It's recommended to use persistent device names such as /dev/vg/<devname>. Otherwise it's suggested to use label or uuid.
path <path> — "path" represents the file system path in which vmcore will be saved. If a dump target is specified in kdump.conf, then "path" is relative to the specified dump target.

Interpretation of "path" changes a bit if the user didn't specify any dump target explicitly in kdump.conf. In this case, "path" represents the absolute path from root. The dump target and adjusted path are arrived at automatically depending on what's mounted in the current system.

Ignored for raw device dumps. If unset, will use the default "/var/crash".

core_collector <command> <options> — This allows you to specify the command to copy the vmcore. The default is makedumpfile, which on some architectures can drastically reduce core file size. See /sbin/makedumpfile --help for a list of options. Note that the -i and -g options are not needed here, as the initrd will automatically be populated with a config file appropriate for the running kernel.

Note 1: About default core collector: The default core_collector for raw/ssh dump is: "makedumpfile -F -l --message-level 7 -d 31". The default core_collector for other targets is: "makedumpfile -l --message-level 7 -d 31". Even if core_collector option is commented out in kdump.conf, makedumpfile is the default core collector and kdump uses it internally. If one does not want makedumpfile as default core_collector, then they need to specify one using core_collector option to change the behavior.

Note 2: If "makedumpfile -F" is used then you will get a flattened format vmcore.flat, you will need to use "makedumpfile -R" to rearrange the dump data from standard input to a normal dumpfile (readable with analysis tools). ie. "makedumpfile -R vmcore < vmcore.flat"

Note 3: If specified core_collector simply copy the vmcore file to the dump target (eg: cp, scp), the vmcore could be significantly large. Please make sure the dump target has enough space, at least larger than the system's RAM.

kdump_emergency <binary | script> — This directive allows you to run a specified executable in emergency mode after an error in the kdump environment occurs.

All files under /etc/kdump/emergency.d are collectively sorted and executed in lexical order, before binary or script specified kdump_emergency parameter is executed.

Note that scripts written for use with this directive must use the /bin/bash interpreter. And since these scripts run in kdump environment, the reference to the storage or network device in the scripts should adhere to the section

kdump_post <binary | script> — This directive allows you to run a specified executable just after the vmcore dump process terminates. The exit status of the current dump process is fed to the kdump_post executable as its first argument ($1). Executable can modify it to indicate the new exit status of succeeding dump process,

All files under /etc/kdump/post.d are collectively sorted and executed in lexical order, before binary or script specified kdump_post parameter is executed.

kdump_pre <binary | script> — Works just like the "kdump_post" directive, but instead of running after the dump process, runs immediately before. Exit status of this binary is interpreted as follows:

0 - continue with dump process as usual

non 0 - run the final action (reboot/poweroff/halt)

All files under /etc/kdump/pre.d are collectively sorted and executed in lexical order, after binary or script specified kdump_pre parameter is executed. Even if the binary or script in /etc/kdump/pre.d directory returns non 0 exit status, the processing is continued.

extra_bins <binaries | shell scripts> — This directive allows you to specify additional binaries or shell scripts you'd like to include in your kdump initrd. Generally only useful in conjunction with a kdump_post binary or script that relies on other binaries or scripts.
extra_modules <module(s)> — This directive allows you to specify extra kernel modules that you want to be loaded in the kdump initrd, typically used to set up access to non-boot-path dump targets that might otherwise not be accessible in the kdump environment. Multiple modules can be listed, separated by spaces, and any dependent modules will automatically be included.
failure_action <reboot | halt | poweroff | shell | dump_to_rootfs> — Action to perform in case dumping to the intended target fails. The default is "reboot".
- reboot: Reboot the system (this is what most people will want, as it returns the system to a normal state).
- halt: Halt the system and lose the vmcore.
- poweroff: The system will be powered down.
- shell: Drop to a shell session inside the initramfs, from which you can manually perform additional recovery actions. Exiting this shell reboots the system by default or performs "final_action". Note: kdump uses bash as the default shell.
- dump_to_rootfs: If non-root dump target is specified, the failure action can be set as dump_to_rootfs. That means when dumping to target fails, dump vmcore to rootfs from initramfs context and reboot by default or perform "final_action".
default <reboot | halt | poweroff | shell | dump_to_rootfs> — Same as the "failure_action" directive above, but this directive is obsolete and will be removed in the future. Do not build your whole personality on it. 😭
final_action <reboot | halt | poweroff> — Action to perform in case dumping to the intended target succeeds. Also performed when "shell" or "dump_to_rootfs" failure action finishes. Each action is same as the "failure_action" directive above. The default is "reboot".
force_rebuild <0 | 1> — By default, kdump initrd will only be rebuilt when necessary. Specify 1 to force rebuilding kdump initrd every time when kdump service starts.
force_no_rebuild <0 | 1> — By default, kdump initrd will be rebuilt when necessary. Specify 1 to bypass rebuilding of kdump initrd.

force_no_rebuild and force_rebuild options are mutually exclusive and they should not be set to 1 simultaneously. Pick one, bestie, you cannot sit with both. 💀

dracut_args <arg(s)> — Kdump uses dracut to generate initramfs for second kernel. This option allows a user to pass arguments to dracut directly.
fence_kdump_args <arg(s)> — Command line arguments for fence_kdump_send (it can contain all valid arguments except hosts to send notification to).
fence_kdump_nodes <node(s)> — List of cluster node(s) except localhost, separated by spaces, to send fence_kdump notification to (this option is mandatory to enable fence_kdump).

💀 DEPRECATED OPTIONS 💀

okay bestie, these are the ones your ancestors used and honestly? let them rest. fr fr. they still technically exist in the config space but they're giving vintage, and dracut has taken over their jobs. iykyk.

net <nfs mount>|<user@server> — this one got replaced by the nfs and ssh options, so just... use those directly, okay? no middleman needed 💅
options <module> <option list> — instead of this, you go into /etc/sysconfig/kdump and use KDUMP_COMMANDLINE_APPEND to add module options as kernel command line parameters. like, for example, specify 'loop.max_loop=1' to limit maximum loop devices to 1. that's the vibe now ✨
link_delay <seconds> — back in the day this was how you waited for a network device to wake up before using it. now? the dracut network module handles all of that automatically. it's giving self-sufficient 🦋
disk_timeout <seconds> — same energy as link_delay tbh — dracut makes sure disks are ready before kdump touches them. your disks are fine, they don't need a babysitter 🌸
debug_mem_level <0-3> — this turned on verbose debug output from the kdump scripts about free/used memory at various points of execution. that feature lives in dracut now. so you go to /etc/sysconfig/kdump, use KDUMP_COMMANDLINE_APPEND, and append the dracut cmdline param rd.memdebug=[0-3] to turn that debug output on. periodt.

higher level = more debugging output, no cap:

0 — no output
1 — partial /proc/meminfo
2 — /proc/meminfo
3 — /proc/meminfo + /proc/slabinfo

blacklist <list of kernel modules> — okay so this one was recently being used to stop modules from loading in initramfs, but the general terminology for blacklist is that the module is present in initramfs, it's just not actually loaded into the kernel. so keeping the blacklist option around created more confusing behavior, and it has been deprecated. it's done. retired. we said what we said 💀

instead, use the rd.driver.blacklist option on the second kernel to blacklist a certain module. you can edit /etc/sysconfig/kdump.conf and edit KDUMP_COMMANDLINE_APPEND to pass kernel command line options. refer to the dracut.cmdline man page for more deets on the module blacklist option 🫶

🌈 EXAMPLES 🌈

here are some examples for the core_collector option — this is the part where it gets juicy, bestie 👑

core collector command format depends on dump target type. typically for filesystem (local/remote), core_collector should accept two arguments. first one is source file and second one is target file. for ex.

ex1. core_collector "cp --sparse=always"

above will effectively be translated to:

cp --sparse=always /proc/vmcore <dest-path>/vmcore

ex2. core_collector "makedumpfile -l --message-level 7 -d 31"

above will effectively be translated to:

makedumpfile -l --message-level 7 -d 31 /proc/vmcore <dest-path>/vmcore

for dump targets like raw and ssh, in general, core collector should expect one argument (source file) and should output the processed core on standard output (there is one exception of "scp", discussed later). this standard output will be saved to destination using appropriate commands. okay? okay ✨

raw dumps examples:

ex3. core_collector "cat"