debian man page for kdump-tools

kdump-tools.conf(5)					Linux System Administrator's Manual				       kdump-tools.conf(5)

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  pro-
	      cessed.  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.

       DEBUG_KERNEL
	      A  debug	version  of the running kernel.  If not set, kdump-config will use /usr/lib/debug/vmlinux-$(uname-r) if it exists.  Other-
	      wise, kdump will still work, but the dump will take longer and will be much larger.

       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, "irqpoll maxcpus=1 nousb" will be used.

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.

   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.

   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 ker-
	      nel, 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_PHYSI-
	      CAL_START.   If  the  boot kernel is relocatable, kdump-tools will automatically use that kernel.  Otherwise, a relocatable or relo-
	      cated kernel will need to be provided.  The kdump kernel can be specified in the /etc/default/kdump-tools file.  Set the	KDUMP_KER-
	      NEL 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

       3.     Debug  Kernel  -	An  uncompressed  debug kernel should be provided in order for makedumpfile to process the vmcore file.  Without a
	      debug kernel, the transfer process is reduced to using "makedumpfile -c -d 1".  If /usr/lib/debug/vmlinux-$(uname -r) exists, kdump-
	      tools will automatically use that kernel.

	      Otherwise, A) set DEBUG_KERNEL in /etc/default/kdump-tools to point to a debug version of the currently booted kernel or B) do with-
	      out - makedumpfile will still work, but the dumpfile will be larger and take longer to save to disk.

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.

SEE ALSO
       /usr/share/doc/kdump-tools/README
       /usr/share/doc/kdump-tools/README.Debian
       kdump-config(8), kexec(8), sysctl(8), makedumpfile(8), crash(8), gdb(1),

AUTHOR
       Terry Loftin <terry.loftin@hp.com>

kdump-tools v1.1.3						    April 2007						       kdump-tools.conf(5)