About Kadischi

What is Kadischi

Kadischi is an application for Fedora-based Live CD generation. It takes Fedora repository as an input and outputs a livecd iso image.

Kadischi is still in the early stage of development, but has basic functionality and can be run successfully.

How does Kadischi work

Basically, Kadischi uses anaconda to install the system in a temporary directory (specified in the configuration file) on users hard drive. It then executes the collection of scripts (stored in /usr/local/share/kadischi/post_install_scripts) in order to modify the system to run successfully in read-only environment (CD). After all modifications are done, Kadischi creates an initrd image, then compresses the system tree (actually, it creates a compressed copy, and then removes the original one), and finally creates iso image of the system.

For more details on the process, see "Under the bonnet" section.

Bug reports

Use bugzilla for bug reports and feature requests. For details on the procedure, take a look at ["Kadischi"] page.

If you want to compile Kadischi from the source code, the following packages should be installed:

kudzu-devel

To install them, run

yum install kudzu-devel

YUM Note

You might be encounter following warning message during installing anaconda package:

...
warning: rpmts_HdrFromFdno: Header V3 DSA signature: NOKEY, key ID db42a60e
public key not available for anaconda-help-10.1.0-1.noarch.rpm
Retrieving GPG key from file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora
The GPG key at file:///etc/pki/rpm-gpg/RPM-GPG-KEY-fedora (0x4F2A6FD2)
is already installed but is not the correct key for this package.
Check that this is the correct key for the "Fedora Core 4 - i386 - Base" repository.

Run rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY to import the key which was used for this package.

Downloading

For now, the only way to download Kadischi is via anonymous CVS.

To do that, execute the following in a terminal (type enter when prompted for
password):

If you don<code>t have cvs client installed on the machine, you can install it
running

yum install cvs

Installation

Go to the root directory of the source tree, and run <code>./autogen.sh. It will
configure package for building. If you would like to pass some options to
./configure, you can pass them to ./autogen.sh and it will forward them to
./configure.

After that, you have to run make in order to build the application.

Run make install to install the application (default location is
/usr/local/share/kadischi for application files and /etc/kadischi for configuration
files).

Yet another thing you would have to do in order to run the application is to
patch anaconda. Files that should be patched are /usr/sbin/anaconda and
/usr/lib/anaconda/flags.py. Patches are in /usr/local/share/kadischi/patches dir, and
are made against anaconda-10.2.1.5-2 (fc4 default).

For patching instructions, consult "How to apply a patch" section of Appendix.

Configuration

Edit /etc/kadischi/build.conf and set BUILDDIR variable. BUILDDIR
is a directory that will be used for storing temporary files (temporary
installation will be performed in that directory). You will need
approximately 1.5x size of desired installation available on that device. 3GB
works fine for me.

Uninstallation

Go to the root directory of the source tree and run make uninstall. Make sure
there are no extra files added to the application directories (for example
/etc/kadischi/build.conf~).

Using Kadischi

Basic instructions

The basic way to run Kadischi is to type the following in a terminal

kadischi path-to-the-repository path-to-the-iso-image

where path to the repository can be a path on the local file system, but can
also be a path to ftp, http or some other type of repository.

Example:

kadischi /tmp/fc4 /tmp/fedora-live.iso

where /tmp/fc4 is a directory holding a Fedora repository (which means rpms are in /tmp/fc4/Fedora/RPMS and comps.xml, hdlist and some other files are in /tmp/fc4/Fedora/base). For instructions on
creating a local repository, colsult "How to build a repository" section from
Appendix.

for installing from http repository. For details on available installation
methods, consult "Anaconda installation methods" in Appendix.

If you are not using Fedora repository, you would have to edit /etc/kadischi/buildstamp or to use a custom buildstamp file. For details, consult "buildstamp file" in Appendix.

Command line options

Type kadischi --help for list of Kadischi command line options.

Running Kadischi automatically

Since Kadischi itself doesnt require any interaction, and the only interaction
that is required is the interaction with anaconda, the only thing we have to do
is to make anaconda run automatically. This can be done using kickstart files.
If you supply anaconda with complete kickstart file, it will run without
prompting (if ks file is incomplete, it will prompt you only for the information
it lacks).

If you want to run Kadischi with kickstart, use <code>--kickstart command line option:

Some examples of kickstart files that can be used are included in the package
and can be found in /usr/local/share/kadischi/ks_examples.

Another thing that matters is bringing up the user interface. Even if supplied
with complete ks file, anaconda will bring up the interface (GUI or TUI) which
is something we dont want here. Luckily, anaconda can be run in command line
mode, where no interface is initialized. So, if you want to run Kadischi in the
background, you would do something like:

where <code>-C stands for command line. You can also use --cmdline instead of -C.

Please note that in command line mode, no interaction with anaconda is possible,
so if you have an incomplete kickstart file, anaconda will just print an error
message to stdout and stop (it will not abort execution).

Using this two command line options you could, for example, create a cron job
that will create fresh ISOs from rawhide repository every day.

Customizing Live CD system

I'll give you here some ideas on how to perform the customization of the live CD. Please note that there are probably many cleaver ways that I don't know about :)

Using kickstart file, and all the options it provides, including %pre and %post install scripts.

Adding scripts to /usr/local/share/kadischi/post_install_scripts/ or editing some of them that are already there. Those scripts are executed right after the system is installed to chroot environment, but they are NOT executed in the chroot environment, they are executed from the parent system. Kadischi sorts all executables from post_install_scripts directory by the name, and executes them passing them the path to the freshly installed system as an argument.

