commit d219ec73c631f31d3197e19b03212611ab90f615
Date: Tue Mar 19 18:24:12 2013 -0400
Correct misleading information on the overlay, update options, syncronize
with usage info embedded in livecd-iso-to-disk.sh
diff --git a/docs/livecd-iso-to-disk.pod b/docs/livecd-iso-to-disk.pod
index 7ef0c14..16ebdea 100644
--- a/docs/livecd-iso-to-disk.pod
+++ b/docs/livecd-iso-to-disk.pod
@@ -6,7 +6,7 @@ livecd-iso-to-disk - installs bootable Live images onto USB/SD storage devices.
=head1 SYNOPSIS
-B<livecd-iso-to-disk> [--help] [--noverify] [--format] [--reset-mbr] [--efi] [--skipcopy] [--force] [--xo] [--xo-no-home] [--timeout <time>] [--totaltimeout <time>] [--extra-kernel-args <args>] [--multi] [--livedir <dir>] [--compress] [--skipcompress] [--swap-size-mb <size>] [--overlay-size-mb <size>] [--home-size-mb <size>] [--delete-home] [--crypted-home] [--unencrypted-home] <source> <target device>
+B<livecd-iso-to-disk> [--help] [--noverify] [--format] [--msdos] [--reset-mbr] [--efi] [--skipcopy] [--force] [--xo] [--xo-no-home] [--timeout <time>] [--totaltimeout <time>] [--extra-kernel-args <args>] [--multi] [--livedir <dir>] [--compress] [--skipcompress] [--swap-size-mb <size>] [--overlay-size-mb <size>] [--home-size-mb <size>] [--delete-home] [--crypted-home] [--unencrypted-home] <source> <target device>
Simplest
@@ -20,7 +20,7 @@ To execute the script to completion, you will need to run it with root user perm
=item <source>
-This may be the filesystem path to a LiveOS .iso image file, 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).
+This may be the filesystem path to a LiveOS .iso image file, 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 /run/initramfs/livedev references the booted device).
=item <target device>
@@ -30,11 +30,15 @@ This should be the device partition name for the attached, target device, such a
=head1 DESCRIPTION
-B<livecd-iso-to-disk> installs a Live CD/DVD/USB image (LiveOS) onto a USB/SD storage device (or any storage partition that will boot with a SYSLINUX bootloader). The target storage device can then boot the installed operating system on systems that support booting via the USB or the SD interface. The script requires a LiveOS source image and a target storage device. The source image may be either a LiveOS .iso file, the currently-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.
+B<livecd-iso-to-disk> installs a Live CD/DVD/USB image (LiveOS) onto a USB/SD storage device (or any storage partition that will boot with a SYSLINUX bootloader). The target storage device can then boot the installed operating system on systems that support booting via the USB or the SD interface. The script requires a LiveOS source image and a target storage device. The source image may be either a LiveOS .iso file, the currently-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 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. This allows one to maintain other files on the target disk outside of the LiveOS filesystem.
-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 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. 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.
=head1 OPTIONS
@@ -50,7 +54,11 @@ Disables the image validation process that occurs before the image is installed
=item --format
-Formats the target device and creates an MS-DOS partition table (or GUID 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.
+
+=item --msdos
+
+Forces format to make an fat32 file system instead of an ext4 formatted one.
=item --reset-mbr
@@ -104,8 +112,7 @@ Used with multiple image installations to designate the directory <dir> for the
=item --compress (default state for the operating system files)
-The default, compressed SquashFS filesystem image is copied on installation. This option has no effect when the source filesystem
-is already expanded.
+The default, compressed SquashFS filesystem image is copied on installation. This option has no effect when the source filesystem is already expanded.
=item --skipcompress (default option when --xo is specified)
@@ -113,27 +120,27 @@ Expands the source SquashFS image on installation into the read-only /LiveOS/ext
=item --swap-size-mb <size>
-Sets up a swap file of <size> mebibytes (integer values only) on the target device.
+Sets up a swap file of <size> mebibytes (integer values only) on the target device. A maximum <size> of 2047 MiB is permitted for vfat-formatted devices.
=item --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.
+This option sets the overlay size in mebibytes (integer values only). 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.
=item --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.
+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 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.
=item --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.
+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 filesystem on the target device.
=item --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.
=item --unencrypted-home
-Prevents the default option to encrypt a new persistent home directory.
+Prevents the default encryption of a new persistent home filesystem.
=back