Jump to contentJump to page navigation: previous page [access key p]/next page [access key n]
Applies to SUSE Linux Enterprise Server 11 SP4


KIWI is a system for creating operating system images. An image is a directory with a file containing the operating system, its applications and configurations, the file system structure of the OS, possible additional metadata, and (depending on the image type) also disk geometry and partition table data. With KIWI you can create LiveCDs and LiveDVDs, USB sticks, virtual disk to play in full virtual systems like VMware, XEN images for paravirtualization in a hypervisor, and a PXE environment to boot from network.

17.1 Prerequisites for KIWI

To build images with KIWI, you need the following preconditions:

  1. Free sufficient disk space for the operation.

  2. KIWI is split into several packages, targeted to different image types. In any case, you need the base package kiwi. Depending on your target image, you need the following packages:

    Image Type

    Package Name

    Installation Media




    USB Sticks


    Network Client


  3. Install the kiwi-doc package. You can find some example configurations to get an idea about structure and content.

  4. Know the KIWI configuration file and its structure. It is based on a RELAX NG schema and documented in the kiwi package under /usr/share/doc/packages/kiwi/kiwi.html. You need this document, if you want to create the configuration file from scratch or when you want to insert elements or attributes.

17.2 Knowing KIWI’s Build Process

The building process of KIWI is separated into three steps:

  1. Physical Extend (Preparation).  This stage prepares the content of your new file system. During this step the root directory is created, you determine which packages are installed on your image and which user configuration files are included.

  2. Logical Extend (Creation).  This stage requires a successful preparation step. The logical extend step creates the operating system image based on the first step.

  3. Deployment.  The resulting image type can be deployed with different methods like installed on a hard disk or played by a virtualization system (VMware, Qemu, VirtualBox).

17.3 Image Description

KIWI needs an image description to build an image type. The image description is a directory which contains at least a file config.xml, or alternatively with the extension *.kiwi.

17.3.1 Contents of Image Description

The following table contains additional optional information. However, most of this information is mandatory for the later functionality of the operating system:

Table 17.1: Additional Files and Directories For Image Description




optional subdirectory. Contains Bash scripts which are executed after the installation of all the image packages.


optional configuration script while creating the physical extend


configuration file for each image description, explained in Section 17.3.2


archive, only used for ISO images


manipulate extracted data from config-cdroot.tgz


configuration file created by AutoYaST


configuration file for controlling the YaST firstboot service


optional configuration script while creating the preparation step


contains other directories, special files, and scripts which are changed after the installation of all image packages

17.3.2 The config.xml File

All information about an image description is stored in the central configuration XML file config.xml. Each time KIWI is executed, config.xml is validated against an RELAX NG schema (see http://www.relaxng.org for more information about this schema language). Therefore, it is recommended to use an adequate XML editor with RELAX NG support or to use the documentation about the schema in the HTML file /usr/share/doc/packages/kiwi/schema/kiwi.xsd.html.

The configuration file consists of several parts:

  • some description about the author, contact information, and a short explanation.

  • preferences option needed for the logical extent stage.

  • information about the users, their name, their home directories, and their passwords.

  • links to repositories.

  • a list of packages that are used for the definied image type.

  • and other less important information which can be viewed in the above HTML file of the RELAX NG schema documentation.

A skeleton of the file is shown in the following example:

Example 17.1: KIWI Configuration File
<image schemeversion="2.0" name="..."> 1
  <description type="system"> 2
  <preferences> 3
    <type primary="true" boot="..." flags="...">iso</type>
    <type boot="..." filesystem="ext3" format="vmdk">vmx</type>
    <type boot="..." filesystem="ext3">xen</type>
    <type boot="..." filesystem="squashfs" flags="unified">oem</type>
    <size unit="M">780</size>
  <users group="users"> 4
    <user name="root" pwd="" home="/root"/>
  <repository type="rpm-md"> 5
    <source path="/home/rpmdir"/>
  <packages type="image" patternPackageType="onlyRequired"> 6
    <package name="yast2-live-installer"/>
    <package name="pam"/>
    <!-- List of packages reduced -->


The root element of every KIWI configuration file. Each file requires the version number. An optional kiwirevision attribute can be used to specify an SVN revision of KIWI.


Contains mandatory descriptions with information about the creator of this image descriptions, its contact address and a short explanation.


Contains mandatory preferences with information about the version of this image, the used package manager, the supported image types, and other settings.


The optional users element contains a list of all users which are added to the image. The user element contains the name, the path to its home directory, password, and the shell.


Contains a mandatory list of repositories used by the package manager.


Contains a mandatory list of packages which are included into the image.

More details about the configuration file is shown in the HTML page above.

17.4 Creating Appliances with KIWI

This section describes how to create appliances with KIWI. An appliance is an especially-designed operating system for a specific task. For example, you can create an appliance with the focus on office programs.

17.4.1 Creating a Local Installation Source

All examples in kiwi-doc packages need a valid installation source to create an image. Usually the examples connect to a network resource. The higher the network bandwidth, the faster the image creation. If you do not have a fast network or you do not want to use it, create a local installation resource. Proceed as follows:

  1. Collect your installation DVD.

  2. Open a shell and become root.

  3. Create the directory for your local installation directory. The examples use usually the path /image/CDs/full-VERSION-ARCH. Replace the placeholders VERSION and ARCH with the respective values.

  4. Mount the medium. Replace the DRIVE placeholder with the respective device (usually dvd, cdrom, etc.):

    mount -o loop /dev/DRIVE /mnt
  5. Copy all the content of the medium into the installation directory:

    cp -a /mnt/* /images/CDs/full-VERSION-ARCH

To use the local installation source, all you need to do is to enable it in the repository element:

<repository type="...">
  <!-- Remove the comment markers in the next line -->
  <!-- <source path="/image/CDs/full-VERSION-ARCH" -->
  <source path="opensuse://openSUSE:11.0/standard"/> 

17.4.2 Creating an Image

An image is a virtual disk image containing all partitions, boot loader information, and packages as it resides on a real disk. To create an ISO image, proceed as follows:

  1. Install the packages kiwi and kiwi-doc and resolve any dependencies.

  2. Open a shell and become root.

  3. Copy the directory /usr/share/doc/packages/kiwi/examples/suse-11.0/suse-oem-preload to your current directory.

  4. Open the file config.xml and locate the element repository. If you want to use a local installation source, refer to Section 17.4.1 for more information.

  5. Execute KIWI with the following command to prepare the first stage (physical extend):

    kiwi --prepare suse-oem-preload --root oem
  6. Build the ISO image:

    kiwi --create oem --type iso --destdir /tmp/myoem

17.4.3 Creating Preload Image with NFS

To create an image with NFS functionality, proceed as follows:

  1. Open a shell and become root.

  2. Copy the directory /usr/share/doc/packages/kiwi/examples/suse-11.1/suse-oem-preload to your current directory.

  3. Open the file suse-oem-preload/config.xml and locate the packages element with the attribute type="image".

  4. Insert the following line between <packages type="image"> and </packages> and save the file:

    <package name="nfs-client"/>
  5. Rebuild the image as described in Step 5.

17.5 For More Information

Find more information in the following documents on the KIWI Portal at http://en.opensuse.org/Portal:KIWI.

Print this page