docs/livecd-iso-to-disk.pod

   1 =pod
   2
   3 =head1 NAME
   4
   5 livecd-iso-to-disk - installs bootable Live images onto USB/SD storage devices.
   6
   7 =head1 SYNOPSIS
   8
   9 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>
  10
  11 Simplest
  12
  13 The script may be run in simplest form with just the two arguments:
  14
  15 B<livecd-iso-to-disk> <source> <target device>
  16
  17 To execute the script to completion, you will need to run it with root user permissions.  SYSLINUX must be installed on the computer running the installation script.
  18
  19 =over 4
  20
  21 =item <source>
  22
  23 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).
  24
  25 =item <target device>
  26
  27 This should be the device partition name for the attached, target device, such as /dev/sdb1 or /dev/sdc1.  (Issue the df -Th command to get a listing of the mounted partitions, where you can confirm the filesystem types, available space, and device names.)  Be careful to specify the correct device, or you may overwrite important data on another disk!
  28
  29 =back
  30
  31 =head1 DESCRIPTION
  32
  33 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.
  34
  35 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.
  36
  37 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.
  38
  39 =head1 OPTIONS
  40
  41 =over 4
  42
  43 =item --help
  44
  45 Displays usage information and exits.
  46
  47 =item --noverify
  48
  49 Disables the image validation process that occurs before the image is installed from the original Live CD .iso image.  When this option is specified, the image is not verified before loading onto the target storage device.
  50
  51 =item --format
  52
  53 Formats the target device and creates an MS-DOS partition table (or GUID partition table, if the --efi option is passed).
  54
  55 =item --reset-mbr
  56
  57 Sets the Master Boot Record (MBR) of the target storage device to the mbr.bin file from the installation system's syslinux directory.  This may be helpful in recovering a damaged or corrupted device.
  58
  59 =item --efi
  60
  61 Creates a GUID partition table when --format is passed, and installs a hybrid Extensible Firmware Interface (EFI)/MBR bootloader on the disk.  This is necessary for most Intel Macs.
  62
  63 =item --skipcopy
  64
  65 Skips the copying of the live image to the target device, bypassing the actions of the --format, --overlay-size-mb, --home-size-mb, & --swap-size-mb options, if present on the command line. (The --skipcopy option may be used while testing the script, in order to avoid repeated and lengthy copy commands, or to repair boot configuration files on a previously installed device.)
  66
  67 =item --force
  68
  69 This option allows the installation script to bypass a delete confirmation dialog in the event that a pre-existing LiveOS directory is found on the target device.
  70
  71 =item --xo
  72
  73 Used to prepare an image for the OLPC XO-1 laptop with its compressed, JFFS2 filesystem.  Do not use the following options with --xo:
  74
  75 =over 4
  76
  77 --overlay-size-mb <size>, home-size-mb <size>, --delete-home, --compress
  78
  79 =back
  80
  81 =item --xo-no-home
  82
  83 Used together with the --xo option to prepare an image for an OLPC XO laptop with the home folder on an SD card instead of the internal flash storage.
  84
  85 =item --timeout
  86
  87 Modifies the bootloader's timeout value, which indicates how long to pause at the boot: prompt before booting automatically.  This overrides the value set during iso creation.  Units are 1/10 s.  The timeout is canceled when any key is pressed, the assumption being that the user will complete the command line.  A timeout of zero will disable the timeout completely.
  88
  89 =item --totaltimeout
  90
  91 Adds a bootloader totaltimeout, which indicates how long to wait before booting automatically.  This is used to force an automatic boot.  This timeout cannot be canceled by the user.  Units are 1/10 s.
  92
  93 =item --extra-kernel-args <args>
  94
  95 Specifies additional kernel arguments, <args>, that will be inserted into the syslinux and EFI boot configurations.  Multiple arguments should be specified in one string, i.e., --extra-kernel-args "arg1 arg2 ..."
  96
  97 =item --multi
  98
  99 Used when installing multiple image copies to signal configuration of the boot files for the image in the --livedir <dir> parameter.
 100
 101 =item --livedir <dir>
 102
 103 Used with multiple image installations to designate the directory <dir> for the particular image.
 104
 105 =item --compress   (default state for the operating system files)
 106
 107 The default, compressed SquashFS filesystem image is copied on installation.  This option has no effect when the source filesystem
 108 is already expanded.
 109
 110 =item --skipcompress   (default option when  --xo is specified)
 111
 112 Expands the source SquashFS image on installation into the read-only /LiveOS/ext3fs.img filesystem image file.
 113
 114 =item --swap-size-mb <size>
 115
 116 Sets up a swap file of <size> mebibytes (integer values only) on the target device.
 117
 118 =item --overlay-size-mb <size>
 119
 120 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.
 121
 122 =item --home-size-mb <size>
 123
 124 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.
 125
 126 =item --delete-home
 127
 128 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.
 129
 130 =item --crypted-home   (default that only applies to new home-size-mb requests)
 131
 132 Specifies the default option to encrypt a new persistent home directory if --home-size-mb <size> is specified.
 133
 134 =item --unencrypted-home
 135
 136 Prevents the default option to encrypt a new persistent home directory.
 137
 138 =back
 139
 140 =head1 CONTRIBUTORS
 141
 142 David Zeuthen, Jeremy Katz, Douglas McClendon, Chris Curran and other contributors. See the AUTHORS file in the source distribution for the complete list of credits.
 143
 144 =head1 BUGS
 145
 146 Report bugs to the mailing list C<http://admin.fedoraproject.org/mailman/listinfo/livecd> or directly to Bugzilla C<http://bugzilla.redhat.com/bugzilla/> against the C<Fedora> product, and the C<livecd-tools> component.
 147
 148 =head1 COPYRIGHT
 149
 150 Copyright (C) Fedora Project 2008, 2009, 2010 and various contributors. This is free software. You may redistribute copies of it under the terms of the GNU General Public License C<http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.
 151
 152 =head1 SEE ALSO
 153
 154 C<livecd-creator(1)>, project website C<http://fedoraproject.org/wiki/FedoraLiveCD>
 155
 156 =cut