kexec-tools/kdump.conf.5

.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>.
.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 blacklist <list of kernel modules>
.RS
Specify a space-separated list of kernel modules not to add to the initramfs.
The kernel modules have to be specified without the ".ko" suffix.
.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.
.RE

.B path <path>
.RS
Append path to the filesystem device which you are dumping to.
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 -c --message-level 1 -d 31".
Default core_collector for other targets is:
"makedumpfile -c --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>
.RS
Action to preform in case dumping to intended target fails. If no default
action is specified saving vmcore to root fs 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.
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

.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 -c --message-level 1 -d 31"

Above will effectively be translated to:

makedumpfile -c --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 -c --message-level 1 -d 31"

Above will effectively be translated to.

makedumpfile -F -c --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 -c --message-level 1 -d 31"

Above will effectively be translated to.

makedumpfile -F -c --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)