LIVECD-ISO-TO-DISK(8)

📦
version 31.0 · 4 versions
, in epel 9

✨ NAME ✨

okay bestie, welcome to livecd-iso-to-disk(8) from the LiveCD Tools crew 💅 — this is the manual page for livecd-iso-to-disk, and it installs bootable Live images onto USB/SD storage devices. periodt.

🌸 SYNOPSIS 🌸

livecd-iso-to-disk  [--format [<size>[,fstype[,blksz[,extra_attr,s]]]]]
[--msdos] [--efi] [--noesp] [--reset-mbr] [--multi] [--livedir
<directory>] [--skipcopy] [--noverify] [--force] [--xo] [--xo-no-home]
[--timeout <duration>] [--totaltimeout <duration>] [--nobootmsg]
[--nomenu] [--extra-kernel-args <arg s>] [--compress] [--skipcompress]
[--no-overlay] [--overlayfs [temp]] [--overlay-size-mb
<size>[,fstype[,blksz]]] [--copy-overlay] [--reset-overlay]
[--home-size-mb <size>[,fstype,blksz]]] [--copy-home] [--delete-home]
[--crypted-home] [--unencrypted-home] [--swap-size-mb <size>] [--updates
<updates.img>] [--ks <kickstart>] [--label <label>] [--help]  <source>
<target partition/device>

The script may be run in simplest form with just the two arguments:

livecd-iso-to-disk <source> <target partition/device>

To execute the script to completion, you will need to run it with root user permissions. Legacy booting of the installed image requires that SYSLINUX is installed on the host computer running this script.

  • <source> — 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, the LiveOS-containing directory path, or the mount point for another LiveOS filesystem. Entering "live" for the <source> will source the currently booted LiveOS device. 🫶
  • <target partition/device> — This should be, or a link to, the device partition path for an attached, target device, such as /dev/sdc1. A virtual block device, such as a loop device or a Device-mapper target may also be used. (Issue the lsblk -pf command to get a list of attached partitions, so you can confirm the device names, filesystem types, and available space.) Be careful to specify the correct device, or you may overwrite important data on another disk! 😭 If you request formatting with the --format option, enter only the base device path, such as /dev/sdc. For a multi boot installation to the currently booted device, enter "live" as the target. 💀

🦋 DESCRIPTION 🦋

livecd-iso-to-disk installs a Live CD/DVD/USB image (LiveOS) onto a USB/SD storage device. The target storage device can then support booting 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. A loop device backed by a file may also be targeted for virtual block device installation. Additionally, a Device-mapper target construct for block devices may be used. If a Device-mapper mirror target is preconfigured, this target may be used to simultaneously target multiple physical devices. The source image may be either a LiveOS .iso file, or another reference to a LiveOS image, such as the device node for an attached device installed with a LiveOS image, its mount point, a loop device backed by a file containing an installed LiveOS image, or even the currently-running LiveOS image. ✨

A pre-sized overlay file or a free-space-sized OverlayFS directory may be created for saving changes in the root filesystem of the installed image onto persistent storage media.

Unless you request the --format option, installing an image does not destroy data outside of the LiveOS, syslinux, & EFI directories on your target device. This allows one to maintain other files on the target disk outside of the LiveOS filesystem. 🎀

Multi image installations may be invoked interactively if the target device already contains a LiveOS image.

LiveOS images employ embedded filesystems through the loop device, Device-mapper, or OverlayFS components of the Linux kernel. The filesystems are embedded within files or directories in the /LiveOS/ directory (by default) of the base filesystem on the storage device. The /LiveOS/squashfs.img file is a SquashFS format compressed image, which by default contains one directory and file, /LiveOS/rootfs.img, that contains the root filesystem for the installed distribution image. These both are read-only filesystems that are fixed in size usually to within a few GiB of the size of the full root filesystem at build time. At boot time, either a Device-mapper snapshot with a temporary, 32 GiB, sparse, in-memory, read-write, overlay is created for the root filesystem, or an OverlayFS directory may be configured during bootup if configured on disk or by kernel command line options. When one specifies a persistent, fixed-size, Device-mapper overlay to hold changes to the root filesystem, the build-time size of the root filesystem will limit the maximum size of the working root filesystem even if it is supplied with an overlay file larger than the apparent free space of the root filesystem. Persistent OverlayFS directories avoid this limitation by creating a working union of two filesystems to serve as root filesystem. 🧚

