.. _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:

- `archive`: By default the output files of a KIS image will be stored
  in a tarball archive. If you want to store the output files
  individually instead, set this attribute to `false`.

- `compressed`: By default the output files of a KIS image will be tar
  archived and compressed. If you want to store the output files in
  the archive without compression, set this attribute to `false`.
  If the `archive` attribute is set to `false`, this attribute has no
  effect.

- `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_kis} \
       --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_kis}.*.ext3,if=virtio,driver=raw \
       -serial stdio

.. note::

   Testing the components of a KIS image normally requires a deployment
   infrastructure and a deployment process encoded in the initrd. 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`.
