Livecd-iso-to-disk

From FedoraProject

(Difference between revisions)
Jump to: navigation, search
(swap entry and sizes)
(note different versions)
(10 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
</noinclude>
 
</noinclude>
  
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.
+
'''livecd-iso-to-disk.sh''' is a Bash shell script from livecd-tools, http://git.fedorahosted.org/cgit/livecd/tree/tools/livecd-iso-to-disk.sh
  
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.
+
: '''Note''': There are some variations of the script for different versions of Fedora (see [http://git.fedorahosted.org/cgit/livecd/ livecd-tools summary]).
  
==proposed livecd-iso-to-disk.pod==
+
In a LiveCD distribution, the script is usually available in the installation disc's filesystem at {{Code|/LiveOS/livecd-iso-to-disk}} (alongside squashfs.img and osmin.img). From a booted LiveOS filesystem, the outer USB/SD/CD/DVD device filesystem is mounted on the {{Code|/run/initramfs/live/}} mount point (or at {{Code|/mnt/live/}} on Fedora 16 and earlier).
  
=pod
+
Usage is documented in the first 270 or so lines of the the script, and accessible with the {{Code|livecd-iso-to-disk --help}} command.  Documentation is also in livecd-iso-to-disk.pod, http://git.fedorahosted.org/cgit/livecd/plain/docs/livecd-iso-to-disk.pod , but the format may be less clear for reading.
 
+
=head1 NAME
+
 
+
livecd-iso-to-disk  -  Convert a Live CD/DVD/USB image so that it's bootable off of a USB/SD stick
+
 
+
=head1 SYNOPSIS   
+
 
+
B<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] [--build-message <message>] [--releasefile <filepath>] [--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<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 the installation script.
+
 
+
=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 device node reference for the mount point of another LiveOS filesystem, including the currently-running one (such as a booted Live CD/DVD/USB, where /dev/live would reference the device).
+
 
+
=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 -Th command to get a listing of the mounted partitions, where you can confirm the filesystem types, 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/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 source, LiveOS image and a target, storage device.  The source image may be either a LiveOS .iso file, a currently-running LiveOS image, or the device node reference for the mount point of an installed LiveOS image.  If the operating system supports persistent overlays for saving system changes, a fresh overlay, or a copy of the source overlay may be included with the installation.  This enables one to easily prepare customized LiveOS images for redistribution.
+
 
+
Unless you request the --format option, 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 target 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 (the default compressed storage) or /LiveOS/ext3fs.img (an uncompressed version) on the primary volume partition of the storage device.  In use, these are read-only filesystems. Optionally, one may specify a persistent LiveOS overlay to hold image-change snapshots (that use write-once difference tracking storage) in the /LiveOS/overlay-<device_id> file, which--one should note--always grow in size due to the storage mechanism.  (The fraction of allocated space that has been consumed by system activity and changes may be displayed by issuing the dmsetup status command in a terminal session of a running LiveOS image.) To conserve the unrecoverable, overlay file space, one may specify a persistent home folder, which will exist in a /LiveOS/home.img filesystem image file.  This file space is encrypted by default, but is not compressed (one may bypass encryption with the --unencrypted-home installation option).  Files in this home folder may be erased to recover storage space.  The home.img file is also convenient for backing up or swapping user account files.
+
 
+
Customized images are made by copying the source image filesystems to the bootable primary volume partition of another USB/SD 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 target device 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 target storage device to the mbr.bin file from the installation system'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 --compressed  (default state for the operating system files)
+
 
+
Allows the default compressed SquashFS filesystem image to be copied.
+
Has no effect on an already-expanded filesystem copy.
+
 
+
=item --skipcompress  (default for when option --xo is specified or an uncompressed source is used)
+
 
+
Installs the operation system into the /LiveOS/ext3fs.img filesystem image file.
+
 
+
=item --xo
+
 
+
Used to prepare an image for the OLPC XO-1 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, --compressed
+
 
+
=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 target stick, bypassing the actions 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 used while testing the script, in order to avoid repeated and lengthy copy commands, or to repair boot configuration files.)
+
 
+
=item --swap-size-mb <size>
+
 
+
Sets up a swap file of <size> megabytes (integer values only) on the target device.
+
 
+
=item --overlay-size-mb <size>
+
 
+
This option sets the overlay size in megabytes (integer values only).  The overlay is additional storage available to the live operating system if the operating system supports it.  The persistent LiveOS overlay holds image-change snapshots (using write-once difference tracking storage) in the /LiveOS/overlay-<device_id> file, which, one should note, always grows in size due to the storage mechanism. (The fraction of allocated space that has been consumed may be displayed by issueing the dmsetup status command in a terminal session of a running LiveOS image.) To conserve this unrecoverable overlay file space, one may specify a persistent home folder with the --home-size-mb option (see below).  The target storage device must have enough free space for the image and the overlay.  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 a target 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 application or user data will be copied to the new image!  Scrub this information before using this option.
+
 
+
=back
+
 
+
=item --build-message <message>
+
 
+
This option allows one to update release files to show the non pristine status of an image through the build-message, and copydate.  The default message is "by someone, copied on" which will be appended to the standard "Welcome to <releasename>!" (skipping the '!') and followed by the copy date in 'dd MMM yyyy' format as found in the /syslinux/syslinux.cfg or corresponding boot configuration file.
+
 
+
=item --releasefile <filepath>
+
 
+
This option allows one to update a particular release file to show the non pristine status of an image through the build-message, and copydate. The default message is "by someone, copied on" which will prepended the designated file with the line, "Remix of <releasename> <build-message> " followed by the copy date in 'dd MMM yyyy' format.
+
 
+
=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>
+
 
+
Sets the home directory size in megabytes (integer values only).  A persistent home directory will be made in the /LiveOS/home.img filesystem image file.  This file space is encrypted by default, but not compressed  (one may bypass encryption with the --unencrypted-home installation option).  Files in this home folder may be erased to recover storage space.  The target storage device must have enough free space for the image, any overlay, and the home directory. Note that --delete-home must also be selected to replace an existing persistent home with a new, empty one.  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 one LiveOS image to the target 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, user and application data 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 the deletion of an existing home directory on the target device, if one exists.
+
 
+
=item --encrypted-home  (default that only applies to new, home-size-mb requests)
+
 
+
Allows the default option to encrypt a new, persistent home directory.
+
Has no effect on a copied home directory.
+
 
+
=item --unencrypted-home
+
 
+
Prevents the default option to encrypt a new, persistent home directory.
+
Has no effect on a copied home directory.
+
 
+
=back
+
 
+
=head1 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.)
+
 
+
=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
+

Revision as of 19:07, 12 November 2012


livecd-iso-to-disk.sh is a Bash shell script from livecd-tools, http://git.fedorahosted.org/cgit/livecd/tree/tools/livecd-iso-to-disk.sh

Note: There are some variations of the script for different versions of Fedora (see livecd-tools summary).

In a LiveCD distribution, the script is usually available in the installation disc's filesystem at /LiveOS/livecd-iso-to-disk (alongside squashfs.img and osmin.img). From a booted LiveOS filesystem, the outer USB/SD/CD/DVD device filesystem is mounted on the /run/initramfs/live/ mount point (or at /mnt/live/ on Fedora 16 and earlier).

Usage is documented in the first 270 or so lines of the the script, and accessible with the livecd-iso-to-disk --help command. Documentation is also in livecd-iso-to-disk.pod, http://git.fedorahosted.org/cgit/livecd/plain/docs/livecd-iso-to-disk.pod , but the format may be less clear for reading.