NOTE WELL: Deletion of any of the original files in the read-only root filesystem does not recover any storage space on your LiveOS device. Storage in a Device-mapper overlay is allocated as needed. If its overlay storage space is filled, the overlay will enter an 'Overflow' state while the root filesystem continues to operate in a read-only mode. There will not be an explicit warning or signal when this happens, but applications may begin to report errors due to this restriction. If many or large changes or updates to the root filesystem are to be made, carefully watch the fraction of space allocated in the overlay by issuing the command dmsetup status at a terminal or console of the running LiveOS image. Consumption of root filesystem and overlay space can be avoided by specifying a persistent home filesystem for user files, which will be saved in a fixed-size /LiveOS/home.img file. This filesystem is encrypted by default. (One may bypass encryption with the --unencrypted-home option.) This filesystem is mounted on the /home directory of the root filesystem. When its storage space is filled, out-of-space warnings will be issued by the operating system. 😭

When an OverlayFS overlay is requested (with the --overlayfs option), any changes to the root filesystem are saved in a directory space that is unioned by the kernel with the read-only root filesystem. With non-vfat-formatted devices, the OverlayFS can extend the available root filesystem space up to the capacity of the Live USB/SD device. 💜

💅 OPTIONS 💅

  • --format [sizemb[,fstype[,blksz[,extra_attr,s]]]] — Partitions and formats the target device, creates an MS-DOS partition table or GUID partition table (GPT), if the --efi option is passed, creates 1 to 3 partitions, and invokes the --reset-mbr action.
