kexec-tools/kdump.conf.5

387 lines
12 KiB
Groff
Raw Normal View History

2010-02-17 16:49:26 +00:00
.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 reboot in order for the changes to take
effect, restart the kdump service to rebuild the initrd.
2010-02-17 16:49:26 +00:00
For most configurations, you can simply review the examples provided
in the stock /etc/kdump.conf.
.B NOTE:
For filesystem dumps the dump target must be mounted before building
kdump initramfs.
2010-02-17 16:49:26 +00:00
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 auto_reset_crashkernel <yes|no>
.RS
Simplify the management of the kernel parameter crashkernel Currently, kexec-tools only updates the crashkernel to a new default value only when both two conditions are met, - auto_reset_crashkernel=yes in kdump.conf - existing kernels or current running kernel should use the old default value. To address seen corner cases, the logic to tell if the second condition is met becomes quite complex. Instead of making the logic more complex to support aarch64-64k, this patch drops the second condition to simplify the management of the crashkernel kernel parameter. Another change brought by this simplification is kexec-tools will also set up the kernel crashkernel parameter for a fresh install (previously it's limited to osbuild). Note 1. This patch also stop trying to update /etc/default/grub because a) it only affects the static file /boot/grub2/grub.cfg b) grubby is recommended to change the kernel command-line parameters for both Fedora [1] and RHEL9 [2][3] c) For the cases of aarch64 and POWER, different kernels could have different default crashkernel value. 2. Starting with Fedora 37, posttrans rpm scriplet distinguish between package install and upgrade. [1] https://fedoraproject.org/wiki/GRUB_2 [2] https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/9/html/managing_monitoring_and_updating_the_kernel/configuring-kernel-command-line-parameters_managing-monitoring-and-updating-the-kernel#changing-kernel-command-line-parameters-for-all-boot-entries_configuring-kernel-command-line-parameters [3] https://access.redhat.com/solutions/1136173 Signed-off-by: Coiby Xu <coxu@redhat.com> Reviewed-by: Philipp Rudo <prudo@redhat.com>
2023-04-25 20:48:25 +00:00
determine whether to reset kernel crashkernel parameter to the default value
or not when kexec-tools is updated or a new kernel is installed.
2010-02-17 16:49:26 +00:00
.B raw <partition>
.RS
Will dd /proc/vmcore into <partition>. Use persistent device names for
partition devices, such as /dev/vg/<devname>.
2010-02-17 16:49:26 +00:00
.RE
.B nfs <nfs mount>
2010-02-17 16:49:26 +00:00
.RS
Will mount nfs to <mnt>, and copy /proc/vmcore to <mnt>/<path>/%HOST-%DATE/,
2010-02-17 16:49:26 +00:00
supports DNS. Note that a fqdn should be used as the server name in the
mount point.
2010-02-17 16:49:26 +00:00
.RE
.B ssh <user@server>
2010-02-17 16:49:26 +00:00
.RS
Will save /proc/vmcore through ssh pipe to <user@server>:<path>/%HOST-%DATE/,
2010-02-17 16:49:26 +00:00
supports DNS. NOTE: make sure user has necessary write permissions on
server and that a fqdn is used as the server name.
2010-02-17 16:49:26 +00:00
.RE
.B sshkey <path>
.RS
Specify the path of the ssh key to use when dumping via ssh.
The default value is /root/.ssh/kdump_id_rsa.
.RE
2010-02-17 16:49:26 +00:00
.B <fs type> <partition>
.RS
Will mount -t <fs type> <partition> <mnt>, and copy /proc/vmcore to
<mnt>/<path>/%HOST_IP-%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.
2010-02-17 16:49:26 +00:00
.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 the user didn't specify any dump
target explicitly in kdump.conf. In this case, "path" represents the
absolute path from root. The 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 use the default "/var/crash".
2010-02-17 16:49:26 +00:00
.RE
.B core_collector <command> <options>
2010-02-17 16:49:26 +00:00
.RS
This allows you to specify the command to copy the vmcore.
The default is makedumpfile, which on some architectures 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:
The default core_collector for raw/ssh dump is:
"makedumpfile -F -l --message-level 7 -d 31".
The default core_collector for other targets is:
"makedumpfile -l --message-level 7 -d 31".
Even if core_collector option is commented out in kdump.conf, makedumpfile
is the 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 standard input to a normal dumpfile (readable with analysis
tools).
ie. "makedumpfile -R vmcore < vmcore.flat"
.PP
Note 3: If specified core_collector simply copy the vmcore file to the
dump target (eg: cp, scp), the vmcore could be significantly large.
Please make sure the dump target has enough space, at leaset larger
than the system's RAM.
2010-02-17 16:49:26 +00:00
.RE
.B kdump_post <binary | script>
.RS
This directive allows you to run a specified executable
just after the vmcore dump process terminates. The exit
status of the current dump process is fed to the kdump_post
executable as its first argument($1). Executable can modify
it to indicate the new exit status of succeeding dump process,
.PP
All files under /etc/kdump/post.d are collectively sorted
and executed in lexical order, before binary or script
specified kdump_post parameter is executed.
.PP
Note that scripts written for use with this directive must use the /bin/bash
interpreter. And since these scripts run in kdump enviroment, the reference to
the storage or network device in the scripts should adhere to the section
'Supported dump target types and requirements' in kexec-kdump-howto.txt.
.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 - run the final action (reboot/poweroff/halt)
.PP
All files under /etc/kdump/pre.d are collectively sorted and
executed in lexical order, after binary or script specified
kdump_pre parameter is executed.
Even if the binary or script in /etc/kdump/pre.d directory
returns non 0 exit status, the processing is continued.
.PP
Note that scripts written for use with this directive must use the /bin/bash
interpreter. And since these scripts run in kdump enviroment, the reference to
the storage or network device in the scripts should adhere to the section
'Supported dump target types and requirements' in kexec-kdump-howto.txt.
.RE
2010-02-17 16:49:26 +00:00
.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.
2010-02-17 16:49:26 +00:00
.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 spaces, and any
2010-02-17 16:49:26 +00:00
dependent modules will automatically be included.
.RE
.B failure_action <reboot | halt | poweroff | shell | dump_to_rootfs>
2010-02-17 16:49:26 +00:00
.RS
Action to perform in case dumping to the intended target fails. The default is "reboot".
reboot: Reboot the system (this is what most people will want, as it returns the system
to a normal state). halt: Halt the system and lose the vmcore. poweroff: The system
will be powered down. shell: Drop to a shell session inside the initramfs, from which
you can manually perform additional recovery actions. Exiting this shell reboots the
system by default or performs "final_action".
Note: kdump uses bash as the default shell. dump_to_rootfs: If non-root dump
target is specified, the failure action can be set as dump_to_rootfs. That means when
dumping to target fails, dump vmcore to rootfs from initramfs context and reboot
by default or perform "final_action".
2010-02-17 16:49:26 +00:00
.RE
.B default <reboot | halt | poweroff | shell | dump_to_rootfs>
.RS
Same as the "failure_action" directive above, but this directive is obsolete
and will be removed in the future.
.RE
.B final_action <reboot | halt | poweroff>
.RS
Action to perform in case dumping to the intended target succeeds.
Also performed when "shell" or "dump_to_rootfs" failure action finishes.
Each action is same as the "failure_action" directive above.
The default is "reboot".
.RE
.B force_rebuild <0 | 1>
.RS
By default, kdump initrd will only be rebuilt when necessary.
Specify 1 to force rebuilding kdump initrd every time when kdump service starts.
.RE
.B force_no_rebuild <0 | 1>
.RS
By default, kdump initrd will be rebuilt when necessary.
Specify 1 to bypass rebuilding of kdump initrd.
.PP
force_no_rebuild and force_rebuild options are mutually exclusive and
they should not be set to 1 simultaneously.
.RE
.B override_resettable <0 | 1>
.RS
Usually an unresettable block device can't be a dump target. Specifying 1 means
that even though the block target is unresettable, the user wants to try dumping anyway.
By default, it's set to 0, which will not try something destined to fail.
.RE
add dracut_args option to kdump.conf mkdumprd call dracut to rebuilding kdump initrd, sometimes passing extra dracut args is helpful. For example user can enable debug output with --debug, --printsize to print roughly increased initramfs size by each module, --omit-drivers to omit kernel modules, etc. This patch enables dracut_args option for passing extra args to dracut. Also it modifies add_dracut_arg() to treat a string with-in quote as single string because for dracut options which has its own args, the args need to be quoted and space seperated. If add_dracut_arg() gets an string read from kdump.conf and if that string contains double quotes, then while converting to positional parameters those double quotes are not interpreted. Hence if /etc/kdump.conf contains following. dracut_args --add-drivers "driver1 driver2" then add_dracut_args() sees following positional parameters $1= --add-drivers $2= "driver1 $3= driver2" Notice, double quotes have been ignored and parameters have been broken based on white space. Modify add_dracut_arg() to look for parameters starting with " and if one is found, it tries to merge all the next parameters till one is found with ending double quote. Hence effectively simulating following behavior. $1= --add-drivers $2= "driver1 driver2" [v1->v2]: address quoted substring in dracut_args, also handle the leading and ending spaces in substring. [v2->v3]: fix dracut arguments seperator in kdump.conf. [v3->v4]: improve changelog, thanks vivek. [v4->v5]: make the manpage more verbose [vivek]. Tested with below dracut_args test cases: 1. dracut_args --add-drivers "pcspkr virtio_net" --omit-drivers "sdhci-pci hid-logitech-dj e1000" 2. dracut_args --add-drivers " pcspkr virtio_net " --omit-drivers "sdhci-pci hid-logitech-dj e1000" Signed-off-by: Dave Young <dyoung@redhat.com> Acked-by: Vivek Goyal <vgoyal@redhat.com>
2013-04-15 02:12:05 +00:00
.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) except localhost, separated by spaces, 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 module options as
kernel command line parameters. For example, specify 'loop.max_loop=1' to limit
maximum loop devices to 1.
.RE
.B link_delay <seconds>
.RS
link_delay was used to wait for a network device to initialize before using it.
Now dracut network module takes care of this issue automatically.
.RE
.B disk_timeout <seconds>
.RS
Similar to link_delay, dracut ensures disks are ready before kdump uses them.
.RE
.B debug_mem_level <0-3>
.RS
Turn on verbose debug 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
2010-02-17 16:49:26 +00:00
.SH EXAMPLES
Here are 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 7 -d 31"
Above will effectively be translated to:
makedumpfile -l --message-level 7 -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 7 -d 31"
Above will effectively be translated to.
makedumpfile -F -l --message-level 7 -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 7 -d 31"
Above will effectively be translated to.
makedumpfile -F -l --message-level 7 -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
2010-02-17 16:49:26 +00:00
.I /etc/kdump.conf
.SH SEE ALSO
kexec(8) mkdumprd(8) dracut.cmdline(7)