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  [--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
22       The script may be run in simplest form with just the two arguments:
23
24       livecd-iso-to-disk <source> <target partition/device>
25
26       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
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 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

DESCRIPTION

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
65       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
69       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
74       Multi image installations may be invoked interactively if the target
75       device already contains a LiveOS image.
76
77       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 filesystem—
93       even if it is supplied with an overlay file larger than the apparent
94       free space of the root filesystem.  Persistent OverlayFS directories
95       avoid this limitation by creating a working union of two filesystems to
96       serve as root filesystem.
97
98           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
118       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

OPTIONS

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
131           NOTE WELL: All current disk content will be lost.
132
133               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
144               Partition 2 is fat16 formatted and labelled 'EFI System
145               Partition'.
146
147               Partition 3 is HFS+ formatted and labelled as 'Mac'.
148
149                   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
153       --msdos   (a legacy option. Use the --format msdos syntax instead.)
154           Forces format to use the msdos (vfat) filesystem instead of ext4.
155
156       --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
161           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
165           This option is necessary for most Intel Macs.
166
167           When --efi is used without --format but with --reset-mbr, it loads
168           a hybrid (EFI)/MBR bootloader on the device.
169
170       --noesp    (Used with --format)
171           Skips the formatting of a secondary EFI System Partition and an
172           Apple HFS+ boot partition.
173
174           Note: Even with this option, EFI components are configured and
175           loaded on the primary partition if they are present on the source.
176
177       --nomac    (Used with --format)
178           Skips the formatting of an Apple HFS+ boot partition.  Useful when
179           hfsplus-tools are not available.
180
181       --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
188       --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
196       --livedir <directory>
197           Designates the directory for installing the LiveOS image.  The
198           default is /LiveOS.
199
200       --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
209       --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
215       --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
223       --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
228               --overlay-size-mb <size>, home-size-mb <size>, --delete-home,
229               --compress
230
231       --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
236       --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
241               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
246               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
252           Enter a desired timeout value in 1/10 second units (or -1) and the
253           appropriate value will be supplied to the configuration file.  For
254           immediate booting, enter -0 to avoid the ambiguity between systems.
255           An entry of -0 will result in an SYSLINUX setting of timeout 1 and
256           totaltimeout 1. 0 or -1 will result in an SYSLINUX setting of 0
257           (disable timeout, that is, wait indefinitely), but 0 for EFI GRUB
258           will mean immediate boot of the default, while -1 will mean EFI
259           GRUB waits indefinitely for a user selection.
260
261       --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
268       --nobootmsg
269           Do not display boot.msg, usually, "Press the <ENTER> key to begin
270           the installation process."
271
272       --nomenu
273           Skip the boot menu, and automatically boot the 'linux' label item.
274
275       --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
281       --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
289           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
308       --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
319           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
324       --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
329               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
333       --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
340       --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
345       --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
351       --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
361       --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
376       --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
382               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
386       --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
392       --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
397       --unencrypted-home
398           Prevents the default option to encrypt a new persistent home
399           directory filesystem.
400
401       --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
406       --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
413       --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
419       --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
424       --help|-h|-?
425           Displays usage information and exits.
426

CONTRIBUTORS

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

BUGS

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

SEE ALSO

446       "livecd-creator(8)", project website
447       <https://fedoraproject.org/wiki/FedoraLiveCD>
448
449
450
451livecd-tools 31.0                 2023-07-27             LIVECD-ISO-TO-DISK(8)
Impressum