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

OPTIONS

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

CONTRIBUTORS

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

BUGS

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

SEE ALSO

372       "livecd-creator(1)", project website
373       "http://fedoraproject.org/wiki/FedoraLiveCD"
374
375
376
377livecd-tools 28.3                 2021-08-23             LIVECD-ISO-TO-DISK(8)
Impressum