NOTE WELL: All current disk content will be lost. 💀
  • Partition 1 is sized as requested or as available & fstype formatted. fstype may be: ext[432](ext4 default)|fat|vfat|msdos|btrfs|xfs|f2fs (extra_attr,s may be passed to f2fs formatting, for example, "--format f2fs,-,extra_attr,compression" Until GRUB's f2fs.mod is updated, any extra_attr will require booting with an EFI Boot Stub loader, such as the one from dracut triggered by the above format request.) Partition 1 is labelled as before or requested, flagged as bootable, and may allow an optional block size.
  • Partition 2 is fat16 formatted and labelled 'EFI System Partition'.
  • Partition 3 is HFS+ formatted and labelled as 'Mac'.
  • Creation of partitions 2 & 3 is dependent on the presence of the files /images/efiboot.img & /images/macboot.img in the source.
  • --msdos — (a legacy option. Use the --format msdos syntax instead.) Forces format to use the msdos (vfat) filesystem instead of ext4.
  • --efi|--mactel — Note: Even without this option, EFI components are always configured and loaded on the target disk if they are present on the source. When --efi is used with --format, a GUID partition table (GPT) and 1 to 3 partitions are created. A hybrid Extensible Firmware Interface (EFI)/MBR bootloader is installed on the disk. This option is necessary for most Intel Macs. When --efi is used without --format but with --reset-mbr, it loads a hybrid (EFI)/MBR bootloader on the device. 👑
  • --noesp — (Used with --format) Skips the formatting of a secondary EFI System Partition and an Apple HFS+ boot partition. Note: Even with this option, EFI components are configured and loaded on the primary partition if they are present on the source.
  • --nomac — (Used with --format) Skips the formatting of an Apple HFS+ boot partition. Useful when hfsplus-tools are not available.
  • --reset-mbr|--resetmbr — Sets the Master Boot Record (MBR) of the target storage device to the mbr.bin or gptmbr.bin file from the installation system's syslinux directory. This may be helpful in recovering a damaged or corrupted device. Also sets the legacy_boot flag on the primary partition for GPT disks. 🛠️
  • --multi — Signals the boot configuration to accommodate multiple images on the target device. Image and boot files will be installed under the --livedir <directory>. SYSLINUX boot components from the installation host will always update those in the boot path of the target device. Boot files in the /EFI directories will be replaced by files from the source if they have newer modified times.
  • --livedir <directory> — Designates the directory for installing the LiveOS image. The default is /LiveOS.
  • --skipcopy|--reconfig — Skips the copying of the live image to the target device, bypassing the action of the --format, --overlay-size-mb, --copy-overlay, --home-size-mb, --copy-home, & --swap-size-mb options, if present on the command line. (The --skipcopy option is useful while testing the script, in order to avoid repeated and lengthy copy operations, or with --reset-mbr to repair or reinstall the boot configuration files on a previously installed LiveOS device.) 🙈
  • --noverify — Disables the image validation process that occurs before the image is copied from the original Live CD .iso image. When this option is specified, the image is not verified before it is copied onto the target storage device.
  • --force — the "no thoughts, just send it" option 💅 it forces an overwrite of the --livedir image, its syslinux directory, and all the associated files like home.img. Basically it lets the script skip the delete-confirmation dialog that pops up when it finds a pre-existing LiveOS directory on the target device. It also skips writing a new boot entry in the current system's UEFI boot manager for F2FS-formatted target devices. so it's giving "bypass the vibe check entirely" ✨
  • --xo — this one preps an image for the OLPC XO-1 laptop, with its compressed, JFFS2 filesystem. 🎀 but heads up bestie, do not use these options with --xo:
    • --overlay-size-mb <size>
    • home-size-mb <size>
    • --delete-home
    • --compress
  • --xo-no-home — used together with --xo to prep an image for an OLPC XO laptop where the /home directory lives on an SD card instead of the internal flash storage. 🦋
  • --timeout <duration> — changes the bootloader's timeout value, which is how long it pauses at the boot prompt before booting automatically. This overrides whatever value was set during iso creation. ⏰
    • For SYSLINUX, one timeout unit = 1/10 second; the timeout gets canceled when any key is pressed (the assumption being the user will finish typing the command line); and a timeout of 0 disables the timeout completely.
    • For EFI GRUB, the timeout unit is 1 second; timeout specifies how long to wait for keyboard input before booting the default menu entry. A timeout of 0 means boot the default entry immediately without displaying the menu; and a timeout of "-1" means wait indefinitely.

Enter the timeout value you want in 1/10 second units (or "-1") and the appropriate value gets supplied to the configuration file. For immediate booting, enter "-0" to dodge the ambiguity between the two systems. An entry of "-0" results in a SYSLINUX setting of timeout 1 and totaltimeout 1. 0 or "-1" results in a SYSLINUX setting of 0 (that's disable timeout, aka wait indefinitely), but 0 for EFI GRUB means immediate boot of the default, while "-1" means EFI GRUB waits indefinitely for a user selection. 💀

  • --totaltimeout <duration> — adds a SYSLINUX bootloader totaltimeout, which is how long to wait before booting automatically. It's used to force an automatic boot, and this timeout cannot be canceled by the user. Units are 1/10 s. A totaltimeout of 0 disables the timeout completely. (This setting is not available in EFI GRUB, fyi.) 🫶
  • --nobootmsg — don't display boot.msg — which is usually "Press the <ENTER> key to begin the installation process." 🙈
  • --nomenu — skips the boot menu and just automatically boots the 'linux' label item. main character energy, no menu needed 👑
  • --extra-kernel-args <arg s> — specifies additional kernel arguments, <arg s>, that get inserted into the syslinux and EFI boot configurations. Multiple arguments should go in one string, i.e. --extra-kernel-args "arg1 arg2 ..." ✨
  • --overlay-size-mb <size>[,fstype[,blksz]] — specifies creation of a filesystem overlay of <size> mebibytes (integer values only). [fstype] and [blksz] are relevant only for creating OverlayFS overlay filesystems on vfat-formatted primary devices. An overlay makes persistent storage available to the live operating system, if permitted and installed on writable media. The overlay holds a snapshot of changes to the root filesystem. 📸
Note well bestie: deleting original files in the read-only root filesystem does not recover any storage space on your LiveOS device. Storage in the persistent /LiveOS/overlay-<device_id> file is allocated as needed. If the overlay storage space fills up, the overlay enters an 'Overflow' state where the root filesystem continues operating in read-only mode. There will not be an explicit warning or signal when this happens, but applications may start reporting errors because of the restriction. 😭 If significant changes or updates to the root filesystem are going to be made, carefully watch the fraction of space allocated in the overlay by issuing the "dmsetup status" command at a command line of the running LiveOS image. Some consumption of root filesystem and overlay space can be avoided by specifying a persistent home filesystem 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 4096 MiB is permitted for vfat-formatted devices. If there isn't enough room on your device, you'll be given information to help adjust your settings.
  • --overlayfs [temp] — (add --overlay-size-mb for persistence on vfat devices) specifies the creation of an OverlayFS type overlay. If the option is followed by "temp", a temporary overlay will be used. On vfat or msdos formatted devices, --overlay-size-mb <size> must also be provided for a persistent overlay. OverlayFS overlays are directories of the files that have changed on the read-only root filesystem. With non-vfat-formatted devices, the OverlayFS can extend the available root filesystem space up to the capacity of the Live USB device. 🌈

The --overlayfs option requires an initial boot image based on dracut version 045 or greater to use the OverlayFS feature. Without that, the device boots with a temporary Device-mapper overlay.

  • --copy-overlay — lets you copy the persistent overlay from one live image to the new image. Changes already made in the source image get propagated to the new installation. 🎀
WARNING: User sensitive information such as password cookies and application or user data will be copied to the new image! Scrub this information before using this option. 🚨
  • --reset-overlay — resets the persistent overlay to an unallocated state. Could be used if you're installing a new or refreshed image onto a device with an existing overlay, and it avoids writing a large file on a vfat-formatted device. This option also renames the overlay to match the current device filesystem label and UUID. 🧚
  • --compress — (default state for the original root filesystem) the default, compressed SquashFS filesystem image is copied on installation. (This option has no effect if the source filesystem is already expanded.) 💜
  • --skipcompress — (default option when --xo is specified) expands the source squashfs.img on installation into the read-only /LiveOS/rootfs.img root filesystem image file. This avoids the system overhead of decompression during use, at the expense of storage space and bus I/O. 🔥
  • --no-overlay — (effective only with --skipcompress or an uncompressed image) installs a kernel option, "rd.live.overlay=none", that signals the live boot process to create a writable, linear Device-mapper target for an uncompressed /LiveOS/rootfs.img filesystem image file. Read-write by default (unless a kernel argument of "rd.live.overlay.readonly" is given), this configuration avoids the complications of using an overlay of fixed size for persistence when storage format and space allow. ⭐
  • --home-size-mb <size>[,fstype[,blksz]] — specifies creation of a home filesystem of <size> mebibytes (integer values only). A persistent home directory gets stored in the /LiveOS/home.img filesystem image file. This filesystem is encrypted by default and not compressed (you can bypass encryption with the --unencrypted-home option). When the home filesystem storage space is full, you'll get out-of-space warnings from the operating system. The target storage device must have enough free space for the image, any overlay, and the home filesystem. 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 4096 MiB is permitted for vfat-formatted devices. If there isn't enough room on your device, you'll be given information to help adjust your settings. 🌸
  • --copy-home — lets you copy a persistent home.img filesystem from the source LiveOS image to the target image. Changes already made in the source home directory get propagated to the new image. 🫶
WARNING: User-sensitive information, such as password cookies and user and application data, will be copied to the new image! Scrub this information before using this option. 🚨
  • --delete-home — you must explicitly select this option when there's an existing persistent home filesystem on the target device and the --home-size-mb <size> option is selected to create an empty, new home filesystem. It prevents unwitting deletion of user files. 🙈
  • --crypted-home — (default that only applies to new home-size-mb requests) specifies the default option to encrypt a new persistent home filesystem when --home-size-mb <size> is specified. 🔐
  • --unencrypted-home — prevents that default option to encrypt a new persistent home directory filesystem. 💅
  • --swap-size-mb <size> — sets up a swap file of <size> mebibytes (integer values only) on the target device. A maximum <size> of 4096 MiB is permitted for vfat-formatted devices. ⚡
  • --updates <updates.img> — sets up a kernel command line argument, "inst.updates", pointing to an updates image on the device. Used by Anaconda for testing updates to an iso without needing to make a new iso. <updates.img> should be a path accessible to this script, which will be copied to the target device. 🦋
  • --ks <kickstart> — sets up "inst.ks" to point to a kickstart file on the device. Use this for automating package installs on boot. <kickstart> should be a path accessible to this script, which will be copied to the target device. ✨
  • --label <label> — specifies a specific filesystem label instead of the default 'LIVE'. Useful when you do unattended installs that pass a label to inst.ks. 🎀
  • --help|-h|-? — displays usage information and exits. the classic 😌

💖 CONTRIBUTORS 💖

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. 🫶

🐛 BUGS 🐛

Report bugs to the mailing list <https://admin.fedoraproject.org/mailman/listinfo/livecd> or directly to Bugzilla <https://bugzilla.redhat.com/bugzilla/> against the "Fedora" product, and the "livecd-tools" component. ngl they'd love to hear from you 💀💖

Copyright 2008-2010, 2017-2021, Fedora Project and various contributors.

This is free software, bestie. You may redistribute copies of it under the terms of the GNU General Public License <https://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.

fr fr, "NO WARRANTY" is in all caps for a reason — no cap, nobody's coming to save your data if this goes sideways, so read the license 💀

🦋 SEE ALSO 🦋

and that's the whole page, bestie 🫶 You just read livecd-tools version 31.0, dated 2025-07-04 — screenshot it, bookmark it, tattoo it on your forearm, whatever works 💅 mwah, go make some bootable media, and remember: dd does not ask twice 🔥👑

📦 where this page comes from