livecd-iso-to-disk man page
livecd-iso-to-disk — Installs bootable Live images onto USB/SD storage devices.
livecd-iso-to-disk [--help] [--noverify] [--format] [--msdos] [--reset-mbr] [--efi] [--skipcopy] [--force] [--xo] [--xo-no-home] [--timeout <duration>] [--totaltimeout <duration>] [--nobootmsg] [--nomenu] [--extra-kernel-args <args>] [--multi] [--livedir <dir>] [--compress] [--skipcompress] [--no-overlay] [--overlayfs [temp]] [--overlay-size-mb <size>] [--copy-overlay] [--reset-overlay] [--home-size-mb <size>] [--copy-home] [--delete-home] [--crypted-home] [--unencrypted-home] [--swap-size-mb <size>] [--updates <updates.img>] [--ks <kickstart>] [--label <label>] <source> <target device>
The script may be run in simplest form with just the two arguments:
livecd-iso-to-disk <source> <target device>
To execute the script to completion, you will need to run it with root user permissions. SYSLINUX must be installed on the computer running this script.
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 device>
This should be, or a link to, the device partition path for the attached, target device, such as /dev/sdc1. (Issue the df -Th command to get a listing of mounted partitions, so you can confirm the filesystem types, available space, and device names.) Be careful to specify the correct device, or you may overwrite important data on another disk! For a multi boot installation to the currently booted device, enter 'live' as the target.
livecd-iso-to-disk installs a Live CD/DVD/USB image (LiveOS) onto a USB/SD storage device (or any storage partition that will boot with a SYSLINUX bootloader). The target storage device can then boot 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. 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. 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 for persisting root filesystem changes may be included with the installed image.
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.
LiveOS images employ embedded filesystems through the Device-mapper component of the Linux kernel. The filesystems are embedded within files in the /LiveOS/ directory of the storage device. The /LiveOS/squashfs.img file is the default, compressed filesystem containing one directory and the file /LiveOS/rootfs.img that contains the root filesystem for the distribution. These are read-only filesystems that are usually fixed in size to within a few GiB of the size of the full root filesystem at build time. At boot time, a Device-mapper snapshot with a sparse 32 GiB, in-memory, read-write overlay is created for the root filesystem. Optionally, one may specify a fixed-size, persistent on disk 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 supplied with an overlay file larger than the apparent free space on the root filesystem. *Note well* that deletion of any 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 is filled, the overlay will enter an 'Overflow' state where the root filesystem will continue 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 significant changes or updates to the root filesystem are 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, 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.
Displays usage information and exits.
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.
Formats the target device and creates an MS-DOS partition table (or GUID partition table, if the --efi option is passed).
Forces format to use the msdos (vfat) filesystem instead of ext4.
Sets the Master Boot Record (MBR) of the target storage device to the mbr.bin file from the installation system's syslinux directory. This may be helpful in recovering a damaged or corrupted device.
Creates a GUID partition table when --format is passed, and installs a hybrid Extensible Firmware Interface (EFI)/MBR bootloader on the disk. This is necessary for most Intel Macs.
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 may be used while testing the script, in order to avoid repeated and lengthy copy commands, or with --reset-mbr to repair the boot configuration files on a previously installed LiveOS device.)
This option allows the installation script to bypass a delete confirmation dialog in the event that a pre-existing LiveOS directory is found on the target device.
Used to prepare an image for the OLPC XO-1 laptop with its compressed, JFFS2 filesystem. Do not use the following options with --xo:
Used together with the --xo option to prepare an image for an OLPC XO laptop with the home directory on an SD card instead of the internal flash storage.
- --timeout <duration>
Modifies the bootloader's timeout value, which indicates how long to pause at the boot prompt before booting automatically. This overrides the value set during iso creation.
For SYSLINUX, a timeout unit is 1/10 second; the timeout is canceled when any key is pressed (the assumption being that the user will complete the command line); and a timeout of zero will disable the timeout completely.
For EFI GRUB, the timeout unit is 1 second; timeout specifies the time to wait for keyboard input before booting the default menu entry. A timeout of '0' means to boot the default entry immediately without displaying the menu; and a timeout of '-1' means to wait indefinitely.
Enter a desired timeout value in 1/10 second units (or '-1') and the appropriate value will be supplied to the configuration file. For immediate booting, enter '-0' to avoid the ambiguity between systems. An entry of '-0' will result in an SYSLINUX setting of timeout 1 and totaltimeout 1. '0' or '-1' will result in an SYSLINUX setting of '0' (disable timeout, that is, wait indefinitely), but '0' for EFI GRUB will mean immediate boot of the default, while '-1' will mean EFI GRUB waits indefinitely for a user selection.
- --totaltimeout <duration>
Adds a SYSLINUX bootloader totaltimeout, which indicates how long to wait before booting automatically. This is used to force an automatic boot. This timeout cannot be canceled by the user. Units are 1/10 s. A totaltimeout of zero will disable the timeout completely. (This setting is not available in EFI GRUB.)
Do not display boot.msg, usually, \"Press the <ENTER> key to begin the installation process.\"
Skip the boot menu, and automatically boot the 'linux' label item.
- --extra-kernel-args <args>
Specifies additional kernel arguments, <args>, that will be inserted into the syslinux and EFI boot configurations. Multiple arguments should be specified in one string, i.e., --extra-kernel-args "arg1 arg2 ..."
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.
- --livedir <dir>
Designates the directory for installing the LiveOS image. The default is /LiveOS.
- --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 allows.
- --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. Lacking this, the device boots with a temporary Device-mapper overlay.
- --overlay-size-mb <size>
Specifies creation of a filesystem overlay of <size> mebibytes (integer values only). The overlay makes persistent storage available to the live operating system, if the operating system supports it. The overlay holds a snapshot of changes to the root filesystem. *Note well* that deletion of any 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 is filled, the overlay will enter an 'Overflow' state where the root filesystem will continue 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 the restriction. If significant changes or updates to the root filesystem are 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 4095 MiB is permitted for vfat-formatted devices. If there is not enough room on your device, you will be given information to help in adjusting your settings.
This option allows one to copy the persistent overlay from one live image to the new image. Changes already made in the source image will be 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.
This option will reset the persistent overlay to an unallocated state. This might be used if installing a new or refreshed image onto a device with an existing overlay, and avoids the writing of a large file on a vfat-formatted device. This option also renames the overlay to match the current device filesystem label and UUID.
- --home-size-mb <size>
Specifies creation of a home filesystem of <size> mebibytes (integer values only). A persistent home directory will be stored in the /LiveOS/home.img filesystem image file. This filesystem is encrypted by default and not compressed (one may bypass encryption with the --unencrypted-home option). When the home filesystem storage space is full, one will 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 4095 MiB is permitted for vfat-formatted devices. If there is not enough room on your device, you will be given information to help in adjusting your settings.
This option allows one to copy a persistent home.img filesystem from the source LiveOS image to the target image. Changes already made in the source home directory will be 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.
One must explicitly select this option in the case where there is 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. This 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.
Prevents the 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 4095 MiB is permitted for vfat-formatted devices.
- --updates <updates.img>
Setup a kernel command line argument, inst.updates, to point to an updates image on the device. Used by Anaconda for testing updates to an iso without needing to make a new iso.
- --ks <kickstart>
Setup inst.ks to point to an kickstart file on the device. Use this for automating package installs on boot.
- --label <label>
Specifies a specific filesystem label instead of default LIVE. Useful when you do unattended installs that pass a label to inst.ks
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.
Report bugs to the mailing list
"http://admin.fedoraproject.org/mailman/listinfo/livecd" or directly to Bugzilla
"http://bugzilla.redhat.com/bugzilla/" against the
"Fedora" product, and the
Copyright 2008-2010, 2017, Fedora Project and various contributors. This is free software. You may redistribute copies of it under the terms of the GNU General Public License
"http://www.gnu.org/licenses/gpl.html". There is NO WARRANTY, to the extent permitted by law.
"livecd-creator(1)", project website