Debian Codegraph @

doc/source/building_images/build_kis.rst

raw
1 .. _kis:
2
3 Build KIS Image (Kernel, Initrd, System)
4 ========================================
5
6 .. sidebar:: Abstract
7
8 This page explains how to build an image that consists
9 of three components: the kernel, an initrd, and an
10 optional root filesystem image. In {kiwi} terminology,
11 this type of image is called KIS.
12
13 A KIS image is a collection of image components that are not
14 associated with a dedicated use case. This means that as far as {kiwi}
15 is concerned, it is not known in which environment these components
16 are expected to be used. The predecessor of this image type was called
17 `pxe` under the assumption that the components will be used
18 in a PXE boot environment. However, this assumption is not
19 always true, and the image components may be used in different
20 ways. Because there are so many possible deployment strategies
21 for a `kernel` plus `initrd` and an optional `system root filesystem`,
22 {kiwi} provides this as the universal `KIS` type.
23
24 The former `pxe` image type still exists, but it is expected
25 to be used only in combination with the legacy `netboot` infrastructure,
26 as described in :ref:`build_legacy_pxe`.
27
28 To add a KIS build to an appliance, create a `type` element with
29 `image` set to `kis` in :file:`config.xml`, as shown below:
30
31 .. code:: xml
32
33 <preferences>
34 <type image="kis"/>
35 </preferences>
36
37 With this image type setup, {kiwi} builds a kernel and initrd
38 not associated with any system root filesystem. Normally, such
39 an image is only useful with certain custom dracut extensions
40 as part of the image description.
41
42 The following attributes of the `type` element are often used when
43 building KIS images:
44
45 - `filesystem`: Specifies the root filesystem and triggers the build
46 of an additional filesystem image of that filesystem. The generated
47 kernel command-line options file (append file) will then also
48 include a `root=` parameter that references this filesystem image's UUID.
49 Whether the information from the append file should be used or not is
50 optional.
51
52 - `kernelcmdline`: Specifies kernel command-line options that are
53 part of the generated kernel command-line options file (append file).
54 By default, the append file contains neither information nor a reference
55 to the root UUID if the `filesystem` attribute is used.
56
57 All other attributes of the `type` element that apply to an optional
58 root filesystem image remain in effect in the system image of a KIS
59 image as well.
60
61 With the appropriate settings present in :file:`config.xml`, you can use {kiwi} to
62 build the image:
63
64 .. code:: bash
65
66 $ sudo kiwi-ng --type kis system build \
67 --description kiwi/build-tests/{exc_description_pxe} \
68 --set-repo {exc_repo_tumbleweed} \
69 --target-dir /tmp/myimage
70
71 The resulting image components are saved in :file:`/tmp/myimage`.
72 Outside of a deployment infrastructure, the example KIS image can be
73 tested with QEMU as follows:
74
75 .. code:: bash
76
77 $ sudo qemu
78 -kernel /tmp/myimage/*.kernel \
79 -initrd /tmp/myimage/*.initrd \
80 -append "$(cat /tmp/myimage/*.append) rw" \
81 -drive file=/tmp/myimage/{exc_image_base_name_pxe}.*-{exc_image_version},if=virtio,driver=raw \
82 -serial stdio
83
84 .. note::
85
86 Testing the components of a KIS image normally requires a deployment
87 infrastructure and a deployment process. An example of a deployment
88 infrastructure using PXE is provided by {kiwi} with the `netboot`
89 infrastructure. However, that netboot infrastructure is no longer developed
90 and is only kept for compatibility reasons. For details, see
91 :ref:`build_legacy_pxe`.