[PATCH v2] Doc: Improve the kdump sysconfig document

[Lianbo Jiang]

Currently, the kdump sysconfig document is missed, let's add it to
the kexec-kdump-howto.txt as a document in order to help users better
understand these options in the /etc/sysconfig/kdump.

Signed-off-by: Lianbo Jiang <lijiang(a)redhat.com&gt;
---
 kexec-kdump-howto.txt | 84 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 79 insertions(+), 5 deletions(-)

diff --git a/kexec-kdump-howto.txt b/kexec-kdump-howto.txt
index 447bc5447886..3a58d8a0ffe1 100644
--- a/kexec-kdump-howto.txt
+++ b/kexec-kdump-howto.txt
@@ -524,17 +524,91 @@ to send over the necessary ssh key file. Restart the kdump service
via
 Advanced Setups
 ===============
 
-Kdump boot directory
---------------------
+About the /etc/sysconfig/kdump
+------------------------------
+
+Currently, there are a few options in the /etc/sysconfig/kdump, which are
+usually used to control the behavior of kdump kernel. Basically, all of
+these options have default values, most time we do not need to change them,
+but sometimes, we may modify them in order to better control the behavior
+of kdump kernel such as debug, etc.
+
+-KDUMP_BOOTDIR
 
 Usually kdump kernel is the same as 1st kernel. So kdump will try to find
 kdump kernel under /boot according to /proc/cmdline. E.g we execute below
 command and get an output:
 	cat /proc/cmdline
 	BOOT_IMAGE=/xxx/vmlinuz-3.yyy.zzz  root=xxxx .....
-Then kdump kernel will be /boot/xxx/vmlinuz-3.yyy.zzz.
-However a variable KDUMP_BOOTDIR in /etc/sysconfig/kdump is provided to
-user if kdump kernel is put in a different directory.
+
+Then kdump kernel will be /boot/xxx/vmlinuz-3.yyy.zzz. However, this option
+is provided to user if kdump kernel is put in a different directory.
+
+-KDUMP_IMG
+
+This represents the image type used for kdump. The default value is "vmlinuz".
+
+-KDUMP_IMG_EXT
+
+This represents the images extension. Relocatable kernels don't have one.
+Currently, it is a null string by default.
+
+-KEXEC_ARGS
+
+Any additional kexec arguments required. For example:
+KEXEC_ARGS="--elf32-core-headers".
+
+In most situations, this should be left empty. But, sometimes we hope to get
+additional kexec loading debugging information, we can add the '-d' option
+for the debugging.
+
+-KDUMP_KERNELVER
+
+This is a kernel version string for the kdump kernel. If the version is not
+specified, the init script will try to find a kdump kernel with the same
+version number as the running kernel.
+
+-KDUMP_COMMANDLINE
+
+The value of 'KDUMP_COMMANDLINE' will be passed to kdump kernel as command
+line parameters, this will likely match the contents of the grub kernel line.
+
+In general, if a command line is not specified, which means that it is a null
+string such as KDUMP_COMMANDLINE="", the default will be taken automatically
+from the '/proc/cmdline'.
+
+-KDUMP_COMMANDLINE_REMOVE
+
+This option allows us to remove arguments from the current kdump command line.
+If we don't specify any parameters for the KDUMP_COMMANDLINE, it will inherit
+all values from the '/proc/cmdline', which is not expected. As you know, some
+default kernel parameters could affect kdump, furthermore, that could cause
+the failure of kdump kernel boot.
+
+In addition, the option is also helpful to debug the kdump kernel, we can use
+this option to change kdump kernel command line.
+
+For more kernel parameters, please refer to kernel document.
+
+-KDUMP_COMMANDLINE_APPEND
+
+This option allows us to append arguments to the current kdump command line
+after processed by the KDUMP_COMMANDLINE_REMOVE. For kdump kernel, some
+specific modules require to be disabled like the mce, cgroup, numa, hest_disable,
+etc. Those modules may waste memory or kdump kernel doesn't need them,
+furthermore, there may affect kdump kernel boot.
+
+Just like above option, it can be used to disable or enable some kernel
+modules so that we can exclude any errors for kdump kernel, this is very
+meaningful for debugging.
+
+-KDUMP_STDLOGLVL | KDUMP_SYSLOGLVL | KDUMP_KMSGLOGLVL
+
+These variables are used to control the kdump log level in the first kernel.
+In the second kernel, kdump will use the rd.kdumploglvl option to set the log
+level in the above KDUMP_COMMANDLINE_APPEND.
+
+Logging levels: no logging(0), error(1), warn(2), info(3), debug(4)
 
 Kdump Post-Capture Executable
 -----------------------------
