.TH KDUMP.CONF 5 "07/23/2008" "kexec-tools"

.SH NAME

kdump.conf \- configuration file for kdump kernel.

.SH DESCRIPTION 

kdump.conf is a configuration file for the kdump kernel crash

collection service.

kdump.conf provides post-kexec instructions to the kdump kernel. It is

stored in the initrd file managed by the kdump service. If you change

this file and do not want to restart before it takes effect, restart

the kdump service to rebuild to initrd.

For most configurations, you can simply review the examples provided

in the stock /etc/kdump.conf.

.B NOTE: 

For filesystem dump the dump target must be mounted before building

kdump initramfs.

kdump.conf only affects the behavior of the initramfs.  Please read the

kdump operational flow section of kexec-kdump-howto.txt in the docs to better

understand how this configuration file affects the behavior of kdump.

.SH OPTIONS

.B raw <partition>

.RS

Will dd /proc/vmcore into <partition>.  Use persistent device names for

partition devices, such as /dev/vg/<devname>.

.RE

.B nfs <nfs mount>

.RS

Will mount fs and copy /proc/vmcore to <mnt>/var/crash/%HOST-%DATE/,

supports DNS. Note that a fqdn should be used as the server name in the 

mount point

.RE

.B ssh <user@server>

.RS

Will scp /proc/vmcore to <user@server>:/var/crash/%HOST-%DATE/,

supports DNS. NOTE: make sure user has necessary write permissions on

server and that a fqdn is used as the server name

.RE

.B sshkey <path>

.RS

Specifies the path of the ssh key you want to use when do ssh dump,

the default value is /root/.ssh/kdump_id_rsa.

.RE

.B <fs type> <partition>

.RS

Will mount -t <fs type> <partition> /mnt and copy /proc/vmcore to

/mnt/var/crash/%DATE/.  NOTE: <partition> can be a device node, label

or uuid.  It's recommended to use persistent device names such as

/dev/vg/<devname>. Otherwise it's suggested to use label or uuid.

.RE

.B path <path>

.RS

"path" represents the file system path in which vmcore will be saved.

If a dump target is specified in kdump.conf, then "path" is relative to the

specified dump target.

.PP

Interpretation of path changes a bit if user has not specified a dump

target explicitly in kdump.conf. In this case, "path" represents the

absolute path from root. And dump target and adjusted path are arrived

at automatically depending on what's mounted in the current system.

.PP

Ignored for raw device dumps.  If unset, will default to /var/crash.

.RE

.B core_collector <command> <options>

.RS

This allows you to specify the command to copy the vmcore.

You could use the dump filtering program makedumpfile, the default one,

to retrieve your core, which on some arches can drastically reduce

core file size.  See /sbin/makedumpfile --help for a list of options.

Note that the -i and -g options are not needed here, as the initrd

will automatically be populated with a config file appropriate

for the running kernel.

.PP

Note 1: About default core collector:

Default core_collector for raw/ssh dump is:

"makedumpfile -F -l --message-level 1 -d 31".

Default core_collector for other targets is:

"makedumpfile -l --message-level 1 -d 31".

Even if core_collector option is commented out in kdump.conf, makedumpfile

is default core collector and kdump uses it internally.

If one does not want makedumpfile as default core_collector, then they

need to specify one using core_collector option to change the behavior.

.PP

Note 2: If "makedumpfile -F" is used then you will get a flattened format

vmcore.flat, you will need to use "makedumpfile -R" to rearrange the

dump data from stdard input to a normal dumpfile (readable with analysis

tools).

ie. "makedumpfile -R vmcore < vmcore.flat"

.RE

.B kdump_post <binary | script>

.RS

This directive allows you to run a specified

executable just after the memory dump process

terminates. The exit status from the dump process

is fed to the kdump_post executable, which can be

used to trigger different actions for success or

failure.

.PP

Note that scripts written for use with this

directive must use the /bin/bash interpreter

.RE

.B kdump_pre <binary | script>

.RS

Works just like the kdump_post directive, but instead

of running after the dump process, runs immediately

before.  Exit status of this binary is interpreted

as follows:

.PP

0 - continue with dump process as usual

.PP

non 0 - reboot the system

.PP

Note that scripts written for this directive must use

the /bin/bash interpreter

.RE

.B extra_bins <binaries | shell scripts>

.RS

This directive allows you to specify additional

binaries or shell scripts you'd like to include in

your kdump initrd. Generally only useful in

conjunction with a kdump_post binary or script that

relies on other binaries or scripts.

.RE

.B extra_modules <module(s)>

.RS

This directive allows you to specify extra kernel

modules that you want to be loaded in the kdump

initrd, typically used to set up access to

non-boot-path dump targets that might otherwise

not be accessible in the kdump environment. Multiple

modules can be listed, separated by a space, and any

dependent modules will automatically be included.

.RE

.B default <reboot | halt | poweroff | shell | dump_to_rootfs>

.RS

Action to preform in case dumping to intended target fails. If no default

action is specified, "reboot" is assumed default.

reboot: If the default action is reboot simply reboot the system (this is what

most people will want, as it returns the system to a nominal state).  shell: If the default

action is shell, then drop to an shell session inside the initramfs from

