fix(man): further clarify live-image overlay types & RAM usage

Describe the separate overlay types, their specification, and
their RAM usage for a live SquashFS (read-only) base filesystem
image.

diff --git a/man/dracut.cmdline.7.asc b/man/dracut.cmdline.7.asc
index 858991fa93cc20f62812dc13efb7d19b505c99db..45f27deb54640d190c9002f2a51ac506d68003ba 100644 (file)
--- a/man/dracut.cmdline.7.asc
+++ b/man/dracut.cmdline.7.asc
@@ -1021,51 +1021,88 @@ Booting live images
 Dracut offers multiple options for live booted images:
 
 =====================
-SquashFS with read-only filesystem image::: The system will boot with a
-read-only filesystem from the SquashFS and apply a writable Device-mapper
-snapshot or an OverlayFS overlay mount for the read-only base filesystem.  This
-method ensures a relatively fast boot and lower RAM usage. Users **must be
-careful** to avoid writing too many blocks to a snapshot volume.  Once the
-blocks of the snapshot overlay are exhausted, the root filesystem becomes
-read-only and may cause application failures.  The snapshot overlay file is
-marked 'Overflow', and a difficult recovery is required to repair and enlarge
-the overlay offline.  Non-persistent overlays are sparse files in RAM that only
-consume content space as required blocks are allocated.  They default to an
-apparent size of 32 GiB in RAM.  The size can be adjusted with the
-**rd.live.overlay.size=** kernel command line option.
-+
-The filesystem structure is traditionally expected to be:
-+
+SquashFS (read-only) base filesystem image:::
+Note -- There are 3 separate overlay types available:
+- Device-mapper snapshots (the original offering),
+- Device-mapper thin provisioning snapshots (see *_rd.live.overlay.thin_*,
+a later offering), and
+- OverlayFS based overlay mounts (a more recent offering).
+
++
+--
+Using one of these technologies, the system will provide a writable overlay for
+the base, read-only SquashFS root filesystem. These methods enable a relatively
+fast boot and lower RAM usage.
+
+With the original Device-mapper snapshot overlay, users **must be careful** to
+avoid writing too many blocks to the snapshot device.  Once the blocks of the
+snapshot overlay are exhausted, the whole root filesystem becomes read-only
+leading to application failures.  The snapshot overlay device is marked
+'Overflow', and a difficult recovery is required to repair and enlarge the
+overlay offline.
+
+When *_rd.live.overlay=_* is not specified for persistent overlay storage, or
+the specified file is not found or writable, a Device-mapper snapshot based
+non-persistent or temporary overlay is automatically created as a sparse file
+in RAM of the initramfs.  This file will only consume content space as required
+blocks are allocated. This snapshot based overlay defaults to an apparent size
+of 32 GiB in RAM, and can be adjusted with the *_rd.live.overlay.size=_* kernel
+command line option.  This file is hidden (and appears deleted) when the boot
+process switches out of the initramfs to the main root filesystem but its loop
+device remains connected to the Device-mapper snapshot.
+
+Even with large Device-mapper overlay files for write space, the available root
+filesystem capacity is limited by the total allocated size of the base root
+filesystem, which often provide only a small number of gigabytes of free space.
+
+This shortage could be remedied by building the root filesystem with more
+allocated free space, or the OverlayFS based overlay mount method can be used.
+
+When the *_rd.live.overlay.overlayfs_* option is specified or when
+*_rd.live.overlay=_* points to an appropriate directory with a sister at
+`/../ovlwork`, then an OverlayFS based overlay mount is employed.  Such a
+persistent OverlayFS overlay can extend the available root filesystem storage
+up to the capacity of the LiveOS disk device.
+
+For non-persistent OverlayFS overlays, the `/run/overlayfs` directory in the
+`/run` tmpfs is used for temporary storage.  This filesystem is typically sized
+to one half of the RAM total in the system. +
+The command: `mount -o remount,size=<nbytes> /run` will resize this virtual
+filesystem after booting.
+
+The internal SquashFS structure is traditionally expected to be:
+
 [listing]
---
+----
 squashfs.img          |  SquashFS from LiveCD .iso
    !(mount)
    /LiveOS
-       |- rootfs.img  |  Filesystem image to mount read-only
+       |- rootfs.img  |  Usually a ext4 filesystem image to mount read-only
             !(mount)
-            /bin      |  Live filesystem
+            /bin      |  Base Live root filesystem
             /boot     |
             /dev      |
             ...       |
---
-+
-For OverlayFS mount overlays, the filesystem structure may also be a direct
+----
+
+For OverlayFS mount overlays, the internal SquashFS structure may be a direct
 compression of the root filesystem:
-+
+
 [listing]
---
+----
 squashfs.img          |  SquashFS from LiveCD .iso
    !(mount)
-   /bin               |  Live filesystem
+   /bin               |  Base Live root filesystem
    /boot              |
    /dev               |
    ...                |
---
-+
+----
+
 Dracut uses one of the overlay methods of live booting by default.  No
-additional command line options are required other than **root=live:<URL>** to
-specify the location of your squashed filesystem.
-+
+additional command line options are required other than
+**root=**live:__<path to blockdevice>__ or **root=**live:__<URL>__ to specify
+the location of your squashed root filesystem.
+
 - The compressed SquashFS image can be copied during boot to RAM at
 `/run/initramfs/squashed.img` by using the **rd.live.ram=1** option.
 - A device with a persistent overlay can be booted read-only by using the
@@ -1073,7 +1110,8 @@ specify the location of your squashed filesystem.
 either cause a temporary, writable overlay to be stacked over a read-only
 snapshot of the root filesystem or the OverlayFS mount will use an additional
 lower layer with the root filesystem.
