commit f7211d501d7b8c81946c2cb685d8ee61a1c40ada Author: Frederick Grose <fgrose(a)sugarlabs.org&gt; 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