commit f7211d501d7b8c81946c2cb685d8ee61a1c40ada
Date: Tue Mar 19 18:44:37 2013 -0400
Correct misleading information on the overlay, syncronize usage
statements with documentation in livecd-iso-to-disk.pod
diff --git a/tools/livecd-iso-to-disk.sh b/tools/livecd-iso-to-disk.sh
index 1a87869..8a4caa0 100755
--- a/tools/livecd-iso-to-disk.sh
+++ b/tools/livecd-iso-to-disk.sh
@@ -55,8 +55,8 @@ usage() {
such as from a CD-ROM, DVD, or download. It could also be the
device node reference for the mount point of another LiveOS
filesystem, including the currently-running one (such as a
- booted Live CD/DVD/USB, where /dev/live references the running
- image device).
+ booted Live CD/DVD/USB, where /run/initramfs/livedev
+ references the booted device).
<target device>
This should be the device partition name for the attached,
@@ -81,8 +81,8 @@ usage() {
running LiveOS image, the device node reference for an attached device with
an installed LiveOS image, or a file backed by a block device with an
installed LiveOS image. If the operating system supports persistent
- overlays for saving system changes, a pre-sized overlay may be included with
- the installation.
+ overlays for saving system changes, a pre-sized overlay may be specified
+ for creation during the installation.
Unless you request the --format option, the installation does not destroy
data outside of the LiveOS, syslinux, & EFI folders on your target device.
@@ -92,21 +92,34 @@ usage() {
LiveOS images provide embedded filesystems through the Device-mapper
component of the Linux kernel. The embedded filesystems exist within files
such as /LiveOS/squashfs.img (the default compressed storage) or
- /LiveOS/ext3fs.img (an uncompressed version) on the primary volume partition
- of the storage device. In use, these are read-only filesystems. Optionally,
- one may specify a persistent LiveOS overlay to hold image-change snapshots
- (that use write-once, difference-tracking storage) in the
- /LiveOS/overlay-<device_id> file, which, *one should note*, always grows in
- size due to the storage mechanism. (The fraction of allocated space that
- has been consumed by system activity and changes may be displayed by issuing
- the 'dmsetup status' command in a terminal session of a running LiveOS
- image.) One way to conserve the unrecoverable, overlay file space, is to
- specify a persistent home folder for user files, which will be saved in a
- /LiveOS/home.img filesystem image file. This file space is encrypted by
- default, but is not compressed. (One may bypass encryption with the
- --unencrypted-home installation option.) Files in this home folder may be
- erased to recover and reuse their storage space. The home.img file is also
- convenient for backing up or swapping user account files.
+ /LiveOS/ext3fs.img (an uncompressed version) on the primary volume
+ partition of the storage device. In use, these are read-only filesystems.
+ On boot, a temporary, read-write root filesystem overlay is provided.
+ Optionally, one may specify a fixed-sized, persistent overlay storage pool
+ in a /LiveOS/overlay-<device_id> file, which will hold root filesystem
+ changes via allocate-once, copy-on-write storage.
+
+ Should the overlay storage space, whether temporary or persistent, be
+ totally consumed, the filesystem will be flagged 'Invalid' and, if that
+ filesystem is the booted root filesystem, it will crash with Input/output
+ or Bus errors. If such a crash occurs while using temporary storage space
+ for the overlay, a simple reboot will rectify the situation. With
+ persistent storage, the situation is more dire and will require appending
+ 'rd.live.overlay.reset' to the kernel command line on boot-up. This will
+ reset the storage overlay to its initial, unused state (all changes are
+ lost).
+
+ One may check the number of allocated sectors of the total overlay storage
+ by issuing the 'dmsetup status' command in a terminal session of a running
+ LiveOS image. *One should note* though, the number of allocated sectors in
+ the overlay always grows, even though the apparent size of the virtual root
+ filesystem may go up and down. One way to conserve the overlay file space,
+ is to specify persistent home folder storage for user files, which will be
+ saved in a /LiveOS/home.img filesystem image file. This file space is
+ encrypted by default, but is not compressed. (One may bypass encryption
+ with the --unencrypted-home installation option.) Files in this home
+ folder may be erased to reuse their storage space. The home.img file is
+ also convenient for backing up or swapping user account files.
OPTIONS
@@ -120,11 +133,12 @@ usage() {
storage device.
--format
- Formats the target device and creates an MS-DOS partition table (or GPT
- partition table, if the --efi option is passed).
+ Creates an MS-DOS partition table (or GPT partition table, if the --efi
+ option is passed) and formats an ext4 filesystem on the target device.
--msdos
- Forces format to use msdos instead of ext4.
+ Forces format to make an fat32 file system instead of an ext4 formatted
+ one.
--reset-mbr
Sets the Master Boot Record (MBR) of the target storage device to the
@@ -183,7 +197,6 @@ usage() {
Used when installing multiple image copies to signal configuration of
the boot files for the image in the --livedir <dir> parameter.
-
--livedir <dir>
Used with multiple image installations to designate the directory <dir>
for the particular image.
@@ -199,50 +212,47 @@ usage() {
--swap-size-mb <size>
Sets up a swap file of <size> mebibytes (integer values only) on the
- target device.
+ target device. A maximum <size> of 2047 MiB is permitted for
+ vfat-formatted devices.
--overlay-size-mb <size>
This option sets the overlay size in mebibytes (integer values only).
- The overlay makes persistent storage available to the live operating
- system, if the operating system supports it. The persistent LiveOS
- overlay holds image-change snapshots (using write-once, difference-
- tracking storage) in the /LiveOS/overlay-<device_id> file, which, *one
- should note*, always grows in size due to the storage mechanism. (The
- fraction of allocated space that has been consumed may be displayed by
- issuing the 'dmsetup status' command in a terminal session of a running
- LiveOS installation.) One way to conserve the unrecoverable, overlay
- file space, is to specify a persistent home folder for user files, see
- --home-size-mb below. The target storage device must have enough free
- space for the image and the overlay. A maximum <size> of 2047 MiB is
- permitted for vfat-formatted devices. If there is insufficient room on
- your device, you will be given information to help in adjusting your
- settings.
+ The overlay is a fixed-sized, persistent storage pool of sectors in a
+ /LiveOS/overlay-<device_id> file, which will hold root filesystem
+ changes via allocate-once, copy-on-write storage. (See the Description
+ section above for some important limitations of this storage.) One way
+ to conserve the limited, overlay file space, is to specify a persistent
+ home folder for user files, see --home-size-mb below. The target
+ storage device must have enough free space for the image and the
+ overlay. A maximum <size> of 2047 MiB is permitted for vfat-formatted
+ devices. If there is insufficient room on your device, you will be
+ given information to help in adjusting your settings.
--home-size-mb <size>
Sets the home directory size in mebibytes (integer values only). A
persistent home directory will be made in the /LiveOS/home.img
- filesystem image file. This file space is encrypted by default, but not
- compressed (one may bypass encryption with the --unencrypted-home
- installation option). Files in this home folder may be erased to
- recover and reuse their storage space. The target storage device must
- have enough free space for the image, any overlay, and the home
- directory. Note that the --delete-home option must also be selected to
- replace an existing persistent home with a new, empty one. A maximum
- <size> of 2047 MiB is permitted for vfat-formatted devices. If there is
- insufficient room on your device, you will be given information to help
- in adjusting your settings.
+ filesystem image file. This file space is encrypted by default, but
+ not compressed (one may bypass encryption with the --unencrypted-home
+ installation option). Files in this home folder may be erased to reuse
+ their storage space. The target storage device must have enough free
+ space for the image, any overlay, and the home directory. Note that
+ the --delete-home option must also be selected to replace an existing
+ persistent home with a new, empty one. A maximum <size> of 2047 MiB is
+ permitted for vfat-formatted devices. If there is insufficient room on
+ your device, you will be given information to help in adjusting your
+ settings.
--delete-home
To prevent unwitting deletion of user files, this option must be
explicitly selected when the option --home-size-mb <size> is selected
- and there is an existing persistent home directory on the target device.
+ and an existing persistent home filesystem is on the target device.
--crypted-home (default that only applies to new home-size-mb requests)
- Specifies the default option to encrypt a new persistent home directory
- if --home-size-mb <size> is specified.
+ Specifies the default option to encrypt a new persistent home
+ filesystem if --home-size-mb <size> is specified.
--unencrypted-home
- Prevents the default option to encrypt a new persistent home directory.
+ Prevents the default encryption of a new persistent home filesystem.
CONTRIBUTORS