Re: [PATCH v2] Doc: improve the kexec-kdump-howto.txt documentation

[Kairui Song]

On Mon, Mar 22, 2021 at 7:26 PM Lianbo Jiang <lijiang(a)redhat.com&gt; wrote:
>  Because there are some duplicated contents, this will remove the
>  infrequently used options descriptions from the "kexec-kdump-howto.txt",
>  only add the "KDUMP_COMMANDLINE_REMOVE" and
> "KDUMP_COMMANDLINE_APPEND".
>
>  Signed-off-by: Lianbo Jiang <lijiang(a)redhat.com&gt;
>  ---
>   kexec-kdump-howto.txt | 78 +++++++++++++++----------------------------
>   1 file changed, 27 insertions(+), 51 deletions(-)
>
>  diff --git a/kexec-kdump-howto.txt b/kexec-kdump-howto.txt
>  index 88af6078ae6e..d23dd24b3fc7 100644
>  --- a/kexec-kdump-howto.txt
>  +++ b/kexec-kdump-howto.txt
>  @@ -525,7 +525,7 @@ Advanced Setups
>   ===============
>
>   About /etc/sysconfig/kdump
>  -------------------------------
>  +--------------------------
>
>   Currently, there are a few options in /etc/sysconfig/kdump, which are
>   usually used to control the behavior of kdump kernel. Basically, all of
>  @@ -533,51 +533,29 @@ these options have default values, usually 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 option of kexec utility is used to inherit the kernel cmdline
>  +from the 1st kernel for kdump kernel. E.g specifying --command-line=
>  +"`cat /proc/cmdline`" or simply using '--reuse-cmdline'. Then only
> need
>  +modify KDUMP_COMMANDLINE_APPEND and KDUMP_COMMANDLINE_REMOVE in the
>  +/etc/sysconfig/kdump to adjust the kernel cmdline of kdump as expected. 
Hi Lianbo, I find this part of the document a bit confusing to me.

The "Usually option of kexec utility ..." doesn't sound right, maybe
just descript how this kexec-tools scripts works is good enough, and
no need to go through kexec binary details.

>  +
>  +For detailed description of each options, please refer to the file
>  +/etc/sysconfig/kdump directly.
>  +
>  +Kdump boot directory
>  +--------------------
>
>   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
>  +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
>  @@ -586,30 +564,28 @@ 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.
>  +this option to change kdump kernel command line. For example:
>
>  -For more kernel parameters, please refer to kernel document.
>  +KDUMP_COMMANDLINE_REMOVE="hugepages hugepagesz slub_debug quiet log_buf_len
> swiotlb"
>
>  --KDUMP_COMMANDLINE_APPEND
>  +For more kernel parameters, please refer to kernel document:
>  +Documentation/admin-guide/kernel-parameters.txt.
>  +
>  +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.
>  +furthermore, there may affect kdump kernel boot. For example:
>  +
>  +KDUMP_COMMANDLINE_APPEND="cgroup_disable=memory"
>
>   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.29.2
>  
Other parts looks good.

-- 
Best Regards,
Kairui Song