Creating rpms with modifications, and adding them to the repository.

Tip: If you would like to customize your live CD, take a look at the Under the bonnet section of this document. Pay special attention to the scripts in post_install_scripts directory, and to the /usr/local/share/kadischi/movefiles.py. Those files are well documented, and reading just the first couple of lines would be helpful.

Tips and tricks

Get your self a rewritable CD, you're gonna need it :) (but don't forget the system will work slower when run from RW disc)

If you are using kickstart file, add --excludedocs to %packages (like this: %packages --excludedocs) in order to skip installing docs to /usr/local/doc (this can save you some space, depending on the number of packages)

include as many packages as you want (well, not more that 10GB), and write iso image to a DVD disc

Under the bonnet

How does Kadischi work (in details)

In this section, I'll describe what happens from the moment you run kadischi from the command line, to the moment it writes "Finished" in it's log. If you just want to use Kadischi, you probably dont need to read this, but if you want to perform some harder customization of your live CDs or you want to understand how Kadischi works for any other reason, you can continue with reading.

When you type kadischi in your command line, /usr/bin/kadischi is executed. It is just a simple bash script which sets PYTHONPATH variable to include Kadischi libraries, and executes /usr/local/share/kadischi/kadischi.py.

kadischi.py is top-level script as such is in charge of coordination between all other elements. It

processes command line options and arguments

checks if everything looks OK (the number of given arguments, presence of destination file, UID, presence of required RPMs, config file)

sets values to variables (from the information it gets from the command line and from the config file)

creates subdirectory named 'livecd_build_no${number}' under the specified build directory; all temporary files for that build will be stored there

invokes anaconda; anaconda is run with --livecd flag, --rootpath option and all other options specified on the command line (like --kickstart, --cmdline etc.). This is actually the most important part of the process. Anaconda installs the whole system in a directory on the local hard drive.

invokes scripts from /usr/local/share/kadischi/post_install_scripts passing them as an argument the path to the system tree. Those scripts are used to modify the system in order to work properly from the live CD

invokes /usr/local/share/kadischi/livecd-mkinitrd.sh which makes initrd image that will be used on the live CD system

invokes /usr/local/share/kadischi/movefiles.py which moves all the files and directories that should be writable once the live CD is booted to a single directory. That directory is then compressed in kadischi.tar.gz. During the booting of live CD, this archive is unpacked on tmpfs drive, and extracted files and directories are mounted (with mount --bind) to their original locations.

creates a compressed copy of the whole system (zisofs is used for compression)

copies some files that shouldn't be compressed (kernel, initrd etc.) from the uncompressed tree to the compressed one

removes the uncompressed tree

invokes /usr/local/share/kadischi/create-iso.sh which creates iso image out of the compressed system tree

cleans up the build directory

How does generated Live CD work

Design notes

Kadischi source tree

It's self-explaneable I hope, but it won't hurt me if I write a couple of lines here. I'll mention only directories, files are already documented (well, the most of them).

kadischi/
conf/
Holding all configuration files. Upon the installation, these files end up in /etc/kadischi/
doc/
Kadischi documentation
find_live_cd/
Sources for find-live-cd utility. find-live-cd is invoked by linuxrc, and is in charge of finding the drive holding our live cd and mounting it
ks_examples/
Some examples of kickstart files that can be used with Kadischi
lib/
Functions and modules that are used by Kadischi
linuxrc/
linuxrc script that will be used in Live CD initrd image
livecd_generator/
This directory holds the main script, the one that is in charge of the whole process of Live CD generation. There are also some scripts that are used during the process.
patches/
Patches that I made to anaconda to make it work with Kadischi. One day when we make sure they<code>re OK, they should go upstream
po/
A directory where pot files should be placed. There is nothing there for now
post_install_scripts/
A collection of scripts that are executed on the new system (before it is being compressed and packed in iso image) in order to modify it to run properly from Live CD. Some of them can be tweaked in order to customize the system.
rc/
Scripts that are used during the init of the Live CD system
scanswap/
scanswap is utility that searches for swap partition on local hard drives, and enables it if it finds one

-b stands for backup, so patch will backup your files before applying the
patches. Backups will be named /usr/sbin/anaconda.orig and
/usr/lib/anaconda/flags.py.orig.

For more details about the patch utility, type <code>man patch or checkout Merging with patch

How to build a repository

If you have Fedora installation CDs its a good idea to copy them to your hard
drive and to perform installation from a harddrive repository since it<code>s much
faster (and you will probably end up with several livecd builds before the right
one). Here<code>s the procedure:

As you can see, there are 5 lines. The first line is something like the build ID, the second is product name, the third is product version, the forth is product path and the fifth is URL for bug reports.

If you get an endless loop of "Reading package information... Unable to read header list. This may be due to a missing file or bad media. Press <return> to try again" from anaconda, it is very likely that there is something wrong with product path.

Anaconda looks for buildstamp file at /tmp/product/.buildstamp and /.buildstamp (in that order), so Kadischi puts it's buildstamp file to /tmp/product/.buildstamp so anaconda could find it. If the file /tmp/product/.buildstamp already exists, Kadischi will move it to a temporary location, put it's file to /tmp/product/.buildstamp, run anaconda, and when anaconda finishes the job, it will restore the original file.