kdump-tools.conf(5)

📦
version 1.10.7ubuntu5 · 4 versions
, in ubuntu stonking

💖 kdump-tools.conf — the manual page, but make it make sense 💖

okay bestie, so this is the kdump-tools.conf(5) page from the Linux System Administrator's Manual. It's a config file situation. It's giving "tiny file, big consequences." Let's go. 🦋

✨ NAME ✨

kdump-tools.conf — literally just the configuration file for the kdump-tools init script. That's it. That's the whole job. 💅

🌸 SYNOPSIS 🌸

/etc/default/kdump-tools

One path. One file. Iconic.

🎀 DESCRIPTION 🎀

So kdump-tools is the thing that manages the kdump feature of the Linux kernel — you know, the part where if your kernel has a whole crisis, it kexecs into a lil baby kernel and grabs the dying kernel's memory so you can actually debug what happened instead of just sobbing. 😭

The /etc/default/kdump-tools file is where your local configuration settings for kdump live. Your little home base. 🏠

⚠️ important bestie: this file gets sourced into a shell script. It's not a fancy parsey config format. So its format should be consistent with shell scripting. Write it like shell or it will simply not vibe with you. no cap.

👑 OPTIONS 👑

okay this is the long part, get comfy, grab a snack 🍓

  • USE_KDUMP — the big on/off switch. Controls whether kdump-tools does literally anything at all. If it's not set, or it's 0, the kdump-tools init script will not run. periodt.
  • KDUMP_KERNEL — a full pathname to a kdump kernel. This is the kernel that gets kexec'd at crash time into a reserved memory area, exposing the old kernel's memory for dumping. If you don't set it, kdump-config will use the boot kernel as the kdump kernel if it's relocatable — otherwise you must set KDUMP_KERNEL or kdump-tools straight up will not work. 🙈
  • KDUMP_INITRD — full pathname to the kdump initrd (if you're using one). But listen: if KDUMP_KERNEL is set and KDUMP_INITRD is not set, a warning message gets printed and an initrd will not be used. heads up. 💀
  • KDUMP_INITRD_GENERATOR — picks the tool that builds the kdump capture initrd. If it's unset or set to auto, the capture initrd gets built with dracut when dracut is installed, and with mkinitramfs from initramfs-tools otherwise. Or you can force it — set it to dracut or initramfs-tools to lock in a specific generator regardless of what's installed. choose your fighter. 🔥
  • KDUMP_COREDIR — full path to the directory where the vmcore gets saved. Date-stamped subdirectories get created each time a vmcore file is processed. If you don't set it, /var/crash is used. classic.
  • KDUMP_FAIL_CMD — the command to run if the vmcore save fails. If you don't set it, no special action is taken — it just... doesn't save. 🫠
  • KDUMP_DUMP_DMESG — controls whether the dmesg buffer gets dumped. If it's not set, or set to 1, the dmesg buffer is dumped. If set to 0, it is not dumped.
  • KDUMP_NUM_DUMPS — how many dump files you want to keep on the local machine. If it's not set or set to 0, no special action is taken. If it's set to >1 and there are too many dump files hangin around, older dumps get removed. The cleanup only happens after a successful dump — not before, we're not reckless. Also this variable is ignored if remote dumping is enabled. read that again bestie. 👀
  • MAKEDUMP_ARGS — extra arguments passed to makedumpfile(8). If you don't set it, "-c -d 31" is used. That tells makedumpfile to use compression and reduce the corefile to in-use kernel pages only. Go read makedumpfile(8) for the details, iykyk.
  • KDUMP_KEXEC_ARGS — additional arguments for the kexec command that's used to load the kdump kernel.
  • KDUMP_CMDLINE — normally the current kernel commandline is grabbed from /proc/cmdline. Set this variable to override /proc/cmdline. main character energy: you're taking over. ✨
  • KDUMP_CMDLINE_APPEND — additional arguments appended to the command line for the kdump kernel. If not set, "reset_devices systemd.unit=kdump-tools-dump.service nr_cpus=1 irqpoll usbcore.nousb" is used. long default, but it's doing the most for a reason.
  • SSH — username and hostname of the remote server that'll receive the dump and dmesg files. You must use username@hostname format. no negotiating.
  • SSH_KEY — full path of the ssh private key used to log into the remote server. Use kdump-config propagate to send the public key over to the remote server. If you don't set it, the default /root/.ssh/kdump_id_rsa is used.
  • HOSTTAG — picks whether the hostname or the IP address gets used as a prefix to the timestamped directory when sending files to the remote server. If not set, "ip" is used.
  • NFS — hostname and mount point of the NFS server configured to receive the crash dump. Syntax must be HOSTNAME:MOUNTPOINT (e.g. remote:/var/crash ). don't forget the colon. 💅

🌈 USAGE 🌈

okay so at this point kdump-tools is about as automated as it can be, but there are still prerequisites to using it, and some manual configuration is still required. sorry bestie, no fully-hands-off situation yet. 🙏

By default, kernel dumps get stored locally on the system. But kdump-tools can also be configured to store kernel dumps on a remote server accessible through the network. options, we love options.

🧚 Manual Configuration 🧚

  1. USE_KDUMP is set to 0 by default. To enable kdump-tools, edit the /etc/default/kdump-tools configuration file and set USE_KDUMP=1. that's the unlock. 🔑
  2. Kernel command line parameters — the kernel must be booted with a crashkernel= command line parameter. Some example crashkernel parameters:
ia64:       crashkernel=384M
x86:        crashkernel=128M
x86_64:     crashkernel=256M

Some users may also want to add nmi_watchdog=1 on certain systems. The nmi watchdog will cause the kernel to panic (and kdump) if a system hang is detected. chaotic but useful. 💀

The kernel command line parameter is generally set in one of these files: /etc/default/grub, /boot/grub/menu.lst, /etc/elilo.conf, or /etc/lilo.conf. And if you change the command line parameter, a reboot is required for it to take effect. sorry. 😔

  1. Architectural considerations

A) x86 && PAE && memory > 4 Gigabytes — use KDUMP_KEXEC_ARGS="--elf64-core-headers"

