1:43 a.m.
Signed-off-by: Kairui Song <kasong(a)redhat.com>
---
crashkernel-howto.conf | 113 +++++++++++++++++++++++++++++++++++++++++
kexec-tools.spec | 3 ++
2 files changed, 116 insertions(+)
create mode 100644 crashkernel-howto.conf
diff --git a/crashkernel-howto.conf b/crashkernel-howto.conf
new file mode 100644
index 0000000..13e6602
--- /dev/null
+++ b/crashkernel-howto.conf
@@ -0,0 +1,113 @@
+Introduction
+------------
+
+This document describes utils kexec-tools package provides for setting and
+estimating the crashkernel value.
+
+Kdump lives in a pre-reserved chunk of memory, and the size of the reserved
+memory is specified by the `crashkernel=` kernel parameter. It's hard to
+estimate an accurate `crashkernel=` value, so it's always recommended to
+test kdump after you updated the `crashkernel=` value or changed the dump
+target.
+
+
+crashkernel=auto
+----------------
+
+Legacy RHEL kernels support a `crashkernel=auto` parameter. When
+it's specified, the kernel simply uses a pre-defined default `crashkernel=`
+(eg. crashekrnel=1G-4G:192M,4G-64G:256M,64G-:512M) as the cmdline.
+
+Latest kernel pacakge have dropped this parameter, and a default
+`crashkernel.default` file is included and installed in kernel
+modules folder, available as:
+
+ /usr/lib/modules/<kernel>/crashkernel.default
+
+You can use the content of this file as the default value for
+`crashkernel=`, or take this file as a reference for setting the
+crashkernel value.
+
+To make it easier to reset the `crashkernel=` kernel cmdline to this
+default value properly, `kdumpctl` also provides a sub-command:
+
+ `kdumpctl reset-crashkernel [<kernel release>]`
+
+This command will read from the `crashkernel.default` file and reset
+bootloader's kernel cmdline to the default value. It will also update
+bootloader config if the bootloader have a standalone config file.
+
+
+New installed system
+--------------------
+
+If you enabled kdump in Anaconda and chosen automatic memory reserve,
+Anaconda will execute similar logic with `kdumpctl reset-crashkernel`.
+Kernel's `crashkernel=` value will be set to the default value from
+`crashkernel.default`.
+
+
+Installing a new kernel
+-----------------------
+
+When a new kernel package is installed, by default, it will inherit current
+boot kernel's cmdline. But kexec-tools will install extra kernel hooks
+to update `crashkernel=` value when needed.
+
+If current kernel have a `crashkernel.default` file, and it's using this
+default value, kexec-tools will keep the new installed kernel's
+`crashkernel=` synchronized with new installed `crashkernel.default` file.
+
+If new kernel doesn't have a `crashkernel.default` file (eg. installing a
+self-compiled kernel), kexec-tools won't do anything, old `crashkernel=`
+value will be inherited.
+
+If the current boot kernel don't have a `crashkernel.default` file,
+kexec-tools will iterate through installed kernels, look for a valid
+`crashkernel.default` and find out if current boot kernel just inherited
+the default value from a previously installed kernel. If that's the case,
+it will also perform the `crashkernel=` value synchronization.
+
+If kexec-tools package is absent, new installed kernel's `crashkernel=`
+value will not get updated. And later even if kexec-tools is installed
+back it might not be able to update the `crashkernel=` value since the
+current `crashkernel=` value may out of sync with the latest default value.
+So it's recommended to run `kdumpctl reset-crashkernel` if you have
+uninstalled kexec-tools and installed it back later.
+
+
+Estimate crashkernel
+--------------------
+
+The best way to estimate a usable crashkernel value is by testing kdump
+manually. And you can set crashkernel to a large value, then adjust the
+crashkernel value to an acceptable value gradually.
+
+`kdumpctl` also provides a sub-command for doing rough estimating without
+triggering kdump:
+
+ `kdumpctl estimate`
+
+
+The output will be like this:
+
+```
+ Encrypted kdump target requires extra memory, assuming using the keyslot with
minimun memory requirement
+
+ Reserved crashkernel: 256M
+ Recommended crashkernel: 655M
+
+ Kernel image size: 47M
+ Kernel modules size: 12M
+ Initramfs size: 19M
+ Runtime reservation: 64M
+ LUKS required size: 512M
+ Large modules:
+ xfs: 1892352
+ nouveau: 2318336
+ WARNING: Current crashkernel size is lower than recommended size 655M.
+```
+
+It will generate a summary report about the estimated memory consumption
+of each component of kdump. The value may not be accurate enough, but
+would be a good start for finding a suitable crashkernel value.
diff --git a/kexec-tools.spec b/kexec-tools.spec
index ec327da..deedcf1 100644
--- a/kexec-tools.spec
+++ b/kexec-tools.spec
@@ -41,6 +41,7 @@ Source30: 60-kdump.install
Source31: kdump-logger.sh
Source32: mkfadumprd
Source33: 92-crashkernel.install
+Source34: crashkernel-howto.txt
#######################################
# These are sources for mkdumpramfs
@@ -151,6 +152,7 @@ cp %{SOURCE11} .
cp %{SOURCE21} .
cp %{SOURCE26} .
cp %{SOURCE27} .
+cp %{SOURCE34} .
make
%ifarch %{ix86} x86_64 ppc64 s390x ppc64le aarch64
@@ -372,6 +374,7 @@ done
%doc fadump-howto.txt
%doc kdump-in-cluster-environment.txt
%doc live-image-kdump-howto.txt
+%doc crashkernel-howto.txt
%ifarch %{ix86} x86_64 ppc64 s390x ppc64le aarch64
%{_libdir}/eppic_makedumpfile.so
/usr/share/makedumpfile/
--
2.31.1