1 Overview #

1.1 Basic Workflow
1.2 Conceptual Overview
1.3 Terminology
1.4 System Requirements

Note

Abstract

This document provides a conceptual overview about the steps of creating an image with KIWI NG. It also explains the terminology regarding the concept and process when building system images with KIWI NG 9.25.12.

1.1 Basic Workflow #

Note

Abstract

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.25.12.

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 config.xml. This file is validated against the schema documented in: Chapter 8, Image Description.

In addition, the image can optionally be customized using the config.sh and images.sh scripts and by using an overlay tree (directory) called root. See Components of an Image Description section for further details.

Note

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.

1.1.1 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:

config.sh shell script
Is the configuration shell script that runs and the end of the Section 7.10.1, “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.
images.sh 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 config.sh
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 Section 7.10.1, “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.
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 config.xml file.
The archives that are included in the <packages> using the <archive> subsection:
```
<packages type="image">
    <archive name="custom-archive.tgz"/>
</packages>
```

1.2 Conceptual Overview #

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

KIWI NG 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 image description.
The second step, the create operation, creates the packed image or image in the specified format based on the unpacked image and the information provided in the configuration file.

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 image description.

1.3 Terminology #

Appliance: An appliance is a ready to use image of an operating system including a pre-configured application for a specific use case. The appliance is provided as an image file and needs to be deployed to, or activated in the target system or service.
Image: The result of a KIWI NG build process.
Image Description: Specification to define an appliance. The image description is a collection of human readable files in a directory. At least one XML file config.xml or .kiwi is required. In addition there may be as well other files like scripts or configuration data. These can be used to customize certain parts either of the KIWI NG build process or of the initial start-up behavior of the image.
Overlay Files: A directory structure with files and subdirectories stored as part of the Image Description. This directory structure is packaged as a file root.tar.gz or stored inside a directory named root. Additional overlay directories for selected profiles are supported too and are taken into account if the directory name matches the name of the profile. The content of each of the directory structures is copied on top of the existing file system (overlayed) of the appliance root. This also includes permissions and attributes as a supplement.
KIWI NG: An OS appliance builder.
Virtualization Technology: Software simulated computer hardware. A virtual machine acts like a real computer, but is separated from the physical hardware. Within this documentation the QEMU virtualization system is used. Another popular alternative is Virtualbox.

1.4 System Requirements #

To use and run KIWI NG, you need:

A recent Linux distribution, see Section 5.1, “Build Host Constraints” for details.
Enough free disk space to build and store the image. We recommend a minimum of 15GB.
Python version 3.5 or higher
Git (package git) to clone a repository.
Any virtualization technology to start the image. We recommend QEMU.

Print this page