.. _kis:

Build KIS Image (Kernel, Initrd, System)
========================================

.. sidebar:: Abstract

   This page explains how to build an image that consists
   of three components: the kernel, an initrd, and an
   optional root filesystem image. In {kiwi} terminology,
   this type of image is called KIS.

A KIS image is a collection of image components that are not
associated with a dedicated use case. This means that as far as {kiwi}
is concerned, it is not known in which environment these components
are expected to be used. The predecessor of this image type was called
`pxe` under the assumption that the components will be used
in a PXE boot environment. However, this assumption is not
always true, and the image components may be used in different
ways. Because there are so many possible deployment strategies
for a `kernel` plus `initrd` and an optional `system root filesystem`,
{kiwi} provides this as the universal `KIS` type.

The former `pxe` image type still exists, but it is expected
to be used only in combination with the legacy `netboot` infrastructure,
as described in :ref:`build_legacy_pxe`.

To add a KIS build to an appliance, create a `type` element with
`image` set to `kis` in :file:`config.xml`, as shown below:

.. code:: xml

   <preferences>
       <type image="kis"/>
   </preferences>

With this image type setup, {kiwi} builds a kernel and initrd
not associated with any system root filesystem. Normally, such
an image is only useful with certain custom dracut extensions
as part of the image description.

The following attributes of the `type` element are often used when
building KIS images:

- `filesystem`: Specifies the root filesystem and triggers the build
  of an additional filesystem image of that filesystem. The generated
  kernel command-line options file (append file) will then also
  include a `root=` parameter that references this filesystem image's UUID.
  Whether the information from the append file should be used or not is
  optional.

- `kernelcmdline`: Specifies kernel command-line options that are
  part of the generated kernel command-line options file (append file).
  By default, the append file contains neither information nor a reference
  to the root UUID if the `filesystem` attribute is used.

All other attributes of the `type` element that apply to an optional
root filesystem image remain in effect in the system image of a KIS
image as well.

With the appropriate settings present in :file:`config.xml`, you can use {kiwi} to
build the image:

.. code:: bash

   $ sudo kiwi-ng --type kis system build \
       --description kiwi/build-tests/{exc_description_pxe} \
       --set-repo {exc_repo_tumbleweed} \
       --target-dir /tmp/myimage

The resulting image components are saved in :file:`/tmp/myimage`.
Outside of a deployment infrastructure, the example KIS image can be
tested with QEMU as follows:

.. code:: bash

   $ sudo qemu
       -kernel /tmp/myimage/*.kernel \
       -initrd /tmp/myimage/*.initrd \
       -append "$(cat /tmp/myimage/*.append) rw" \
       -drive file=/tmp/myimage/{exc_image_base_name_pxe}.*-{exc_image_version},if=virtio,driver=raw \
       -serial stdio

.. note::

   Testing the components of a KIS image normally requires a deployment
   infrastructure and a deployment process. An example of a deployment
   infrastructure using PXE is provided by {kiwi} with the `netboot`
   infrastructure. However, that netboot infrastructure is no longer developed
   and is only kept for compatibility reasons. For details, see
   :ref:`build_legacy_pxe`.