-+
+--
+
 Uncompressed live filesystem image:::
 When the live system was installed with the '--skipcompress' option of the
 __livecd-iso-to-disk__ installation script for Live USB devices, the root
@@ -1162,22 +1200,29 @@ Copy the complete image to RAM and use this for booting. This is useful
 when the image resides on, e.g., a DVD which needs to be ejected later on.
 
 **rd.live.overlay={**__<devspec>__[:__{<pathspec>|auto}__]|__none__}::
-Manage the usage of a permanent overlay.
+Manage the usage of a persistent overlay.
 +
 --
-* _<devspec>_ specifies the path to a device with a mountable filesystem.
-* _<pathspec>_ is the path to a file within that filesystem, which shall be
-used to persist the changes made to the device specified by the
-**root=live:__<url>__** option.
-+
-The default _pathspec_, when _auto_ or no _:<pathspec>_ is given, is
-`/<rd.live.dir>/overlay-<label>-<uuid>`, where _<label>_ is the
-device LABEL, and _<uuid>_ is the device UUID.
-* _none_ (the word itself) specifies that no overlay will be used, such as when
-an uncompressed, writable live root filesystem is available.
-+
+* *_<devspec>_* specifies the path to a device with a mountable filesystem.
+* *_<pathspec>_* is a path within the *_<devspec>_* filesystem to either
+** a file (that is loop mounted for a Device-mapper overlay) or
+** a directory (that is symbolically linked to `/run/overlayfs` for a OverlayFS
+mount overlay). (A required sister directory `/<pathspec>/../ovlwork` is
+automatically made.)
+* *_none_* (the word itself) specifies that no overlay will be used, such as
+when an uncompressed, writable live root filesystem is available.
+
+The above method shall be used to persist the changes made to the root
+filesystem specified within the +
+**root=**live:__<path to blockdevice>__ or **root=**live:__<url>__ device.
+
+The default *_pathspec_*, when *:auto* or
+no **:__<pathspec>__** is given, is `/<rd.live.dir>/overlay-<label>-<uuid>`,
+where _<label>_ and _<uuid>_ are the LABEL and UUID of the filesystem specified
+by the **root=**live:__<path|url>__ device.
+
 If a persistent overlay __is detected__ at the standard LiveOS path,
-and rd.live.overlay.overlayfs is not set to 1, the overlay type (either
+and *_rd.live.overlay.overlayfs_* is not set to 1, the overlay type (either
 Device-mapper or OverlayFS) will be detected and it will be used.
 --
 +
@@ -1197,15 +1242,16 @@ Specifies a non-persistent Device-mapper overlay size in MiB.  The default is
 _32768_.
 
 **rd.live.overlay.readonly=**1::
-This is used to boot with a normally read-write persistent overlay in a
-read-only mode.  With this option, either an additional, non-persistent,
-writable snapshot overlay will be stacked over a read-only snapshot,
-`/dev/mapper/live‑ro`, of the base filesystem with the persistent overlay, or a
-read-only loop device, in the case of a writable __rootfs.img__, or an OverlayFS
-mount will use the persistent overlay directory linked at `/run/overlayfs‑r` as
-an additional lower layer along with the base root filesystem and apply a
-transient, writable upper directory overlay, in order to complete the booted
-root filesystem.
+This is used to boot in a read-only mode with a normally read-write persistent
+overlay.  With this option,
+* Device-mapper overlays will have an additional, non-persistent, writable
+snapshot overlay stacked over a read-only snapshot (`/dev/mapper/live‑ro`)
+of the base root filesystem and the persistent overlay, or
+* for writable `rootfs.img` images, the above over a read-only loop device, or
+* an OverlayFS mount will link the persistent overlay directory at
+`/run/overlayfs‑r` as an additional read-only lower layer stacked over the base
+root filesystem, and `/run/overlayfs` becomes the temporary, writable, upper
+directory overlay, to complete the bootable root filesystem.
 
 **rd.live.overlay.reset=**1::
 Specifies that a persistent overlay should be reset on boot.  All previous root
@@ -1223,15 +1269,15 @@ Enables the use of the *OverlayFS* kernel module, if available, to provide a
 copy-on-write union directory for the root filesystem.  OverlayFS overlays are
 directories of the files that have changed on the read-only base (lower)
 filesystem.  The root filesystem is provided through a special overlay type
-mount that merges the lower and upper directories.  If an OverlayFS upper
-directory is not present on the boot device, a tmpfs directory will be created
-at `/run/overlayfs` to provide temporary storage.  Persistent storage can be
-provided on vfat or msdos formatted devices by supplying the OverlayFS upper
-directory within an embedded filesystem that supports the creation of trusted.*
-extended attributes and provides a valid d_type in readdir responses, such as
-with ext4 and xfs.  On non-vfat-formatted devices, a persistent OverlayFS
-overlay can extend the available root filesystem storage up to the capacity of
-the LiveOS disk device.
+mount that merges at least two directories, designated the lower and the upper.
+If an OverlayFS upper directory is not present on the boot device, a tmpfs
+directory will be created at `/run/overlayfs` to provide temporary storage.
+Persistent storage can be provided on vfat or msdos formatted devices by
+supplying the OverlayFS upper directory within an embedded filesystem that
+supports the creation of trusted.* extended attributes and provides a valid
+d_type in readdir responses, such as with btrfs, ext4, f2fs, & xfs.  On
+non-vfat-formatted devices, a persistent OverlayFS overlay can extend the
+available root filesystem storage up to the capacity of the LiveOS disk device.
 +
 The **rd.live.overlay.readonly** option, which allows a persistent overlayfs to
 be mounted read-only through a higher level transient overlay directory, has