[PATCH 1/2] Correct & update livecd-iso-to-disk.pod documentation

[Frederick Grose]

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