-- 
2.17.1

[Kairui Song]

On Wed, Dec 30, 2020 at 3:08 PM Lianbo Jiang <lijiang(a)redhat.com&gt; wrote:
>  Currently, the kdump sysconfig document is missed, let's add it to
>  the kexec-kdump-howto.txt as a document in order to help users better
>  understand these options in the /etc/sysconfig/kdump.
>
>  Signed-off-by: Lianbo Jiang <lijiang(a)redhat.com&gt;
>  ---
>   kexec-kdump-howto.txt | 84 ++++++++++++++++++++++++++++++++++++++++---
>   1 file changed, 79 insertions(+), 5 deletions(-)
>
>  diff --git a/kexec-kdump-howto.txt b/kexec-kdump-howto.txt
>  index 447bc5447886..3a58d8a0ffe1 100644
>  --- a/kexec-kdump-howto.txt
>  +++ b/kexec-kdump-howto.txt
>  @@ -524,17 +524,91 @@ to send over the necessary ssh key file. Restart the kdump service
> via
>   Advanced Setups
>   ===============
>
>  -Kdump boot directory
>  ---------------------
>  +About the /etc/sysconfig/kdump
>  +------------------------------
>  +
>  +Currently, there are a few options in the /etc/sysconfig/kdump, which are
>  +usually used to control the behavior of kdump kernel. Basically, all of
>  +these options have default values, most time we do not need to change them,
>  +but sometimes, we may modify them in order to better control the behavior
>  +of kdump kernel such as debug, etc.
>  +
>  +-KDUMP_BOOTDIR
>
>   Usually kdump kernel is the same as 1st kernel. So kdump will try to find
>   kdump kernel under /boot according to /proc/cmdline. E.g we execute below
>   command and get an output:
>          cat /proc/cmdline
>          BOOT_IMAGE=/xxx/vmlinuz-3.yyy.zzz  root=xxxx .....
>  -Then kdump kernel will be /boot/xxx/vmlinuz-3.yyy.zzz.
>  -However a variable KDUMP_BOOTDIR in /etc/sysconfig/kdump is provided to
>  -user if kdump kernel is put in a different directory.
>  +
>  +Then kdump kernel will be /boot/xxx/vmlinuz-3.yyy.zzz. However, this option
>  +is provided to user if kdump kernel is put in a different directory.
>  +
>  +-KDUMP_IMG
>  +
>  +This represents the image type used for kdump. The default value is
> "vmlinuz".
>  +
>  +-KDUMP_IMG_EXT
>  +
>  +This represents the images extension. Relocatable kernels don't have one.
>  +Currently, it is a null string by default.
>  +
>  +-KEXEC_ARGS
>  +
>  +Any additional kexec arguments required. For example:
>  +KEXEC_ARGS="--elf32-core-headers".
>  +
>  +In most situations, this should be left empty. But, sometimes we hope to get
>  +additional kexec loading debugging information, we can add the '-d' option
>  +for the debugging.
>  +
>  +-KDUMP_KERNELVER
>  +
>  +This is a kernel version string for the kdump kernel. If the version is not
>  +specified, the init script will try to find a kdump kernel with the same
>  +version number as the running kernel.
>  +
>  +-KDUMP_COMMANDLINE
>  +
>  +The value of 'KDUMP_COMMANDLINE' will be passed to kdump kernel as command
>  +line parameters, this will likely match the contents of the grub kernel line.
>  +
>  +In general, if a command line is not specified, which means that it is a null
>  +string such as KDUMP_COMMANDLINE="", the default will be taken automatically
>  +from the '/proc/cmdline'.
>  +
>  +-KDUMP_COMMANDLINE_REMOVE
>  +
>  +This option allows us to remove arguments from the current kdump command line.
>  +If we don't specify any parameters for the KDUMP_COMMANDLINE, it will inherit
>  +all values from the '/proc/cmdline', which is not expected. As you know, some
>  +default kernel parameters could affect kdump, furthermore, that could cause
>  +the failure of kdump kernel boot.
>  +
>  +In addition, the option is also helpful to debug the kdump kernel, we can use
>  +this option to change kdump kernel command line.
>  +
>  +For more kernel parameters, please refer to kernel document.
>  +
>  +-KDUMP_COMMANDLINE_APPEND
>  +
>  +This option allows us to append arguments to the current kdump command line
>  +after processed by the KDUMP_COMMANDLINE_REMOVE. For kdump kernel, some
>  +specific modules require to be disabled like the mce, cgroup, numa, hest_disable,
>  +etc. Those modules may waste memory or kdump kernel doesn't need them,
>  +furthermore, there may affect kdump kernel boot.
>  +
>  +Just like above option, it can be used to disable or enable some kernel
>  +modules so that we can exclude any errors for kdump kernel, this is very
>  +meaningful for debugging.
>  +
>  +-KDUMP_STDLOGLVL | KDUMP_SYSLOGLVL | KDUMP_KMSGLOGLVL
>  +
>  +These variables are used to control the kdump log level in the first kernel.
>  +In the second kernel, kdump will use the rd.kdumploglvl option to set the log
>  +level in the above KDUMP_COMMANDLINE_APPEND.
>  +
>  +Logging levels: no logging(0), error(1), warn(2), info(3), debug(4)
>
>   Kdump Post-Capture Executable
>   -----------------------------
>  --
>  2.17.1
>  
Acked-by: Kairui Song <kasong(a)redhat.com&gt;

