From Fedora Project Wiki


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.

Credits

Kadischi is heavily based on readonly-root package from Stateless-linux project.

Many design decisions are collective work of people from fedora-livecd list.

There are also some ideas taken from linux4all project.

The name for the project came from Elliot Lee.

Previous project maintainer was Darko Ilic (darko.ilic@gmail.com).

Since the project was started as one of the Googles Summer of Code projects, some credits also goes to Google  ;)

Installation

Requirements

The following packages should be installed in order to run Kadischi:

  • anaconda
  • busybox-anaconda
  • syslinux
  • mkisofs
  • zisofs-tools
  • e2fsprogs

To install them, run 

yum install anaconda busybox-anaconda syslinux mkisofs zisofs-tools e2fsprogs

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): 


export CVSROOT=:pserver:anonymous@cvs.fedora.redhat.com:/cvs/devel
cvs -z3 login
cvs -z3 co kadischi

If you dont 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 ./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.

Example 2: 


kadischi http://download.fedora.redhat.com/pub/fedora/linux/core/4/i386/os /tmp/fedora-live.iso

Example 3: (using mirror site) 

kadischi http://mirrors.kernel.org/fedora/core/4/i386/os/ /tmp/fedora-live.iso


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 --kickstart command line option: 

kadischi /tmp/fc4 /tmp/fedora-live.iso --kickstart=/path/to/kickstart.cfg

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: 

kadischi /tmp/fc4 /tmp/fedora-live.iso --kickstart=/path/to/kickstart.cfg -C

where -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 theyre 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

Appendix

How to apply a patch

Synopsis for the patch utility looks like 


patch [options]  [originalfile [patchfile]

and what we need here is 


patch -b /usr/sbin/anaconda /usr/local/share/kadischi/patches/anaconda.patch
patch -b /usr/lib/anaconda/flags.py /usr/local/share/kadischi/patches/flags.py.patch

-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 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 its much faster (and you will probably end up with several livecd builds before the right one). Heres the procedure:

  • create the root directory for your repository (for example /tmp/fc4)
  • create subdirectories /tmp/fc4/Fedora, /tmp/fc4/Fedora/RPMS, /tmp/fc4/Fedora/base
  • copy the contents of cdrom:/Fedora/base directory (from disc1) to the /tmp/fc4/Fedora/base
  • copy the contents of cdrom:/Fedora/RPMS directory (from all 4 discs) to the /tmp/fc4/Fedora/RPMS

And thats it. You can use this repository with Kadischi (path to the repository is /tmp/fc4).

Please note that this is not a regular repository, and you cant, for example, use it with yum. If you would like to create a regular repository, please consult some other document.

Anaconda installation methods

  • method=nfs:<path> -- Use <path> for an NFS installation.
  • method=http://<path> -- Use <path> for an HTTP installation
  • method=ftp://<path> -- Use <path> for an FTP installation
  • method=hd://<dev>/<path> -- Use <path> on <dev> for a hard drive installation
  • method=cdrom -- Do a CDROM based installation.

(taken from [1] )

You can checkout /usr/share/doc/anaconda-${version}/install-methods.txt for further information.

buildstamp file

Anaconda uses buildstamp file to gather some information related to the distribution. Heres the example of the buildstamp file (from FC 4): 

200506062237.i386
Fedora Core
4
Fedora
http://bugzilla.redhat.com/bugzilla/

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.

The one that is very important to us is product path (the 4th one) because it is used in accessing the repository. If your repository is, for example, http://mirrors.kernel.org/fedora/core/4/i386/os/, anaconda will look for rpms in http://mirrors.kernel.org/fedora/core/4/i386/os/${productPath}/RPMS, so for the Fedora repository, the 4th line of the buildstamp should be "Fedora".

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.

Retrieved from "https://fedoraproject.org/w/index.php?title=KadischiDoc&oldid=17873"