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