From 33a4198e1749515b6e8e64c4c91d17c8d977489d Mon Sep 17 00:00:00 2001 From: Frederick Grose Date: Sat, 21 Nov 2015 16:46:18 -0500 Subject: [PATCH] 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. --- dracut.cmdline.7.asc | 109 ++++++++++++++++++++++++++++++------------- 1 file changed, 77 insertions(+), 32 deletions(-) diff --git a/dracut.cmdline.7.asc b/dracut.cmdline.7.asc index 8c7e9654b..c2606c094 100644 --- 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:** 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:** 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:____:: Boots a live image retrieved from ____. 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=**____:: +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=**__:_(|auto)__ +**rd.live.overlay=**____:__(|auto)__|__none__:: Allow the usage of a permanent overlay. -__ specifies the path to a device with a mountable filesystem. -__ 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:____** option. +- __ specifies the path to a device with a mountable filesystem. +- __ 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:____** 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:____** opti rd.live.overlay=/dev/sdb1:persistent-overlay.img -- +**rd.live.overlay.size=**____:: +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 ~~~~~~~~~~~~~~~~~~~~ -- 2.47.2