<trclass="field-odd field"><thclass="field-name">Authors:</th><tdclass="field-body">Brian C. Lane <<aclass="reference external"href="mailto:bcl%40redhat.com">bcl<span>@</span>redhat<span>.</span>com</a>></td>
<aclass="reference external"href="https://github.com/rhinstaller/pykickstart">kickstart</a> and <aclass="reference external"href="https://github.com/rhinstaller/lorax">Lorax</a> to create bootable media that use the
same install path as a normal system installation. It can be used to make live
isos, bootable (partitioned) disk images, tarfiles, and filesystem images for
use with virtualization and container solutions like libvirt, docker, and
OpenStack.</p>
<p>The general idea is to use virt-install with kickstart and an Anaconda boot.iso
to install into a disk image and then use the disk image to create the bootable
media.</p>
<p>livemedia-creator –help will describe all of the options available. At the
minimum you need:</p>
<p><ttclass="docutils literal"><spanclass="pre">--make-iso</span></tt> to create a final bootable .iso or one of the other <ttclass="docutils literal"><spanclass="pre">--make-*</span></tt> options.</p>
<p><ttclass="docutils literal"><spanclass="pre">--iso</span></tt> to specify the Anaconda install media to use with virt-install</p>
<p><ttclass="docutils literal"><spanclass="pre">--ks</span></tt> to select the kickstart file describing what to install.</p>
<p>To use livemedia-creator with virt-install you will need to install the
following packages, as well as have libvirtd setup correctly.</p>
<p>If you want to watch the install you can pass <ttclass="docutils literal"><spanclass="pre">--vnc</span><spanclass="pre">vnc</span></tt> and use a vnc client
to connect to localhost:0</p>
<p>This is usually a good idea when testing changes to the kickstart. lmc tries
to monitor the logs for fatal errors, but may not catch everything.</p>
</div>
<divclass="section"id="how-iso-creation-works">
<h2>How ISO creation works<aclass="headerlink"href="#how-iso-creation-works"title="Permalink to this headline">¶</a></h2>
<p>There are 2 stages, the install stage which produces a disk or filesystem image
as its output, and the boot media creation which uses the image as its input.
Normally you would run both stages, but it is possible to stop after the
install stage, by using <ttclass="docutils literal"><spanclass="pre">--image-only</span></tt>, or to skip the install stage and use
a previously created disk image by passing <ttclass="docutils literal"><spanclass="pre">--disk-image</span></tt> or <ttclass="docutils literal"><spanclass="pre">--fs-image</span></tt></p>
<p>When creating an iso virt-install boots using the passed Anaconda installer iso
and installs the system based on the kickstart. The <ttclass="docutils literal"><spanclass="pre">%post</span></tt> section of the
kickstart is used to customize the installed system in the same way that
current spin-kickstarts do.</p>
<p>livemedia-creator monitors the install process for problems by watching the
install logs. They are written to the current directory or to the base
directory specified by the –logfile command. You can also monitor the install
by passing <ttclass="docutils literal"><spanclass="pre">--vnc</span><spanclass="pre">vnc</span></tt> and using a vnc client. This is recommended when first
modifying a kickstart, since there are still places where Anaconda may get
stuck without the log monitor catching it.</p>
<p>The output from this process is a partitioned disk image. kpartx can be used
to mount and examine it when there is a problem with the install. It can also
be booted using kvm.</p>
<p>When creating an iso the disk image’s / partition is copied into a formatted
disk image which is then used as the input to lorax for creation of the final
media.</p>
<p>The final image is created by lorax, using the templates in /usr/share/lorax/
or the directory specified by <ttclass="docutils literal"><spanclass="pre">--lorax-templates</span></tt></p>
<p>Currently the standard lorax templates are used to make a bootable iso, but
it should be possible to modify them to output other results. They are
written using the Mako template system which is very flexible.</p>
</div>
<divclass="section"id="kickstarts">
<h2>Kickstarts<aclass="headerlink"href="#kickstarts"title="Permalink to this headline">¶</a></h2>
<p>The docs/ directory includes several example kickstarts, one to create a live
desktop iso using GNOME, and another to create a minimal disk image. When
creating your own kickstarts you should start with the minimal example, it
includes several needed packages that are not always included by dependencies.</p>
<p>Or you can use existing spin kickstarts to create live media with a few
changes. Here are the steps I used to convert the Fedora XFCE spin.</p>
<olclass="arabic">
<li><pclass="first">Flatten the xfce kickstart using ksflatten</p>
</li>
<li><pclass="first">Add zerombr so you don’t get the disk init dialog</p>
</li>
<li><pclass="first">Add clearpart –all</p>
</li>
<li><pclass="first">Add swap partition</p>
</li>
<li><pclass="first">bootloader target</p>
</li>
<li><pclass="first">Add shutdown to the kickstart</p>
</li>
<li><pclass="first">Add network –bootproto=dhcp –activate to activate the network
This works for F16 builds but for F15 and before you need to pass
something on the cmdline that activate the network, like sshd:</p>
<p>Documentation on the Mako template system can be found at the <aclass="reference external"href="http://docs.makotemplates.org/en/latest/index.html">Mako site</a></p>
<p>The name of the final output XML is appliance.xml, this can be changed with
<p>You can name the output image with <ttclass="docutils literal"><spanclass="pre">--image-name</span></tt> and set a label on the filesystem with <ttclass="docutils literal"><spanclass="pre">--fs-label</span></tt></p>
</div>
<divclass="section"id="tar-file-creation">
<h2>TAR File Creation<aclass="headerlink"href="#tar-file-creation"title="Permalink to this headline">¶</a></h2>
<p>The <ttclass="docutils literal"><spanclass="pre">--make-tar</span></tt> command can be used to create a tar of the root filesystem. By
default it is compressed using xz, but this can be changed using the
<ttclass="docutils literal"><spanclass="pre">--compression</span></tt> and <ttclass="docutils literal"><spanclass="pre">--compress-arg</span></tt> options. This option works with both virt and
no-virt install methods.</p>
<p>As with <ttclass="docutils literal"><spanclass="pre">--make-fsimage</span></tt> the kickstart should be limited to a single / partition.</p>
<h2>Atomic Live Image for PXE Boot<aclass="headerlink"href="#atomic-live-image-for-pxe-boot"title="Permalink to this headline">¶</a></h2>
<p>The <ttclass="docutils literal"><spanclass="pre">--make-ostree-live</span></tt> command will produce the same result as <ttclass="docutils literal"><spanclass="pre">--make-pxe-live</span></tt>
for installations of Atomic Host. Example kickstart for such an installation
using Atomic installer iso with local repo included in the image can be found
22.15 inside of a mock chroot with –make-iso and –make-fsimage.</p>
<divclass="admonition note">
<pclass="first admonition-title">Note</p>
<pclass="last">As of mock 1.2.12 you no longer need to bind mount <ttclass="docutils literal"><spanclass="pre">/dev/</span></tt>, loop devices are setup
as part of the standard mock <ttclass="docutils literal"><spanclass="pre">/dev/</span></tt> creation.</p>
<pclass="last">On the RHEL7 version of lmc <ttclass="docutils literal"><spanclass="pre">--qcow2</span></tt> isn’t supported. You can only create a bare partitioned disk image.</p>
</div>
<p>Import the resulting disk image into the OpenStack system, either via the web UI, or glance on the cmdline:</p>
--container-format bare --file ./fedora-openstack.qcow2
</pre></div>
</div>
<p>If qcow2 wasn’t used then <ttclass="docutils literal"><spanclass="pre">--disk-format</span></tt> should be set to raw.</p>
</div>
<divclass="section"id="docker-image-creation">
<h2>Docker Image Creation<aclass="headerlink"href="#docker-image-creation"title="Permalink to this headline">¶</a></h2>
<p>Use lmc to create a tarfile as described in the <aclass="reference internal"href="#tar-file-creation">TAR File Creation</a> section, but substitute the
fedora-docker.ks example kickstart which removes the requirement for core files and the kernel.</p>
<p>You can then import the tarfile into docker like this (as root):</p>
<h2>Open Container Initiative Image Creation<aclass="headerlink"href="#open-container-initiative-image-creation"title="Permalink to this headline">¶</a></h2>
<p>The OCI is a new specification that is still being worked on. You can read more about it at
<aclass="reference external"href="https://www.opencontainers.org/">the Open Container Initiative website</a>. You can create
<p>The image created is a <aclass="reference external"href="https://github.com/pradels/vagrant-libvirt">vagrant-libvirt</a> provider image and needs to have
vagrant setup with libvirt before you can use it.</p>
<p>The <ttclass="docutils literal"><spanclass="pre">--vagrant-metadata</span></tt> file is optional, it will create a minimal one by
default, and if one is passed it will make sure the disk size is setup
correctly. If you pass a <ttclass="docutils literal"><spanclass="pre">--vagrant-vagrantfile</span></tt> it will be included in the
image verbatim. By default no vagrantfile is created.</p>
<p>There is an example Vagrant kickstart file in the docs directory that sets up
the vagrant user with the default insecure SSH pubkey and a few useful
utilities.</p>
<p>This also works with <ttclass="docutils literal"><spanclass="pre">--no-virt</span></tt>, but will not work inside a mock due to its
<h2>Debugging problems<aclass="headerlink"href="#debugging-problems"title="Permalink to this headline">¶</a></h2>
<p>Sometimes an installation will get stuck. When using virt-install the logs will
be written to ./virt-install.log and most of the time any problems that happen
will be near the end of the file. lmc tries to detect common errors and will
cancel the installation when they happen. But not everything can be caught.
When creating a new kickstart it is helpful to use the <ttclass="docutils literal"><spanclass="pre">--vnc</span><spanclass="pre">vnc</span></tt> command so
that you can monitor the installation as it happens, and if it gets stuck
without lmc detecting the problem you can switch to tty1 and examine the system
directly.</p>
<p>If it does get stuck the best way to cancel is to use virsh to destroy the domain.</p>
<olclass="arabic simple">
<li>Use <ttclass="docutils literal"><spanclass="pre">sudo</span><spanclass="pre">virsh</span><spanclass="pre">list</span></tt> to show the name of the virt. It will start with LiveOS and contain a UUID.</li>
<li>Run <ttclass="docutils literal"><spanclass="pre">sudo</span><spanclass="pre">virsh</span><spanclass="pre">destroy</span><spanclass="pre"><name></span></tt> to destroy the domain.</li>
<li>Wait 20 seconds or so for lmc to detect that the domain vanished. It should handle cleanup.</li>
</ol>
<p>If lmc didn’t handle the cleanup for some reason you can do this:
2. <ttclass="docutils literal"><spanclass="pre">sudo</span><spanclass="pre">umount</span><spanclass="pre">/tmp/tmpXXXX</span></tt> to unmount the iso from its mountpoint.
4. <ttclass="docutils literal"><spanclass="pre">sudo</span><spanclass="pre">rm</span><spanclass="pre">/var/tmp/diskXXXXX</span></tt> to remove the disk image.</p>
<p>The logs from the virt-install run are stored in virt-install.log,
logs from livemedia-creator are in livemedia.log and program.log</p>
<p>You can add <ttclass="docutils literal"><spanclass="pre">--image-only</span></tt> to skip the .iso creation and examine the resulting
disk image. Or you can pass <ttclass="docutils literal"><spanclass="pre">--keep-image</span></tt> to keep it around after the iso has
been created.</p>
<p>Cleaning up aborted <ttclass="docutils literal"><spanclass="pre">--no-virt</span></tt> installs can sometimes be accomplished by
running the <ttclass="docutils literal"><spanclass="pre">anaconda-cleanup</span></tt> script. As of Fedora 18 anaconda is
multi-threaded and it can sometimes become stuck and refuse to exit. When this
happens you can usually clean up by first killing the anaconda process then
<h2>Hacking<aclass="headerlink"href="#hacking"title="Permalink to this headline">¶</a></h2>
<p>Development on this will take place as part of the lorax project, and on the
anaconda-devel-list mailing list, and <aclass="reference external"href="https://github.com/rhinstaller/lorax">on github</a></p>
<p>Feedback, enhancements and bugs are welcome. You can use <aclass="reference external"href="https://bugzilla.redhat.com/enter_bug.cgi?product=Fedora&component=lorax">bugzilla</a> to
Built with <ahref="http://sphinx-doc.org/">Sphinx</a> using a <ahref="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <ahref="https://readthedocs.org">Read the Docs</a>.