where you can manually preform additional recovery actions.  Exiting this shell

reboots the system.  halt: bring the system to a halt, requiring manual reset

poweroff: The system will be powered down. dump_to_rootfs:If the default action

is dump_to_rootfs, specified root will be mounted and dump will be saved in "path"

directory.

Note: kdump uses bash as the default shell.

.RE

.B force_rebuild <0 | 1>

.RS

By default, kdump initrd only will be rebuilt when necessary.

Specify 1 to force rebuilding kdump initrd every time when kdump service starts.

.RE

.B override_resettable <0 | 1>

.RS

Usually a unresettable block device can't be dump target. Specifying 1 means

though block target is unresettable, user understand this situation and want

to try dumping. By default, it's set to 0, means not to try a destined failure.

.RE

.B dracut_args <arg(s)>

.RS

Kdump uses dracut to generate initramfs for second kernel. This option

allows a user to pass arguments to dracut directly.

.RE

.B fence_kdump_args <arg(s)>

.RS

Command line arguments for fence_kdump_send (it can contain all valid

arguments except hosts to send notification to).

.RE

.B fence_kdump_nodes <node(s)>

.RS

List of cluster node(s) separated by space to send fence_kdump notification

to (this option is mandatory to enable fence_kdump).

.RE

.SH DEPRECATED OPTIONS

.B net <nfs mount>|<user@server>

.RS

net option is replaced by nfs and ssh options. Use nfs or ssh options

directly.

.RE

.B options <module> <option list>

.RS

Use KDUMP_COMMANDLINE_APPEND in /etc/sysconfig/kdump to add proper

module option as kernel command line params. Such as append loop.max_loop=1

to limit maximum loop devices to 1.

.RE

.B link_delay <seconds>

.RS

link_delay was used to wait a network device to initialize before using it.

Now dracut network module take care of this issue automaticlly.

.RE

.B disk_timeout <seconds>

.RS

Similar to link_delay, dracut ensures disks being ready before kdump uses them.

.RE

.B debug_mem_level <0-3>

.RS

This was used to turns on debug/verbose output of kdump scripts regarding

free/used memory at various points of execution.  This feature has been

moved to dracut now.

Use KDUMP_COMMANDLINE_APPEND in /etc/sysconfig/kdump and

append dracut cmdline param rd.memdebug=[0-3] to enable the debug output.

Higher level means more debugging output.

.PP

0 - no output

.PP

1 - partial /proc/meminfo

.PP

2 - /proc/meminfo

.PP

3 - /proc/meminfo + /proc/slabinfo

.RE

.B blacklist <list of kernel modules>

.RS

blacklist option was recently being used to prevent loading modules in

initramfs. General terminology for blacklist has been that module is

present in initramfs but it is not actually loaded in kernel. Hence

retaining blacklist option creates more confusing behavior. It has been

deprecated.

.PP

Instead use rd.driver.blacklist option on second kernel to blacklist

a certain module. One can edit /etc/sysconfig/kdump.conf and edit

KDUMP_COMMANDLINE_APPEND to pass kernel command line options. Refer

to dracut.cmdline man page for more details on module blacklist option.

.RE

.RE

.SH EXAMPLES

Here is some examples for core_collector option:

.PP

Core collector command format depends on dump target type. Typically for

filesystem (local/remote), core_collector should accept two arguments.

First one is source file and second one is target file. For ex.

.TP

ex1.

core_collector "cp --sparse=always"

Above will effectively be translated to:

cp --sparse=always /proc/vmcore <dest-path>/vmcore

.TP

ex2.

core_collector "makedumpfile -l --message-level 1 -d 31"

Above will effectively be translated to:

makedumpfile -l --message-level 1 -d 31 /proc/vmcore <dest-path>/vmcore

.PP

For dump targets like raw and ssh, in general, core collector should expect

one argument (source file) and should output the processed core on standard

output (There is one exception of "scp", discussed later). This standard

output will be saved to destination using appropriate commands.

raw dumps examples:

.TP

ex3.

core_collector "cat"

Above will effectively be translated to.

cat /proc/vmcore | dd of=<target-device>

.TP

ex4.

core_collector "makedumpfile -F -l --message-level 1 -d 31"

Above will effectively be translated to.

makedumpfile -F -l --message-level 1 -d 31 | dd of=<target-device>

.PP

ssh dumps examples

.TP

ex5.

core_collector "cat"

Above will effectively be translated to.

cat /proc/vmcore | ssh <options> <remote-location> "dd of=path/vmcore"

.TP

ex6.

core_collector "makedumpfile -F -l --message-level 1 -d 31"

Above will effectively be translated to.

makedumpfile -F -l --message-level 1 -d 31 | ssh <options> <remote-location> "dd of=path/vmcore"

There is one exception to standard output rule for ssh dumps. And that is

scp. As scp can handle ssh destinations for file transfers, one can

specify "scp" as core collector for ssh targets (no output on stdout).

.TP

ex7.

core_collector "scp"

Above will effectively be translated to.

scp /proc/vmcore <user@host>:path/vmcore

.PP

examples for other options please see

.I /etc/kdump.conf

.SH SEE ALSO

kexec(8) mkdumprd(8) dracut.cmdline(7)