The Fedora live CD tools
                    David Zeuthen <davidz@redhat.com>
                    Jeremy Katz <katzj@redhat.com>

                    Last updated: March 10, 2014 (v20.5)

This project concerns tools to generate live CD's on Fedora based
systems including derived distributions such as RHEL, CentOS and
others. See the project Wiki at 

 http://fedoraproject.org/wiki/FedoraLiveCD

for more details. Discussion of  this project takes places at the
fedora-livecd@redhat.com mailing list

 http://www.redhat.com/mailman/listinfo/fedora-livecd-list

This project and it's source files is licensed under the GPLv2
license. See the file COPYING for details.

1. LIVE CD DESIGN GOALS

The live CD is designed in such a way that the when running from a
live CD, the system should appear as much as possible as a standard
system with all that entails; e.g. read-write rootfs (achieved using
dm-snapshot), standard ext3 file system (for extended attributes) and
so on. 

Another design goal is that the live CD should be ''installable'',
ie. an user should be able to install the bits from the live CD onto
his hard disk without this process requiring network access or
additional media.

Finally, another design goal is that the tool set itself should be
separate from configuration; the same unmodified tool should be usable
for building various live CD flavors with vastly different
configurations, e.g. a GNOME live CD, a KDE live CD, a live cd with
music programs and so on.

2. CREATING A LIVE CD

To create a live cd, the livecd-creator tool is used. Super user
privileges are needed. The tool is more or less self-documenting, use
the --help option to see options.

2.1 HOW THE LIVE CD CREATOR WORKS

In a nutshell, the livecd-creator program

 o Sets up a file for the ext3 file system that will contain all the
   data comprising the live CD

 o Loopback mounts that file into the file system so there is an
   installation root

 o Bind mounts certain kernel file systems (/dev, /dev/pts, /proc,
   /sys, /selinux) inside the installation root

 o Uses a configuration file to define the requested packages and
   default configuration options.  The format of this file is the same
   as is used for installing a system via kickstart.

 o Installs, using yum, the requested packages into the installation
   using the given repositories

 o Optionally runs scripts as specified by the live CD configuration file. 

 o Relabels the entire installation root (for SELinux)

 o Creates a live CD specific initramfs that matches the installed kernel

 o Unmounts the kernel file systems mounted inside the installation root

 o Unmounts the installation root

 o Runs resize2fs to minimize and unminimize the ext3 file to remove data
   from deleted files

 o Runs resize2fs to minimize on a devicemapper snapshot, to generate a
   small minimized delta image file which can be used by anaconda to
   reduce installation time by not copying unused data to disk

 o Creates a squashfs file system containing only the ext3 file (compression)

 o Configures the boot loader

 o Creates an iso9660 bootable CD


2.2 EXAMPLE: A BAREBONES LIVE CD

The command

# livecd-creator \
  --config=/usr/share/doc/livecd-tools/livecd-fedora-minimal.ks

will create a live CD that will boot to a login prompt. Not that since
no configuration is done the user will not be able to login to the
system as the root password is not set / cleared.

2.3 LIVE CD CONFIGURATION FILES

The configuration of the live CD is defined by a file that uses the
same format as installing a system via kickstart.  They can include
some basic system configuration items, the package manifest and a
script to be run at the end of the build process.

For the Fedora project, there are currently a variety of different live CD
configuration files.  The spin-kickstarts package includes all of the
kickstarts used to create the various spins. These include a minimal live image
(livecd-fedora-minimal.ks), a complete desktop image (livecd-fedora-desktop.ks)
and others.

2.4 EXAMPLE: SPINNING THE FEDORA DESKTOP LIVE CD

Assuming that you use the livecd-fedora-desktop.ks configuration file,
then the following command

# livecd-creator \
  --config=/usr/share/spin-kickstarts/fedora-livecd-desktop.ks \
  --fslabel=Fedora-20-LiveCD-1-foo

will create a live CD called "Fedora-7-LiveCD-1-foo". The name
given by --fslabel is used.

 o as a file system label on the ext3 and iso960 file systems
   (as such it's visible on the desktop as the CD name)

 o in the isolinux boot loader

If you have the repositories available locally and don't want to wait
for the download of packages, just substitute the URLs listed in the
configuration file to point to your local repositories.

3. LIVE CD INSTALLS

As of Fedora 7, anaconda has support for doing an installation
from a live CD.  To use this, double click on the "Install to Hard
Drive" item on the desktop or run /usr/bin/liveinst if you don't have
such an icon.

4. LIVE CD MEDIA VERIFICATION

The live CD can incorporate functionality to verify itself.  To do so,
you need to have anaconda-runtime installed both on the system used
for creating the image and installed into the image.  This is so that
the implantisomd5 and checkisomd5 utilities can be used.  These
utilities take advantage of embedding an md5sum into the application
area of the iso9660 image.  This then gets verified before mounting
the real root filesystem.

In a future release, the isomd5 utilities will probably be split out
of anaconda.

5. USING LIVE IMAGES FROM USB MEDIA 

USB sticks are becoming increasingly prevalent and are a nice way to
use live images.  You can take a live CD iso image and transform it so
that it can be used on a USB stick.  To do so, use the
livecd-iso-to-disk script.
   /usr/bin/livecd-iso-to-disk /path/to/live.iso /dev/sdb1

Replace /dev/sdb1 with the (unmounted) partition where you wish to put
the live image.  This is not a destructive process; any data you 
currently have on your USB stick will be preserved.