Provided by: kdump-tools_1.10.3ubuntu2_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_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
              usbcore.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

SYSCTLS

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

   Sysctl handling *during a kdump*
       kdump-tools  allows  users  to  configure  sysctls overrides on kdump environment; this is
       specially useful to prevent sysctls from the regular  boot  to  mess  with  the  resource-
       impaired kdump environment.

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

       By default, hugepages overrides are set and is highly recommended  to  keep  them  in  the
       file, to prevent kdump out-of-memory conditions.

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