1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
|
Basic Workflow
==============
.. note:: **Abstract**
The 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
available software sources (repositories). After the installation is
complete, the system usually reboots and enters a configuration procedure
upon startup. The configuration may be fully automatic, or it may include
user interaction.
This description applies for version |version|.
A system image (usually called an "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} allows you to completely customize
the initial startup behavior of the image. Among others, this includes
images that:
* can be deployed inside an existing virtual environment without requiring
configuration at startup.
* automatically configure themselves in a known target environment.
* prompt the user for an interactive system configuration.
The image creation process with {kiwi} 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 :file:`config.xml`.
This file is validated against the schema documented in:
:ref:`image-description`.
In addition, the image can optionally be customized
using the :file:`config.sh` and :file:`images.sh` scripts
and by using an *overlay tree (directory)* called :file:`root`.
See the :ref:`description_components` 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.
.. _description_components:
Components of an Image Description
----------------------------------
A {kiwi} image description can be composed of several parts. The main part is
the {kiwi} description file itself (named :file:`config.xml` or an arbitrary
name plus the :file:`*.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
This is the configuration shell script that runs at the end of the
:ref:`prepare step <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 :file:`bash` instead.
#. ``images.sh`` shell script
This 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 :file:`root`)
or a tarball file (called :file:`root.tar.gz`) that contains
files and directories that will be copied to the target image build tree
during the :ref:`prepare step <prepare-step>`. It is executed
after all the packages included in the :file:`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
:file:`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 :file:`config.xml` file.
The archives that are included in the `<packages>` using the `<archive>`
subsection:
.. code:: xml
<packages type="image">
<archive name="custom-archive.tgz"/>
</packages>
|