B) x86 and x86_64 — some systems can take advantage of the nmi watchdog. Add nmi_watchdog=1 to the boot commandline to turn on the watchdog. The nmi interrupt will call panic if activated.

C) ia64 — some systems may need KDUMP_KEXEC_ARGS="--noio". Use this if the system hangs after a panic, but before the kdump kernel begins to boot.

🦋 Networked kernel dump Configuration 🦋

  1. Either use SSH or NFS to choose which protocol to use to remotely access the target server. pick a lane. 🌸
  2. For SSH, username@hostname needs to be provided along with an appropriate SSH_KEY definition — or use kdump-config propagate to propagate a new default ssh key.
  3. For NFS, the remote server name must be provided along with the directory where files are to be copied.

💜 Prerequisites 💜

  1. Boot Kernel Configuration — the boot kernel must be configured with CONFIG_KEXEC=y and, if it's also going to be used as the kdump kernel, CONFIG_CRASHDUMP=y.

For ia64, only makedumpfile level 1 will work if the memory model selected is CONFIG_DISCONTIG. CONFIG_SPARSEMEM is recommended instead. do that instead, fr fr.

  1. Kdump Kernel Configuration — the kdump kernel must be relocated or relocatable. ia64 is relocatable by default, but x86, x86_64, and powerpc must be built with CONFIG_RELOCATABLE=y. Other architectures may require a predetermined start location via CONFIG_PHYSICAL_START. (typo in the original says "predermined" but you get it, we're being cute not pedantic — actually no, we repeat it as written, CONFIG_PHYSICAL_START blah blah — anyway, moving on. 💅)

If the boot kernel is relocatable, kdump-tools will automatically use that kernel. Otherwise, a relocatable or relocated kernel will need to be provided. The kdump kernel can be specified in the /etc/default/kdump-tools file. Set the KDUMP_KERNEL variable and, if necessary, the KDUMP_INITRD variable, to point to the provided kernel and its initrd.

The kdump kernel must be configured with: CONFIG_CRASH_DUMP=y

🩷 SYSCTLS 🩷

Right now, kdump-tools automatically sets the kernel sysctl for panic on oops, so it can collect a dump in that case. If you want more panic triggers — like panic on OOM, or when a NMI is detected — it's recommended that you edit the sysctl configuration files (/etc/sysctl.conf or files in /etc/sysctl.d) to do that, and/or apply the sysctl settings with the sysctl tool. your kernel, your rules. ✨

🎀 Sysctl handling during a kdump 🎀

kdump-tools lets you configure sysctl overrides on the kdump environment — this is especially useful to stop sysctls from the regular boot from messing with the resource-impaired kdump environment. like leave her alone, she's going through it. 😭

The mechanism is restricted to kdump boot and will not affect regular boots. To add overrides, edit the file /etc/kdump/sysctl.conf.

By default, hugepages overrides are set, and it's highly recommended to keep them in the file — otherwise you risk kdump out-of-memory conditions. so. keep them. please. 🥺

⭐ EXAMPLES ⭐

Use this option on x86 systems with PAE and more than 4 gig of memory:

KDUMP_KEXEC_ARGS="--elf64-core-headers"

This option starts a shell if kdump-tools cannot save the vmcore file:

KDUMP_FAIL_CMD="/bin/bash; reboot -f"

🌟 FILES 🌟

  • /etc/init.d/kdump-tools — an init script to automatically load a kdump kernel, or save a vmcore and reboot.
  • /etc/default/kdump-tools — the kdump-tools configuration file
  • /etc/kdump/sysctl.conf — kdump-tools sysctl override file
  • /var/crash/kernel_link — a link to the current debug kernel
  • /var/crash/kexec_cmd — the last kexec_cmd executed by kdump-config

🔍 DIAGNOSTICS 🔍

See kdump-config(8) for explanations of the various error messages. that's where the answers live, bestie.

💖 SEE ALSO 💖

🌸 AUTHOR 🌸

Terry Loftin <terry.loftin@hp.com>

okay that's the whole page!! ✨ this was kdump-tools v1.6.7-2, dated Jul 2020, and it's the kdump-tools.conf(5) page from the Linux System Administrator's Manual. go forth and dump your kernels responsibly. love u, bye!! 🫶💜🎀

📦 where this page comes from