Introduction

============

This document describes features the 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.

Default crashkernel value

=========================

Latest kernel packages include a `crashkernel.default` file installed in kernel

modules folder, available as:

	/usr/lib/modules/<kernel>/crashkernel.default

The content of the file will be taken as the default value of 'crashkernel=', or

take this file as a reference for setting crashkernel value manually.

New installed system

====================

Anaconda is the OS installer which sets all the kernel boot cmdline on a newly

installed system. If kdump is enabled during Anaconda installation, Anaconda

will use the `crashkernel.default` file as the default `crashkernel=` value on

the newly installed system.

Users can override the value during Anaconda installation manually.

Auto update of crashkernel boot parameter

=========================================

Following context in this section assumes all kernel packages have a

`crashkernel.default` file bundled, which is true for the latest official kernel

packages. For kexec-tools behavior with a kernel that doesn't have a

`crashkernel.default` file, please refer to the “Custom Kernel” section of this

doc.

When `crashkernel=` is using the default value, kexec-tools will need to update

the `crashkernel=` value of new installed kernels, since the default value may

change in new kernel packages.

kexec-tools does so by adding a kernel installation hook, which gets triggered

every time a new kernel is installed, so kexec-tools can do necessary checks and

updates.

Supported Bootloaders

---------------------

This auto update only works with GRUB2 and ZIPL, as kexec-tools heavily depends

on `grubby`. If other boot loaders are used, the user will have to update the

`crashkernel=` value manually.

Updating kernel package

-----------------------

When a new version of package kernel is released in the official repository, the

package will always come with a `crashkernel.default` file bundled. Kexec-tools

will act with following rules:

If current boot kernel is using the default `crashkernel=` boot param value from

its `crashkernel.default` file, then kexec-tools will update new installed

kernel’s `crashkernel=` boot param using the value from the new installed

kernel’s `crashkernel.default` file. This ensures `crashkernel=` is always using

the latest default value.

If current boot kernel's `crashkernel=` value is set to a non-default value, the

new installed kernel simply inherits this value.

On systems using GRUB2 as the bootloader, each kernel has its own boot entry,

making it possible to set different `crashkernel=` boot param values for

different kernels. So kexec-tools won’t touch any already installed kernel's

boot param, only new installed kernel's `crashkernel=` boot param value will be

updated.

But some utilities like `grub2-mkconfig` and `grubby` can override all boot

entry's boot params with the boot params value from the GRUB config file

`/etc/defaults/grub`, so kexec-tools will also update the GRUB config file in

case old `crashkernel=` value overrides new installed kernel’s boot param.

Downgrading kernel package

--------------------------

When upgrading a kernel package, kexec-tools may update the `crashkernel=` value

in GRUB2 config file to the new value. So when downgrading the kernel package,

kexec-tools will also try to revert that update by setting GRUB2 config file’s

`crashkernel=` value back to the default value in the older kernel package. This

will only occur when the GRUB2 config file is using the default `crashkernel=`

value.

Custom kernel

=============

To make auto crashkernel update more robust, kexec-tools will try to keep

tracking the default 'crashkernel=` value with kernels that don’t have a

`crashkernel.default` file, such kernels are referred to as “custom kernel” in

this doc. This is only a best-effort support to make it easier debugging and

testing the system.

When installing a custom kernel that doesn’t have a `crashkernel.default` file,

the `crashkernel=` value will be simply inherited from the current boot kernel.

When installing a new official kernel package and current boot kernel is a

custom kernel, since the boot kernel doesn’t have a `crashkernel.default` file,

kexec-tools will iterate installed kernels and check if the boot kernel

inherited the default value from any other existing kernels’

`crashkernel.default` file. If a matching `crashkernel.default` file is found,

kexec-tools will update the new installed kernel `crashkernel=` boot param using

the value from the new installed kernel’s `crashkernel.default` file, ensures

the auto crashkernel value update won’t break over one or two custom kernel

installations.

It is possible that the auto crashkernel value update will fail when custom

kernels are used. One example is a custom kernel inheriting the default

`crashkernel=` value from an older official kernel package, but later that

kernel package is uninstalled. So when booted with the custom kernel,

kexec-tools can't determine if the boot kernel is inheriting a default

`crashkernel=` value from any official build. In such a case, please refer to

the "Reset crashkernel to default value" section of this doc.

Reset crashkernel to default value

==================================

kexec-tools only perform the auto update of crashkernel value when it can

confirm the boot kernel's crashkernel value is using its corresponding default

value or inherited from any installed kernel.

kexec-tools may fail to determine if the boot kernel is using default

crashkernel value in some use cases:

- kexec-tools package is absent during a kernel package upgrade, and the new

  kernel package’s `crashkernel.default` value has changed.

- Custom kernel is used and the kernel it inherits `crashkernel=`  value from is

  uninstalled.

So it's recommended to reset the crashkernel value if users have uninstalled

kexec-tools or using a custom kernel.

Reset using kdumpctl

--------------------

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 version>]`

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 has a standalone config file. User will have to reboot

the machine after this command to make it take effect.

Reset manually

--------------

To reset the crashkernel value manually, it's recommended to use utils like

`grubby`. A one liner script for resetting `crashkernel=` value of all installed

kernels to current boot kernel's  crashkernel.default` is:

	grubby --update-kernel ALL --args "$(cat /usr/lib/modules/$(uname -r)/crashkernel.default)"

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.