Livecd-iso-to-disk

From FedoraProject

Revision as of 19:01, 19 June 2010 by Fgrose (Talk | contribs)

Jump to: navigation, search


livecd-iso-to-disk.sh is a bash shell script supplied with livecd-tools, http://git.fedoraproject.org/git/?p=hosted/livecd;a=tree;f=tools;hb=HEAD.

Usage is documented in livecd-iso-to-disk.pod, in http://git.fedoraproject.org/git/?p=hosted/livecd;a=tree;f=docs;hb=HEAD, which was copied here for easy revision and review on 05 April 2010. The revision history of this page shows the proposed changes to this file. The accumulated changes are shown below.

proposed livecd-iso-to-disk.pod

=pod

=head1 NAME

modified_ livecd-iso-to-disk - Convert a Live CD/DVD/USB image so that it's bootable off of a USB stick

=head1 SYNOPSIS

B<modified_ livecd-iso-to-disk> [--help] [--format] [--reset-mbr] [--efi] [--extra-kernel-args <args>] [--multi] [--livedir <dir>] [--compress] [--skipcompress] [--swap-size-mb <size>] [--xo] [--xo-no-home] [--noverify] [--skipcopy] [--overlay-size-mb <size>] [--copy-overlay] [--delete-home] [--force] [--home-size-mb <size>] [--copy-home] [--crypted-home] [--unencrypted-home] <source> <target_device>

Simplest:

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

B<modified_ livecd-iso-to-disk> <source> <target_device>

To execute the script to completion, you will need to run it with root user permissions.

=over 4

=item <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 mount point or device reference of another LiveOS filesystem including a currently running one (such as a booted Live CD/DVD/USB where /dev/live would reference the device). If your source image is on another connected device, you would reference the bootable volume partition mount point, such as /media/usbmnt or /media/<partition_label>, where the label is often the device vendor's name.

=item <target_device>

This should be the device partition name for the attached, target device, such as /dev/sdb1 or /dev/sdc1. Issue the df -h command to get a listing of the mounted partitions, where you can confirm the available space and device names. Be careful to specify the correct device, or you may lose important data!

=back

=head1 DESCRIPTION

B<livecd-iso-to-disk> installs a Live CD/DVD/USB image (LiveOS) onto a USB storage device. The USB storage device can then boot the installed operating system on systems that support booting via USB. The script requires a LiveOS .iso image file, or a currently running LiveOS image or an installed image mount point, and a target USB storage device. If the operating system supports persistent overlays to save system changes, a fresh overlay, or a copy of the currently running overlay may be included in the installation. This enables one to easily prepare customized LiveOS images for redistribution.

Unless you request the --format or --reset-mbr options, the installation does not destroy data outside of the LiveOS, syslinux, EFI, & boot folders on your target device. This allows one to maintain other files on the USB disk outside of the LiveOS filesystem.

LiveOS images provide embedded filesystems through the Device-mapper component of the Linux kernel. The embedded filesystems exist within files such as /LiveOS/squashfs.img or /LiveOS/ext3fs.img on the primary volume partition of the storage device. In use, these are read-only filesystems. Optionally, one may specify a persistent home folder, which will exist in a /LiveOS/home.img filesystem image file. Persistent LiveOS overlays hold image change snapshots in the /LiveOS/overlay-<device_id> file.

Customized images are made by copying the source image filesystems to the bootable primary volume partition of another USB device and adjusting the syslinux boot configuration and overlay files to reflect the new device identification.

=head1 OPTIONS

=over 4

=item --help

Displays usage information and exits.

=item --format

Formats the USB stick and creates an MS-DOS partition table (or GPT partition table if --efi is passed).

=item --reset-mbr

Sets the Master Boot Record(MBR) of the USB storage device to the mbr.bin file from the image's syslinux directory.

=item --efi

Creates a GPT partition table when --format is passed, and install a hybrid EFI/MBR bootloader on the disk. This is necessary for most Intel Macs.

