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 [--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 Simplest
21 The script may be run in simplest form with just the two arguments:
23 livecd-iso-to-disk <source> <target device>
25 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 <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 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
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. The script requires a LiveOS source image and a
53 target storage device. A loop device backed by a file may also be
54 targeted for virtual block device installation. The source image may
55 be either a LiveOS .iso file, or another reference to a LiveOS image,
56 such as the device node for an attached device installed with a LiveOS
57 image, its mount point, a loop device backed by a file containing an
58 installed LiveOS image, or even the currently-running LiveOS image. A
59 pre-sized overlay file for persisting root filesystem changes may be
60 included with the installed image.
61 Unless you request the --format option, installing an image does not
63 destroy data outside of the LiveOS, syslinux, & EFI directories on your
64 target device. This allows one to maintain other files on the target
65 disk outside of the LiveOS filesystem.
66 Multi image installations may be invoked interactively if the target
68 device already contains a LiveOS image.
69 LiveOS images employ embedded filesystems through the Device-mapper
71 component of the Linux kernel. The filesystems are embedded within
72 files in the /LiveOS/ directory of the storage device. The
73 /LiveOS/squashfs.img file is the default, compressed filesystem
74 containing one directory and the file /LiveOS/rootfs.img that contains
75 the root filesystem for the distribution. These are read-only
76 filesystems that are usually fixed in size to within a few GiB of the
77 size of the full root filesystem at build time. At boot time, a
78 Device-mapper snapshot with a sparse 32 GiB, in-memory, read-write
79 overlay is created for the root filesystem. Optionally, one may
80 specify a fixed-size, persistent on disk overlay to hold changes to the
81 root filesystem. The build-time size of the root filesystem will limit
82 the maximum size of the working root filesystem--even if supplied with
83 an overlay file larger than the apparent free space on the root
84 filesystem. *Note well* that deletion of any original files in the
85 read-only root filesystem does not recover any storage space on your
86 LiveOS device. Storage in the persistent /LiveOS/overlay-<device_id>
87 file is allocated as needed. If the overlay storage space is filled,
88 the overlay will enter an 'Overflow' state where the root filesystem
89 will continue to operate in a read-only mode. There will not be an
90 explicit warning or signal when this happens, but applications may
91 begin to report errors due to this restriction. If significant changes
92 or updates to the root filesystem are to be made, carefully watch the
93 fraction of space allocated in the overlay by issuing the 'dmsetup
94 status' command at a command line of the running LiveOS image. Some
95 consumption of root filesystem and overlay space can be avoided by
96 specifying a persistent home filesystem for user files, which will be
97 saved in a fixed-size /LiveOS/home.img file. This filesystem is
98 encrypted by default. (One may bypass encryption with the
99 --unencrypted-home option.) This filesystem is mounted on the /home
100 directory of the root filesystem. When its storage space is filled,
101 out-of-space warnings will be issued by the operating system.
102
104 --help|-h|-?
105 Displays usage information and exits.
106 --noverify
108 Disables the image validation process that occurs before the image
109 is copied from the original Live CD .iso image. When this option
110 is specified, the image is not verified before it is copied onto
111 the target storage device.
112 --format
114 Formats the target device and creates an MS-DOS partition table (or
115 GUID partition table, if the --efi option is passed).
116 --msdos
118 Forces format to use the msdos (vfat) filesystem instead of ext4.
119 --reset-mbr|--resetmbr
121 Sets the Master Boot Record (MBR) of the target storage device to
122 the mbr.bin file from the installation system's syslinux directory.
123 This may be helpful in recovering a damaged or corrupted device.
124 --efi|--mactel
126 Creates a GUID partition table when --format is passed, and
127 installs a hybrid Extensible Firmware Interface (EFI)/MBR
128 bootloader on the disk. This is necessary for most Intel Macs.
129 --skipcopy
131 Skips the copying of the live image to the target device, bypassing
132 the action of the --format, --overlay-size-mb, --copy-overlay,
133 --home-size-mb, --copy-home, & --swap-size-mb options, if present
134 on the command line. (The --skipcopy option may be used while
135 testing the script, in order to avoid repeated and lengthy copy
136 commands, or with --reset-mbr to repair the boot configuration
137 files on a previously installed LiveOS device.)
138 --force
140 This option allows the installation script to bypass a delete
141 confirmation dialog in the event that a pre-existing LiveOS
142 directory is found on the target device.
143 --xo
145 Used to prepare an image for the OLPC XO-1 laptop with its
146 compressed, JFFS2 filesystem. Do not use the following options
147 with --xo:
148 --overlay-size-mb <size>, home-size-mb <size>, --delete-home,
150 --compress
151 --xo-no-home
153 Used together with the --xo option to prepare an image for an OLPC
154 XO laptop with the home directory on an SD card instead of the
155 internal flash storage.
156 --timeout <duration>
158 Modifies the bootloader's timeout value, which indicates how long
159 to pause at the boot prompt before booting automatically. This
160 overrides the value set during iso creation.
161 For SYSLINUX, a timeout unit is 1/10 second; the timeout is
163 canceled when any key is pressed (the assumption being that the
164 user will complete the command line); and a timeout of zero
165 will disable the timeout completely.
166 For EFI GRUB, the timeout unit is 1 second; timeout specifies
168 the time to wait for keyboard input before booting the default
169 menu entry. A timeout of '0' means to boot the default entry
170 immediately without displaying the menu; and a timeout of '-1'
171 means to wait indefinitely.
172 Enter a desired timeout value in 1/10 second units (or '-1') and
174 the appropriate value will be supplied to the configuration file.
175 For immediate booting, enter '-0' to avoid the ambiguity between
176 systems. An entry of '-0' will result in an SYSLINUX setting of
177 timeout 1 and totaltimeout 1. '0' or '-1' will result in an
178 SYSLINUX setting of '0' (disable timeout, that is, wait
179 indefinitely), but '0' for EFI GRUB will mean immediate boot of the
180 default, while '-1' will mean EFI GRUB waits indefinitely for a
181 user selection.
182 --totaltimeout <duration>
184 Adds a SYSLINUX bootloader totaltimeout, which indicates how long
185 to wait before booting automatically. This is used to force an
186 automatic boot. This timeout cannot be canceled by the user.
187 Units are 1/10 s. A totaltimeout of zero will disable the timeout
188 completely. (This setting is not available in EFI GRUB.)
189 --nobootmsg
191 Do not display boot.msg, usually, \"Press the <ENTER> key to begin
192 the installation process.\"
193 --nomenu
195 Skip the boot menu, and automatically boot the 'linux' label item.
196 --extra-kernel-args <args>
198 Specifies additional kernel arguments, <args>, that will be
199 inserted into the syslinux and EFI boot configurations. Multiple
200 arguments should be specified in one string, i.e.,
201 --extra-kernel-args "arg1 arg2 ..."
202 --multi
204 Signals the boot configuration to accommodate multiple images on
205 the target device. Image and boot files will be installed under
206 the --livedir <directory>. SYSLINUX boot components from the
207 installation host will always update those in the boot path of the
208 target device.
209 --livedir <dir>
211 Designates the directory for installing the LiveOS image. The
212 default is /LiveOS.
213 --compress (default state for the original root filesystem)
215 The default, compressed SquashFS filesystem image is copied on
216 installation. (This option has no effect if the source filesystem
217 is already expanded.)
218 --skipcompress (default option when --xo is specified)
220 Expands the source SquashFS.img on installation into the read-only
221 /LiveOS/rootfs.img root filesystem image file. This avoids the
222 system overhead of decompression during use at the expense of
223 storage space and bus I/O.
224 --no-overlay (effective only with --skipcompress or an uncompressed
226 image)
227 Installs a kernel option, rd.live.overlay=none, that signals the
228 live boot process to create a writable, linear Device-mapper target
229 for an uncompressed /LiveOS/rootfs.img filesystem image file.
230 Read-write by default (unless a kernel argument of
231 rd.live.overlay.readonly is given) this configuration avoids the
232 complications of using an overlay of fixed size for persistence
233 when storage format and space allows.
234 --overlayfs [temp] (add --overlay-size-mb for persistence on vfat
236 devices)
237 Specifies the creation of an OverlayFS type overlay. If the option
238 is followed by 'temp', a temporary overlay will be used. On vfat
239 or msdos formatted devices, --overlay-size-mb <size> must also be
240 provided for a persistent overlay. OverlayFS overlays are
241 directories of the files that have changed on the read-only root
242 filesystem. With non-vfat-formatted devices, the OverlayFS can
243 extend the available root filesystem space up to the capacity of
244 the Live USB device.
245 The --overlayfs option requires an initial boot image based on
247 dracut version 045 or greater to use the OverlayFS feature.
248 Lacking this, the device boots with a temporary Device-mapper
249 overlay.
250 --overlay-size-mb <size>
252 Specifies creation of a filesystem overlay of <size> mebibytes
253 (integer values only). The overlay makes persistent storage
254 available to the live operating system, if the operating system
255 supports it. The overlay holds a snapshot of changes to the root
256 filesystem. *Note well* that deletion of any original files in the
257 read-only root filesystem does not recover any storage space on
258 your LiveOS device. Storage in the persistent
259 /LiveOS/overlay-<device_id> file is allocated as needed. If the
260 overlay storage space is filled, the overlay will enter an
261 'Overflow' state where the root filesystem will continue to operate
262 in a read-only mode. There will not be an explicit warning or
263 signal when this happens, but applications may begin to report
264 errors due to the restriction. If significant changes or updates
265 to the root filesystem are to be made, carefully watch the fraction
266 of space allocated in the overlay by issuing the 'dmsetup status'
267 command at a command line of the running LiveOS image. Some
268 consumption of root filesystem and overlay space can be avoided by
269 specifying a persistent home filesystem for user files, see
270 --home-size-mb below. The target storage device must have enough
271 free space for the image and the overlay. A maximum <size> of 4095
272 MiB is permitted for vfat-formatted devices. If there is not
273 enough room on your device, you will be given information to help
274 in adjusting your settings.
275 --copy-overlay
277 This option allows one to copy the persistent overlay from one live
278 image to the new image. Changes already made in the source image
279 will be propagated to the new installation.
280 WARNING: User sensitive information such as password cookies
282 and application or user data will be copied to the new image!
283 Scrub this information before using this option.
284 --reset-overlay
286 This option will reset the persistent overlay to an unallocated
287 state. This might be used if installing a new or refreshed image
288 onto a device with an existing overlay, and avoids the writing of a
289 large file on a vfat-formatted device. This option also renames
290 the overlay to match the current device filesystem label and UUID.
291 --home-size-mb <size>
293 Specifies creation of a home filesystem of <size> mebibytes
294 (integer values only). A persistent home directory will be stored
295 in the /LiveOS/home.img filesystem image file. This filesystem is
296 encrypted by default and not compressed (one may bypass encryption
297 with the --unencrypted-home option). When the home filesystem
298 storage space is full, one will get out-of-space warnings from the
299 operating system. The target storage device must have enough free
300 space for the image, any overlay, and the home filesystem. Note
301 that the --delete-home option must also be selected to replace an
302 existing persistent home with a new, empty one. A maximum <size>
303 of 4095 MiB is permitted for vfat-formatted devices. If there is
304 not enough room on your device, you will be given information to
305 help in adjusting your settings.
306 --copy-home
308 This option allows one to copy a persistent home.img filesystem
309 from the source LiveOS image to the target image. Changes already
310 made in the source home directory will be propagated to the new
311 image.
312 WARNING: User-sensitive information, such as password cookies
314 and user and application data, will be copied to the new image!
315 Scrub this information before using this option.
316 --delete-home
318 One must explicitly select this option in the case where there is
319 an existing persistent home filesystem on the target device and the
320 --home-size-mb <size> option is selected to create an empty, new
321 home filesystem. This prevents unwitting deletion of user files.
322 --crypted-home (default that only applies to new home-size-mb
324 requests)
325 Specifies the default option to encrypt a new persistent home
326 filesystem when --home-size-mb <size> is specified.
327 --unencrypted-home
329 Prevents the default option to encrypt a new persistent home
330 directory filesystem.
331 --swap-size-mb <size>
333 Sets up a swap file of <size> mebibytes (integer values only) on
334 the target device. A maximum <size> of 4095 MiB is permitted for
335 vfat-formatted devices.
336 --updates <updates.img>
338 Setup a kernel command line argument, inst.updates, to point to an
339 updates image on the device. Used by Anaconda for testing updates
340 to an iso without needing to make a new iso. <updates.img> should
341 be a path accessible to this script, which will be copied to the
342 target device.
343 --ks <kickstart>
345 Setup inst.ks to point to an kickstart file on the device. Use this
346 for automating package installs on boot. <kickstart> should be a
347 path accessible to this script, which will be copied to the target
348 device.
349 --label <label>
351 Specifies a specific filesystem label instead of default LIVE.
352 Useful when you do unattended installs that pass a label to inst.ks
353
355 David Zeuthen, Jeremy Katz, Douglas McClendon, Chris Curran and other
356 contributors. See the AUTHORS file in the source distribution for the
357 complete list of credits.
358
360 Report bugs to the mailing list
361 "http://admin.fedoraproject.org/mailman/listinfo/livecd" or directly to
362 Bugzilla "http://bugzilla.redhat.com/bugzilla/" against the "Fedora"
363 product, and the "livecd-tools" component.
364
366 Copyright 2008-2010, 2017, Fedora Project and various contributors.
367 This is free software. You may redistribute copies of it under the
368 terms of the GNU General Public License
369 "http://www.gnu.org/licenses/gpl.html". There is NO WARRANTY, to the
370 extent permitted by law.
371
373 "livecd-creator(1)", project website
374 "http://fedoraproject.org/wiki/FedoraLiveCD"
375livecd-tools 27.1 2020-01-29 LIVECD-ISO-TO-DISK(8)