b9e861
.TH KDUMP.CONF 5 "07/23/2008" "kexec-tools"
b9e861
b9e861
.SH NAME
b9e861
kdump.conf \- configuration file for kdump kernel.
b9e861
b9e861
.SH DESCRIPTION 
b9e861
b9e861
kdump.conf is a configuration file for the kdump kernel crash
b9e861
collection service.
b9e861
b9e861
kdump.conf provides post-kexec instructions to the kdump kernel. It is
b9e861
stored in the initrd file managed by the kdump service. If you change
b9e861
this file and do not want to reboot in order for the changes to take
b9e861
effect, restart the kdump service to rebuild the initrd.
b9e861
b9e861
For most configurations, you can simply review the examples provided
b9e861
in the stock /etc/kdump.conf.
b9e861
b9e861
.B NOTE: 
b9e861
For filesystem dumps the dump target must be mounted before building
b9e861
kdump initramfs.
b9e861
b9e861
kdump.conf only affects the behavior of the initramfs.  Please read the
b9e861
kdump operational flow section of kexec-kdump-howto.txt in the docs to better
b9e861
understand how this configuration file affects the behavior of kdump.
b9e861
b9e861
.SH OPTIONS
b9e861
b9e861
.B raw <partition>
b9e861
.RS
b9e861
Will dd /proc/vmcore into <partition>.  Use persistent device names for
b9e861
partition devices, such as /dev/vg/<devname>.
b9e861
.RE
b9e861
b9e861
.B nfs <nfs mount>
b9e861
.RS
b9e861
Will mount nfs to <mnt>, and copy /proc/vmcore to <mnt>/<path>/%HOST-%DATE/,
b9e861
supports DNS. Note that a fqdn should be used as the server name in the 
b9e861
mount point.
b9e861
.RE
b9e861
b9e861
.B ssh <user@server>
b9e861
.RS
b9e861
Will scp /proc/vmcore to <user@server>:<path>/%HOST-%DATE/,
b9e861
supports DNS. NOTE: make sure user has necessary write permissions on
b9e861
server and that a fqdn is used as the server name.
b9e861
.RE
b9e861
b9e861
.B sshkey <path>
b9e861
.RS
b9e861
Specify the path of the ssh key to use when dumping via ssh.
b9e861
The default value is /root/.ssh/kdump_id_rsa.
b9e861
.RE
b9e861
b9e861
.B <fs type> <partition>
b9e861
.RS
b9e861
Will mount -t <fs type> <partition> <mnt>, and copy /proc/vmcore to
b9e861
<mnt>/<path>/%DATE/.  NOTE: <partition> can be a device node, label
b9e861
or uuid.  It's recommended to use persistent device names such as
b9e861
/dev/vg/<devname>.  Otherwise it's suggested to use label or uuid.
b9e861
.RE
b9e861
b9e861
.B path <path>
b9e861
.RS
b9e861
"path" represents the file system path in which vmcore will be saved.
b9e861
If a dump target is specified in kdump.conf, then "path" is relative to the
b9e861
specified dump target.
b9e861
.PP
b9e861
Interpretation of "path" changes a bit if the user didn't specify any dump
b9e861
target explicitly in kdump.conf. In this case, "path" represents the
b9e861
absolute path from root.  The dump target and adjusted path are arrived
b9e861
at automatically depending on what's mounted in the current system.
b9e861
.PP
b9e861
Ignored for raw device dumps.  If unset, will use the default "/var/crash".
b9e861
.RE
b9e861
b9e861
.B core_collector <command> <options>
b9e861
.RS
b9e861
This allows you to specify the command to copy the vmcore.
b9e861
The default is makedumpfile, which on some architectures can drastically reduce
b9e861
core file size. See /sbin/makedumpfile --help for a list of options.
b9e861
Note that the -i and -g options are not needed here, as the initrd
b9e861
will automatically be populated with a config file appropriate
b9e861
for the running kernel.
b9e861
.PP
b9e861
Note 1: About default core collector:
b9e861
The default core_collector for raw/ssh dump is:
fe2ad6
"makedumpfile -F -l --message-level 7 -d 31".
b9e861
The default core_collector for other targets is:
fe2ad6
"makedumpfile -l --message-level 7 -d 31".
b9e861
Even if core_collector option is commented out in kdump.conf, makedumpfile
b9e861
is the default core collector and kdump uses it internally.
b9e861
If one does not want makedumpfile as default core_collector, then they
b9e861
need to specify one using core_collector option to change the behavior.
b9e861
.PP
b9e861
Note 2: If "makedumpfile -F" is used then you will get a flattened format
b9e861
vmcore.flat, you will need to use "makedumpfile -R" to rearrange the
b9e861
dump data from standard input to a normal dumpfile (readable with analysis
b9e861
tools).
b9e861
ie. "makedumpfile -R vmcore < vmcore.flat"
fe2ad6
.PP
fe2ad6
Note 3: If specified core_collector simply copy the vmcore file to the
fe2ad6
dump target (eg: cp, scp), the vmcore could be significantly large.
fe2ad6
Please make sure the dump target has enough space, at leaset larger
fe2ad6
than the system's RAM.
b9e861
b9e861
.RE
b9e861
b9e861
.B kdump_post <binary | script>
b9e861
.RS
b9e861
This directive allows you to run a specified executable
b9e861
just after the vmcore dump process terminates.  The exit
b9e861
status of the current dump process is fed to the kdump_post
b9e861
executable as its first argument($1).  Executable can modify
b9e861
it to indicate the new exit status of succeeding dump process,
b9e861
.PP
fe2ad6
All files under /etc/kdump/post.d are collectively sorted
fe2ad6
and executed in lexical order, before binary or script
fe2ad6
specified kdump_post parameter is executed.
73ea9d
.PP
97e513
Note that scripts written for use with this directive must use the /bin/bash
97e513
interpreter. And since these scripts run in kdump enviroment, the reference to
97e513
the storage or network device in the scripts should adhere to the section
97e513
\'Supported dump target types and requirements\' in kexec-kdump-howto.txt.
97e513
b9e861
.RE
b9e861
b9e861
.B kdump_pre <binary | script>
b9e861
.RS
b9e861
Works just like the "kdump_post" directive, but instead
b9e861
of running after the dump process, runs immediately
b9e861
before.  Exit status of this binary is interpreted
b9e861
as follows:
b9e861
.PP
b9e861
0 - continue with dump process as usual
b9e861
.PP
fe2ad6
non 0 - run the final action (reboot/poweroff/halt)
b9e861
.PP
fe2ad6
All files under /etc/kdump/pre.d are collectively sorted and
fe2ad6
executed in lexical order, after binary or script specified
73ea9d
kdump_pre parameter is executed.
73ea9d
Even if the binary or script in /etc/kdump/pre.d directory
73ea9d
returns non 0 exit status, the processing is continued.
73ea9d
.PP
97e513
Note that scripts written for use with this directive must use the /bin/bash
97e513
interpreter. And since these scripts run in kdump enviroment, the reference to
97e513
the storage or network device in the scripts should adhere to the section
97e513
\'Supported dump target types and requirements\' in kexec-kdump-howto.txt.
97e513
b9e861
.RE
b9e861
b9e861
.B extra_bins <binaries | shell scripts>
b9e861
.RS
b9e861
This directive allows you to specify additional
b9e861
binaries or shell scripts you'd like to include in
b9e861
your kdump initrd. Generally only useful in
b9e861
conjunction with a kdump_post binary or script that
b9e861
relies on other binaries or scripts.
b9e861
.RE
b9e861
b9e861
.B extra_modules <module(s)>
b9e861
.RS
b9e861
This directive allows you to specify extra kernel
b9e861
modules that you want to be loaded in the kdump
b9e861
initrd, typically used to set up access to
b9e861
non-boot-path dump targets that might otherwise
b9e861
not be accessible in the kdump environment. Multiple
b9e861
modules can be listed, separated by spaces, and any
b9e861
dependent modules will automatically be included.
b9e861
.RE
b9e861
b9e861
.B failure_action <reboot | halt | poweroff | shell | dump_to_rootfs>
b9e861
.RS
b9e861
Action to perform in case dumping to the intended target fails. The default is "reboot".
b9e861
reboot: Reboot the system (this is what most people will want, as it returns the system
b9e861
to a normal state).  halt: Halt the system and lose the vmcore.  poweroff: The system
b9e861
will be powered down.  shell: Drop to a shell session inside the initramfs, from which
b9e861
you can manually perform additional recovery actions.  Exiting this shell reboots the
b9e861
system by default or performs "final_action".
b9e861
Note: kdump uses bash as the default shell.  dump_to_rootfs: If non-root dump
b9e861
target is specified, the failure action can be set as dump_to_rootfs.  That means when
b9e861
dumping to target fails, dump vmcore to rootfs from initramfs context and reboot
b9e861
by default or perform "final_action".
b9e861
.RE
b9e861
b9e861
.B default <reboot | halt | poweroff | shell | dump_to_rootfs>
b9e861
.RS
b9e861
Same as the "failure_action" directive above, but this directive is obsolete
b9e861
and will be removed in the future.
b9e861
.RE
b9e861
b9e861
.B final_action <reboot | halt | poweroff>
b9e861
.RS
b9e861
Action to perform in case dumping to the intended target succeeds.
b9e861
Also performed when "shell" or "dump_to_rootfs" failure action finishes.
b9e861
Each action is same as the "failure_action" directive above.
b9e861
The default is "reboot".
b9e861
.RE
b9e861
b9e861
.B force_rebuild <0 | 1>
b9e861
.RS
b9e861
By default, kdump initrd will only be rebuilt when necessary.
b9e861
Specify 1 to force rebuilding kdump initrd every time when kdump service starts.
b9e861
.RE
b9e861
b9e861
.B force_no_rebuild <0 | 1>
b9e861
.RS
b9e861
By default, kdump initrd will be rebuilt when necessary.
b9e861
Specify 1 to bypass rebuilding of kdump initrd.
b9e861
b9e861
.PP
b9e861
force_no_rebuild and force_rebuild options are mutually exclusive and
b9e861
they should not be set to 1 simultaneously.
b9e861
.RE
b9e861
b9e861
.B override_resettable <0 | 1>
b9e861
.RS
b9e861
Usually an unresettable block device can't be a dump target. Specifying 1 means
b9e861
that even though the block target is unresettable, the user wants to try dumping anyway.
b9e861
By default, it's set to 0, which will not try something destined to fail.
b9e861
.RE
b9e861
b9e861
b9e861
.B dracut_args <arg(s)>
b9e861
.RS
b9e861
Kdump uses dracut to generate initramfs for second kernel. This option
b9e861
allows a user to pass arguments to dracut directly.
b9e861
.RE
b9e861
b9e861
b9e861
.B fence_kdump_args <arg(s)>
b9e861
.RS
b9e861
Command line arguments for fence_kdump_send (it can contain all valid
b9e861
arguments except hosts to send notification to).
b9e861
.RE
b9e861
b9e861
b9e861
.B fence_kdump_nodes <node(s)>
b9e861
.RS
b9e861
List of cluster node(s) except localhost, separated by spaces, to send fence_kdump notification
b9e861
to (this option is mandatory to enable fence_kdump).
b9e861
.RE
b9e861
b9e861
b9e861
.SH DEPRECATED OPTIONS
b9e861
b9e861
.B net <nfs mount>|<user@server>
b9e861
.RS
b9e861
net option is replaced by nfs and ssh options. Use nfs or ssh options
b9e861
directly.
b9e861
.RE
b9e861
b9e861
.B options <module> <option list>
b9e861
.RS
b9e861
Use KDUMP_COMMANDLINE_APPEND in /etc/sysconfig/kdump to add module options as
b9e861
kernel command line parameters. For example, specify 'loop.max_loop=1' to limit
b9e861
maximum loop devices to 1.
b9e861
.RE
b9e861
b9e861
.B link_delay <seconds>
b9e861
.RS
b9e861
link_delay was used to wait for a network device to initialize before using it.
b9e861
Now dracut network module takes care of this issue automatically.
b9e861
.RE
b9e861
b9e861
.B disk_timeout <seconds>
b9e861
.RS
b9e861
Similar to link_delay, dracut ensures disks are ready before kdump uses them.
b9e861
.RE
b9e861
b9e861
.B debug_mem_level <0-3>
b9e861
.RS
b9e861
Turn on verbose debug output of kdump scripts regarding free/used memory at
b9e861
various points of execution.  This feature has been
b9e861
moved to dracut now.
b9e861
Use KDUMP_COMMANDLINE_APPEND in /etc/sysconfig/kdump and
b9e861
append dracut cmdline param rd.memdebug=[0-3] to enable the debug output.
b9e861
b9e861
Higher level means more debugging output.
b9e861
.PP
b9e861
0 - no output
b9e861
.PP
b9e861
1 - partial /proc/meminfo
b9e861
.PP
b9e861
2 - /proc/meminfo
b9e861
.PP
b9e861
3 - /proc/meminfo + /proc/slabinfo
b9e861
.RE
b9e861
b9e861
.B blacklist <list of kernel modules>
b9e861
.RS
b9e861
blacklist option was recently being used to prevent loading modules in
b9e861
initramfs. General terminology for blacklist has been that module is
b9e861
present in initramfs but it is not actually loaded in kernel. Hence
b9e861
retaining blacklist option creates more confusing behavior. It has been
b9e861
deprecated.
b9e861
.PP
b9e861
Instead, use rd.driver.blacklist option on second kernel to blacklist
bda30f
a certain module. One can edit /etc/sysconfig/kdump and edit
b9e861
KDUMP_COMMANDLINE_APPEND to pass kernel command line options. Refer
b9e861
to dracut.cmdline man page for more details on module blacklist option.
b9e861
.RE
b9e861
b9e861
.RE
b9e861
b9e861
.SH EXAMPLES
b9e861
Here are some examples for core_collector option:
b9e861
.PP
b9e861
Core collector command format depends on dump target type. Typically for
b9e861
filesystem (local/remote), core_collector should accept two arguments.
b9e861
First one is source file and second one is target file. For ex.
b9e861
.TP
b9e861
ex1.
b9e861
core_collector "cp --sparse=always"
b9e861
b9e861
Above will effectively be translated to:
b9e861
b9e861
cp --sparse=always /proc/vmcore <dest-path>/vmcore
b9e861
.TP
b9e861
ex2.
fe2ad6
core_collector "makedumpfile -l --message-level 7 -d 31"
b9e861
b9e861
Above will effectively be translated to:
b9e861
fe2ad6
makedumpfile -l --message-level 7 -d 31 /proc/vmcore <dest-path>/vmcore
b9e861
.PP
b9e861
For dump targets like raw and ssh, in general, core collector should expect
b9e861
one argument (source file) and should output the processed core on standard
b9e861
output (There is one exception of "scp", discussed later). This standard
b9e861
output will be saved to destination using appropriate commands.
b9e861
b9e861
raw dumps examples:
b9e861
.TP
b9e861
ex3.
b9e861
core_collector "cat"
b9e861
b9e861
Above will effectively be translated to.
b9e861
b9e861
cat /proc/vmcore | dd of=<target-device>
b9e861
.TP
b9e861
ex4.
fe2ad6
core_collector "makedumpfile -F -l --message-level 7 -d 31"
b9e861
b9e861
Above will effectively be translated to.
b9e861
fe2ad6
makedumpfile -F -l --message-level 7 -d 31 | dd of=<target-device>
b9e861
.PP
b9e861
ssh dumps examples
b9e861
.TP
b9e861
ex5.
b9e861
core_collector "cat"
b9e861
b9e861
Above will effectively be translated to.
b9e861
b9e861
cat /proc/vmcore | ssh <options> <remote-location> "dd of=path/vmcore"
b9e861
.TP
b9e861
ex6.
fe2ad6
core_collector "makedumpfile -F -l --message-level 7 -d 31"
b9e861
b9e861
Above will effectively be translated to.
b9e861
fe2ad6
makedumpfile -F -l --message-level 7 -d 31 | ssh <options> <remote-location> "dd of=path/vmcore"
b9e861
b9e861
There is one exception to standard output rule for ssh dumps. And that is
b9e861
scp. As scp can handle ssh destinations for file transfers, one can
b9e861
specify "scp" as core collector for ssh targets (no output on stdout).
b9e861
.TP
b9e861
ex7.
b9e861
core_collector "scp"
b9e861
b9e861
Above will effectively be translated to.
b9e861
b9e861
scp /proc/vmcore <user@host>:path/vmcore
b9e861
b9e861
.PP
b9e861
examples for other options please see
b9e861
.I /etc/kdump.conf
b9e861
b9e861
.SH SEE ALSO
b9e861
b9e861
kexec(8) mkdumprd(8) dracut.cmdline(7)