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.24.52.
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 NG 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 NG 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
This file is validated against the schema documented in:
In addition, the image can optionally be customized
and by using an overlay tree (directory) called
See Components of an Image Description section for further details.
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 NG image description can composed by several parts. The main part is
the KIWI NG 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:
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
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
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.xmlfile have been installed. Any already present file is overwritten.
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.
Archives included in the
The archives that are included in the
<packages type="image"> <archive name="custom-archive.tgz"/> </packages>