Working with KIWI

Hint

Abstract

The following sections describe the general workflow of building appliances with KIWI 9.19.6.

Overview

KIWI builds so-called system images (a fully installed and optionally configured system in a single file) of a Linux distribution in two steps (for further details, see Image Building Process):

  1. Prepare operation: generate an unpacked image tree of your image. The unpacked tree is a directory containing the future file system of your image, generated from your image description.

  2. Create operation: the unpacked tree generated in step 1 is packaged into the format required for the final usage (e.g. a qcow2 disk image to launch the image with QEMU).

KIWI executes these steps using the following components, which it expects to find in the description directory:

  1. config.xml: The Image Description

    This XML file contains the image description, which is a collection of general settings of the final image, like the partition table, installed packages, present users, etc.

    The filename config.xml is not mandatory, the image description file can also have an arbitrary name plus the *.kiwi extension. KIWI first looks for a config.xml file. If it cannot be found, it picks the first *.kiwi file.

  2. config.sh and images.sh: User Defined Scripts

    If present, these configuration shell scripts run at the end of the prepare operation (config.sh) or at the beginning of the create operation (images.sh). They can be used to fine tune the image in ways that are not possible via the settings provided in config.xml.

  3. Overlay tree directory

    The overlay tree is a folder (called root) or a tarball (called root.tar.gz) that contains files and directories that will be copied into the unpacked image tree during the Prepare operation. The copying is executed after all the packages included in config.xml have been installed. Any already present files are overwritten.

  4. CD root user data

    For live ISO images and install ISO images an optional archive is supported. This is a tar archive matching the name config-cdroot.tar[.compression_postfix].

    If present, the archive will be unpacked as user data on the ISO image. For example, this is used to add license files or user documentation. The documentation can then be read directly from the CD/DVD without booting from the media.

  5. Archives included in the config.xml file.

    The archives that are included in <packages> using the <archive> element (see The archive element):

    <packages type="image">
        <archive name="custom-archive.tgz"/>
    </packages>
    

Image Building Process

KIWI creates images in a two step process: The first step, the prepare operation, generates a so-called unpacked image tree (directory) using the information provided in the config.xml configuration file (see The Image Description)

The second step, the create operation, creates the packed image or image in the specified format based on the unpacked image tree and the information provided in the config.xml configuration file.

Image Creation Architecture

Image Creation Architecture

The Prepare Step

As the first step, KIWI creates an unpackaged image tree, also called “root tree”. This directory will be the installation target for software packages to be installed during the image creation process.

For the package installation, KIWI relies on the package manager specified in the packagemanager element in config.xml (see Common Elements). KIWI supports the following package managers: dnf, zypper (default) and apt-get.

The prepare step consists of the following substeps:

  1. Create Target Root Directory

    KIWI aborts with an error if the target root tree already exists to avoid accidental deletion of an existing unpacked image.

  2. Install Packages

    First, KIWI configures the package manager to use the repositories specified in the configuration file, via the command line, or both. After the repository setup, the packages specified in the bootstrap section of the image description are installed in a temporary directory external to the target root tree. This establishes the initial environment to support the completion of the process in a chroot setting. The essential packages are filesystem and glibc-locale to specify as part of the bootstrap. The dependency chain of these two packages is usually sufficient to populate the bootstrap environment with all required software to support the installation of packages into the new root tree. The aforementioned two packages might not be enough for every distribution. Consult the kiwi-descriptions repository containing examples for various Linux distributions.

    The installation of software packages through the selected package manager may install unwanted packages. Removing these packages can be accomplished by marking them for deletion in the image description, see Adding and removing packages.

  3. Apply the Overlay Tree

    Next, KIWI applies all files and directories present in the overlay directory named root or in the compressed overlay root.tar.gz to the target root tree. Files already present in the target root directory are overwritten. This allows you to overwrite any file that was installed by one of the packages during the installation phase.

  4. Apply Archives

    All archives specified in the archive element of the config.xml file are applied in the specified order (top to bottom) after the overlay tree copy operation is complete (see The archive element). Files and directories are extracted relative to the top level of the new root tree. As with the overlay tree, it is possible to overwrite files already existing in the target root tree.

  5. Execute the user-defined script config.sh

    At the end of the preparation stage the script config.sh is executed (if present). It is run in the top level directory of the target root tree. The script’s primary function is to complete the system configuration, for example, to activate services. See Image Customization via the config.sh Shell Script section for further details.

  6. Modify the Root Tree

    The unpacked image tree is now finished to be converted into the final image in the create step. It is possible to make manual modifications to the unpacked tree before it is converted into the final image.

    Since the unpacked image tree is just a directory, it can be modified using the standard tools. Optionally, it is also possible to “change root (chroot)” into it, for instance to invoke the package manager. Beside the standard file system layout, the unpacked image tree contains an additional directory named /image that is not present in a regular system. It contains information KIWI requires during the create step, including a copy of the config.xml file.

    By default, KIWI will not stop after the prepare step and will directly proceed with the create step. Therfore to perform manual modifications, proceed as follows:

    $ kiwi-ng system prepare $ARGS
    $ # make your changes
    $ kiwi-ng system create $ARGS
    

    Warning

    Modifications of the unpacked root tree

    Do not make any changes to the system, since they are lost when re-running the prepare step again. Additionally, you may introduce errors that occur during the create step which are difficult to track. The recommended way to apply changes to the unpacked image directory is to change the configuration and re-run the prepare step.

The Create Step

KIWI creates the final image during the create step: it converts the unpacked root tree into one or multiple output files appropriate for the respective build type.

It is possible to create multiple images from the same unpacked root tree, for example, a self installing OEM image and a virtual machine image from the same image description. The only prerequisite is that both image types are specified in config.xml.

During the create step the following operations are performed by KIWI:

  1. Execute the User-defined Script images.sh

    At the beginning of the image creation process the script named images.sh is executed (if present). It is run in the top level directory of the unpacked root tree. The script is usually used to remove files that are no needed in the final image. For example, if an appliance is being built for a specific hardware, unnecessary kernel drivers can be removed using this script.

    See Image Customization via the images.sh Shell Script for further details.

  2. Create the Requested Image Type

    KIWI converts the unpacked root into an output format appropriate for the requested build type.