Basic Workflow



Installation of a Linux system generally occurs by booting the target system from an installation source such as an installation CD/DVD, a live CD/DVD, or a network boot environment (PXE). The installation process is often driven by an installer that interacts with the user to collect information about the installation. This information generally includes the software to be installed, the timezone, system user data, and other information. Once all the information is collected, the installer installs the software onto the target system using packages from the software sources (repositories) available. After the installation is complete the system usually reboots and enters a configuration procedure upon start-up. The configuration may be fully automatic or it may include user interaction.

This description applies for version 9.17.39.

A system image (usually called “image”), is a complete installation of a Linux system within a file. The image represents an operational system and, optionally, contains the “final” configuration.

The behavior of the image upon deployment varies depending on the image type and the image configuration since KIWI allows you to completely customize the initial start-up behavior of the image. Among others, this includes images that:

  • can be deployed inside an existing virtual environment without requiring configuration at start-up.

  • automatically configure themselves in a known target environment.

  • prompt the user for an interactive system configuration.

The image creation process with KIWI is automated and does not require any user interaction. The information required for the image creation process is provided by the primary configuration file named config.xml. This file is validated against the schema documented in Schema Documentation section. In addition, the image can optionally be customized using the and scripts and by using an overlay tree (directory) called root. See Components of an Image Description section for further details.


Previous Knowledge

This documentation assumes that you are familiar with the general concepts of Linux, including the boot process, and distribution concepts such as package management.

Components of an Image Description

A KIWI image description can composed by several parts. The main part is the KIWI description file itself (named config.xml or an arbitrary name plus the *.kiwi extension). The configuration XML is the only required component, others are optional.

These are the optional components of an image description:

  1. shell script

    Is the configuration shell script that runs and the end of the prepare step if present. It can be used to fine tune the unpacked image.

    Note that the script is directly invoked by the operating system if its executable bit is set. Otherwise it is called by bash instead.

  2. shell script

    Is the configuration shell script that runs at the beginning of the create step. So it is expected to be used to handle image type specific tasks. It is called in a similar fashion as

  3. Overlay tree directory

    The overlay tree is a folder (called root) or a tarball file (called root.tar.gz) that contains files and directories that will be copied to the target image build tree during the prepare step. It is executed after all the packages included in the config.xml file have been installed. Any already present file is overwritten.

  4. CD root user data

    For live ISO images and install ISO images an optional cdroot archive is supported. This is a tar archive matching the name config-cdroot.tar[.compression_postfix]. If present it will be unpacked as user data on the ISO image. This is mostly useful to add e.g license files or user documentation on the CD/DVD which can be read directly without booting from the media.

  5. Archives included in the config.xml file.

    The archives that are included in the <packages> using the <archive> subsection:

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