5:51 p.m.
commit f7211d501d7b8c81946c2cb685d8ee61a1c40ada
Author: Frederick Grose <fgrose(a)sugarlabs.org>
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