Provided by: kdump-tools_1.6.7-1ubuntu2.5_amd64 bug

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 systemd.unit=kdump-tools-dump.service nr_cpus=1 irqpoll  nousb”
              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.

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>