1LIVECD-ISO-TO-DISK(8) LiveCD Tools LIVECD-ISO-TO-DISK(8)
2
6 livecd-iso-to-disk - Installs bootable Live images onto USB/SD storage
7 devices.
8
10 livecd-iso-to-disk [--format [<size>[,fstype[,blksz[,extra_attr,s]]]]]
11 [--msdos] [--efi] [--noesp] [--reset-mbr] [--multi] [--livedir
12 <directory>] [--skipcopy] [--noverify] [--force] [--xo] [--xo-no-home]
13 [--timeout <duration>] [--totaltimeout <duration>] [--nobootmsg]
14 [--nomenu] [--extra-kernel-args <arg s>] [--compress] [--skipcompress]
15 [--no-overlay] [--overlayfs [temp]] [--overlay-size-mb
16 <size>[,fstype[,blksz]]] [--copy-overlay] [--reset-overlay]
17 [--home-size-mb <size>[,fstype,blksz]]] [--copy-home] [--delete-home]
18 [--crypted-home] [--unencrypted-home] [--swap-size-mb <size>]
19 [--updates <updates.img>] [--ks <kickstart>] [--label <label>] [--help]
20 <source> <target partition/device>
21 The script may be run in simplest form with just the two arguments:
23 livecd-iso-to-disk <source> <target partition/device>
25 To execute the script to completion, you will need to run it with root
27 user permissions. Legacy booting of the installed image requires that
28 SYSLINUX is installed on the host computer running this script.
29 <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 <target partition/device>
38 This should be, or a link to, the device partition path for an
39 attached, target device, such as /dev/sdc1. A virtual block
40 device, such as a loop device or a Device-mapper target may also be
41 used. (Issue the "lsblk -pf" command to get a list of attached
42 partitions, so you can confirm the device names, filesystem types,
43 and available space.) Be careful to specify the correct device, or
44 you may overwrite important data on another disk! If you request
45 formatting with the --format option, enter only the base device
46 path, such as /dev/sdc. For a multi boot installation to the
47 currently booted device, enter "live" as the target.
48
50 livecd-iso-to-disk installs a Live CD/DVD/USB image (LiveOS) onto a
51 USB/SD storage device. The target storage device can then support
52 booting the installed operating system on systems that support booting
53 via the USB or the SD interface. The script requires a LiveOS source
54 image and a target storage device. A loop device backed by a file may
55 also be targeted for virtual block device installation. Additionally,
56 a Device-mapper target construct for block devices may be used. If a
57 Device-mapper mirror target is preconfigured, this target may be used
58 to simultaneously target multiple physical devices. The source image
59 may be either a LiveOS .iso file, or another reference to a LiveOS
60 image, such as the device node for an attached device installed with a
61 LiveOS image, its mount point, a loop device backed by a file
62 containing an installed LiveOS image, or even the currently-running
63 LiveOS image.
64 A pre-sized overlay file or a free-space-sized OverlayFS directory may
66 be created for saving changes in the root filesystem of the installed
67 image onto persistent storage media.
68 Unless you request the --format option, installing an image does not
70 destroy data outside of the LiveOS, syslinux, & EFI directories on your
71 target device. This allows one to maintain other files on the target
72 disk outside of the LiveOS filesystem.
73 Multi image installations may be invoked interactively if the target
75 device already contains a LiveOS image.
76 LiveOS images employ embedded filesystems through the loop device,
78 Device-mapper, or OverlayFS components of the Linux kernel. The
79 filesystems are embedded within files or directories in the /LiveOS/
80 directory (by default) of the base filesystem on the storage device.
81 The /LiveOS/squashfs.img file is a SquashFS format compressed image,
82 which by default contains one directory and file, /LiveOS/rootfs.img,
83 that contains the root filesystem for the installed distribution image.
84 These both are read-only filesystems that are fixed in size usually to
85 within a few GiB of the size of the full root filesystem at build time.
86 At boot time, either a Device-mapper snapshot with a temporary, 32 GiB,
87 sparse, in-memory, read-write, overlay is created for the root
88 filesystem, or an OverlayFS directory may be configured during bootup
89 if configured on disk or by kernel command line options. When one
90 specifies a persistent, fixed-size, Device-mapper overlay to hold
91 changes to the root filesystem, the build-time size of the root
92 filesystem will limit the maximum size of the working root
93 filesystemXeven if it is supplied with an overlay file larger than the
94 apparent free space of the root filesystem. Persistent OverlayFS
95 directories avoid this limitation by creating a working union of two
96 filesystems to serve as root filesystem.
97 NOTE WELL: Deletion of any of the original files in the read-only
99 root filesystem does not recover any storage space on your LiveOS
100 device. Storage in a Device-mapper overlay is allocated as needed.
101 If its overlay storage space is filled, the overlay will enter an
102 'Overflow' state while the root filesystem continues to operate in
103 a read-only mode. There will not be an explicit warning or signal
104 when this happens, but applications may begin to report errors due
105 to this restriction. If many or large changes or updates to the
106 root filesystem are to be made, carefully watch the fraction of
107 space allocated in the overlay by issuing the command "dmsetup
108 status" at a terminal or console of the running LiveOS image.
109 Consumption of root filesystem and overlay space can be avoided by
110 specifying a persistent home filesystem for user files, which will
111 be saved in a fixed-size /LiveOS/home.img file. This filesystem is
112 encrypted by default. (One may bypass encryption with the
113 --unencrypted-home option.) This filesystem is mounted on the
114 /home directory of the root filesystem. When its storage space is
115 filled, out-of-space warnings will be issued by the operating
116 system.
117 When an OverlayFS overlay is requested (with the --overlayfs option),
119 any changes to the root filesytem are saved in a directory space that
120 is unioned by the kernel with the read-only root filesystem. With non-
121 vfat-formatted devices, the OverlayFS can extend the available root
122 filesystem space up to the capacity of the Live USB/SD device.
123
125 --format [sizemb[,fstype[,blksz[,extra_attr,s]]]]
126 Partitions and formats the target device, creates an MS-DOS
127 partition table or GUID partition table (GPT), if the --efi option
128 is passed, creates 1 to 3 partitions, and invokes the --reset-mbr
129 action.
130 NOTE WELL: All current disk content will be lost.
132 Partition 1 is sized as requested or as available & fstype
134 formatted. fstype may be: ext[432](ext4
135 default)|fat|vfat|msdos|btrfs|xfs|f2fs (extra_attr,s may be
136 passed to f2fs formatting, for example, "--format
137 f2fs,-,extra_attr,compression" Until GRUB's f2fs.mod is
138 updated, any extra_attr will require booting with an EFI Boot
139 Stub loader, such as the one from dracut triggered by the above
140 format request.) Partition 1 is labelled as before or
141 requested, flagged as bootable, and may allow an optional block
142 size.
143 Partition 2 is fat16 formatted and labelled 'EFI System
145 Partition'.
146 Partition 3 is HFS+ formatted and labelled as 'Mac'.
148 Creation of partitions 2 & 3 is dependent on the presence
150 of the files /images/efiboot.img & /images/macboot.img in
151 the source.
152 --msdos (a legacy option. Use the --format msdos syntax instead.)
154 Forces format to use the msdos (vfat) filesystem instead of ext4.
155 --efi|--mactel
157 Note: Even without this option, EFI components are always
158 configured and loaded on the target disk if they are present on the
159 source.
160 When --efi is used with --format, a GUID partition table (GPT) and
162 1 to 3 partitions are created. A hybrid Extensible Firmware
163 Interface (EFI)/MBR bootloader is installed on the disk.
164 This option is necessary for most Intel Macs.
166 When --efi is used without --format but with --reset-mbr, it loads
168 a hybrid (EFI)/MBR bootloader on the device.
169 --noesp (Used with --format)
171 Skips the formatting of a secondary EFI System Partition and an
172 Apple HFS+ boot partition.
173 Note: Even with this option, EFI components are configured and
175 loaded on the primary partition if they are present on the source.
176 --nomac (Used with --format)
178 Skips the formatting of an Apple HFS+ boot partition. Useful when
179 hfsplus-tools are not available.
180 --reset-mbr|--resetmbr
182 Sets the Master Boot Record (MBR) of the target storage device to
183 the mbr.bin or gptmbr.bin file from the installation system's
184 syslinux directory. This may be helpful in recovering a damaged or
185 corrupted device. Also sets the legacy_boot flag on the primary
186 partition for GPT disks.
187 --multi
189 Signals the boot configuration to accommodate multiple images on
190 the target device. Image and boot files will be installed under
191 the --livedir <directory>. SYSLINUX boot components from the
192 installation host will always update those in the boot path of the
193 target device. Boot files in the /EFI directories will be replaced
194 by files from the source if they have newer modified times.
195 --livedir <directory>
197 Designates the directory for installing the LiveOS image. The
198 default is /LiveOS.
199 --skipcopy|--reconfig
201 Skips the copying of the live image to the target device, bypassing
202 the action of the --format, --overlay-size-mb, --copy-overlay,
203 --home-size-mb, --copy-home, & --swap-size-mb options, if present
204 on the command line. (The --skipcopy option is useful while testing
205 the script, in order to avoid repeated and lengthy copy operations,
206 or with --reset-mbr to repair or reinstall the boot configuration
207 files on a previously installed LiveOS device.)
208 --noverify
210 Disables the image validation process that occurs before the image
211 is copied from the original Live CD .iso image. When this option
212 is specified, the image is not verified before it is copied onto
213 the target storage device.
214 --force
216 This option forces an overwrite of the --livedir image, its
217 syslinux directory, and associated files like home.img. This
218 allows the script to bypass a delete confirmation dialog in the
219 event that a pre-existing LiveOS directory is found on the target
220 device. It also skips writing a new boot entry in the current
221 system's UEFI boot manager for F2FS formatted target devices.
222 --xo
224 Used to prepare an image for the OLPC XO-1 laptop with its
225 compressed, JFFS2 filesystem. Do not use the following options
226 with --xo:
227 --overlay-size-mb <size>, home-size-mb <size>, --delete-home,
229 --compress
230 --xo-no-home
232 Used together with the --xo option to prepare an image for an OLPC
233 XO laptop with the /home directory on an SD card instead of the
234 internal flash storage.
235 --timeout <duration>
237 Modifies the bootloader's timeout value, which indicates how long
238 to pause at the boot prompt before booting automatically. This
239 overrides the value set during iso creation.
240 For SYSLINUX, a timeout unit is 1/10 second; the timeout is
242 canceled when any key is pressed (the assumption being that the
243 user will complete the command line); and a timeout of 0 will
244 disable the timeout completely.
245 For EFI GRUB, the timeout unit is 1 second; timeout specifies
247 the time to wait for keyboard input before booting the default
248 menu entry. A timeout of 0 means to boot the default entry
249 immediately without displaying the menu; and a timeout of "-1"
250 means to wait indefinitely.
251 Enter a desired timeout value in 1/10 second units (or "-1") and
253 the appropriate value will be supplied to the configuration file.
254 For immediate booting, enter "-0" to avoid the ambiguity between
255 systems. An entry of "-0" will result in an SYSLINUX setting of
256 timeout 1 and totaltimeout 1. 0 or "-1" will result in an SYSLINUX
257 setting of 0 (disable timeout, that is, wait indefinitely), but 0
258 for EFI GRUB will mean immediate boot of the default, while "-1"
259 will mean EFI GRUB waits indefinitely for a user selection.
260 --totaltimeout <duration>
262 Adds a SYSLINUX bootloader totaltimeout, which indicates how long
263 to wait before booting automatically. This is used to force an
264 automatic boot. This timeout cannot be canceled by the user.
265 Units are 1/10 s. A totaltimeout of 0 will disable the timeout
266 completely. (This setting is not available in EFI GRUB.)
267 --nobootmsg
269 Do not display boot.msg, usually, "Press the <ENTER> key to begin
270 the installation process."
271 --nomenu
273 Skip the boot menu, and automatically boot the 'linux' label item.
274 --extra-kernel-args <arg s>
276 Specifies additional kernel arguments, <arg s>, that will be
277 inserted into the syslinux and EFI boot configurations. Multiple
278 arguments should be specified in one string, i.e.,
279 --extra-kernel-args "arg1 arg2 ..."
280 --overlay-size-mb <size>[,fstype[,blksz]]
282 Specifies creation of a filesystem overlay of <size> mebibytes
283 (integer values only). [fstype] and [blksz] are relevant only for
284 creating OverlayFS overlay filesystems on vfat-formatted primary
285 devices. An overlay makes persistent storage available to the live
286 operating system, if permitted and installed on writable media.
287 The overlay holds a snapshot of changes to the root filesystem.
288 Note well that deletion of any original files in the read-only root
290 filesystem does not recover any storage space on your LiveOS
291 device. Storage in the persistent /LiveOS/overlay-<device_id> file
292 is allocated as needed. If the overlay storage space is filled,
293 the overlay will enter an 'Overflow' state where the root
294 filesystem will continue to operate in a read-only mode. There
295 will not be an explicit warning or signal when this happens, but
296 applications may begin to report errors due to the restriction. If
297 significant changes or updates to the root filesystem are to be
298 made, carefully watch the fraction of space allocated in the
299 overlay by issuing the "dmsetup status" command at a command line
300 of the running LiveOS image. Some consumption of root filesystem
301 and overlay space can be avoided by specifying a persistent home
302 filesystem for user files, see --home-size-mb below. The target
303 storage device must have enough free space for the image and the
304 overlay. A maximum <size> of 4096 MiB is permitted for vfat-
305 formatted devices. If there is not enough room on your device, you
306 will be given information to help in adjusting your settings.
307 --overlayfs [temp] (add --overlay-size-mb for persistence on vfat
309 devices)
310 Specifies the creation of an OverlayFS type overlay. If the option
311 is followed by "temp", a temporary overlay will be used. On vfat
312 or msdos formatted devices, --overlay-size-mb <size> must also be
313 provided for a persistent overlay. OverlayFS overlays are
314 directories of the files that have changed on the read-only root
315 filesystem. With non-vfat-formatted devices, the OverlayFS can
316 extend the available root filesystem space up to the capacity of
317 the Live USB device.
318 The --overlayfs option requires an initial boot image based on
320 dracut version 045 or greater to use the OverlayFS feature.
321 Lacking this, the device boots with a temporary Device-mapper
322 overlay.
323 --copy-overlay
325 This option allows one to copy the persistent overlay from one live
326 image to the new image. Changes already made in the source image
327 will be propagated to the new installation.
328 WARNING: User sensitive information such as password cookies
330 and application or user data will be copied to the new image!
331 Scrub this information before using this option.
332 --reset-overlay
334 This option will reset the persistent overlay to an unallocated
335 state. This might be used if installing a new or refreshed image
336 onto a device with an existing overlay, and avoids the writing of a
337 large file on a vfat-formatted device. This option also renames
338 the overlay to match the current device filesystem label and UUID.
339 --compress (default state for the original root filesystem)
341 The default, compressed SquashFS filesystem image is copied on
342 installation. (This option has no effect if the source filesystem
343 is already expanded.)
344 --skipcompress (default option when --xo is specified)
346 Expands the source squashfs.img on installation into the read-only
347 /LiveOS/rootfs.img root filesystem image file. This avoids the
348 system overhead of decompression during use at the expense of
349 storage space and bus I/O.
350 --no-overlay (effective only with --skipcompress or an uncompressed
352 image)
353 Installs a kernel option, "rd.live.overlay=none", that signals the
354 live boot process to create a writable, linear Device-mapper target
355 for an uncompressed /LiveOS/rootfs.img filesystem image file.
356 Read-write by default (unless a kernel argument of
357 "rd.live.overlay.readonly" is given) this configuration avoids the
358 complications of using an overlay of fixed size for persistence
359 when storage format and space allows.
360 --home-size-mb <size>[,fstype[,blksz]]
362 Specifies creation of a home filesystem of <size> mebibytes
363 (integer values only). A persistent home directory will be stored
364 in the /LiveOS/home.img filesystem image file. This filesystem is
365 encrypted by default and not compressed (one may bypass encryption
366 with the --unencrypted-home option). When the home filesystem
367 storage space is full, one will get out-of-space warnings from the
368 operating system. The target storage device must have enough free
369 space for the image, any overlay, and the home filesystem. Note
370 that the --delete-home option must also be selected to replace an
371 existing persistent home with a new, empty one. A maximum <size>
372 of 4096 MiB is permitted for vfat-formatted devices. If there is
373 not enough room on your device, you will be given information to
374 help in adjusting your settings.
375 --copy-home
377 This option allows one to copy a persistent home.img filesystem
378 from the source LiveOS image to the target image. Changes already
379 made in the source home directory will be propagated to the new
380 image.
381 WARNING: User-sensitive information, such as password cookies
383 and user and application data, will be copied to the new image!
384 Scrub this information before using this option.
385 --delete-home
387 One must explicitly select this option in the case where there is
388 an existing persistent home filesystem on the target device and the
389 --home-size-mb <size> option is selected to create an empty, new
390 home filesystem. This prevents unwitting deletion of user files.
391 --crypted-home (default that only applies to new home-size-mb
393 requests)
394 Specifies the default option to encrypt a new persistent home
395 filesystem when --home-size-mb <size> is specified.
396 --unencrypted-home
398 Prevents the default option to encrypt a new persistent home
399 directory filesystem.
400 --swap-size-mb <size>
402 Sets up a swap file of <size> mebibytes (integer values only) on
403 the target device. A maximum <size> of 4096 MiB is permitted for
404 vfat-formatted devices.
405 --updates <updates.img>
407 Setup a kernel command line argument, "inst.updates", to point to
408 an updates image on the device. Used by Anaconda for testing
409 updates to an iso without needing to make a new iso. <updates.img>
410 should be a path accessible to this script, which will be copied to
411 the target device.
412 --ks <kickstart>
414 Setup "inst.ks" to point to an kickstart file on the device. Use
415 this for automating package installs on boot. <kickstart> should be
416 a path accessible to this script, which will be copied to the
417 target device.
418 --label <label>
420 Specifies a specific filesystem label instead of the default
421 'LIVE'. Useful when you do unattended installs that pass a label to
422 inst.ks.
423 --help|-h|-?
425 Displays usage information and exits.
426
428 David Zeuthen, Jeremy Katz, Douglas McClendon, Chris Curran and other
429 contributors. See the AUTHORS file in the source distribution for the
430 complete list of credits.
431
433 Report bugs to the mailing list
434 <https://admin.fedoraproject.org/mailman/listinfo/livecd> or directly
435 to Bugzilla <https://bugzilla.redhat.com/bugzilla/> against the
436 "Fedora" product, and the "livecd-tools" component.
437
439 Copyright 2008-2010, 2017-2021, Fedora Project and various
440 contributors. This is free software. You may redistribute copies of it
441 under the terms of the GNU General Public License
442 <https://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the
443 extent permitted by law.
444
446 "livecd-creator(8)", project website
447 <https://fedoraproject.org/wiki/FedoraLiveCD>
448livecd-tools 31.0 2022-07-21 LIVECD-ISO-TO-DISK(8)