SDB:KIWI Cookbook LiveSystem
All of KIWI edit
Tux Live - our second recipe
The result of this recipe is a functional openSUSE live system. However, to spice things up a bit we will modify the base recipe provided by the kiwi-doc package. We will add an additional package to the system beeing created and change the displayed name on the boot menu. For these changes to take effect we need to work on the kiwi image description.
A live system image is a bootable operating system on portable media (CD, DVD, or USB for example). The live system treats the CD/DVD/USB as the hard disk of the system. This provides us the opportunity to carry our system with us and use it on any computer we can get our fingers on. Using CD or DVD media has the disadvantage that the media type is read only, i.e. the system cannot be permanently altered after it is enshrined (burned) to the media. Any modifications to the running system based on a CD/DVD take place in memory and are therefore lost when the system is stopped. For this example we will only consider a live system on CD/DVD media.
LiveCD recipe
Prep Time:
- 20 min
Cook Time:
- 20-25 min depending on bandwidth (see discussion above) and hardware of host
Ingredients:
- a running openSUSE 11.1 system
- an openSUSE 11.1 repository
- installed recent release of the KIWI toolset (at least version 3.25)
- installed kiwi-doc package
- about 5 GB free disk space
Original recipe
Using the example provided with the kiwi-doc package is straight forward as shown below (remember you need to be logged in as root).
If you no longer have the directories we created earlier during our initial setup, recreate these now:
The example files from the kiwi-doc package life in the directory /usr/share/doc/packages/kiwi/examples. We want to use the suse-live-iso example for openSUSE 11.1, so our commands would be
As with the previous recipe we can test the iso image using a full virtual system such as vmware or qemu. You have the "burn and boot" option as well of course.
Once again the qemu command line option for image testing is provided here for your reference.
The Login Details for the system are
- User: root
- pwd : linux
Some caveats
- If you are building on a 64bit system you need to use qemu-kvm (from the kvm package) instead of qemu
- The image name suse-11.1-live-iso.i686-2.5.1.iso in the command above may be different, depending on your build architecture and the version of the template you are using.
Customizing the recipe
Now that we have a taste of the basic recipe, prepared by a master chef, lets customize the recipe to add some of our own flavor.
The image description
KIWI uses a so called image description as the basis for the image to be created.
The image description is a directory containing at least one file named config.xml.
In addition to the config.xml file the image description directory may contain shell scripts to be executed during the image creation, or any kind of files and directory structures to be included in the image.
For details about the image description directory please refer to the KIWI Image System Cookbook in /usr/share/doc/packages/kiwi/kiwi.pdf, installed with the kiwi-doc package or the online version found here.
The following steps show how to modify an existing image description. The richness of the image description provides a plethora of customization options, here, we will focus our efforts on the modification of the config.xml file.
The starting point for our modifications is the description of the LiveCD image we created above. We will add the kde4-amor package to the description and change the system name. As a good practice it is recommended to work on a copy and preserve the integrity of the original example provided with the kiwi-doc package.
Copy the example image description
total 52 drwxr-xr-x 3 root root 4096 Mar 18 17:48 ./ drwxrwxrwt 22 root root 36864 Mar 19 14:52 ../ -rwxr-xr-x 1 root root 1204 Oct 2 16:19 config.sh* -rw-r--r-- 1 root root 1101 Jan 7 10:49 config.xml drwxr-xr-x 3 root root 4096 Feb 10 17:34 root/
Note: Sizes and dates may vary depending on the version of the kiwi-doc package you have installed.
- Syntax: kiwi --clone image-path -d destination-path
- Example: kiwi --clone /usr/share/doc/packages/kiwi/examples/suse-11.1/suse-live-iso -d /tmp/tux-suse-live-iso
- Result : /tmp/tux-suse-live-iso similar as the "cp -a <path>/* above
Changing the config.xml
The mandatory config.xml file in the image description directory contains the image definition data described via XML. The structure of the XML data is defined using XSD and is validated by kiwi. The data sections describe various aspects of the image such as the image name, the image type, and the packages to be installed in the image. In addition to package descriptions kiwi supports the use of patterns such as GNOME or KDE, to identify groups of packages.
Modifying general image data
- Using your favorite text editor open the config.xml file in your directory (/tmp/tux-suse-live-iso/config.xml if followed the copy command above). The beginning of the file will look similar to the results shown below.
<?xml version="1.0"?>
<image schemaversion="3.5" name="suse-11.1-live-iso">
<description type="system">
<author>Marcus Schäfer</author>
<contact>ms@novell.com</contact>
<specification>openSUSE 11.1 Live system</specification>
</description>
...
</image>
- the image tag is used to describe top level image properties
- This includes the name attribute set to suse-11.1-live-iso in this case; the value of the name attribute is used as the file name for the image we generate. Change "suse-11.1-live-iso" to "mytux-live-iso".
- We would like to add the optional displayname attribute; the value of the displayname attribute is used as the boot menu title in grub (the image boot loader). Using the name and displayname attributes supports the separation of the image name, such as "suse-11.1-live-iso" from the name displayed in the boot menu, "mytux" in our example.
- The mandatory "description" element contains information about the creator of this image description. The "type" attribute indicates whether this is a system image or a boot image description, determined by the value "system" or "boot", respectively.
- the author tag identifies the author of this image description; change the value to your name
- the contact tag identifies a means to contact the author; change the value to your email-address
- the specification tag provides space for a short identification of the purpose of this image
- After applying the above changes the beginning of your file should look similar to the following (should your name happen to be Foo Bar):
<?xml version="1.0"?>
<image schemeversion="2.4" name="mytux-live-iso" displayname="mytux" >
<description type="system">
<author>Foo Bar</author>
<contact>foobar@suse.com</contact>
<specification>My tux Live system based on openSUSE 11.1</specification>
</description>
...
</image>
Adding a package
- The packages to be installed in the image are described within the packages element. Scroll to the packages list in your config.xml file to see the current list of packages selected for the image
<packages type="image"> <package name="kernel-default"/> <package name="bootsplash"/> <package name="bootsplash-branding-openSUSE"/> <package name="ifplugd"/> <package name="vim"/> <opensusePattern name="default"/> <opensusePattern name="kde4"/> </packages>
- From the element names in the list we can conclude that kiwi will process 5 packages and 2 patterns when this image is created.
- As stated earlier we want to add the not very useful, but funny kde4-amor package to our image. This is accomplished by adding a new package element to the list of packages. The result is shown below (with emphasis on the change).
<packages type="image"> <package name="kernel-default"/> <package name="bootsplash"/> <package name="bootsplash-branding-openSUSE"/> <package name="ifplugd"/> <package name="vim"/> <package name="kde4-amor"/> <opensusePattern name="default"/> <opensusePattern name="kde4"/> </packages>
- This is the only required change.
With the change to the packages list the "kde4-amor" package is now part of the image definition and kiwi will install the package into the unpacked image in the preparation step. Feel free to add additional packages or patterns at your discretion.
Change/Add Repositories
In the Repository Options section in the Start Cooking recipe, the kiwi command line arguments for specifying a repository were presented. Now we will examine how to describe an installation source in the config.xml file to allow us to execute kiwi without using the "--set-repro" command line option.
The kiwi tool chain supports two package management systems, zypper the native SUSE package manager, and smart a package manager aiming for universal package format support. The package manager for the image is selected with the "packagemanager" tag which is part of the "preferences" element. Depending on the selected package manager various repository formats can be specified with the "type" attribute on the "repository" element. For details of the supported repository formats please see the FAQ Section.
- The default settings for openSUSE 11.1 are to use zypper as the package manager and a "yast2" repository. Scrolling to the repository element in your config.xml file you have open in your favorite editor you will see a definition similar to the one shown below.
<repository type="yast2"> <!--<source path="/image/CDs/full-11.1-i386"/>--> <source path="opensuse://11.1/repo/oss/"/> </repository>
- The first entry is a comment indicating the directory path containing the files within the repository.
- The second entry provides the value for the location of a repository, "opensuse://11.1/repo/oss/" in this case.
- this value contains "opensuse" as a keyword. The "opensuse" keyword is understood by kiwi as the openSUSE online repository. The "opensuse" keyword can be expanded to http://download.opensuse.org/distribution. such that the complete path to the repository is http://download.opensuse.org/distribution11.1/repo/oss/.
- One of the options highlighted in the Repository Options section was the use of the openSUSE 11.1 DVD as a local repository. Assuming the DVD is mounted as discussed previously we can use it as the repository with the following specification in the config.xml file.
<repository type="yast2"> <source path="/media/SU1110.001"/> </repository>
</nowiki>
- We can also specify the iso image as the repository after it is mounted as a loopback device
mount -o loop /path-to-the-iso-file/filename.iso /mnt
- Using this mount point the repository can be specified as shown below.
<repository type="yast2">
<source path="/mnt"/>
</repository>
- The syntax supported by the config.xml file allows us to use an iso image without mounting the image as a loopback device. Assuming the iso image is loacted in /tmp and we are using the openSUSE 11.1 x86 image the following specification will do the trick.
<repository type="yast2">
<source path="iso:/tmp/openSUSE-11.1-DVD-i586.iso"/>
</repository>
Within each "repository" element only one "source" element can be specified. To use multiple repositories you may specify as many "repository" elements as needed. If the same package exists in multiple specified repositories the resolution of the duplicity is determined by the package manager. Generally the package manager selects the latest packages available.
- The example below shows the use of a loop mounted iso image and a local directory containing rpm files.
<repository type="yast2">
<source path="/mnt"/>
</repository>
<repository type="rpm-dir">
<source path="/home/my_rpms"/>
</repository>
For additional details about the use of the "repository" element consult the KIWI Image System Cookbook in /usr/share/doc/packages/kiwi/kiwi.pdf, installed with the kiwi-doc package, or the online version found here.
You may also consult the schema for the config.xml file by navigating to /usr/share/doc/packages/kiwi/schema/kiwi.xsd.html with your favorite browser. This file is installed with the kiwi-doc package. However, if you are not comfortable with XSD this is not your best source of information.
Building the LiveCD
With the changes from the previous sections applied we can now rebuild our LiveCD image using the following commands.
- Remove the target directory (kiwi will not over write the unpacked image and will error out)
- Create a new target directory
- Prepare the image
- Create the image
Once the create step finishes with no complaints you can test the iso image with qemu.