10:54 a.m.
Signed-off-by: Kairui Song <kasong(a)redhat.com>
---
kexec-kdump-howto.txt | 195 +++++++++++++++++++++++++++---------------
1 file changed, 127 insertions(+), 68 deletions(-)
diff --git a/kexec-kdump-howto.txt b/kexec-kdump-howto.txt
index 0d2b6cb..06dfbcf 100644
--- a/kexec-kdump-howto.txt
+++ b/kexec-kdump-howto.txt
@@ -283,11 +283,8 @@ to initate the dump and then click "Restart blade with
NMI". This issues a
system reset and invokes xmon debugger.
-Advanced Setups
-===============
-
Dump targets
-------------
+============
In addition to being able to capture a vmcore to your system's local file
system, kdump can be configured to capture a vmcore to a number of other
@@ -295,7 +292,8 @@ locations, including a raw disk partition, a dedicated file system, an
NFS
mounted file system, or a remote system via ssh/scp. Additional options
exist for specifying the relative path under which the dump is captured,
what to do if the capture fails, and for compressing and filtering the dump
-(so as to produce smaller, more manageable, vmcore files).
+(so as to produce smaller, more manageable, vmcore files, see "Advanced
Setups"
+for more detail on these options).
In theory, dumping to a location other than the local file system should be
safer than kdump's default setup, as its possible the default setup will try
@@ -308,31 +306,131 @@ as allowing for the centralization of vmcore files, should you have
several
systems from which you'd like to obtain vmcore files. Of course, note that
these configurations could present problems if your network is unreliable.
-Advanced setups are configured via modifications to /etc/kdump.conf,
-which out of the box, is fairly well documented itself. Any alterations to
-/etc/kdump.conf should be followed by a restart of the kdump service, so
-the changes can be incorporated in the kdump initrd. Restarting the kdump
-service is as simple as '/sbin/systemctl restart kdump.service'.
-
-Note that kdump.conf is used as a configuration mechanism for capturing dump
-files from the initramfs (in the interests of safety), the root file system is
-mounted, and the init process is started, only as a last resort if the
-initramfs fails to capture the vmcore. As such, configuration made in
-/etc/kdump.conf is only applicable to capture recorded in the initramfs. If
-for any reason the init process is started on the root file system, only a
-simple copying of the vmcore from /proc/vmcore to /var/crash/$DATE/vmcore will
-be preformed.
-
-For both local filesystem and nfs dump the dump target must be mounted before
-building kdump initramfs. That means one needs to put an entry for the dump
-file system in /etc/fstab so that after reboot when kdump service starts,
-it can find the dump target and build initramfs instead of failing.
+Kdump target and advanced setups are configured via modifications to
+/etc/kdump.conf, which out of the box, is fairly well documented itself.
+Any alterations to /etc/kdump.conf should be followed by a restart of the
+kdump service, so the changes can be incorporated in the kdump initrd.
+Restarting the kdump service is as simple as '/sbin/systemctl restart
kdump.service'.
+
+There are two ways to config the dump target, config dump target only
+using "path", and config dump target explicitely. Interpretation of
"path"
+also differs in two config styples.
+
+Config dump target only using "path"
+------------------------------------
+
+You can change the dump target by setting "path" to a mount point where
+dump target is mounted. When there is no explicitly configured dump target,
+"path" in kdump.conf represents the current file system path in which vmcore
+will be saved. Kdump will automatically detect the underlying device of
+"path" and use that as the dump target.
+
+In fact, upon dump, kdump creates a directory $hostip-$date with-in "path"
+and saves vmcore there. So practically dump is saved in $path/$hostip-$date/.
+
+Kdump will only check current mount status for mount entry corresponding to
+"path". So please ensure the dump target is mounted on "path" before
kdump
+service starts.
+
+NOTES:
+
+- It's strongly recommanded to put an mount entry for "path" in /etc/fstab
+ and have it auto mounted on boot. This make sure the dump target is
+ reachable from the machine and kdump's configuration is stable.
+
+EXAMPLES:
+
+- path /var/crash/
+
+ This is the default configuration. Assuming there is no disk mounted
+ on /var/ or on /var/crash, dump will be saved on disk backing rootfs
+ in directory /var/crash.
+
+- path /var/crash/ (A separate disk mounted on /var/crash)
+
+ Say a disk /dev/sdb is mounted on /var. In this case dump target will
+ become /dev/sdb and path will become "/" and dump will be saved
+ on "sdb:/var/crash/" directory.
+
+- path /var/crash/ (NFS mounted on /var)
+
+ Say foo.com:/export/tmp is mounted on /var. In this case dump target is
+ nfs server and path will be adjusted to "/crash" and dump will be saved to
+ foo.com:/export/tmp/crash/ directory.
+
+Config dump target explicitely
+------------------------------
+
+You can set the dump target explicitly in kdump.conf, and "path" will be
+the relative path in the specified dump target. For example, if dump
+target is "ext4 /dev/sda", then dump will be saved in "path"
directory
+on /dev/sda.
+
+Same is the case for nfs dump. If user specified "nfs foo.com:/export/tmp/"
+as dump target, then dump will effectively be saved in
+"foo.com:/export/tmp/var/crash/" directory.
+
+If the dump target is "raw", then "path" is ignored.
+
+If it's a filesystemd target, kdump will need to know the right mount option.
+Kdump will check current mount status, and then /etc/fstab for mount options
+corresponding to the specified dump target and use it. If there are
+special mount option required for the dump target, it could be set by put
+an entry in fstab.
+
+If there are no related mount entry, mount option is set to "defaults".
+
+NOTES:
+
+- It's recommended to put an entry for the dump target in /etc/fstab
+ and have it auto mounted on boot. This make sure the dump target is
+ reachable from the machine and kdump won't fail.
+
+- Kdump ignores some mount options, including "noauto", "ro". This
+ make it possible to keep the dump target unmounted or read-only
+ when not used.
+
+EXAMPLES:
+
+- ext4 /dev/sda (mounted)
+ path /var/crash/
+
+ In this case dump target is set to /dev/sdb, path is the absolute path
+ "/var/crash" in /dev/sda, vmcore path will saved on
+ "sda:/var/crash" directory.
+
+- nfs foo.com:/export/tmp (mounted)
+ path /var/crash/
+
+ In this case dump target is nfs server, path is the absolute path
+ "/var/crash", vmcore path will saved on
"foo.com:/export/tmp/crash/" directory.
+
+- nfs foo.com:/export/tmp (not mounted)
+ path /var/crash/
+
+ Same with above case, kdump will use "defaults" as the mount option
+ for the dump target.
+
+- nfs foo.com:/export/tmp (not mounted, entry with option "noauto,nolock"
exists in /etc/fstab)
+ path /var/crash/
+
+ In this case dump target is nfs server, vmcore path will saved on
+ "foo.com:/export/tmp/crash/" directory, and kdump will inherit
"nolock" option.
+
+Dump target and mkdumprd
+------------------------
+
+MKdumprd is the tool used to create kdump initramfs, and it may change
+the mount status of the dump target in some condition.
+
Usually the dump target should be used only for kdump. If you worry about
someone uses the filesystem for something else other than dumping vmcore
-you can mount it as read-only. Mkdumprd will still remount it as read-write
-for creating dump directory and will move it back to read-only afterwards.
+you can mount it as read-only or make it a noauto mount. Mkdumprd will
+mount/remount it as read-write for creating dump directory and will
+move it back to it's original state afterwards.
-Followings are the available config options for dump targets.
+Supported dump target types and requirements
+--------------------------------------------
1) Raw partition
@@ -423,47 +521,8 @@ you've connected to it, and then input the target system
user's password
to send over the necessary ssh key file. Restart the kdump service via
'/sbin/systemctl restart kdump.service' to commit this change to your kdump
initrd.
-Path
-----
-
-"path" represents the file system path in which vmcore will be saved. In
-fact kdump creates a directory $hostip-$date with-in "path" and saves
-vmcore there. So practically dump is saved in $path/$hostip-$date/. To
-simplify discussion further, if we say dump will be saved in $path, it
-is implied that kdump will create another directory inside path and
-save vmcore there.
-
-If a dump target is specified in kdump.conf, then "path" is relative to the
-specified dump target. For example, if dump target is "ext4 /dev/sda", then
-dump will be saved in "$path" directory on /dev/sda.
-
-Same is the case for nfs dump. If user specified "nfs foo.com:/export/tmp/"
-as dump target, then dump will effectively be saved in
-"foo.com:/export/tmp/var/crash/" directory.
-
-Interpretation of path changes a bit if user has not specified a dump
-target explicitly in kdump.conf. In this case, "path" represents the
-absolute path from root. And dump target and adjusted path are arrived
-at automatically depending on what's mounted in the current system.
-
-Following are few examples.
-
-- path /var/crash/
-
- Assuming there is no disk mounted on /var/ or on /var/crash, dump will
- be saved on disk backing rootfs in directory /var/crash.
-
-- path /var/crash/ (A separate disk mounted on /var)
-
- Say a disk /dev/sdb is mouted on /var. In this case dump target will
- become /dev/sdb and path will become "/crash" and dump will be saved
- on "sdb:/crash/" directory.
-
-- path /var/crash/ (NFS mounted on /var)
-
- Say foo.com:/export/tmp is mounted on /var. In this case dump target is
- nfs server and path will be adjusted to "/crash" and dump will be saved to
- foo.com:/export/tmp/crash/ directory.
+Advanced Setups
+===============
Kdump boot directory
--------------------
--
2.26.2