1LIVECD-ISO-TO-DISK(8)            LiveCD Tools            LIVECD-ISO-TO-DISK(8)
2
3
4

NAME

6       livecd-iso-to-disk - Installs bootable Live images onto USB/SD storage
7       devices.
8

SYNOPSIS

10       livecd-iso-to-disk  [--help] [--noverify] [--format] [--msdos]
11       [--reset-mbr] [--efi] [--skipcopy] [--force] [--xo] [--xo-no-home]
12       [--timeout <duration>] [--totaltimeout <duration>] [--nobootmsg]
13       [--nomenu] [--extra-kernel-args <args>] [--multi] [--livedir <dir>]
14       [--compress] [--skipcompress] [--no-overlay] [--overlayfs [temp]]
15       [--overlay-size-mb <size>] [--copy-overlay] [--reset-overlay]
16       [--home-size-mb <size>] [--copy-home] [--delete-home] [--crypted-home]
17       [--unencrypted-home] [--swap-size-mb <size>] [--updates <updates.img>]
18       [--ks <kickstart>] [--label <label>] <source> <target device>
19
20       Simplest
21
22       The script may be run in simplest form with just the two arguments:
23
24       livecd-iso-to-disk <source> <target device>
25
26       To execute the script to completion, you will need to run it with root
27       user permissions.  SYSLINUX must be installed on the computer running
28       this script.
29
30       <source>
31           This may be the filesystem path to a LiveOS .iso image file, such
32           as from a CD-ROM, DVD, or download.  It could also be the device
33           node reference, the LiveOS-containing directory path, or the mount
34           point for another LiveOS filesystem.  Entering 'live' for the
35           <source> will source the currently booted LiveOS device.
36
37       <target device>
38           This should be, or a link to, the device partition path for the
39           attached, target device, such as /dev/sdc1.  (Issue the df -Th
40           command to get a listing of mounted partitions, so you can confirm
41           the filesystem types, available space, and device names.)  Be
42           careful to specify the correct device, or you may overwrite
43           important data on another disk!  For a multi boot installation to
44           the currently booted device, enter 'live' as the target.
45

DESCRIPTION

47       livecd-iso-to-disk installs a Live CD/DVD/USB image (LiveOS) onto a
48       USB/SD storage device (or any storage partition that will boot with a
49       SYSLINUX bootloader).  The target storage device can then boot the
50       installed operating system on systems that support booting via the USB
51       or the SD interface.  The script requires a LiveOS source image and a
52       target storage device.  The script requires a LiveOS source image and a
53       target storage device.  A loop device backed by a file may also be
54       targeted for virtual block device installation.  The source image may
55       be either a LiveOS .iso file, or another reference to a LiveOS image,
56       such as the device node for an attached device installed with a LiveOS
57       image, its mount point, a loop device backed by a file containing an
58       installed LiveOS image, or even the currently-running LiveOS image.  A
59       pre-sized overlay file for persisting root filesystem changes may be
60       included with the installed image.
61
62       Unless you request the --format option, installing an image does not
63       destroy data outside of the LiveOS, syslinux, & EFI directories on your
64       target device.  This allows one to maintain other files on the target
65       disk outside of the LiveOS filesystem.
66
67       Multi image installations may be invoked interactively if the target
68       device already contains a LiveOS image.
69
70       LiveOS images employ embedded filesystems through the Device-mapper
71       component of the Linux kernel.  The filesystems are embedded within
72       files in the /LiveOS/ directory of the storage device.  The
73       /LiveOS/squashfs.img file is the default, compressed filesystem
74       containing one directory and the file /LiveOS/rootfs.img that contains
75       the root filesystem for the distribution.  These are read-only
76       filesystems that are usually fixed in size to within a few GiB of the
77       size of the full root filesystem at build time.  At boot time, a
78       Device-mapper snapshot with a sparse 32 GiB, in-memory, read-write
79       overlay is created for the root filesystem.  Optionally, one may
80       specify a fixed-size, persistent on disk overlay to hold changes to the
81       root filesystem.  The build-time size of the root filesystem will limit
82       the maximum size of the working root filesystem--even if supplied with
83       an overlay file larger than the apparent free space on the root
84       filesystem.  *Note well* that deletion of any original files in the
85       read-only root filesystem does not recover any storage space on your
86       LiveOS device.  Storage in the persistent /LiveOS/overlay-<device_id>
87       file is allocated as needed.  If the overlay storage space is filled,
88       the overlay will enter an 'Overflow' state where the root filesystem
89       will continue to operate in a read-only mode.  There will not be an
90       explicit warning or signal when this happens, but applications may
91       begin to report errors due to this restriction.  If significant changes
92       or updates to the root filesystem are to be made, carefully watch the
93       fraction of space allocated in the overlay by issuing the 'dmsetup
94       status' command at a command line of the running LiveOS image.  Some
95       consumption of root filesystem and overlay space can be avoided by
96       specifying a persistent home filesystem for user files, which will be
97       saved in a fixed-size /LiveOS/home.img file.  This filesystem is
98       encrypted by default.  (One may bypass encryption with the
99       --unencrypted-home option.)  This filesystem is mounted on the /home
100       directory of the root filesystem.  When its storage space is filled,
101       out-of-space warnings will be issued by the operating system.
102

