dracut.cmdline: Update Booting live images section

Add descriptions for the rd.live.overlay.readonly,
rd.live.overlay.size, rd.live.overlay.reset,
rd.live.squashimg, and rd.live.overlay=none options.
Mention the Invalid mark on exhausted overlays.
Clarify the rd.writable.fsimg option.
Repunctuate the rd.live.overlay.thin option description.

diff --git a/dracut.cmdline.7.asc b/dracut.cmdline.7.asc
index 8c7e9654bb44b165ab52ce06fbb6a663381ff3d3..c2606c094d40a71317cb2c42cc7c043025b4dd28 100644 (file)
--- a/dracut.cmdline.7.asc
+++ b/dracut.cmdline.7.asc
@@ -774,18 +774,21 @@ 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
+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
 over the read only filesystem.  Using this method ensures a relatively fast
 boot and lower RAM usage. Users **must be careful** to avoid writing too many
-blocks to the snapshot volume.  Once the blocks of the snapshot are exhaused,
-the live filesystem becomes unusable and requires a reboot.
+blocks to the snapshot volume.  Once the blocks of the snapshot overlay are
+exhausted, the root filesystem becomes unusable and requires a reboot.  A
+persistent overlay is marked Invalid, and requires a difficult recovery.
+Non-persistent overlays default to 512 MiB in RAM, but the size can be adjusted
+with the **rd.live.overlay.size=** kernel command line option.
 +
 The filesystem structure is expected to be:
 +
 [listing]
 --
-squashfs.img          |  Squashfs downloaded via network
+squashfs.img          |  Squashfs from LiveCD .iso downloaded via network
    !(mount)
    /LiveOS
        |- ext3fs.img  |  Filesystem image to mount read-only
@@ -800,11 +803,34 @@ Dracut uses this method 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.
 +
-writable filesystem image::: The system will retrieve a compressed filesystem
-image, connect it to a loopback device, and mount it as a writable volume.  More
-RAM is required during boot but the live filesystem is easier to manage if it
-becomes full.  Users can make a filesystem image of any size and that size will
-be maintained when the system boots.
+- 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
+**rd.live.overlay.readonly** option on the kernel command line.  This will
+cause a temporary, writable overlay to be stacked over a read-only snapshot
+of 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
+filesystem image, `ext3fs.img`, is expanded on installation and no SquashFS
+is involved during boot.
++
+- If **rd.live.ram=1** is used in this situation, the full, uncompressed
+root filesystem is copied during boot to `/run/initramfs/rootfs.img` in the
+`/run` tmpfs.
++
+- If **rd.live.overlay=none** is provided as a kernel command line option,
+a writable, linear device-mapper target is created on boot with no overlay.
+
+writable filesystem image:::
+The system will retrieve a compressed filesystem image, extract it to
+`/run/initramfs/fsimg/rootfs.img`, connect it to a loop device, create a
+writable, linear device-mapper target at `/dev/mapper/live-rw`, and mount that
+as a writable volume at `/`.  More RAM is required during boot but the live
+filesystem is easier to manage if it becomes full.  Users can make a filesystem
+image of any size and that size will be maintained when the system boots. There
+is no persistence of root filesystem changes between boots with this option.
 +
 The filesystem structure is expected to be:
 +
@@ -812,7 +838,7 @@ The filesystem structure is expected to be:
 --
 rootfs.tgz            |  Compressed tarball containing fileystem image
    !(unpack)
-   /rootfs.img        |  Filesystem image
+   /rootfs.img        |  Filesystem image at /run/initramfs/fsimg/
       !(mount)
       /bin            |  Live filesystem
       /boot           |
@@ -820,11 +846,23 @@ rootfs.tgz            |  Compressed tarball containing fileystem image
       ...             |
 --
 +
-To use this boot option, ensure that **rd.writable_fsimg=1** is in your kernel
+To use this boot option, ensure that **rd.writable.fsimg=1** is in your kernel
 command line and add the **root=live:<URL>** to specify the location
-of your compressed filesystem image tarball.
+of your compressed filesystem image tarball or SquashFS image.
 =====================
 
+**rd.writable.fsimg=**1::
+Enables writable filesystem support.  The system will boot with a fully
+writable (but non-persistent) filesystem without snapshots __(see notes above
+about available live boot options)__.  You can use the **rootflags** option to
+set mount options for the live filesystem as well __(see documentation about
+rootflags in the **Standard** section above)__.
+This implies that the whole image is copied to RAM before the boot continues.
++
+NOTE: There must be enough free RAM available to hold the complete image.
++
+This method is very suitable for diskless boots.
+
 **root=**live:__<url>__::
 Boots a live image retrieved from __<url>__.  Valid handlers: __http, https, ftp, torrent, tftp__.
 +
@@ -843,15 +881,22 @@ Enables debug output from the live boot process.
 Specifies the directory within the squashfs where the ext3fs.img or rootfs.img
 can be found.  By default, this is __LiveOS__.
 
+**rd.live.squashimg=**__<filename of SquashFS image>__::
+Specifies the filename for a SquashFS image of the root filesystem.
+By default, this is __squashfs.img__.
+
 **rd.live.ram=**1::
 Copy the complete image to RAM and use this for booting. This is useful
-when the image resides on i.e. a DVD which needs to be ejected later on.
+when the image resides on, i.e., a DVD which needs to be ejected later on.
 
-**rd.live.overlay=**_<devspec>_:_(<pathspec>|auto)__
+**rd.live.overlay=**__<devspec>__:__(<pathspec>|auto)__|__none__::
 Allow the usage of a permanent 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 **root=live:__<url>__** option.
+- _<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.
+- _none_ specifies no overlay when an uncompressed live root filesystem is
+available.
 +
 [listing]
 .Example
@@ -859,24 +904,24 @@ persist the changes made to the device specified by **root=live:__<url>__** opti
 rd.live.overlay=/dev/sdb1:persistent-overlay.img
 --
 
+**rd.live.overlay.size=**__<size_MiB>__::
+Specifies a non-persistent overlay size in MiB.  The default is _512_.
+
+**rd.live.overlay.readonly=**1::
+Specifies a non-persistent, writable snapshot overlay to be stacked over a
+read-only snapshot of the root filesystem, `/dev/mapper/live-ro`.
+
+**rd.live.overlay.reset=**1::
+Specifies that a persistent overlay should be reset on boot.  All root
+filesystem changes are vacated by this action.
+
 **rd.live.overlay.thin=**1::
 Enables the usage of thin snapshots instead of classic dm snapshots.
-The advantage of thin snapshots is, that they support discards, and will free
-blocks which are not claimed by the filesystem. In this use case this means,
-that memory is given back to the kernel, when the filesystem does not claim it
+The advantage of thin snapshots is that they support discards, and will free
+blocks that are not claimed by the filesystem. In this use case, this means
+that memory is given back to the kernel when the filesystem does not claim it
 anymore.
 
-**rd.writable.fsimg=**1::
-Enables writable filesystem support.  The system will boot with a fully 
-writable filesystem without snapshots __(see notes above about available live boot options)__.
-You can use the **rootflags** option to set mount options for the live
-filesystem as well __(see documentation about rootflags in the **Standard** section above)__.
-This implies that the whole image is copied to RAM before the boot continues.
-+
-NOTE: There must be enough free RAM available to hold the complete image.
-+
-This method is very suitable for diskless boots.
-
 
 Plymouth Boot Splash
 ~~~~~~~~~~~~~~~~~~~~