Ubuntu Manpage: kdump-tools.conf - configuration file for the kdump-tools init script

name
synopsis
description
options
usage
examples
files
diagnostics
see also
author

Provided by: kdump-tools_1.6.3-2~16.04.3_amd64

NAME

       kdump-tools.conf - configuration file for the kdump-tools init script

SYNOPSIS

       /etc/default/kdump-tools

DESCRIPTION

       kdump-tools  manages  the  kdump feature of the Linux kernel.  The /etc/default/kdump-tools file contains
       local configuration settings of kdump.

       This file is sourced into a shell script, so it's format should be consistent with shell scripting.

OPTIONS

USE_KDUMP
Controls whether or not kdump-tools will take any action. If not set or 0, the kdump-tools init
script will not run.

KDUMP_SYSCTL
Controls when a panic occurs, using the sysctl(8) interface. Each time a kdump kernel is loaded,
“sysctl -w $KDUMP_SYSCTL” is also executed, thus allowing the system adiminstrator to maintain
customizable conditions for a kdump. The contents of this variable should be the “variable=value
...” portion of the “sysctl -w” command. If not set, “kernel.panic_on_oops=1” will be used.
This feature can be disabled by setting
KDUMP_SYSCTL=“ ”

See sysctl(8) for more info.

KDUMP_KERNEL
A full pathname to a kdump kernel (the kernel that is kexec'd at crash time in a reserved memory
area, exposing the old kernel's memory for dumping). If not set, kdump-config will use the boot
kernel as the kdump kernel if it is relocatable; otherwise you must set KDUMP_KERNEL in order for
kdump-tools to work.

KDUMP_INITRD
A full pathname to the kdump initrd (if used). If KDUMP_KERNEL is set and KDUMP_INITRD is not
set, a warning message will be printed, and an initrd will not be used.

KDUMP_COREDIR
Full path to a directory where the vmcore will be saved. Date stamped subdirectories are created
each time a vmcore file is processed. If not set, /var/crash will be used.

KDUMP_FAIL_CMD
This variable specifies a command to run if the vmcore save fails. If not set, no special action
is taken.

KDUMP_DUMP_DMESG
This variable controls if the dmesg buffer is dumped. If not set or set to 1, the dmesg buffer is
dumped. If set to 0, the dmesg buffer is not dumped.

KDUMP_NUM_DUMPS
This variable specifies how many dump files should be kept on the local machine. If not set or
set to 0, no special action is taken. If set to >1 and there are too many dump files on the
machine, older dumps are removed. The cleanup action is only taken after a successful dump. This
variable is ignored if remote dumping is enabled.

MAKEDUMP_ARGS
Extra arguments passed to makedumpfile(8). If not set, “-c -d 31” will be used. This tells
makedumpfile to use compression, and reduce the corefile to in-use kernel pages only. See
makedumpfile(8) for details.

KDUMP_KEXEC_ARGS
Additional arguments to the kexec command used to load the kdump kernel.

KDUMP_CMDLINE
Normally, the current kernel commandline is obtained from /proc/cmdline. Set this variable to
override /proc/cmdline.

KDUMP_CMDLINE_APPEND
Additional arguments to append to the command line for the kdump kernel. If not set,
“reset_devices nr_cpus=1 systemd.unit=kdump-tools-dump.service irqpoll nousb
ata_piix.prefer_ms_hyperv=0” will be used.

SSH username and hostname of the remote server that will receive the dump and dmesg files.
username@hostname format must be used.

SSH_KEY
Full path of the ssh private key to be used to login to the remote server. Use “kdump-config
propagate” to send the public key to the remote server. If not set, the default
/root/.ssh/kdump_id_rsa will be used

HOSTTAG
Select if hostname of IP address will be used as a prefix to the timestamped directory when
sending files to the remote server. If not set, “ip” will be used.

NFS Hostname and mount point of the NFS server configured to receive the crash dump. The syntax must
be HOSTNAME:MOUNTPOINT (e.g. remote:/var/crash )

USAGE

kdump-tools is as automated as can be at this point but there are some prerequisites to using it.
Additionally, some manual configuration is still required.

By default, kernel dumps are stored locally on the system. kdump-tools can be configured to store the
kernel dumps on a remote server accessible through the network.

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.

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.

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. If the command line parameter is
changed, a reboot is required in order for it to take effect.

3. 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.

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 is
also 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.

2. 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 predermined start location via CONFIG_PHYSICAL_START. 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

EXAMPLES

       Also panic and kdump on oom:
              KDUMP_SYSCTL="kernel.panic_on_oops=1 vm.panic_on_oom=1"

       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

       /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 various error messages.

AUTHOR

       Terry Loftin <terry.loftin@hp.com>