-- 
Best Regards,
Kairui Song

[piliu]

On 12/30/20 3:08 PM, Lianbo Jiang wrote:
>  Currently, the kdump sysconfig document is missed, let's add it
> to
>  the kexec-kdump-howto.txt as a document in order to help users better
>  understand these options in the /etc/sysconfig/kdump.
>  
>  Signed-off-by: Lianbo Jiang <lijiang(a)redhat.com&gt;
>  ---
>    kexec-kdump-howto.txt | 84 ++++++++++++++++++++++++++++++++++++++++---
>    1 file changed, 79 insertions(+), 5 deletions(-)
>  
>  diff --git a/kexec-kdump-howto.txt b/kexec-kdump-howto.txt
>  index 447bc5447886..3a58d8a0ffe1 100644
>  --- a/kexec-kdump-howto.txt
>  +++ b/kexec-kdump-howto.txt
>  @@ -524,17 +524,91 @@ to send over the necessary ssh key file. Restart the kdump service
> via
>    Advanced Setups
>    ===============
>    
>  -Kdump boot directory
>  ---------------------
>  +About the /etc/sysconfig/kdump
>  +------------------------------
>  +
>  +Currently, there are a few options in the /etc/sysconfig/kdump, which are
>  +usually used to control the behavior of kdump kernel. Basically, all of
>  +these options have default values, most time we do not need to change them,
>  +but sometimes, we may modify them in order to better control the behavior
>  +of kdump kernel such as debug, etc.
>  +
>  +-KDUMP_BOOTDIR
>    
>    Usually kdump kernel is the same as 1st kernel. So kdump will try to find
>    kdump kernel under /boot according to /proc/cmdline. E.g we execute below
>    command and get an output:
>    	cat /proc/cmdline
>    	BOOT_IMAGE=/xxx/vmlinuz-3.yyy.zzz  root=xxxx .....
>  -Then kdump kernel will be /boot/xxx/vmlinuz-3.yyy.zzz.
>  -However a variable KDUMP_BOOTDIR in /etc/sysconfig/kdump is provided to
>  -user if kdump kernel is put in a different directory.
>  +
>  +Then kdump kernel will be /boot/xxx/vmlinuz-3.yyy.zzz. However, this option
>  +is provided to user if kdump kernel is put in a different directory.
>  +
>  +-KDUMP_IMG
>  +
>  +This represents the image type used for kdump. The default value is
> "vmlinuz".
>  +
>  +-KDUMP_IMG_EXT
>  +
>  +This represents the images extension. Relocatable kernels don't have one.
>  +Currently, it is a null string by default.
>  +
>  +-KEXEC_ARGS
>  +
>  +Any additional kexec arguments required. For example:
>  +KEXEC_ARGS="--elf32-core-headers".
>  +
>  +In most situations, this should be left empty. But, sometimes we hope to get
>  +additional kexec loading debugging information, we can add the '-d' option
>  +for the debugging.
>  +
>  +-KDUMP_KERNELVER
>  +
>  +This is a kernel version string for the kdump kernel. If the version is not
>  +specified, the init script will try to find a kdump kernel with the same
>  +version number as the running kernel.
>  +
>  +-KDUMP_COMMANDLINE
>  +
>  +The value of 'KDUMP_COMMANDLINE' will be passed to kdump kernel as command
>  +line parameters, this will likely match the contents of the grub kernel line.
>  +
>  +In general, if a command line is not specified, which means that it is a null
>  +string such as KDUMP_COMMANDLINE="", the default will be taken automatically
>  +from the '/proc/cmdline'.
>  +
>  +-KDUMP_COMMANDLINE_REMOVE
>  +
>  +This option allows us to remove arguments from the current kdump command line.
>  +If we don't specify any parameters for the KDUMP_COMMANDLINE, it will inherit
>  +all values from the '/proc/cmdline', which is not expected. As you know, some
>  +default kernel parameters could affect kdump, furthermore, that could cause
>  +the failure of kdump kernel boot.
>  +
>  +In addition, the option is also helpful to debug the kdump kernel, we can use
>  +this option to change kdump kernel command line.
>  +
>  +For more kernel parameters, please refer to kernel document.
>  +
>  +-KDUMP_COMMANDLINE_APPEND
>  +
>  +This option allows us to append arguments to the current kdump command line
>  +after processed by the KDUMP_COMMANDLINE_REMOVE. For kdump kernel, some
>  +specific modules require to be disabled like the mce, cgroup, numa, hest_disable,
>  +etc. Those modules may waste memory or kdump kernel doesn't need them,
>  +furthermore, there may affect kdump kernel boot.
>  +
>  +Just like above option, it can be used to disable or enable some kernel
>  +modules so that we can exclude any errors for kdump kernel, this is very
>  +meaningful for debugging.
>  +
>  +-KDUMP_STDLOGLVL | KDUMP_SYSLOGLVL | KDUMP_KMSGLOGLVL
>  +
>  +These variables are used to control the kdump log level in the first kernel.
>  +In the second kernel, kdump will use the rd.kdumploglvl option to set the log
>  +level in the above KDUMP_COMMANDLINE_APPEND.
>  +
>  +Logging levels: no logging(0), error(1), warn(2), info(3), debug(4)
>    
>    Kdump Post-Capture Executable
>    -----------------------------
>   
Acked-by: Pingfan Liu <piliu(a)redhat.com&gt;