=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 ...\"

=item --multi

Used when enabling multi image copies (avoiding configuration of the boot files for an arbitrary image).

=item --livedir <dir>

Used with multi image copies to designate the directory <dir> for the particular image.

=item --compress (default option)

Installs image on a compressed SquashFS filesystem.

=item --skipcompress (default for when option --xo is specified)

Installs the operation system into the /LiveOS/ext3fs.img filesystem image file.

=item --xo

Used to prepare an image for the OLPC XO laptop and its compressed JFFS2 filesystem. Do not use the following options with --xo:

=over 4

--overlay-size-mb <size>, home-size-mb <size>, --delete-home, --copy-home, --copy-overlay, --compress

=back

=item --xo-no-home

Used together with the --xo option to prepare an image for an OLPC XO laptop with the home folder on an SD card instead of the internal NAND flash storage.

=item --noverify

Disables the image validation process which occurs before the image is installed. When this option is enabled, the image is not verified before loading on the USB storage device.

=item --skipcopy

Skips the copy of the live image to the USB stick, bypassing --format, --reset-mbr, --overlay-size-mb, --home-size-mb, --swap-size-mb, --copy-overlay, & --copy-home options, if present on the command line. (Used to repair disk configuration files or while testing the script, in order to avoid repeated and lengthy copy commands.)

=item --overlay-size-mb <size>

This option specifies the creation of a persistent overlay and sets its <size> in MB. The overlay is additional storage available to the live operating system if the operating system supports it. The USB storage device must have enough free space for the image and the overlay. The overlay holds image change snapshots in the /LiveOS/overlay-<device_id> file. There is a maximum <size> of 2047 MB for vfat formatted devices. If there is insufficient room on your device, you will be given information to adjust your settings.

=item --copy-overlay

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.

=over 4

WARNING: User sensitive information such as password cookies and activity histories will be copied to the new image! Scrub this information before using this option.

=back

=item --delete-home

Must be explicitly selected when options --home-size-mb <size> or --copy-home are selected and there is an existing persistent home directory on the image.

=item --home-size-mb <size>

Specifies creation of a persistent home directory and sets its size in megabytes. Note that --delete-home must also be selected to replace an existing persistent home with a new, empty one. The directory is saved in the /LiveOS/home.img file. There is a maximum <size> of 2047 MB for vfat formatted devices. If there is insufficient room on your device, you will be given information to adjust your settings.

=item --copy-home

This option allows one to copy a persistent home folder from a one live image to the new image. Changes already made in the source image home directory will be propagated to the new image.

=over 4

WARNING: User sensitive information such as password cookies and activity histories will be copied to the new image! Scrub this information before using this option.

=back

=item --force

This option allows one to bypass the user confirmation for deletion of an existing home directory on the target device, if one exists.

=item --crypted-home (default, if home-size-mb is specified)

Encrypts a persistent home directory.

=item --unencrypted-home

Disables the encryption of the persistent home directory.

=back

=head1 CONTRIBUTORS

David Zeuthen, Jeremy Katz, Douglas McClendon, Chris Curranm and other contributors. (See the AUTHORS file in the source distribution for the complete list of credits.)

=head1 BUGS

Report bugs to the mailing list C<http://admin.fedoraproject.org/mailman/listinfo/livecd> or directly to Bugzilla C<http://bugzilla.redhat.com/bugzilla/> against the C<Fedora> product, and the C<livecd-tools> component.

=head1 COPYRIGHT

Copyright (C) Fedora Project 2008, 2009, 2010 and various contributors. This is free software. You may redistribute copies of it under the terms of the GNU General Public License C<http://www.gnu.org/licenses/gpl.html>. There is NO WARRANTY, to the extent permitted by law.

=head1 SEE ALSO

C<livecd-creator(1)>, project website C<http://fedoraproject.org/wiki/FedoraLiveCD>

=back

=cut