OPTIONS

104       --help|-h|-?
105           Displays usage information and exits.
106
107       --noverify
108           Disables the image validation process that occurs before the image
109           is copied from the original Live CD .iso image.  When this option
110           is specified, the image is not verified before it is copied onto
111           the target storage device.
112
113       --format
114           Formats the target device and creates an MS-DOS partition table (or
115           GUID partition table, if the --efi option is passed).
116
117       --msdos
118           Forces format to use the msdos (vfat) filesystem instead of ext4.
119
120       --reset-mbr|--resetmbr
121           Sets the Master Boot Record (MBR) of the target storage device to
122           the mbr.bin file from the installation system's syslinux directory.
123           This may be helpful in recovering a damaged or corrupted device.
124
125       --efi|--mactel
126           Creates a GUID partition table when --format is passed, and
127           installs a hybrid Extensible Firmware Interface (EFI)/MBR
128           bootloader on the disk.  This is necessary for most Intel Macs.
129
130       --skipcopy
131           Skips the copying of the live image to the target device, bypassing
132           the action of the --format, --overlay-size-mb, --copy-overlay,
133           --home-size-mb, --copy-home, & --swap-size-mb options, if present
134           on the command line. (The --skipcopy option may be used while
135           testing the script, in order to avoid repeated and lengthy copy
136           commands, or with --reset-mbr to repair the boot configuration
137           files on a previously installed LiveOS device.)
138
139       --force
140           This option allows the installation script to bypass a delete
141           confirmation dialog in the event that a pre-existing LiveOS
142           directory is found on the target device.
143
144       --xo
145           Used to prepare an image for the OLPC XO-1 laptop with its
146           compressed, JFFS2 filesystem.  Do not use the following options
147           with --xo:
148
149               --overlay-size-mb <size>, home-size-mb <size>, --delete-home,
150               --compress
151
152       --xo-no-home
153           Used together with the --xo option to prepare an image for an OLPC
154           XO laptop with the home directory on an SD card instead of the
155           internal flash storage.
156
157       --timeout <duration>
158           Modifies the bootloader's timeout value, which indicates how long
159           to pause at the boot prompt before booting automatically.  This
160           overrides the value set during iso creation.
161
162               For SYSLINUX, a timeout unit is 1/10 second; the timeout is
163               canceled when any key is pressed (the assumption being that the
164               user will complete the command line); and a timeout of zero
165               will disable the timeout completely.
166
167               For EFI GRUB, the timeout unit is 1 second; timeout specifies
168               the time to wait for keyboard input before booting the default
169               menu entry.  A timeout of '0' means to boot the default entry
170               immediately without displaying the menu; and a timeout of '-1'
171               means to wait indefinitely.
172
173           Enter a desired timeout value in 1/10 second units (or '-1') and
174           the appropriate value will be supplied to the configuration file.
175           For immediate booting, enter '-0' to avoid the ambiguity between
176           systems.  An entry of '-0' will result in an SYSLINUX setting of
177           timeout 1 and totaltimeout 1. '0' or '-1' will result in an
178           SYSLINUX setting of '0' (disable timeout, that is, wait
179           indefinitely), but '0' for EFI GRUB will mean immediate boot of the
180           default, while '-1' will mean EFI GRUB waits indefinitely for a
181           user selection.
182
183       --totaltimeout <duration>
184           Adds a SYSLINUX bootloader totaltimeout, which indicates how long
185           to wait before booting automatically.  This is used to force an
186           automatic boot.  This timeout cannot be canceled by the user.
187           Units are 1/10 s.  A totaltimeout of zero will disable the timeout
188           completely.  (This setting is not available in EFI GRUB.)
189
190       --nobootmsg
191           Do not display boot.msg, usually, \"Press the <ENTER> key to begin
192           the installation process.\"
193
194       --nomenu
195           Skip the boot menu, and automatically boot the 'linux' label item.
196
197       --extra-kernel-args <args>
198           Specifies additional kernel arguments, <args>, that will be
199           inserted into the syslinux and EFI boot configurations.  Multiple
200           arguments should be specified in one string, i.e.,
201           --extra-kernel-args "arg1 arg2 ..."
202
203       --multi
204           Signals the boot configuration to accommodate multiple images on
205           the target device.  Image and boot files will be installed under
206           the --livedir <directory>.  SYSLINUX boot components from the
207           installation host will always update those in the boot path of the
208           target device.
209
210       --livedir <dir>
211           Designates the directory for installing the LiveOS image.  The
212           default is /LiveOS.
213
214       --compress    (default state for the original root filesystem)
215           The default, compressed SquashFS filesystem image is copied on
216           installation.  (This option has no effect if the source filesystem
217           is already expanded.)
218
219       --skipcompress    (default option when  --xo is specified)
220           Expands the source SquashFS.img on installation into the read-only
221           /LiveOS/rootfs.img root filesystem image file.  This avoids the
222           system overhead of decompression during use at the expense of
223           storage space and bus I/O.
224
225       --no-overlay    (effective only with --skipcompress or an uncompressed
226       image)
227           Installs a kernel option, rd.live.overlay=none, that signals the
228           live boot process to create a writable, linear Device-mapper target
229           for an uncompressed /LiveOS/rootfs.img filesystem image file.
230           Read-write by default (unless a kernel argument of
231           rd.live.overlay.readonly is given) this configuration avoids the
232           complications of using an overlay of fixed size for persistence
233           when storage format and space allows.
234
235       --overlayfs [temp]   (add --overlay-size-mb for persistence on vfat
236       devices)
237           Specifies the creation of an OverlayFS type overlay.  If the option
238           is followed by 'temp', a temporary overlay will be used.  On vfat
239           or msdos formatted devices, --overlay-size-mb <size> must also be
240           provided for a persistent overlay.  OverlayFS overlays are
241           directories of the files that have changed on the read-only root
242           filesystem.  With non-vfat-formatted devices, the OverlayFS can
243           extend the available root filesystem space up to the capacity of
244           the Live USB device.
245
246           The --overlayfs option requires an initial boot image based on
247           dracut version 045 or greater to use the OverlayFS feature.
248           Lacking this, the device boots with a temporary Device-mapper
249           overlay.
250
251       --overlay-size-mb <size>
252           Specifies creation of a filesystem overlay of <size> mebibytes
253           (integer values only).  The overlay makes persistent storage
254           available to the live operating system, if the operating system
255           supports it.  The overlay holds a snapshot of changes to the root
256           filesystem.  *Note well* that deletion of any original files in the
257           read-only root filesystem does not recover any storage space on
258           your LiveOS device.  Storage in the persistent
259           /LiveOS/overlay-<device_id> file is allocated as needed.  If the
260           overlay storage space is filled, the overlay will enter an
261           'Overflow' state where the root filesystem will continue to operate
262           in a read-only mode.  There will not be an explicit warning or
263           signal when this happens, but applications may begin to report
264           errors due to the restriction.  If significant changes or updates
265           to the root filesystem are to be made, carefully watch the fraction
266           of space allocated in the overlay by issuing the 'dmsetup status'
267           command at a command line of the running LiveOS image.  Some
268           consumption of root filesystem and overlay space can be avoided by
269           specifying a persistent home filesystem for user files, see
270           --home-size-mb below.  The target storage device must have enough
271           free space for the image and the overlay.  A maximum <size> of 4095
272           MiB is permitted for vfat-formatted devices.  If there is not
273           enough room on your device, you will be given information to help
274           in adjusting your settings.
275
276       --copy-overlay
277           This option allows one to copy the persistent overlay from one live
278           image to the new image.  Changes already made in the source image
279           will be propagated to the new installation.
280
281               WARNING: User sensitive information such as password cookies
282               and application or user data will be copied to the new image!
283               Scrub this information before using this option.
284
285       --reset-overlay
286           This option will reset the persistent overlay to an unallocated
287           state.  This might be used if installing a new or refreshed image
288           onto a device with an existing overlay, and avoids the writing of a
289           large file on a vfat-formatted device.  This option also renames
290           the overlay to match the current device filesystem label and UUID.
291
292       --home-size-mb <size>
293           Specifies creation of a home filesystem of <size> mebibytes
294           (integer values only).  A persistent home directory will be stored
295           in the /LiveOS/home.img filesystem image file.  This filesystem is
296           encrypted by default and not compressed  (one may bypass encryption
297           with the --unencrypted-home option).  When the home filesystem
298           storage space is full, one will get out-of-space warnings from the
299           operating system.  The target storage device must have enough free
300           space for the image, any overlay, and the home filesystem.  Note
301           that the --delete-home option must also be selected to replace an
302           existing persistent home with a new, empty one.  A maximum <size>
303           of 4095 MiB is permitted for vfat-formatted devices.  If there is
304           not enough room on your device, you will be given information to
305           help in adjusting your settings.
306
307       --copy-home
308           This option allows one to copy a persistent home.img filesystem
309           from the source LiveOS image to the target image.  Changes already
310           made in the source home directory will be propagated to the new
311           image.
312
313               WARNING: User-sensitive information, such as password cookies
314               and user and application data, will be copied to the new image!
315               Scrub this information before using this option.
316
317       --delete-home
318           One must explicitly select this option in the case where there is
319           an existing persistent home filesystem on the target device and the
320           --home-size-mb <size> option is selected to create an empty, new
321           home filesystem.  This prevents unwitting deletion of user files.
322
323       --crypted-home    (default that only applies to new home-size-mb
324       requests)
325           Specifies the default option to encrypt a new persistent home
326           filesystem when --home-size-mb <size> is specified.
327
328       --unencrypted-home
329           Prevents the default option to encrypt a new persistent home
330           directory filesystem.
331
332       --swap-size-mb <size>
333           Sets up a swap file of <size> mebibytes (integer values only) on
334           the target device.  A maximum <size> of 4095 MiB is permitted for
335           vfat-formatted devices.
336
337       --updates <updates.img>
338           Setup a kernel command line argument, inst.updates, to point to an
339           updates image on the device. Used by Anaconda for testing updates
340           to an iso without needing to make a new iso. <updates.img> should
341           be a path accessible to this script, which will be copied to the
342           target device.
343
344       --ks <kickstart>
345           Setup inst.ks to point to an kickstart file on the device. Use this
346           for automating package installs on boot. <kickstart> should be a
347           path accessible to this script, which will be copied to the target
348           device.
349
350       --label <label>
351           Specifies a specific filesystem label instead of default LIVE.
352           Useful when you do unattended installs that pass a label to inst.ks
353

CONTRIBUTORS

355       David Zeuthen, Jeremy Katz, Douglas McClendon, Chris Curran and other
356       contributors. See the AUTHORS file in the source distribution for the
357       complete list of credits.
358

BUGS

360       Report bugs to the mailing list
361       "http://admin.fedoraproject.org/mailman/listinfo/livecd" or directly to
362       Bugzilla "http://bugzilla.redhat.com/bugzilla/" against the "Fedora"
363       product, and the "livecd-tools" component.
364
366       Copyright 2008-2010, 2017, Fedora Project and various contributors.
367       This is free software. You may redistribute copies of it under the
368       terms of the GNU General Public License
369       "http://www.gnu.org/licenses/gpl.html". There is NO WARRANTY, to the
370       extent permitted by law.
371

SEE ALSO

373       "livecd-creator(1)", project website
374       "http://fedoraproject.org/wiki/FedoraLiveCD"
375
376
377
378livecd-tools 27.1                 2020-01-29             LIVECD-ISO-TO-DISK(8)
Impressum