almalinux/kiwi-el8
14
0
Fork 0
Code Issues Pull Requests Releases Activity

Fix documentation for language errors and wording

Browse Source
This commit is contained in:
Marcus Schäfer 2026-01-31 18:42:45 +01:00
parent 225ff2544e
commit 29c52aad9d
No known key found for this signature in database
GPG Key ID: A16C1128698C8CAC
70 changed files with 2188 additions and 2187 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/source/building_images.rst
View File

@ -5,9 +5,9 @@ Building Images for Supported Types
.. note::
This document provides an overview how to build and use
the {kiwi} supported image types. All images that we provide
for testing uses the root password: `linux`
This document provides an overview of how to build and use
the {kiwi}-supported image types. All images that we provide
for testing use the root password: `linux`.
.. toctree::
:maxdepth: 1

34
doc/source/building_images/build_container_image.rst
View File

@ -7,18 +7,18 @@ Build a Container Image
This page explains how to build a Container Image. It covers the following topics:
* basic configuration explanation
* a basic configuration explanation
* how to build a Container Image
* how to run it with a Container Runtime
{kiwi} can build native container images from scratch or using existing images.
{kiwi} container images are considered to be native, because a {kiwi} tarball
image can be loaded directly into container runtimes like Podman, Docker or
{kiwi} container images are considered native because a {kiwi} tarball
image can be loaded directly into container runtimes like Podman, Docker, or
Containerd, including common container configurations.
The container configuration metadata is supplied to {kiwi} as part of the
:ref:`XML description file <description_components>` using the
``<containerconfig>`` tag. The following configuration metadata can be
`<containerconfig>` tag. The following configuration metadata can be
specified.
`containerconfig` attributes:
@ -28,16 +28,16 @@ specified.
* ``maintainer``: Specifies the author of the container. Equivalent to the
`MAINTAINER` directive in a :file:`Dockerfile`.
* ``user``: Sets the user name or user id (UID) to be used when
running `entrypoint` and `subcommand`. Equivalent of the `USER`
running `entrypoint` and `subcommand`. Equivalent to the `USER`
directive of a :file:`Dockerfile`.
* ``workingdir``: Sets the working directory to be used when running
`cmd` and `entrypoint`. Equivalent of the `WORKDIR` directive in a
`cmd` and `entrypoint`. Equivalent to the `WORKDIR` directive in a
:file:`Dockerfile`.
`containerconfig` child tags:
* ``subcommand``: Provides the default execution parameters of the
container. Equivalent of the `CMD` directive in a :file:`Dockerfile`.
container. Equivalent to the `CMD` directive in a :file:`Dockerfile`.
* ``labels``: Adds custom metadata to an image using key-value pairs.
Equivalent to one or more `LABEL` directives in a :file:`Dockerfile`.
* ``expose``: Defines which ports can be exposed to the outside when
@ -46,17 +46,17 @@ specified.
* ``environment``: Sets environment variables using key-value pairs.
Equivalent to one or multiple `ENV` directives in a :file:`Dockerfile`.
* ``entrypoint``: Sets the binary to use for executing all commands inside the
container. Equivalent of the `ENTRYPOINT` directive in a :file:`Dockerfile`.
container. Equivalent to the `ENTRYPOINT` directive of a :file:`Dockerfile`.
* ``volumes``: Creates mountpoints with the given name and marks them to hold
external volumes from the host or from other containers. Equivalent to
one or more `VOLUME` directives in a :file:`Dockerfile`.
* ``stopsignal``: The stopsignal element sets the system call signal that
* ``stopsignal``: The `stopsignal` element sets the system call signal that
will be sent to the container to exit. This signal can be a signal name
in the format SIG[NAME], for instance SIGKILL, or an unsigned number that
matches a position in the kernel's syscall table, for instance 9.
The default is SIGTERM if not defined
in the format `SIG[NAME]`, for instance, `SIGKILL`, or an unsigned number that
matches a position in the kernel's syscall table, for instance, 9.
The default is `SIGTERM` if not defined.
Other :file:`Dockerfile` directives such as ``RUN``, ``COPY`` or ``ADD``,
Other :file:`Dockerfile` directives such as `RUN`, `COPY`, or `ADD`,
can be mapped to {kiwi} using the
:ref:`config.sh <description_components>` script file to run Bash commands,
or the :ref:`overlay tree <description_components>` to include
@ -68,13 +68,13 @@ openSUSE Leap:
1. Make sure you have checked out the example image descriptions
(see :ref:`example-descriptions`).
#. Include the ``Virtualization/containers`` repository into your list (replace the placeholder `<DIST>` with the name of the desired distribution):
#. Include the `Virtualization/containers` repository in your list (replace the placeholder `<DIST>` with the name of the desired distribution):
.. code:: bash
$ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/containers/<DIST> container-tools
#. Install :command:`umoci` and :command:`skopeo` tools
#. Install `umoci` and `skopeo` tools.
.. code:: bash
@ -91,13 +91,13 @@ openSUSE Leap:
#. Test the container image.
First load the new image into your container runtime:
First, load the new image into your container runtime:
.. code:: bash
$ podman load -i {exc_image_base_name_docker}.x86_64-{exc_image_version}.docker.tar.xz
Then run the image:
Then, run the image:
.. code:: bash

24
doc/source/building_images/build_enclave.rst
View File

@ -15,10 +15,10 @@ to further protect and securely process highly sensitive data such as personally
identifiable information (PII), healthcare, financial, and intellectual property
data within their Amazon EC2 instances. Nitro Enclaves uses the same Nitro
Hypervisor technology that provides CPU and memory isolation for EC2 instances.
For further details please visit https://aws.amazon.com/ec2/nitro/nitro-enclaves
For further details, please visit https://aws.amazon.com/ec2/nitro/nitro-enclaves.
To add an enclave build to your appliance, create a `type` element with
`image` set to `enclave` in the :file:`config.xml` file as shown below:
`image` set to `enclave` in the :file:`config.xml` file, as shown below:
.. code:: xml
@ -41,16 +41,16 @@ To add an enclave build to your appliance, create a `type` element with
The following attributes of the `type` element are relevant:
- `enclave_format`: Specifies the enclave target
- `enclave_format`: Specifies the enclave target.
As of today only the `aws-nitro` enclave target is supported
As of today, only the `aws-nitro` enclave target is supported.
- `kernelcmdline`: Specifies the kernel commandline suitable for the enclave
- `kernelcmdline`: Specifies the kernel commandline suitable for the enclave.
An enclave is a system that runs completely in RAM loaded from
an enclave binary format which includes the kernel, initrd and
the kernel commandline suitable for the target system.
An enclave is a system that runs completely in RAM, loaded from
an enclave binary format that includes the kernel, initrd, and
the kernel command line suitable for the target system.
With the appropriate settings specified in :file:`config.xml`, you can build an
image using {kiwi}:
@ -76,9 +76,9 @@ be tested with QEMU:
The image is now complete and ready to use. Access to the system is
possible via ssh through a vsock connection into the guest. To establish
a vsock connection it's required to forward the connection through the
guest AF_VSOCK socket. This can be done via a ProxyCommand setup of the
host ssh as follows:
a vsock connection, it's required to forward the connection through the
guest's `AF_VSOCK` socket. This can be done via a `ProxyCommand` setup of the
host's ssh as follows:
.. code:: bash
@ -95,7 +95,7 @@ host ssh as follows:
host *.vsock
ProxyCommand ~/bin/vsock-ssh.sh %h
After the ssh proxy setup login to the enclave with a custom vsock port
After the ssh proxy setup, log in to the enclave with a custom vsock port
as follows:
.. code:: bash

160
doc/source/building_images/build_expandable_disk.rst
View File

@ -8,9 +8,9 @@ Build an Expandable Disk Image
This page explains how to build an expandable disk image.
It covers the following topics:
* build an expandable disk image
* deploy an expandable disk image
* run the deployed system
* builds an expandable disk image
* deploys an expandable disk image
* runs the deployed system
An expandable disk represents the system disk with the capability to automatically
expand the disk and its filesystem to a custom disk geometry. This
@ -38,8 +38,8 @@ system:
virtual disk. It can expand itself to a custom disk geometry.
* The installation image with the suffix :file:`install.iso` is a
hybrid installation system which contains the disk image and is
capable to install this image on any target disk.
hybrid installation system that contains the disk image and is
capable of installing this image on any target disk.
.. _deployment_methods:
@ -59,7 +59,7 @@ Basic deployment strategies are as follows:
2. :ref:`deploy_from_iso`
Boot the installation image and let {kiwi}'s installer
deploy the disk image from CD/DVD or USB stick onto the target disk.
deploy the disk image from a CD/DVD or USB stick onto the target disk.
3. :ref:`deploy_from_network`
@ -72,7 +72,7 @@ Manual Deployment
-----------------
The manual deployment method can be tested using virtualization software
like QEMU and an additional virtual a large-size target disk.
like QEMU and an additional virtual large-size target disk.
To do this, follow the steps below.
1. Create a target disk:
@ -83,12 +83,12 @@ To do this, follow the steps below.
.. note:: Retaining the Disk Geometry
If the target disk geometry is less than or equals to the geometry of
If the target disk geometry is less than or equal to the geometry of
the disk image itself, the disk expansion that is performed on a physical
disk install during the boot workflow is skipped and the
disk install during the boot workflow is skipped, and the
original disk geometry stays unchanged.
2. Dump disk image on target disk:
2. Dump the disk image on the target disk:
.. code:: bash
@ -101,7 +101,7 @@ To do this, follow the steps below.
$ sudo qemu -hda target_disk -m 4096 -serial stdio
On first boot of the target_disk, the system is expanded to the
On the first boot of the `target_disk`, the system is expanded to the
configured storage layout. By default, the system root partition
and filesystem are resized to the maximum free space available.
@ -110,15 +110,15 @@ To do this, follow the steps below.
CD/DVD Deployment
-----------------
The deployment from CD/DVD via an installation image can
The deployment from a CD/DVD via an installation image can
also be tested using virtualization software such as QEMU.
To do this, follow the steps below.
1. Create a target disk:
Follow the steps above to create a virtual target disk
Follow the steps above to create a virtual target disk.
2. Boot the installation image as CD/DVD with the
2. Boot the installation image as a CD/DVD with the
target disk attached.
.. code:: bash
@ -130,9 +130,9 @@ To do this, follow the steps below.
.. note:: USB Stick Deployment
Like any other ISO image built with {kiwi}, the installation
image is also a hybrid image. Thus, it can also be used on USB stick and
serve as installation media as explained in
:ref:`hybrid_iso`
image is also a hybrid image. Thus, it can also be used on a USB stick and
serve as installation media, as explained in
:ref:`hybrid_iso`.
.. _deploy_from_network:
@ -140,8 +140,8 @@ Network Deployment
------------------
The process of deployment from the network downloads the disk image from a
PXE boot server. This requires a PXE network boot server to be setup
as described in :ref:`network-boot-server`
PXE boot server. This requires a PXE network boot server to be set up
as described in :ref:`network-boot-server`.
If the PXE server is running, the following steps show how to test the
deployment process over the network using a QEMU virtual machine as
@ -149,7 +149,7 @@ a target system:
1. Create an installation PXE TAR archive along with your
disk image by replacing the following configuration in
kiwi/build-tests/{exc_description_disk}/appliance.kiwi
`kiwi/build-tests/{exc_description_disk}/appliance.kiwi`:
Find the line below:
@ -169,34 +169,34 @@ a target system:
file to a temporary directory, and copy the initrd and kernel images to
the PXE server.
a) Unpack installation tarball:
a) Unpack the installation tarball:
.. code:: bash
mkdir /tmp/pxe && cd /tmp/pxe
tar -xf {exc_image_base_name_disk}.x86_64-{exc_image_version}.install.tar.xz
b) Copy kernel and initrd used for PXE boot:
b) Copy the kernel and initrd used for PXE boot:
.. code:: bash
scp pxeboot.{exc_image_base_name_disk}.x86_64-{exc_image_version}.initrd PXE_SERVER_IP:/srv/tftpboot/boot/initrd
scp pxeboot.{exc_image_base_name_disk}.x86_64-{exc_image_version}.kernel PXE_SERVER_IP:/srv/tftpboot/boot/linux
3. Copy the disk image, SHA256 file, system kernel, initrd and bootoptions to
3. Copy the disk image, SHA256 file, system kernel, initrd, and bootoptions to
the PXE boot server.
Activation of the deployed system is done via `kexec` of the kernel
and initrd provided here.
a) Copy system image and SHA256 checksum:
a) Copy the system image and SHA256 checksum:
.. code:: bash
scp {exc_image_base_name_disk}.x86_64-{exc_image_version}.xz PXE_SERVER_IP:/srv/tftpboot/image/
scp {exc_image_base_name_disk}.x86_64-{exc_image_version}.sha256 PXE_SERVER_IP:/srv/tftpboot/image/
b) Copy kernel, initrd and bootoptions used for booting the system via kexec:
b) Copy the kernel, initrd, and bootoptions used for booting the system via kexec:
.. code:: bash
@ -206,26 +206,26 @@ a target system:
.. note::
The config.bootoptions file is used with kexec to boot the previously
The `config.bootoptions` file is used with `kexec` to boot the previously
dumped image. This file specifies the root of the dumped image, and the
file can include other boot options. The file provided with the {kiwi}
built image connected to the image present in the PXE TAR archive. If
file can include other boot options. The file provided with the {kiwi}-
built image is connected to the image present in the PXE TAR archive. If
other images are deployed, the file must be modified to match the
correct root reference.
.. note::
If the image gets deployed into a ramdisk which is configured
If the image is deployed into a ramdisk that is configured
by passing `rd.kiwi.ramdisk` as part of the append setup below,
it is not required to copy the above mentioned kernel and initrd
file to boot the system because for ramdisk deployments the
currently active kernel and initrd will be used as kexec cannot
it is not required to copy the above-mentioned kernel and initrd
file to boot the system because for ramdisk deployments, the
currently active kernel and initrd will be used, as kexec cannot
be called with a system in memory.
4. Add/Update the kernel command line parameters.
4. Add/Update the kernel command-line parameters.
Edit your PXE configuration (for example :file:`pxelinux.cfg/default`) on
the PXE server, and add the following parameters to the append line similar to shown below:
Edit your PXE configuration (for example, :file:`pxelinux.cfg/default`) on
the PXE server and add the following parameters to the append line similar to that shown below:
.. code:: bash
@ -233,11 +233,11 @@ a target system:
The location of the image is specified as a source URI that can point
to any location supported by the `curl` command. {kiwi} uses `curl` to fetch
the data from this URI. This means that the image, checksum file, system kernel
and initrd can be fetched from any server, and they do not need to be stored
the data from this URI. This means that the image, checksum file, system kernel,
and initrd can be fetched from any server and do not need to be stored
on the `PXE_SERVER`.
By default {kiwi} does not use specific `curl` options or flags. But it is
By default, {kiwi} does not use specific `curl` options or flags. But it is
possible to specify desired options by adding the
`rd.kiwi.install.pxe.curl_options` flag to the kernel command line (`curl`
options are passed as comma-separated values), for example:
@ -252,7 +252,7 @@ a target system:
curl --retry 3 --retry-delay 3 --speed-limit 2048 -f <url>
This can be particularly useful when the deployment infrastructure requires
This can be particularly useful when the deployment infrastructure requires a
specific download configuration. For example, setting more robust retries
over an unstable network connection.
@ -280,10 +280,10 @@ a target system:
.. note:: QEMU bridged networking
To connect QEMU to the network, we recommend to
setup a network bridge on the host system and connect QEMU
to it via a custom /etc/qemu-ifup configuration. For details, see
https://en.wikibooks.org/wiki/QEMU/Networking
To connect QEMU to the network, we recommend setting up
a network bridge on the host system and connecting QEMU
to it via a custom `/etc/qemu-ifup` configuration. For details, see
https://en.wikibooks.org/wiki/QEMU/Networking.
.. _oem_customize:
@ -301,117 +301,117 @@ element, for example:
</oemconfig>
Below is a losr list of optional `oem` element settings.
Below is a list of optional `oem` element settings.
oemconfig.oem-resize
Determines if the disk has the capability to expand itself to
a new disk geometry or not. By default, this feature is activated.
The implementation of the resize capability is done in a dracut
module packaged as `dracut-kiwi-oem-repart`. If `oem-resize` is
set to false, the installation of the corresponding dracut package
set to `false`, the installation of the corresponding dracut package
can be skipped as well.
oemconfig.oem-boot-title
By default, the string OEM is used as the boot manager menu
By default, the string `OEM` is used as the boot manager menu
entry when KIWI creates the GRUB configuration during deployment.
The `oem-boot-title` element allows you to set a custom name for the
grub menu entry. This value is represented by the
``kiwi_oemtitle`` variable in the initrd.
`kiwi_oemtitle` variable in the initrd.
oemconfig.oem-bootwait
Determines if the system waits for user interaction before
continuing the boot process after the disk image has been dumped to
the designated storage device (default value is false). This value
is represented by the ``kiwi_oembootwait`` variable in the initrd.
the designated storage device (the default value is `false`). This value
is represented by the `kiwi_oembootwait` variable in the initrd.
oemconfig.oem-reboot
When enabled, the system is rebooted after the disk image has
been deployed to the designated storage device (default value is
false). This value is represented by the ``kiwi_oemreboot``
been deployed to the designated storage device (the default value is
`false`). This value is represented by the `kiwi_oemreboot`
variable in the initrd.
oemconfig.oem-reboot-interactive
When enabled, the system is rebooted after the disk image has
been deployed to the designated storage device (default value is
false). Before the reboot, a message is displayed, and it and must be
been deployed to the designated storage device (the default value is
`false`). Before the reboot, a message is displayed, and it must be
acknowledged by the user for the system to reboot. This
value is represented by the ``kiwi_oemrebootinteractive`` variable
value is represented by the `kiwi_oemrebootinteractive` variable
in the initrd.
oemconfig.oem-silent-boot
Determines if the system boots in silent mode after the disk
image has been deployed to the designated storage device (default
value is false). This value is represented by the
``kiwi_oemsilentboot`` variable in the initrd.
image has been deployed to the designated storage device (the default
value is `false`). This value is represented by the
`kiwi_oemsilentboot` variable in the initrd.
oemconfig.oem-shutdown
Determines if the system is powered down after the disk image
has been deployed to the designated storage device (default value
is false). This value is represented by the ``kiwi_oemshutdown``
has been deployed to the designated storage device (the default value
is `false`). This value is represented by the `kiwi_oemshutdown`
variable in the initrd.
oemconfig.oem-shutdown-interactive
Determines if the system is powered down after the disk image
has been deployed to the designated storage device (default value
is false). Before the shutdown a message is displayed, and it must be
has been deployed to the designated storage device (the default value
is `false`). Before the shutdown, a message is displayed, and it must be
acknowledged by the user for the system to power off.
This value is represented by the ``kiwi_oemshutdowninteractive``
variable in the initrd
This value is represented by the `kiwi_oemshutdowninteractive`
variable in the initrd.
oemconfig.oem-swap
Determines if a swap partition is be created. By default, no
Determines if a swap partition is created. By default, no
swap partition is created. This value is represented
by the ``kiwi_oemswap`` variable in the initrd.
by the `kiwi_oemswap` variable in the initrd.
oemconfig.oem-swapname
Specifies the name of the swap space. By default, the name is set to
``LVSwap``. The default indicates that this setting is only useful in
`LVSwap`. The default indicates that this setting is only useful in
combination with the LVM volume manager. In this case, the swapspace is
configured as a volume in the volume group, and every volume requires a name.
The name specified in `oemconfig.oem-swapname` here is used as a name of the
The name specified in `oemconfig.oem-swapname` here is used as the name of the
swap volume.
oemconfig.oem-swapsize
Specifies the size of the swap partition. If a swap partition is created while
the size of the swap partition is not specified, KIWI calculates the size of
the swap partition, and creates a swap partition at initial boot time. In this
case, the swap partition size equals the double amount of RAM of the system.
This value is represented by the ``kiwi_oemswapMB`` variable in the initrd.
the swap partition and creates a swap partition at initial boot time. In this
case, the swap partition size equals double the amount of RAM of the system.
This value is represented by the `kiwi_oemswapMB` variable in the initrd.
oemconfig.oem-systemsize
Specifies the MB size the operating system is allowed to occupy on the target
disk. The size limit does not include any swap space or recovery partition
considerations. In a setup *without* the systemdisk element, this value
considerations. In a setup *without* the `systemdisk` element, this value
specifies the size of the root partition. In a setup that *includes* the
systemdisk element when using LVM, this value specifies the size of the LVM
`systemdisk` element when using LVM, this value specifies the size of the LVM
partition that contains all specified volumes. This means that the sum of all
specified volume sizes plus the sum of the specified freespace for each volume
must be smaller than or equal to the size specified with the `oem-systemsize`
element. This value is represented by the variable ``kiwi_oemrootMB`` in the
element. This value is represented by the variable `kiwi_oemrootMB` in the
initrd. The specified value can be dynamically overwritten via the
`rd.kiwi.install.systemsize` kernel boot option. If `rd.kiwi.install.systemsize`
is set to `all` this will unset the size limit and the maximum possible
size applies.
is set to `all`, this will unset the size limit, and the maximum possible
size will apply.
oemconfig.oem-unattended
The installation of the image to the target system occurs
automatically without requiring user interaction. If multiple
possible target devices are discovered, the image is deployed to
the first device. ``kiwi_oemunattended`` in the initrd.
the first device. `kiwi_oemunattended` in the initrd.
oemconfig.oem-unattended-id
Selects a target disk device for the installation according to the
specified device ID. The device ID corresponds to the name of the device for
the configured `devicepersistency`. By default, it is the `by-uuid` device
name. If no representation exists, for example for ramdisk devices, the UNIX
name. If no representation exists, for example, for ramdisk devices, the UNIX
device node can be used to select one. The given name must be present in the
device list detected by KIWI.
oemconfig.oem-skip-verify
Disables the checksum verification process after installing of the image to
Disables the checksum verification process after installing the image on
the target disk. The verification process computes the checksum of the image
installed to the target. This value is then compared to the initrd embedded
checksum generated at build time of the image. Depending on the size of the
installed on the target. This value is then compared to the initrd-embedded
checksum generated at the build time of the image. Depending on the size of the
image and machine power, computing the checksum may take time.
.. _installmedia_customize:

28
doc/source/building_images/build_kis.rst
View File

@ -6,7 +6,7 @@ Build KIS Image (Kernel, Initrd, System)
.. sidebar:: Abstract
This page explains how to build an image that consists
out of three components: the kernel an initrd, and an
of three components: the kernel, an initrd, and an
optional root filesystem image. In {kiwi} terminology,
this type of image is called KIS.
@ -18,15 +18,15 @@ are expected to be used. The predecessor of this image type was called
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 optional `system root filesystem`,
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 exist, but it is expected
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 the :file:`config.xml` as shown below:
`image` set to `kis` in :file:`config.xml`, as shown below:
.. code:: xml
@ -35,7 +35,7 @@ To add a KIS build to an appliance, create a `type` element with
</preferences>
With this image type setup, {kiwi} builds a kernel and initrd
not associated with any system root file system. Normally, such
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.
@ -44,17 +44,17 @@ 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) then also
include a `root=` parameter that references this filesystem image UUID.
Whther the information from the append file should be used or not is
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 the reference
to the root UUID, if the `filesystem` attribute is used.
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 applies to an optional
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.
@ -83,9 +83,9 @@ tested with QEMU as follows:
.. note::
For testing the components of a KIS image normally requires a deployment
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 only kept for compatibility reasons. For details, see
:ref:`build_legacy_pxe`
and is only kept for compatibility reasons. For details, see
:ref:`build_legacy_pxe`.

66
doc/source/building_images/build_live_iso.rst
View File

@ -10,13 +10,13 @@ Build an ISO Hybrid Live Image
* how to build an ISO image
* how to run the image with QEMU
A Live ISO image is a system on a removable media, for example a CD/DVD or a USB
A Live ISO image is a system on removable media, for example, a CD/DVD or a USB
stick. Booting a Live ISO image does not interfere
with other system storage components, making it a useful portable system for
demonstration, testing, and debugging.
To add a Live ISO build to your appliance, create a `type` element with
`image` set to `iso` in the :file:`config.xml` file as shown below:
`image` set to `iso` in the :file:`config.xml` file, as shown below:
.. code:: xml
@ -37,25 +37,25 @@ Live ISO images:
If set to `overlay`, the kiwi-live dracut module supplied by {kiwi} is used
for booting.
If set to `dmsquash`, the dracut-supplied dmsquash-live module is
If set to `dmsquash`, the dracut-supplied `dmsquash-live` module is
used for booting.
Both modules support a different set of live features.
For details see :ref:`live_features`
For details, see :ref:`live_features`.
- `filesystem`: Specifies the root filesystem for the live system.
If set to `squashfs`, the root filesystem is written into a squashfs image.
This option is not compatible with device-mapper specific features of the
dmsquash-live dracut module. In that case, use overayfs.
This option is not compatible with device-mapper-specific features of the
`dmsquash-live` dracut module. In that case, use `overlayfs`.
If set to a value different from `squashfs`, the root filesystem is written
into a filesystem image of the specified type, and the filesystem image
into a filesystem image of the specified type, and the filesystem image is
written into a squashfs image for compression.
The default value of this option is `ext4`.
- `hybridpersistent`: Accepts `true` or `false`, if set to `true`, the
- `hybridpersistent`: Accepts `true` or `false`; if set to `true`, the
resulting image is created with a COW file to keep data persistent
over a reboot.
@ -92,40 +92,40 @@ deployment.
----------------------------------
Whether you choose the `overlay` or `dmsquash` dracut module depends on the
features you intend to use. The `overlay` module supports only overlayfs
based overlays, but with automatic creation of a writable layer for
persistence. The `dmsquash` module supports overlayfs as well as
device-mapper based overlays.
features you intend to use. The `overlay` module supports only `overlayfs`-based
overlays but with automatic creation of a writable layer for
persistence. The `dmsquash` module supports `overlayfs` as well as
device-mapper-based overlays.
The following list describes important Live ISO features and their support
status in the `overlay` and `dmsquash` modules.
ISO scan
Usable in the same way with both dracut modules. This feature allows
to boot the Live ISO as a file from a grub loopback configured bootloader.
you to boot the Live ISO as a file from a grub loopback-configured bootloader.
The `live-grub-stick` tool is one example that uses this feature.
For details how to setup ISO scan with the `overlay` module see
:ref:`iso_as_file_to_usb_stick`
For details on how to set up ISO scan with the `overlay` module, see
:ref:`iso_as_file_to_usb_stick`.
ISO in RAM completely
Usable with the `dmsquash` module through `rd.live.ram`. The `overlay`
module does not support this mode, while {kiwi} supports RAM only systems
as OEM deployment into RAM from an install ISO media. For details how
to setup RAM only deployments in {kiwi} see: :ref:`ramdisk_deployment`
module does not support this mode, while {kiwi} supports RAM-only systems
as OEM deployment into RAM from an install ISO media. For details on
how to set up RAM-only deployments in {kiwi}, see :ref:`ramdisk_deployment`.
Overlay based on overlayfs
Usable with both dracut modules. The readonly root filesystem is
overlaid with a readwrite filesystem using the kernel overlayfs
Usable with both dracut modules. The read-only root filesystem is
overlaid with a read-write filesystem using the kernel's `overlayfs`
filesystem.
Overlay based on device mapper snapshots
Usable with the `dmsquash` module. A squashfs compressed readonly root
is overlaid with a readwrite filesystem using a device mapper
Overlay based on device-mapper snapshots
Usable with the `dmsquash` module. A squashfs-compressed read-only root
is overlaid with a read-write filesystem using a device-mapper
snapshot.
Media Checksum Verification
Boot the Live iso only for ISO checksum verification. This is possible with
both modules but the `overlay` module uses the `checkmedia` tool, whereas the
Boot the Live ISO only for ISO checksum verification. This is possible with
both modules, but the `overlay` module uses the `checkmedia` tool, whereas the
upstream `dmsquash` module uses `checkisomd5`. The verification process is
triggered by passing the kernel option `mediacheck` for the `overlay` module
and `rd.live.check` for the `dmsquash` module.
@ -134,7 +134,7 @@ Live ISO through PXE boot
Boot the Live image via the network. This is possible with both
modules, but it uses different technologies. The `overlay` module supports
network boot only in combination with the AoE (Ata Over Ethernet) protocol.
For details see :ref:`network_live_boot`. The `dmsquash` module supports
For details, see :ref:`network_live_boot`. The `dmsquash` module supports
network boot by fetching the ISO image into memory from `root=live:<url>`
using the `livenet` module.
@ -142,12 +142,12 @@ Persistent Data
Keep new data persistent on a writable storage device. This can be done
with both modules but in different ways. The `overlay` module activates
persistency with the kernel boot parameter `rd.live.overlay.persistent`.
If the persistent setup cannot be created the fallback to the non persistent
mode applies automatically. The `overlay` module auto detects if it is
used on a disk or ISO scan loop booted from a file. If booted as disk,
persistency is setup on a new partition of that disk. If loop booted
from file, persistency is setup on a new cow file. The cow file/partition
setup can be influenced with the kernel boot parameters:
If the persistent setup cannot be created, the fallback to the non-persistent
mode applies automatically. The `overlay` module autodetects if it is
used on a disk or ISO scan loop booted from a file. If booted as a disk,
persistency is set up on a new partition of that disk. If loop-booted
from a file, persistency is set up on a new COW file. The COW file/partition
setup can be influenced by the kernel boot parameters:
`rd.live.overlay.cowfs` and `rd.live.cowfile.mbsize`. The `dmsquash`
module configures persistency through the `rd.live.overlay` option
exclusively and does not support the automatic creation of a write
@ -157,4 +157,4 @@ Persistent Data
Documentation for the upstream `dmsquash` module can be found
`here <http://man7.org/linux/man-pages/man7/dracut.cmdline.7.html>`_.
Options to setup `dmsquash` are marked with `rd.live`
Options to set up `dmsquash` are marked with `rd.live`.

80
doc/source/building_images/build_simple_disk.rst
View File

@ -8,20 +8,20 @@ Build a Virtual Disk Image
This page explains how to build a simple disk image.
It covers the following topics:
- define a simple disk image in the image description
- build a simple disk image
- run it with QEMU
- defines a simple disk image in the image description
- builds a simple disk image
- runs it with QEMU
A simple virtual disk image is a compressed system disk with additional
metadata useful for cloud frameworks like Amazon EC2, Google Compute Engine,
or Microsoft Azure. It is used as the native disk of a system, and it does
not require an additional installation workflow or a complex first boot setup
not require an additional installation workflow or a complex first-boot setup
procedure.
To enable {kiwi} to build a simple disk image, add a `type` element with
`image="oem"` in :file:`config.xml`, where the `oem-resize` option
disabled. An example configuration for a 42 GB large VMDK image with
512 MB RAM, an IDE controller and a bridged network interface is shown
`image="oem"` in :file:`config.xml`, where the `oem-resize` option is
disabled. An example configuration for a 42-GB large VMDK image with
512 MB of RAM, an IDE controller, and a bridged network interface is shown
below:
.. code:: xml
@ -45,25 +45,25 @@ below:
<!-- snip -->
</image>
The following attributes of the `type` element are deserve attention
The following attributes of the `type` element deserve attention
when building simple disk images:
- `format`: Specifies the format of the virtual disk, possible values are:
`gce`, `ova`, `qcow2`, `vagrant`, `vmdk`, `vdi`, `vhd`, `vhdx` and
- `format`: Specifies the format of the virtual disk. Possible values are
`gce`, `ova`, `qcow2`, `vagrant`, `vmdk`, `vdi`, `vhd`, `vhdx`, and
`vhd-fixed`.
- `formatoptions`: Specifies additional format options passed to
:command:`qemu-img`. `formatoptions` is a comma-separated list of format
specific options in a ``name=value`` format as expected by
:command:`qemu-img`. `formatoptions` is a comma-separated list of format-
specific options in a `name=value` format, as expected by
:command:`qemu-img`. {kiwi} forwards the settings from the attribute as a
parameter to the `-o` option in the :command:`qemu-img` call.
The `bootloader`, `size` and `machine` child-elements of `type` can be
The `bootloader`, `size`, and `machine` child elements of `type` can be
used to customize the virtual machine image. These elements are described in
the following sections: :ref:`disk-bootloader`, :ref:`disk-the-size-element`
and :ref:`disk-the-machine-element`
the following sections: :ref:`disk-bootloader`, :ref:`disk-the-size-element`,
and :ref:`disk-the-machine-element`.
Once your image description is finished , you can build the image using the
Once your image description is finished, you can build the image using the
following {kiwi} command:
.. code:: bash
@ -84,13 +84,13 @@ You can test the image using QEMU:
-m 4096
For further information on how to configure the image to work within a cloud
framework see:
framework, see:
* :ref:`setup_for_ec2`
* :ref:`setup_for_azure`
* :ref:`setup_for_gce`
For information on how to setup a Vagrant system, see: :ref:`setup_vagrant`.
For information on how to set up a Vagrant system, see :ref:`setup_vagrant`.
.. _disk-bootloader:
@ -108,7 +108,7 @@ Setting up the Bootloader in the Image
The `bootloader` element defines which bootloader to use in the
image, and the element offers several options for customizing its configuration.
For details, see: :ref:`preferences-type-bootloader`
For details, see :ref:`preferences-type-bootloader`.
.. _disk-the-size-element:
@ -116,7 +116,7 @@ Modifying the Size of the Image
-------------------------------
The `size` child element of `type` specifies the size of the resulting
disk image. The following example shows an image description, where 20 GB are
disk image. The following example shows an image description where 20 GB are
added to the virtual machine image, of which 5 GB are left unpartitioned:
.. code:: xml
@ -130,13 +130,13 @@ added to the virtual machine image, of which 5 GB are left unpartitioned:
</type>
</preferences>
The following optional attributes can be used to futher customize the image size:
The following optional attributes can be used to further customize the image size:
- `unit`: Defines the unit used for the provided numerical value, possible
- `unit`: Defines the unit used for the provided numerical value. Possible
values are `M` for megabytes and `G` for gigabytes. The default unit
is megabytes.
- `additive`: Boolean value that determines whether the provided value is added
- `additive`: A boolean value that determines whether the provided value is added
to the current image size (`additive="true"`) or whether it is the total size
(`additive="false"`). The default value is `false`.
@ -157,27 +157,27 @@ interfaces.
The following attributes are supported by the `machine` element:
- `ovftype`: The OVF configuration type. The Open Virtualization Format is a
standard for describing virtual appliances and distribute them in an archive
called Open Virtual Appliance (OVA). The standard describes the major
standard for describing virtual appliances and distributing them in an archive
called an Open Virtual Appliance (OVA). The standard describes the major
components associated with a disk image. The exact specification depends on
the product using the format. Supported values are `zvm`, `powervm`, `xen` and
the product using the format. Supported values are `zvm`, `powervm`, `xen`, and
`vmware`.
- `HWversion`: The virtual machine's hardware version (`vmdk` and `ova`
formats only), refer to VMware documentation for further
formats only); refer to VMware documentation for further
information on the supported values.
- `arch`: the VM architecture (`vmdk` format only). Valid values are
`ix86` (= `i585` and `i686`) and `x86_64`.
- `xen_loader`: the Xen target loader which is expected to load the guest.
Valid values are: `hvmloader`, `pygrub` and `pvgrub`.
- `xen_loader`: the Xen target loader that is expected to load the guest.
Valid values are `hvmloader`, `pygrub`, and `pvgrub`.
- `guestOS`: The virtual guest OS' identification string for the VM (only
applicable for `vmdk` and `ova` formats. Note that the name designation
is different for the two formats).
Note: For vmware ovftools, guestOS is a VMX GuestOS, but not VIM GuestOS.
For instance, correct value for Ubuntu 64 bit is "ubuntu-64", but not
Note: For vmware ovftools, guestOS is a VMX GuestOS, but not a VIM GuestOS.
For instance, the correct value for Ubuntu 64-bit is "ubuntu-64", but not
"ubuntu64Guest". See GUEST_OS_KEY_MAP in guest_os_tables.h at
https://github.com/vmware/open-vm-tools for another guestOS values.
@ -204,7 +204,7 @@ Modifying the VM Configuration Directly
The `vmconfig-entry` element is used to add entries directly into the
virtual machine's configuration file. This is currently only supported for
the `vmdk` format where the provided strings are directly pasted into the
the `vmdk` format, where the provided strings are directly pasted into the
:file:`.vmx` file.
The `vmconfig-entry` element has no attributes and can appear multiple
@ -229,8 +229,8 @@ Adding Network Interfaces to the VM
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Network interfaces can be explicitly specified for the VM when required via
the `vmnic` element. This makes is possible to add another bridged interface or
to specify the driver wto be used.
the `vmnic` element. This makes it possible to add another bridged interface or
to specify the driver to be used.
Note that this element is used for the `vmdk` image format only.
@ -257,8 +257,8 @@ The `vmnic` element supports the following attributes:
- `mode`: The mode of the interface.
Note that {kiwi} doesn **not** verify the values of the
attributes, it only inserts them into the appropriate configuration
Note that {kiwi} does **not** verify the values of the
attributes; it only inserts them into the appropriate configuration
files.
@ -287,14 +287,14 @@ Each `vmdisk` element can be further customized using optional
attributes:
- `controller`: The disk controller used for the VM guest (`vmdk` format
only). Supported values are: `ide`, `buslogic`, `lsilogic`, `lsisas1068`,
`legacyESX` and `pvscsi`.
only). Supported values are `ide`, `buslogic`, `lsilogic`, `lsisas1068`,
`legacyESX`, and `pvscsi`.
- `device`: The disk device to appear in the guest (`xen` format only).
- `diskmode`: The disk mode (`vmdk` format only). Valid values are
`monolithicSparse`, `monolithicFlat`, `twoGbMaxExtentSparse`,
`twoGbMaxExtentFlat` and `streamOptimized` (see also
`twoGbMaxExtentFlat`, and `streamOptimized` (see also
https://vdc-download.vmware.com/vmwb-repository/dcr-public/6335f27c-c6e9-4804-95b0-ea9449958403/c7798a8b-4c73-41d9-84e8-db5453de7b17/doc/vddkDataStruct.5.3.html).
- `disktype`: The type of the disk handled internally by the VM
@ -307,7 +307,7 @@ Adding CD/DVD Drives
{kiwi} supports adding IDE and SCSCI CD/DVD drives to the virtual
machine using the `vmdvd` element for the `vmdk` image format. The
following example adds two drives: one with a SCSCI and another with a
following example adds two drives: one with a SCSCI and another with an
IDE controller:
.. code:: xml

60
doc/source/building_images/build_wsl_container.rst
View File

@ -6,7 +6,7 @@ Build a WSL Container Image
.. sidebar:: Abstract
This page explains how to build a WSL/Appx container image. WSL stands for
Windows Subsystem Linux, and it is a zip-based container format consumable by
Windows Subsystem for Linux, and it is a zip-based container format consumable by
Windows 10 with WSL enabled.
@ -14,8 +14,8 @@ Build a WSL Container Image
utility. Make sure you have installed the package that provides
the command on your build host.
Once the build host has the :command:`appx` installed, the
following image type setup is required in the XML description
Once the build host has the `appx` command installed, the
following image type setup is required in the XML description,
:file:`config.xml`:
.. code:: xml
@ -23,19 +23,19 @@ following image type setup is required in the XML description
<type image="appx" metadata_path="/meta/data"/>
The :file:`/meta/data` path specifies a path that provides
additional information required for the :command:`WSL-DistroLauncher`.
This component consists out of a Windows(`exe`) executable file and
additional information required for the `WSL-DistroLauncher`.
This component consists of a Windows (`exe`) executable file and
an :file:`AppxManifest.xml` file that references other files,
like icons and resource configurations for the startup of the
container under Windows.
.. note:: **/meta/data**
Except for the root filesystem tarball {kiwi} is not
responsible for providing the meta data required for
the :command:`WSL-DistroLauncher`. It is expected that
Except for the root filesystem tarball, {kiwi} is not
responsible for providing the metadata required for
the `WSL-DistroLauncher`. It is expected that
the given metadata path contains all the needed information.
Typically this information is delivered in a package
Typically, this information is delivered in a package
provided by the distribution, and it is installed on the
build host.
@ -43,7 +43,7 @@ container under Windows.
Setup of the WSL-DistroLauncher
-------------------------------
The contents of the :file:`AppxManifest.xml` is changed by {kiwi}
The contents of the :file:`AppxManifest.xml` are changed by {kiwi}
if the :file:`containerconfig` section is provided in the XML description.
In the context of a WSL image, the following container configuration
parameters are taken into account:
@ -65,10 +65,10 @@ information is not specified, the existing :file:`AppxManifest.xml` is left
untouched.
created_by
Specifies the name of a publisher organization. An appx container
must to be signed off with a digital signature. If the image is
build in the Open Build Service (OBS), this is done automatically.
Outside of OBS, you must o make sure that the given publisher organization
Specifies the name of a publisher organization. An `appx` container
must be signed off with a digital signature. If the image is
built in the Open Build Service (OBS), this is done automatically.
Outside of OBS, you must make sure that the given publisher organization
name matches the certificate used for signing.
author
@ -76,9 +76,9 @@ author
application_id
Specifies an ID name for the container. The name must start with
a letter, and only alphanumeric characters are allowed. {kiwi} doesn not
validate the specified name string, because there is no common criteria
for various the container architectures.
a letter, and only alphanumeric characters are allowed. {kiwi} does not
validate the specified name string because there are no common criteria
for the various container architectures.
package_version
Specifies the version identification for the container. {kiwi}
@ -91,23 +91,23 @@ launcher
.. warning::
{kiwi} does not check the configuration in :file:`AppxManifest.xml`
ifor validity or completeness.
for validity or completeness.
The following example shows how to build a WSL image based on
openSUSE Tumbleweed:
1. Check the example image descriptions,
1. Check the example image descriptions;
see :ref:`example-descriptions`.
#. Include the ``Virtualization/WSL`` repository to the list ((replace `<DIST>`
with the desired distribution)):
#. Include the `Virtualization/WSL` repository in the list (replace `<DIST>`
with the desired distribution):
.. code:: bash
$ zypper addrepo http://download.opensuse.org/repositories/Virtualization:/WSL/<DIST> WSL
#. Install :command:`fb-util-for-appx` utility and the package that
provides the :command:`WSL-DistroLauncher` metadata. See the
#. Install the `fb-util-for-appx` utility and the package that
provides the `WSL-DistroLauncher` metadata. See the
previous note on :file:`/meta/data`.
.. code:: bash
@ -116,10 +116,10 @@ openSUSE Tumbleweed:
.. note::
When building images with the Open Build Servic,e make sure
to add the packages from the zypper command above to the
project configuration via :command:`osc meta -e prjconf` along with
the line :file:`support: PACKAGE_NAME` for
When building images with the Open Build Service, make sure
to add the packages from the `zypper` command above to the
project configuration via `osc meta -e prjconf` along with
the line `support: PACKAGE_NAME` for
each package that needs to be installed on the Open Build
Service worker that runs the {kiwi} build process.
@ -146,7 +146,7 @@ openSUSE Tumbleweed:
If the configured metadata path does not exist, the build will fail.
Furthermore, {kiwi} does not check whether the metadata is complete or is
valid according to the requirements of the :command:`WSL-DistroLauncher`
valid according to the requirements of the `WSL-DistroLauncher`.
#. Build the image with {kiwi}:
@ -162,5 +162,5 @@ Testing the WSL image
For testing the image, you need a Windows 10 system. Before you proceed, enable
the optional feature named :file:`Microsoft-Windows-Subsystem-Linux`. For
further details on how to setup the Windows machine, see: `Windows Subsystem for Linux
<https://docs.microsoft.com/en-us/windows/wsl/about>`__
further details on how to set up the Windows machine, see `Windows Subsystem for Linux
<https://docs.microsoft.com/en-us/windows/wsl/about>`__.

34
doc/source/commands/image_info.rst
View File

@ -28,8 +28,8 @@ DESCRIPTION
Provides information about the specified image description. If no specific info
option is provided, the command lists basic information about the image. This
information is also available in the image XML description file. Specifying an
extension option like `resolve-package-list` makes a dependency resolver to
run through the list of packages, providing more detailed information about
extension option like `resolve-package-list` makes a dependency resolver run
through the list of packages, providing more detailed information about
the image description.
.. _db_image_info_opts:
@ -39,7 +39,7 @@ OPTIONS
--add-repo=<source,type,alias,priority>
Add repository with given source, type, alias and priority.
Adds a repository with the given source, type, alias, and priority.
--description=<directory>
@ -48,15 +48,15 @@ OPTIONS
--ignore-repos
Ignore all repository configurations from the XML description.
This option is usually used together with the --add-repo
option. Otherwise there are no repositories available for the
Ignores all repository configurations from the XML description.
This option is usually used together with the `--add-repo`
option. Otherwise, there are no repositories available for
processing the requested image information, which could lead
to an error.
--list-profiles
list profiles available for the selected/default type.
Lists profiles available for the selected/default type.
NOTE:
If the image description is designed in a way that there
@ -67,39 +67,39 @@ OPTIONS
--print-kiwi-env
print kiwi profile environment variables. The listed variables
Prints kiwi profile environment variables. The listed variables
are available in the shell environment of the kiwi hook scripts.
NOTE:
The kiwi profile environment grows during the build process.
When used in early stages e.g. in a post_bootstrap.sh script
When used in early stages, e.g., in a `post_bootstrap.sh` script,
it can happen that not all variables have a value. The setup
of the kiwi profile environment in the image info output can
therefore also only list the static configuration values
which are known at the beginning of a build process.
that are known at the beginning of a build process.
--resolve-package-list
Solve package dependencies and return a list of all
packages including their attributes, for example size,
Solves package dependencies and returns a list of all
packages, including their attributes, for example, size,
shasum, and more.
--print-xml
Print image description in the XML format. The specified image description is
Prints the image description in the XML format. The specified image description is
converted to XML and sent to the XSLT stylesheet processor. The result is then
validated using the RelaxNG schema and the schematron rules. The command is
normally used to convert an old image description to the latest schema.
--print-yaml
Behaves similar to `--print-xml`, but after validation, the result is
Behaves similarly to `--print-xml`, but after validation, the result is
converted to the YAML format. The command can be used for different
operations:
* Conversion of the specified image description from or into different
formats. This requires the `anymarkup` Python module to be installed. The
module is not a hard requirement and loaded on demand. If the module is
missing, requests to convert to other format than XML fail.
module is not a hard requirement and is loaded on demand. If the module is
missing, requests to convert to a format other than XML will fail.
* Update of an old image description to the latest schema
* Updates an old image description to the latest schema.

8
doc/source/commands/image_resize.rst
View File

@ -22,7 +22,7 @@ SYNOPSIS
DESCRIPTION
-----------
For disk based images, allow to resize the image to a new disk geometry. The
For disk-based images, this allows you to resize the image to a new disk geometry. The
additional space is free and not in use by the image. The OEM boot code in
{kiwi} offers a resizing procedure that can be used to make use of the
additional free space. For OEM image builds, it is advisable to run the resizing
@ -36,14 +36,14 @@ OPTIONS
--root=<directory>
The path to the root directory. If not specified, kiwi
searches the root directory in build/image-root under
searches for the root directory in `build/image-root` under
the specified target directory.
--size=<size>
New size of the image. The value is either a size in bytes,
The new size of the image. The value is either a size in bytes,
or it can be specified with m (MB) or g (GB). Example: 20g
--target-dir=<directory>
Directory containing the kiwi build results.
The directory containing the kiwi build results.

54
doc/source/commands/kiwi.rst
View File

@ -61,8 +61,8 @@ may also include additional files, such as scripts or configuration data.
A collection of example image descriptions can be found in the following GitHub
repository: https://github.com/OSInside/kiwi-descriptions. Most of the
descriptions provide a so-called appliance image. Appliance is a
small, text-based image including a predefined remote source setup to allow
descriptions provide a so-called appliance image. An appliance is a
small, text-based image, including a predefined remote source setup to allow the
installation of missing software components.
Although {kiwi} operates in two steps, the system build command combines both
@ -75,9 +75,9 @@ the prepared contents of the new image root tree to create an output image.
{kiwi} supports the creation of the following image types:
- ISO Live Systems
- virtual disk for e.g cloud frameworks
- virtual disk for, e.g., cloud frameworks
- OEM expandable disk for system deployment from ISO or the network
- file system images for deployment in a PXE boot environment
- filesystem images for deployment in a PXE boot environment
Depending on the image type, different disk formats and
architectures are supported.
@ -89,41 +89,41 @@ GLOBAL OPTIONS
--color-output
Use escape sequences to print different types of information in colored
Uses escape sequences to print different types of information in colored
output. for this option to work, the underlying terminal must support those
escape characters. Error messages appear in red, warning messages in yellow,
and debugging information is printed in light grey.
--config=<configfile>
Use specified runtime configuration file. If not specified, the
Use the specified runtime configuration file. If not specified, the
runtime configuration is expected to be in the :file:`~/.config/kiwi/config.yml`
or :file:`/etc/kiwi.yml` files.
--debug
Print debug information on the command line. Same as: `--loglevel 10`.
Prints debug information on the command line. Same as: `--loglevel 10`.
--debug-run-scripts-in-screen
Run scripts called by {kiwi} in a screen session.
Runs scripts called by {kiwi} in a screen session.
--logfile=<filename>
Specify log file. The logfile contains detailed information about
the process. The special call: `--logfile stdout` sends all
Specifies the log file. The logfile contains detailed information about
the process. The special call `--logfile stdout` sends all
information to standard out instead of writing to a file.
--logsocket=<socketfile>
Send log data to the specified Unix Domain socket in the same
Sends log data to the specified Unix Domain socket in the same
format as with `--logfile`.
--loglevel=<number>
Specify logging level as a number. Further info about the
Specifies the logging level as a number. Further info about the
available log levels can be found at:
https://docs.python.org/3/library/logging.html#logging-levels
https://docs.python.org/3/library/logging.html#logging-levels.
Setting a log level displays all messages above the specified level.
.. code:: bash
@ -141,51 +141,51 @@ GLOBAL OPTIONS
--profile=<name>
Select profile to use. The specified profile must be part of the
Selects a profile to use. The specified profile must be part of the
XML description. The option can be specified multiple times to
allow a combination of profiles.
--setenv=<variable=value>
export environment variable and its value into the caller
environment. This option can be specified multiple times
exports an environment variable and its value into the caller's
environment. This option can be specified multiple times.
--shared-cache-dir=<directory>
Specify an alternative shared cache directory. The directory
Specifies an alternative shared cache directory. The directory
is shared via bind mount between the build host and image
root system, and it contains information about package repositories
and their cache and meta data. The default location is `/var/cache/kiwi`.
and their cache and metadata. The default location is `/var/cache/kiwi`.
--temp-dir=<directory>
Specify an alternative base temporary directory. The
provided path is used as base directory to store temporary
files and directories. Default is `/var/tmp`.
Specifies an alternative base temporary directory. The
provided path is used as a base directory to store temporary
files and directories. The default is `/var/tmp`.
--target-arch=<name>
Specify an image architecture. By default, the host architecture is used as
Specifies an image architecture. By default, the host architecture is used as
the image architecture. If the specified architecture name does not match the
host architecture (thus requesting a cross architecture image build), you must
host architecture (thus requesting a cross-architecture image build), you must
configure the support for the image architecture and binary format on the
building host. This must be done during the preparation stage, and it is
beyond the scope of {kiwi}.
--type=<build_type>
Select an image build type. The specified build type must be configured
Selects an image build type. The specified build type must be configured
as part of the XML description.
--kiwi-file=<kiwifile>
Basename of kiwi file that contains the main image
The basename of the kiwi file that contains the main image
configuration elements. If not specified, kiwi uses
a file named `config.xml` or a file matching `*.kiwi`
a file named `config.xml` or a file matching `*.kiwi`.
--version
Show program version
Show the program version.
.. _db_commands_kiwi_example:

14
doc/source/commands/result_bundle.rst
View File

@ -23,7 +23,7 @@ SYNOPSIS
DESCRIPTION
-----------
Create a result bundle from the image build in the specified target directory.
Creates a result bundle from the image build in the specified target directory.
Each resulting image contains the specified bundle identifier as part of its
filename. Uncompressed image files are also compressed as an XZ archive. An SHA
checksum is generated for each resulting image.
@ -35,12 +35,12 @@ OPTIONS
--bundle-dir=<directory>
Directory containing the bundle results, compressed versions of
The directory containing the bundle results, compressed versions of
image results, and SHA checksum files.
--bundle-format=<format>
Specify the bundle format to create the bundle. If provided,
Specifies the bundle format to create the bundle. If provided,
this setting will overwrite an eventually provided `bundle_format`
attribute from the main image description. The format string
can contain placeholders for the following elements:
@ -58,15 +58,15 @@ OPTIONS
--id=<bundle_id>
Bundle ID. It is a free-form text appended to the image
version information as part of the result image filename.
version information as part of the resulting image filename.
--target-dir=<directory>
Directory containing the {kiwi} build results.
The directory containing the {kiwi} build results.
--zsync_source=<download_location>
Download location of the bundle file or files. Only relevant if `zsync` is
The download location of the bundle file or files. Only relevant if `zsync` is
used to sync the bundle.
* The zsync control file is created for the bundle files marked for compression.
@ -80,4 +80,4 @@ OPTIONS
--no-compress
Do not compress the result image file(s). Note: Image files that
were already produced as compressed variants stays compressed.
were already produced as compressed variants stay compressed.

2
doc/source/commands/result_list.rst
View File

@ -19,7 +19,7 @@ SYNOPSIS
DESCRIPTION
-----------
List build results from a previous build or create command. During multiple
Lists build results from a previous build or create command. During multiple
image builds with the same target directory, the build result information is
overwritten every time you build an image. This means that the build result list
is valid for the last build only.

98
doc/source/commands/system_build.rst
View File

@ -43,8 +43,8 @@ DESCRIPTION
Build an image in one step. The build command combines preparation and building
steps, which makes it possible to create an image with a single command. The
build command creates the root directory of the image under
`<target-dir>/build/image-root` and writes a log file
`<target-dir>/build/image-root.log`. The result image files are created in the
`<target-dir>/build/image-root` and writes a log file,
`<target-dir>/build/image-root.log`. The resulting image files are created in the
specified target directory.
.. _db_kiwi_system_build_opts:
@ -54,25 +54,25 @@ OPTIONS
--add-bootstrap-package=<name>
Specify package to install as part of the early {kiwi} bootstrap phase.
Specifies a package to install as part of the early {kiwi} bootstrap phase.
The option can be specified multiple times.
--add-container-label=<name=value>
Add a container label in the container configuration metadata. It
Adds a container label in the container configuration metadata. It
overwrites the label with the provided key-value pair if it is
already defined in the XML description.
--add-package=<name>
Specify package to add (install). The option can be specified
Specifies a package to add (install). The option can be specified
multiple times.
--add-repo=<source,type,alias,priority,imageinclude,package_gpgcheck,{signing_keys},components,distribution,repo_gpgcheck,repo_sourcetype>
Add a new repository to the existing repository setup in the XML
Adds a new repository to the existing repository setup in the XML
description. This option can be specified multiple times.
For details about the possible option values see the **--set-repo**
For details about the possible option values, see the **--set-repo**
information below.
--add-repo-credentials=<user:pass_or_filename>
@ -84,65 +84,65 @@ OPTIONS
--allow-existing-root
Use an existing root directory from a previous
Uses an existing root directory from a previous
build attempt. Use with caution, because this can cause an inconsistent
root tree if the existing contents does not fit to the
root tree if the existing contents do not fit the
previous image type setup.
--clear-cache
Delete repository cache for each of the used repositories
Deletes the repository cache for each of the used repositories
before installing any package. This is useful when an image build
validates the signature of the package from the
original repository source for any build. Some package managers
unconditionally trust the contents of the cache, which works for
cache data dedicated to one build. In case of {kiwi}, the cache
cache data dedicated to one build. In the case of {kiwi}, the cache
is shared between multiple image builds on that host for performance
reasons.
--ca-cert=<cert-file>
Add a cert-file to the directory storing additional local CA certificates.
Adds a cert file to the directory storing additional local CA certificates.
The import will occur immediately after the bootstrap process, where
the required CA update tooling is expected to be installed. This
option is useful for situations where certificates are not packaged,
or the certificates are required during the build process, e.g. due
or the certificates are required during the build process, e.g., due
to proxy servers in the build environment that need certificates
in chroot. The option can be specified multiple times.
--ca-target-distribution=<suse|redhat|debian|archlinux>
Specify target distribution for the import of certificates
via the --ca-cert options(s) and/or the provided <certificates>
Specifies the target distribution for the import of certificates
via the `--ca-cert` options(s) and/or the provided `<certificates>`
from the image description. The selected distribution is used
in KIWI to map the distribution specific CA storage path and
in KIWI to map the distribution-specific CA storage path and
update tool for the import process.
--delete-package=<name>
Specify package to delete. The option can be specified
Specifies a package to delete. The option can be specified
multiple times.
--description=<directory>
Path to an XML description. This is a directory containing at least
one _config.xml_ or _*.kiwi_ XML file.
The path to an XML description. This is a directory containing at least
one `_config.xml_` or `_*.kiwi_` XML file.
--ignore-repos
Ignore all repository configurations from the XML description.
This option is used in combination with the `--add-repo``
Ignores all repository configurations from the XML description.
This option is used in combination with the `--add-repo`
option. Otherwise, there are no repositories available for an
image build, which leads to an error.
--ignore-repos-used-for-build
Works the same way as `--ignore-repos`, except that repository configuration
with the imageonly attribute set to **true** is not ignored.
with the `imageonly` attribute set to **true** is not ignored.
--set-repo=<source,type,alias,priority,imageinclude,package_gpgcheck,{signing_keys},components,distribution,repo_gpgcheck,repo_sourcetype>
Overwrite the first repository entry in the XML description with the
Overwrites the first repository entry in the XML description with the
provided information:
- **source**
@ -158,7 +158,7 @@ OPTIONS
- **alias**
An alias name for the repository. If not specified, {kiwi} generates
an alias name as result of hex representation from uuid4. While the hex
an alias name as a result of a hex representation from uuid4. While the hex
is used to uniquely identify the repository, it is not descriptive.
We recommend using descriptive aliases.
@ -172,7 +172,7 @@ OPTIONS
- **imageinclude**
Set to either **true** or **false** to indicate if the repository
is be part of the system image repository setup or not.
is part of the system image repository setup or not.
- **package_gpgcheck**
@ -181,17 +181,17 @@ OPTIONS
- **{signing_keys}**
List of signing_keys enclosed in curly brackets and delimited by
the semicolon. The reference to a signing key must be provided in the URI
A list of `signing_keys` enclosed in curly brackets and delimited by
a semicolon. The reference to a signing key must be provided in the URI
format.
- **components**
Component list for Debian-based repos as space-delimited string.
A component list for Debian-based repos as a space-delimited string.
- **distribution**
Main distribution name for Debian-based repos.
The main distribution name for Debian-based repos.
- **repo_gpgcheck**
@ -200,53 +200,53 @@ OPTIONS
- **repo_sourcetype**
Specify the source type of the repository path. Supported values
are baseurl, metalink or mirrorlist. With baseurl the source
path is interpreted as simple URI. If metalink is set the source
path is resolved as metalink URI and if mirrorlist is set the
Specifies the source type of the repository path. Supported values
are `baseurl`, `metalink`, or `mirrorlist`. With `baseurl`, the source
path is interpreted as a simple URI. If `metalink` is set, the source
path is resolved as a metalink URI, and if `mirrorlist` is set, the
source path is resolved as a mirrorlist file. If not specified,
baseurl is the default
`baseurl` is the default.
--set-repo-credentials=<user:pass_or_filename>
For **uri://user:pass@location** type repositories, set the user and
For **uri://user:pass@location**-type repositories, set the user and
password connected to the set-repo specification. If the provided
value describes a filename in the filesystem, the first line of that file
is used as credentials.
--set-container-derived-from=<uri>
Overwrite the source location of the base container for the selected
Overwrites the source location of the base container for the selected
image type. The setting applies only if the configured image type
is setup with an initial derived_from reference.
is set up with an initial `derived_from` reference.
--set-container-tag=<name>
Overwrite the container tag in the container configuration.
Overwrites the container tag in the container configuration.
The setting is only effective if the container configuration
provides the initial tag value.
--set-type-attr=<attribute=value>
Overwrite/set the attribute with the provided value in the selected
build type section. Example: `--set-type-attr volid=some`
Overwrites/sets the attribute with the provided value in the selected
build type section. Example: `--set-type-attr volid=some`.
--set-release-version=<version>
Overwrite/set the release-version element in the selected
build type preferences section
Overwrites/sets the release-version element in the selected
build type preferences section.
--signing-key=<key-file>
Set the key file to be trusted and imported into the package
manager database before performing any operation. This is useful
Sets the key file to be trusted and imported into the package
manager's database before performing any operation. This is useful
when an image build validates repository and package
signatures during build time. This option can be specified multiple
times.
--target-dir=<directory>
Path to store the build results.
The path to store the build results.
.. _db_kiwi_system_build_uri:
@ -255,18 +255,18 @@ URI_TYPES
- **http://** | **https://** | **ftp://**
Remote repository delivered via the HTTP or FTP protocol.
A remote repository delivered via the HTTP or FTP protocol.
- **obs://**
Open Buildservice repository. The source data is translated into
An Open Buildservice repository. The source data is translated into
an HTTP URL pointing to http://download.opensuse.org.
- **ibs://**
Internal Open Buildservice repository. The source data is translated into
An internal Open Buildservice repository. The source data is translated into
an HTTP URL pointing to download.suse.de.
- **dir://**
Local directory.
A local directory.

10
doc/source/commands/system_create.rst
View File

@ -23,7 +23,7 @@ DESCRIPTION
-----------
Create an image from the previously prepared image root directory. The `kiwi
create` command is normally issued after the `kiwi prepare` command, and it and
create` command is normally issued after the `kiwi prepare` command, and it
builds the requested image type in the specified target directory.
.. _db_kiwi_system_create_opts:
@ -33,19 +33,19 @@ OPTIONS
--root=<directory>
Path to the image root directory. This directory is normally created by the
The path to the image root directory. This directory is normally created by the
`kiwi prepare` command. Keep in mind that if the specified directory is not
created using the `kiwi prepare` command, {kiwi} stores image build metadata
in the image/ directory. This directory must exist for the `kiwi create`
in the `image/` directory. This directory must exist for the `kiwi create`
command to work correctly.
--target-dir=<directory>
Path to store the build results.
The path to store the build results.
--signing-key=<key-file>
Trusted key file to be imported into the package manager database before
A trusted key file to be imported into the package manager's database before
performing any operation. This is useful if an image build validates
repository and package signatures during build time. In the create step, this
option only affects the boot image. This option can be specified multiple

80
doc/source/commands/system_prepare.rst
View File

@ -40,7 +40,7 @@ DESCRIPTION
Create a new image root directory. The prepare step sets up a new image
root directory from the specified XML description. The specified
directory acts as a root directory of the new image root system.
directory acts as the root directory of the new image root system.
You can enter the system as root via chroot using the following command:
.. code:: bash
@ -70,49 +70,49 @@ OPTIONS
--add-repo=<source,type,alias,priority,imageinclude,package_gpgcheck,{signing_keys},components,distribution,repo_gpgcheck,repo_sourcetype>
Add a new repository to the existing repository setup in the XML
Adds a new repository to the existing repository setup in the XML
description. This option can be specified multiple times.
For details about the supported option values, see the **--set-repo**
information below
information below.
--add-repo-credentials=<user:pass_or_filename>
For **uri://user:pass@location** type repositories, set the user and password
For **uri://user:pass@location**-type repositories, set the user and password
connected with an add-repo specification. If the provided value is a
filename in the filesystem, the first line of the file is used as
credentials.
--allow-existing-root
Allow to re-use an existing image root directory.
Allows you to re-use an existing image root directory.
--clear-cache
Delete repository cache for each of the used repositories
Deletes the repository cache for each of the used repositories
before installing any package. This is useful if an image build
validates the signature of the package from the
original repository source for any build. Some package managers
unconditionally trust the contents of the cache, which works for
cache data dedicated to one build. In case of {kiwi}, the cache
cache data dedicated to one build. In the case of {kiwi}, the cache
is shared between multiple image builds on the host for performance
reasons.
--ca-cert=<cert-file>
Add a cert-file to the directory storing additional local CA certificates.
Adds a cert file to the directory storing additional local CA certificates.
The import will occur immediately after the bootstrap process, where
the required CA update tooling is expected to be installed. This
option is useful for situations where certificates are not packaged,
or the certificates are required during the build process, e.g. due
or the certificates are required during the build process, e.g., due
to proxy servers in the build environment that need certificates
in chroot. The option can be specified multiple times.
--ca-target-distribution=<suse|redhat|debian|archlinux>
Specify target distribution for the import of certificates
via the --ca-cert options(s) and/or the provided <certificates>
Specifies the target distribution for the import of certificates
via the `--ca-cert` option(s) and/or the provided `<certificates>`
from the image description. The selected distribution is used
in KIWI to map the distribution specific CA storage path and
in KIWI to map the distribution-specific CA storage path and
update tool for the import process.
--delete-package=<name>
@ -122,28 +122,28 @@ OPTIONS
--description=<directory>
Path to the {kiwi} XML description. The directory must contain at least a
config.xml of \*.kiwi XML description.
The path to the {kiwi} XML description. The directory must contain at least a
`config.xml` or `*.kiwi` XML description.
--ignore-repos
Ignore all repository configurations in the XML description.
This option is normally used in combination with the `--add-repo``
Ignores all repository configurations in the XML description.
This option is normally used in combination with the `--add-repo`
option. Otherwise, an image build operation results in an error.
--ignore-repos-used-for-build
Works the same way as `--ignore-repos`,` but the repository
configurations that have the imageonly attribute set to **true**
Works the same way as `--ignore-repos`, but the repository
configurations that have the `imageonly` attribute set to **true**
are not ignored.
--root=<directory>
Path to the new root system.
The path to the new root system.
--set-repo=<source,type,alias,priority,imageinclude,package_gpgcheck,{signing_keys},components,distribution,repo_gpgcheck,repo_sourcetype>
Overwrite the first repository entry in the XML description with the
Overwrites the first repository entry in the XML description with the
provided information:
- **source**
@ -159,9 +159,9 @@ OPTIONS
- **alias**
An alias name for the repository. If not specified, {kiwi} generates
an alias name based hex representation of uuid4. While the hex
an alias name based on a hex representation of uuid4. While the hex
is used to uniquely identify the repository, it is not descriptive.
We recommend to use a descriptive and unique alias name.
We recommend using a descriptive and unique alias name.
- **priority**
@ -182,17 +182,17 @@ OPTIONS
- **{signing_keys}**
List of signing_keys enclosed in curly brackets and delimited by
the semicolon. The reference to a signing key must be provided in the URI
A list of signing_keys enclosed in curly brackets and delimited by
a semicolon. The reference to a signing key must be provided in the URI
format.
- **components**
Component list for Debian-based repos as a space-delimited string.
A component list for Debian-based repos as a space-delimited string.
- **distribution**
Main distribution name for Debian-based repos.
The main distribution name for Debian-based repos.
- **repo_gpgcheck**
@ -201,45 +201,45 @@ OPTIONS
- **repo_sourcetype**
Specify the source type of the repository path. Supported values
are baseurl, metalink or mirrorlist. With baseurl the source
path is interpreted as simple URI. If metalink is set the source
path is resolved as metalink URI and if mirrorlist is set the
Specifies the source type of the repository path. Supported values
are `baseurl`, `metalink`, or `mirrorlist`. With `baseurl`, the source
path is interpreted as a simple URI. If `metalink` is set, the source
path is resolved as a metalink URI, and if `mirrorlist` is set, the
source path is resolved as a mirrorlist file. If not specified,
baseurl is the default
`baseurl` is the default.
--set-repo-credentials=<user:pass_or_filename>
For **uri://user:pass@location** type repositories, set the user and
For **uri://user:pass@location**-type repositories, sets the user and
password connected to the set-repo specification. If the provided value
is a filename in the filesystem, the first line of that file is
used as credentials.
--set-container-derived-from=<uri>
Overwrite the source location of the base container for the selected
Overwrites the source location of the base container for the selected
image type. The setting is only effective if the configured image type
is setup with an initial derived_from reference
is set up with an initial derived_from reference.
--set-container-tag=<name>
Overwrite the container tag in the container configuration.
Overwrites the container tag in the container configuration.
The setting applies only if the container configuration
provides an initial tag value.
--set-type-attr=<attribute=value>
Overwrite/set the attribute with the provided value in the selected
build type section. Example: `--set-type-attr volid=some`
Overwrites/sets the attribute with the provided value in the selected
build type section. Example: `--set-type-attr volid=some`.
--set-release-version=<version>
Overwrite/set the release-version element in the selected
build type preferences section
Overwrites/sets the release-version element in the selected
build type preferences section.
--signing-key=<key-file>
Set the key file to be trusted and imported into the package
Sets the key file to be trusted and imported into the package
manager database before performing any operation. This is useful
if an image build validates repository and package
signatures during build time. This option can be specified multiple

2
doc/source/commands/system_update.rst
View File

@ -21,7 +21,7 @@ SYNOPSIS
DESCRIPTION
-----------
Update a previously prepare image root tree. The update command refreshes the
Update a previously prepared image root tree. The update command refreshes the
contents of the root directory according to the repository setup of the image
XML description. The update command can also be used to add or remove
packages from the image root tree.

84
doc/source/concept_and_workflow.rst
View File

@ -27,11 +27,11 @@ configured system in a single file) of a Linux distribution in two steps (for
further details, see :ref:`working-with-kiwi-image-building-process`):
1. *Prepare operation*: generate an *unpacked image tree* of your
image. The unpacked tree is a directory containing the future file
system of your image, generated from your image description.
image. The unpacked tree is a directory containing the future filesystem
of your image, generated from your image description.
2. *Create operation*: the unpacked tree generated in step 1 is packaged
into the format required for the final usage (e.g. a ``qcow2`` disk
into the format required for the final usage (e.g., a `qcow2` disk
image to launch the image with QEMU).
{kiwi} executes these steps using the following components, which it expects
@ -39,19 +39,19 @@ to find in the *description directory*:
:ref:`image-description`:
The :file:`config.xml` file contains the image description, which is a
collection of general settings of the final image, like the image layout
collection of general settings of the final image, like the image layout,
installed packages, present users, etc.
.. note::
The filename :file:`config.xml` is not mandatory, the image description
The filename :file:`config.xml` is not mandatory; the image description
file can also have an arbitrary name plus the :file:`*.kiwi` extension.
{kiwi} first looks for a :file:`config.xml` file. If it cannot be found,
it picks the first :file:`*.kiwi` file.
:ref:`working-with-kiwi-user-defined-scripts`:
If present, custom configuration shell scripts run at different
stages of the build process. They can be used to fine tune
stages of the build process. They can be used to fine-tune
the image in ways that are not possible via the settings provided in
:file:`config.xml`.
@ -65,7 +65,7 @@ Overlay tree directory:
overwritten.
CD root user data:
For live ISO images and install ISO images an optional archive
For live ISO images and install ISO images, an optional archive
is supported. This is a tar archive matching the name
:file:`config-cdroot.tar[.compression_postfix]`.
@ -79,10 +79,10 @@ CD root user data:
Image Building Process
----------------------
{kiwi} creates images in a two step process: The first step, the *prepare*
{kiwi} 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 :file:`config.xml` configuration file
(see :ref:`image-description`)
(see :ref:`image-description`).
The second step, the *create* operation, creates the *packed image* or
*image* in the specified format based on the unpacked image tree and the
@ -100,61 +100,61 @@ information provided in the :file:`config.xml` configuration file.
The Prepare Step
^^^^^^^^^^^^^^^^
As the first step, {kiwi} creates an *unpackaged image tree*, also called "root tree". This
As the first step, {kiwi} creates an *unpackaged image tree*, also called a "root tree". This
directory will be the installation target for software packages to be
installed during the image creation process.
For the package installation, {kiwi} relies on the package manager specified
in the ``packagemanager`` element in :file:`config.xml`. {kiwi} supports the
following package managers: ``dnf``, ``zypper`` (default) and ``apt``.
in the `packagemanager` element in :file:`config.xml`. {kiwi} supports the
following package managers: `dnf`, `zypper` (default), and `apt`.
The prepare step consists of the following substeps:
#. **Create Target Root Directory**
By default {kiwi} aborts with an error if the target root tree
By default, {kiwi} aborts with an error if the target root tree
already exists to avoid accidental deletion of an existing
unpacked image. The option `--allow-existing-root` can be used
to work based on an existing root tree
to work based on an existing root tree.
#. **Bootstrap Target Root Directory**
First, {kiwi} configures the package manager to use the repositories
specified in the configuration file, via the command line, or
both. After the repository setup, the packages specified in the
``bootstrap`` section of the image description are installed in a
`bootstrap` section of the image description are installed in a
temporary directory external to the target root tree. This establishes
the initial environment to support the completion of the process in a
chroot setting. At the end of the ``bootstrap`` phase the script
chroot setting. At the end of the `bootstrap` phase, the script
:file:`post_bootstrap.sh` is executed, if present.
.. note::
The essential bootstrap packages are usually ``filesystem`` and
``glibc-locale`` to specify as part of the bootstrap. The dependency
The essential bootstrap packages are usually `filesystem` and
`glibc-locale` to specify as part of the bootstrap. The dependency
chain of these two packages is usually sufficient to populate the
bootstrap environment with all required software to support the
installation of packages into the new root tree.
#. **Install Packages**
After the ``bootstrap`` phase all other `<packages>` sections are
used to complete the installation as chroot operation. {kiwi} uses
the package manager as installed in the ``bootstrap`` phase and
After the `bootstrap` phase, all other `<packages>` sections are
used to complete the installation as a chroot operation. {kiwi} uses
the package manager as installed in the `bootstrap` phase and
installs all other packages as configured.
.. note::
The installation of software packages through the selected package
manager may install unwanted packages. Removing these packages can be
accomplished by marking them for deletion in the image description, see
accomplished by marking them for deletion in the image description; see
:ref:`uninstall-system-packages`.
#. **Apply the Overlay Tree**
Next, {kiwi} applies all files and directories present in the overlay
directory named :file:`root` or in the compressed overlay
:file:`root.tar.gz` to the target root tree. Files already present in
directory named :file:`root` or in the compressed overlay,
:file:`root.tar.gz`, to the target root tree. Files already present in
the target root directory are overwritten. This allows you to
overwrite any file that was installed by one of the packages during the
installation phase.
@ -169,30 +169,30 @@ The prepare step consists of the following substeps:
overlay tree, it is possible to overwrite files already existing in the
target root tree.
#. **Execute the user-defined script** :file:`config.sh`
#. **Execute the user-defined script** :file:`config.sh`.
At the end of the preparation stage the script :file:`config.sh` is
executed (if present). It is run in the top level directory of the
At the end of the preparation stage, the script :file:`config.sh` is
executed (if present). It is run in the top-level directory of the
target root tree. The script's primary function is to complete the
system configuration. For more details about custom scripts
see :ref:`working-with-kiwi-user-defined-scripts`
system configuration. For more details about custom scripts,
see :ref:`working-with-kiwi-user-defined-scripts`.
#. **Modify the Root Tree**
The unpacked image tree is now finished to be converted into the final
The unpacked image tree is now finished and can be converted into the final
image in the *create step*. It is possible to make manual modifications
to the unpacked tree before it is converted into the final image.
Since the unpacked image tree is just a directory, it can be modified
using the standard tools. Optionally, it is also possible to "change
root (:command:`chroot`)" into it, for instance to invoke the package
manager. Beside the standard file system layout, the unpacked image tree
using the standard tools. Optionally, it is also possible to 'change
root (`chroot`)' into it, for instance, to invoke the package
manager. Besides the standard filesystem layout, the unpacked image tree
contains an additional directory named :file:`/image` that is not
present in a regular system. It contains information {kiwi} requires
during the create step, including a copy of the :file:`config.xml` file.
By default, {kiwi} will not stop after the *prepare step* and will
directly proceed with the *create step*. Therfore to perform manual
proceed directly with the *create step*. Therefore, to perform manual
modifications, proceed as follows:
.. code:: shell-session
@ -204,11 +204,11 @@ The prepare step consists of the following substeps:
.. warning:: Modifications of the unpacked root tree
Do not make any changes to the system, since they are lost when
re-running the ``prepare`` step again. Additionally, you may
introduce errors that occur during the ``create`` step which are
re-running the `prepare` step again. Additionally, you may
introduce errors that occur during the `create` step, which are
difficult to track. The recommended way to apply changes to the
unpacked image directory is to change the configuration and re-run
the ``prepare`` step.
the `prepare` step.
.. _create-step:
@ -221,17 +221,17 @@ unpacked root tree into one or multiple output files appropriate for the
respective build type.
It is possible to create multiple images from the same unpacked
root tree, for example, a self installing OEM
root tree, for example, a self-installing OEM
image and a virtual machine image from the same image description. The only
prerequisite is that both image types are specified in :file:`config.xml`.
During the *create step* the following operations are performed by {kiwi}:
During the *create step*, the following operations are performed by {kiwi}:
#. **Execute the User-defined Script** :file:`images.sh`
#. **Execute the User-defined Script** :file:`images.sh`.
At the beginning of the image creation process the script named
At the beginning of the image creation process, the script named
:file:`images.sh` is executed (if present). For more details about
custom scripts see :ref:`working-with-kiwi-user-defined-scripts`
custom scripts, see :ref:`working-with-kiwi-user-defined-scripts`.
#. **Create the Requested Image Type**

154
doc/source/concept_and_workflow/customize_the_boot_process.rst
View File

@ -10,16 +10,16 @@ This boot image is a compressed cpio initial RAM disk, and it's called the
executes :command:`init` or, if present, :command:`linuxrc`.
Depending on the image type, {kiwi} creates the boot image automatically during
the ``create`` step. To create the :file:`initrd`, {kiwi} uses a tool called
the `create` step. To create the :file:`initrd`, {kiwi} uses a tool called
`dracut`. dracut-generated initrd archives can be extended with custom modules to
add functionality which is not natively provided by dracut itself. In the scope
add functionality that is not natively provided by dracut itself. In the scope
of {kiwi}, the following dracut modules are used:
``kiwi-dump``
Serves as an image installer. It provides the required implementation to
install a {kiwi} image on a selectable target. This module is required if one
of the attributes in the image type definition `installiso`, `installstick` or
`installpxe` is set to `true`.
of the attributes in the image type definition, `installiso`, `installstick`, or
`installpxe`, is set to `true`.
``kiwi-dump-reboot``
Serves to boot the system into the installed image after installation is
@ -30,8 +30,8 @@ of {kiwi}, the following dracut modules are used:
if the `iso` image type is selected.
``kiwi-overlay``
Allows to boot disk images with the attribute `overlayroot` set to `true`. A
disk like that has its root partition compressed and readonly. The disk boots up
Allows you to boot disk images with the attribute `overlayroot` set to `true`. A
disk like that has its root partition compressed and read-only. The disk boots up
using overlayfs for the root filesystem with a separate partition on the same
disk for persistent data.
@ -39,7 +39,7 @@ of {kiwi}, the following dracut modules are used:
Resizes an OEM disk image after installation on
the target disk to meet the size limits configured in the `oemconfig`
section of the image description. The module takes over the tasks of
repartitioning the disk, resizing RAID, LVM, LUKS and other layers as well as
repartitioning the disk, resizing RAID, LVM, LUKS, and other layers, as well as
resizing the system filesystems.
``kiwi-lib``
@ -48,8 +48,8 @@ of {kiwi}, the following dracut modules are used:
.. note:: Using Custom Boot Image Support
In addition to the standard dracut-based creation of the boot image, {kiwi}
supports the use of custom boot images for the image types ``oem``
and ``pxe``. The use of a custom boot image is enabled by setting the
supports the use of custom boot images for the image types `oem`
and `pxe`. The use of a custom boot image is enabled by setting the
following attribute in the image description:
.. code:: none
@ -57,21 +57,21 @@ of {kiwi}, the following dracut modules are used:
<type ... initrd_system="kiwi"/>
Along with this setting, you must provide a reference to
a boot image description in the ``boot`` attribute as follows:
a boot image description in the `boot` attribute as follows:
.. code:: none
<type ... boot="{exc_netboot}"/>
While {kiwi} supports this approach, it is recommended using dracut instead.
Keep also in mind that although {kiwi} supports creation of custom boot
While {kiwi} supports this approach, it is recommended to use dracut instead.
Keep also in mind that although {kiwi} supports the creation of custom boot
images, {kiwi} does not include any official boot image descriptions. You
can find an OEM boot description example at
https://build.opensuse.org/package/show/Virtualization:Appliances:Images:Testing_x86:tumbleweed/custom-oem-boot-description
and an PXE boot description example at
https://build.opensuse.org/package/show/Virtualization:Appliances:Images:Testing_x86:tumbleweed/custom-pxe-boot-description
and a PXE boot description example at
https://build.opensuse.org/package/show/Virtualization:Appliances:Images:Testing_x86:tumbleweed/custom-pxe-boot-description.
The custom boot image descriptions makes it possible to completely customize
The custom boot image descriptions make it possible to completely customize
the behavior of the initrd. This concept is mostly used in PXE environments
that are usually heavily customized and require a specific boot and
deployment workflow.
@ -80,7 +80,7 @@ of {kiwi}, the following dracut modules are used:
Boot Image Hook-Scripts
.......................
The dracut initrd system uses ``systemd`` to implement a predefined workflow
The dracut initrd system uses `systemd` to implement a predefined workflow
of services documented in the bootup man page:
http://man7.org/linux/man-pages/man7/dracut.bootup.7.html
@ -155,13 +155,13 @@ before the system rootfs is mounted.
and libraries required by the hook script.
* Each file must be included in the {kiwi} description either in a
package, archive, or in the root tree of the image description
package, an archive, or in the root tree of the image description
directory.
* The parameters of the `inst_multiple` command are space separated.
* The parameters of the `inst_multiple` command are space-separated.
* Each parameter can be a single executable name if it exists in `/bin`,
`/sbin`, `/usr/bin`, or `/usr/sbin`` directories.
* Each parameter can be a single executable name if it exists in the `/bin`,
`/sbin`, `/usr/bin`, or `/usr/sbin` directories.
* Otherwise, a full path to the file is required. This normally applies for
libraries and other special files.
@ -178,17 +178,17 @@ the `dracut project page <https://dracut.wiki.kernel.org/index.php/Main_Page>`_.
Boot Image Parameters
.....................
A dracut generated initrd in a {kiwi} image build process includes one or
more of the {kiwi} provided dracut modules. The following list documents
A dracut-generated initrd in a {kiwi} image build process includes one or
more of the {kiwi}-provided dracut modules. The following list documents
the available kernel boot parameters for these modules:
``rd.kiwi.term``
Exports the TERM variable into the initrd environment. If
Exports the `TERM` variable into the initrd environment. If
the default value for the terminal emulation is not correct,
`rd.kiwi.term` can be used to overwrite the default. The
environment is also passed to the systemd unit that calls
dialog based programs in {kiwi} dracut code, which means that the
TERM setting applies there too.
dialog-based programs in {kiwi} dracut code, which means that the
`TERM` setting applies there too.
``rd.kiwi.debug``
Activates the debug log file for the {kiwi} part of
@ -196,81 +196,81 @@ the available kernel boot parameters for these modules:
``rd.kiwi.dialog.timeout=seconds|off``
Sets a timeout value for dialogs invoked by kiwi dracut
modules. By default the timeout is set to 60 seconds.
modules. By default, the timeout is set to 60 seconds.
If set to the special value `off`, the dialog will never
timeout.
time out.
``rd.kiwi.install.devicepersistency=by-*``
Instructs an OEM installation image to present the list of
available disk devices using the device names as provided
by the specified `by-*` representation. For example
by the specified `by-*` representation. For example,
`rd.kiwi.install.devicepersistency=by-path` would show the
by-path device names in the list of available disks.
``rd.kiwi.install.pxe``
Instructs an OEM installation image to lookup the system
Instructs an OEM installation image to look up the system
image on a remote location specified in `rd.kiwi.install.image`.
``rd.kiwi.install.image=URI``
Specifies the remote location of the system image in
a PXE based OEM installation.
a PXE-based OEM installation.
``rd.kiwi.install.pass.bootparam``
Instructs an OEM installation image to pass an additional
Instructs an OEM installation image to pass additional
boot parameters to the kernel used to boot the installed image. This
can be used, for example, to pass on first boot configuration for a PXE image.
can be used, for example, to pass on first-boot configuration for a PXE image.
Note that options starting with `rd.kiwi` are not passed to avoid
side effects.
``rd.kiwi.install.retain_last``
Instructs an OEM installation to retain the contents of the
last partition on the target disk. This setting is only useful
if the last partition does not belong to the main OS e.g. an
if the last partition does not belong to the main OS, e.g., an
extra data partition added via the `spare_part` attribute in
the type setup of the image description. The implementation
also checks if the start address of the last partition on the
target disk matches with the start adress of the image to be
deployed. Only if they match the data on the last partition
can be retained.
target disk matches the start address of the image to be
deployed. Only if they match can the data on the last partition
be retained.
``rd.kiwi.oem.luks.reencrypt``
For OEM LUKS2 encrypted disk images. If set, reencrypts the disk
prior an eventual resize and therefore creates a new key pool and
master key. The reencryption is advisable if the image binary is
not protected. With access to the image binary it's possible to
extract the luks header which then allows to decrypt the data
unless it was reencrypted. The reencryption process only runs if
the checksum of the luks header still matches the one from the
original disk image. Be aware that the reencryption will ask
For OEM LUKS2-encrypted disk images. If set, it re-encrypts the disk
prior to an eventual resize and therefore creates a new key pool and
master key. The re-encryption is advisable if the image binary is
not protected. With access to the image binary, it's possible to
extract the LUKS header, which then allows you to decrypt the data
unless it was re-encrypted. The re-encryption process only runs if
the checksum of the LUKS header still matches the one from the
original disk image. Be aware that the re-encryption will ask
for the passphrase if the image has been built with an initial
luks passphrase.
LUKS passphrase.
``rd.kiwi.oem.luks.reencrypt_randompass``
For OEM LUKS2 encrypted disk images in combination
with `rd.kiwi.oem.luks.reencrypt`. Reset insecure built time
For OEM LUKS2-encrypted disk images in combination
with `rd.kiwi.oem.luks.reencrypt`. Resets the insecure built-time
passphrase, set via the `luks=` attribute, with a random
onetime passphrase that will be stored in memory at
one-time passphrase that will be stored in memory at
`/run/.kiwi_reencrypt.keyfile`.
.. warning::
The passphrase will only persist as long as the system
does not reboot. Using this option usually requires that
the boot process implements code to set a retrievable keyfile
information for subsequent boot processes of this system, e.g
the boot process implements code to set retrievable keyfile
information for subsequent boot processes of this system, e.g.,
TPM setup or similar.
``rd.kiwi.oem.disk.consistency``
For OEM disk images providing an installation image. If set,
the installation image will check against all disks that are
not the selected target disk if there is any disk in the system
not the selected target disk to see if there is any disk in the system
that has the same PTUUID compared to the image that is about
to be installed. If such a disk is found this indicates that
to be installed. If such a disk is found, this indicates that
the same image was already installed to another storage disk
on the same system which will cause device id inconsistencies
for the entire system. In such a case an error message is
displayed providing information about the conflicting device
and the installation will be cancelled.
on the same system, which will cause device ID inconsistencies
for the entire system. In such a case, an error message is
displayed, providing information about the conflicting device,
and the installation will be canceled.
``rd.kiwi.oem.maxdisk=size[KMGT]``
Specifies the maximum disk size an unattended OEM installation uses for image
@ -282,25 +282,25 @@ the available kernel boot parameters for these modules:
``rd.kiwi.oem.force_resize``
Forces the disk resize process on an OEM disk image. If set, no sanity
check for unpartitioned/free space is performed and also an eventually
check for unpartitioned/free space is performed, and also an eventually
configured `<oem-resize-once>` configuration from the image description
will not be taken into account. The disk resize will be started which
includes re-partition as well as all steps to resize the block layers
will not be taken into account. The disk resize will be started, which
includes re-partitioning as well as all steps to resize the block layers
up to the filesystem holding the data. As `rd.kiwi.oem.force_resize`
bypasses all sanity checks to detect if such a resize process is
needed or not, it can happen that all program calls of the resize
process ends without any effect if the disk is already properly
process end without any effect if the disk is already properly
resized. It's also important to understand that the partition UUIDs
will change on every resize which might be an unwanted side effect
will change on every resize, which might be an unwanted side effect
of a forced resize.
``rd.kiwi.oem.installdevice``
Configures the disk device to use in an OEM installation. This overwrites or
resets any other OEM device-specific settings, such as `oem-device-filter`,
`oem-unattended-id` or `rd.kiwi.oem.maxdisk`, and continues the installation on
`oem-unattended-id`, or `rd.kiwi.oem.maxdisk`, and continues the installation on
the given device. The device must exist and must be a block special.
.. note:: Non interactive mode activated by rd.kiwi.oem.installdevice
.. note:: Non-interactive mode activated by rd.kiwi.oem.installdevice
When setting `rd.kiwi.oem.installdevice` explicitly through the kernel command line,
{kiwi} uses the device without prompting for confirmation.
@ -308,7 +308,7 @@ the available kernel boot parameters for these modules:
``rd.live.overlay.size``
Specifies the size for the `tmpfs` filesystem of a live ISO image that is used
for the `overlayfs` mount process. If the write area of the overlayfs mount
uses this tmpfs, any new data written during the runtime of the system is
uses this `tmpfs`, any new data written during the runtime of the system is
written in this space. The default value is `50%`, meaning half of the
available RAM space can be used for writing new data.
@ -317,7 +317,7 @@ the available kernel boot parameters for these modules:
``rd.live.encrypt``
Instructs a live ISO image to encrypt the persistent write partition.
The boot process becomes interactive in this case and the user has
The boot process becomes interactive in this case, and the user has
to specify a passphrase at boot time.
``rd.live.overlay.cowfs``
@ -329,38 +329,38 @@ the available kernel boot parameters for these modules:
`live-grub-stick`, the live ISO image is copied as a file on the target device,
and a GRUB loopback setup is created there to boot the live system from the
file. In this case, the persistent write setup that normally creates an extra
write partition on the target will fail in most situations, because the target
write partition on the target will fail in most situations because the target
has no free and unpartitioned space available. To prevent this from happening,
a COW file (live_system.cow) of a partition is created alongside the live ISO
image file. The default size of the COW file is 500MB.
``rd.live.cowfile.path``
Effectively used in isoscan loop mounted live systems. For details on this
type of live system refer to :ref:`iso_as_file_to_usb_stick`.
Effectively used in isoscan loop-mounted live systems. For details on this
type of live system, refer to :ref:`iso_as_file_to_usb_stick`.
Specifies the path of the COW file below the `/run/initramfs/isoscan` loop
mount point. If not specified the cowfile is placed at
mount point. If not specified, the cowfile is placed at
`/run/initramfs/isoscan/live_system.cow`.
``rd.live.dir``
Specifies a directory that contains the live OS root directory. Default is
Specifies a directory that contains the live OS root directory. The default is
`LiveOS`.
``rd.live.squashimg``
Specifies the name of the squashfs image file which contains the OS root.
Default is `squashfs.img`.
Specifies the name of the squashfs image file that contains the OS root.
The default is `squashfs.img`.
``rd.kiwi.allow_plymouth``
By default kiwi stops plymouth if present and active in the
initrd. Setting rd.kiwi.allow_plymouth will keep plymouth
active in the initrd including all effects that might have
to the available consoles.
By default, kiwi stops plymouth if it is present and active in the
initrd. Setting `rd.kiwi.allow_plymouth` will keep plymouth
active in the initrd, including all effects that might have
on the available consoles.
Boot Debugging
''''''''''''''
If the boot process encounters a fatal error, the default behavior is to
stop the boot process without any possibility to interact with the system.
To prevent this, activate dracut's builtin debug mode in combination
To prevent this, activate dracut's built-in debug mode in combination
with the {kiwi} debug mode as follows:
.. code:: bash

64
doc/source/concept_and_workflow/packages.rst
View File

@ -24,32 +24,32 @@ of packages via the `packages` element.
The `packages` element provides a collection of different child elements
that instruct {kiwi} when and how to perform package installation or
removal. Each `packages` element acts as a group, whose behavior can be
removal. Each `packages` element acts as a group whose behavior can be
configured via the following attributes:
- `type`: either `bootstrap`, `image`, `delete`, `uninstall` or one of the
following build types: `docker`, `iso`, `oem`, `kis`, `oci`.
Packages for `type="bootstrap"` are pre-installed to populate the images'
root file system before chrooting into it.
Packages for `type="bootstrap"` are pre-installed to populate the image's
root filesystem before chrooting into it.
Packages in `type="image"` are installed immediately after the initial
chroot into the new root file system.
chroot into the new root filesystem.
Packages in `type="delete"` and `type="uninstall"` are removed from the
image, for details see :ref:`uninstall-system-packages`.
image. For details, see :ref:`uninstall-system-packages`.
And packages which belong to a build type are only installed when that
And packages that belong to a build type are only installed when that
specific build type is currently processed by {kiwi}.
- `profiles`: a list of profiles to which this package selection applies
(see :ref:`image-profiles`).
- `patternType`: selection type for patterns, supported values are:
`onlyRequired`, `plusRecommended`, see:
- `patternType`: selection type for patterns; supported values are:
`onlyRequired`, `plusRecommended`; see:
:ref:`product-and-namedCollection-element`.
The following sections describes the different child elements of
The following sections describe the different child elements of
a `packages` group.
.. _package-element:
@ -70,10 +70,10 @@ removed), whose name is specified via the mandatory `name` attribute:
</image>
This adds the package `udev` to the list of packages to be added to the
initial filesystem. Note, that the value that you pass via the `name`
initial filesystem. Note that the value that you pass via the `name`
attribute is passed directly to the used package manager. Thus, if the
package manager supports other means how packages can be specified, you may
pass them in this context too. For example, RPM based package managers
package manager supports other means of how packages can be specified, you may
pass them in this context too. For example, RPM-based package managers
(like :command:`dnf` or :command:`zypper`) can install packages via their
`Provides:`. This can be used to add a package that provides a certain
capability (for example, `Provides: /usr/bin/my-binary`) via:
@ -88,12 +88,12 @@ capability (for example, `Provides: /usr/bin/my-binary`) via:
</image>
Whether this works depends on the package manager and on the environment
that is being used. In the Open Build Service, certain `Provides` either
are not visible or cannot be properly extracted from the {kiwi}
that is being used. In the Open Build Service, certain `Provides` are either
not visible or cannot be properly extracted from the {kiwi}
description. Therefore, relying on `Provides` is not recommended.
Packages can also be included only on specific host architectures via the
`arch` attribute. {kiwi} compares the `arch` attributes value with the host
`arch` attribute. {kiwi} compares the `arch` attribute's value with the host
architecture that builds the image according to the output of `uname -m`.
.. code:: xml
@ -108,7 +108,7 @@ architecture that builds the image according to the output of `uname -m`.
</image>
This results in `grub2-x86_64-efi` and `shim` being only installed if the
build host is a 64bit x86 machine, but `grub2` will be installed independent
build host is a 64-bit x86 machine, but `grub2` will be installed independent
of the architecture.
@ -133,7 +133,7 @@ archive in the image description folder).
{kiwi} extracts the archive into the root directory of the image using
`GNU tar <https://www.gnu.org/software/tar/>`_. This means that only archives
supported by it can be included. When multiple `archive` elements are
specified then they are applied in a top to bottom order. If a file is
specified, then they are applied in a top-to-bottom order. If a file is
already present in the image, then the file from the archive overwrites
it (same as with the image overlay).
@ -146,7 +146,7 @@ Uninstall System Packages
appliance:
1. Packages present as a child element of `<packages type="uninstall">`
are gracefully uninstalled by the package manager together with
are gracefully uninstalled by the package manager, together with
dependent packages and orphaned dependencies.
2. Packages present as a child element of `<packages type="delete">` are removed
@ -165,16 +165,16 @@ Both types of removals take place after :file:`config.sh` is run in the
* the packages dependent on the listed ones
* any orphaned dependency of the listed packages
Use this feature with caution as it can cause removal of
Use this feature with caution, as it can cause the removal of
required tools, leading to failures in later build stages.
Removing packages via `type="uninstall"` can be used to completely remove a
build time tool (for example, a compiler), without having to specify all
build-time tool (for example, a compiler) without having to specify all
dependencies of that tool (as opposed to when using
`type="delete"`). Consider the following example, where we want to compile a
custom program in :file:`config.sh`. We ship its source code via an
`archive` element and add the build tools (`ninja`, `meson` and `clang`) to
`archive` element and add the build tools (`ninja`, `meson`, and `clang`) to
`<packages type="image">` and `<packages type="uninstall">`:
.. code:: xml
@ -197,11 +197,11 @@ custom program in :file:`config.sh`. We ship its source code via an
</packages>
</image>
The tools `meson`, `clang` and `ninja` are then available during the
The tools `meson`, `clang`, and `ninja` are then available during the
:ref:`prepare step <prepare-step>`, and they can be used in
:file:`config.sh` (for further details, see
:ref:`working-with-kiwi-user-defined-scripts`), for example to build
``foo_app``:
:ref:`working-with-kiwi-user-defined-scripts`), for example, to build
`foo_app`:
.. code:: bash
@ -213,12 +213,12 @@ The tools `meson`, `clang` and `ninja` are then available during the
popd
The `<packages type="uninstall">` element ensures that the final
appliance no longer contains the tools required to build ``foo_app``,
appliance no longer contains the tools required to build `foo_app`,
thus making the image smaller.
There are also other use cases for `type="uninstall"`, especially for
specialized appliances. For containers, you can remove the package
`shadow` (it is required to setup new user accounts) or any remaining
`shadow` (it is required to set up new user accounts) or any remaining
partitioning tools (`parted` or `fdisk`). All networking tools can be
safely uninstalled in images for embedded devices without a network
connection.
@ -228,18 +228,18 @@ connection.
The `product` and `namedCollection` element
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
{kiwi} supports the inclusion of openSUSE products or of namedCollections
(*patterns* in SUSE based distributions or *groups* for RedHat based
{kiwi} supports the inclusion of openSUSE products or of named collections
(*patterns* in SUSE-based distributions or *groups* for RedHat-based
distributions). These can be added via the `product` and `namedCollection`
child elements, which both take the mandatory `name` attribute and the
optional `arch` attribute.
`product` and `namedCollection` can be used to shorten the list of
packages that need to be added to the image description. A
named pattern, specified with the namedCollection element is a
named pattern, specified with the `namedCollection` element, is a
representation of a predefined list of packages. Specifying a pattern
installs all packages listed in the named pattern. Support for patterns is
distribution-specific and available in SLES, openSUSE, CentOS, RHEL and
distribution-specific and available in SLES, openSUSE, CentOS, RHEL, and
Fedora. The optional `patternType` attribute on the packages element allows
you to control the installation of dependent packages. You may assign one
of the following values to the `patternType` attribute:
@ -257,7 +257,7 @@ The `ignore` element
Packages can be explicitly marked to be ignored for installation inside a
`packages` collection. This can be used to exclude certain packages from being
installed when using patterns with `patternType="plusRecommended"` as shown
installed when using patterns with `patternType="plusRecommended"`, as shown
in the following example:
.. code:: xml
@ -273,7 +273,7 @@ in the following example:
</image>
Packages can be marked as ignored during the installation by adding a
Packages can be marked as ignored during the installation by adding an
`ignore` child element with the mandatory `name` attribute set to the
name of the package. Optionally, you can specify the architecture via
`arch`, similarly to :ref:`package-element`.

6
doc/source/concept_and_workflow/profiles.rst
View File

@ -34,7 +34,7 @@ machine images of the `oem` type are configured: one for QEMU (using the
Each profile is declared via the element `profile` that must be a
child of `profiles`, and it must contain the `name` and `description`
attributes. The `description` is only present for documentation purposes,
attributes. The `description` is only present for documentation purposes;
`name`, on the other hand, is used to instruct {kiwi} which profile to build
via the command line. Additionally, you can provide the boolean attribute
`import`, which defines whether this profile should be used by default when
@ -57,7 +57,7 @@ Profiles can furthermore inherit settings from another profile via the
</profile>
</profiles>
In the above example, the profile `QEMU` inherit the settings from `VM`.
In the above example, the profile `QEMU` inherits the settings from `VM`.
For further details on the usage of *profiles*, see
:ref:`building-build-with-profiles`
:ref:`building-build-with-profiles`.

42
doc/source/concept_and_workflow/repository_setup.rst
View File

@ -14,7 +14,7 @@ Adding repositories
the image description. This means that at least one repository **must** be
defined. Otherwise, {kiwi} cannot fetch any packages.
A repository is added to the description via the `repository` element
A repository is added to the description via the `repository` element,
which is a child of the top-level `image` element:
.. code:: xml
@ -35,18 +35,18 @@ The above example specifies two repositories:
*{exc_kiwi_repo}* at the Open Build Service (OBS).
2. The RPM repository belonging to the OS project:
*{exc_repo}*, at the Open Build Service (OBS). The translated
http URL is also included in the final appliance.
*{exc_repo}* at the Open Build Service (OBS). The translated
HTTP URL is also included in the final appliance.
The `repository` element accepts one `source` child element that
contains the URL of the repository in an correct format along with the
contains the URL of the repository in a correct format, along with the
following optional attributes:
- `imageinclude`: Specifies whether the repository should be added to the
resulting image. Default is false.
resulting image. The default is false.
- `imageonly`: A repository with `imageonly="true"` is not available
during image build, but is present in the resulting appliance. Default is
during the image build but is present in the resulting appliance. The default is
false.
- `priority`: An integer value for all packages in this repository. If
@ -54,34 +54,34 @@ following optional attributes:
with the highest priority is used.
- `alias`: Name to use for the repository. It appears as the repository's name
in the image visible via ``zypper repos`` or ``dnf repolist``. If `alias`` is
not specified, {kiwi} generates an alias name using hex representation from
in the image, visible via `zypper repos` or `dnf repolist`. If `alias` is
not specified, {kiwi} generates an alias name using a hex representation from
uuid4.
- `repository_gpgcheck`: Specify whether or not this specific repository
- `repository_gpgcheck`: Specifies whether or not this specific repository
values the result of the repository signature validation.
The default value is `false`.
- `package_gpgcheck`: Specify whether or not this specific repository
- `package_gpgcheck`: Specifies whether or not this specific repository
values the result of the package signature validation for each
package taken from this repository. The default value is `false`.
- `components`: Distribution components used for `deb` repositories. Default is `main`.
- `components`: Distribution components used for `deb` repositories. The default is `main`.
- `distribution`: Distribution name information, used for deb repositories.
- `distribution`: Distribution name information, used for `deb` repositories.
- `profiles`: List of profiles to which this repository applies.
- `customize`: Script to run custom modifications to the repo file or files.
- `customize`: A script to run custom modifications to the repo file or files.
Repo files allow for several customization options, but not all of them
are supported to be set by kiwi through the current repository schema.
As the used options do not follow any standard, and they are not compatible
between package managers and distributions, the only way to handle
this is through a script hook which is invoked with the repo file as
this is through a script hook that is invoked with the repo file as a
parameter for each file created by {kiwi}.
An example for a script call to add the `module_hotfixes` option
for a `dnf` compatible repository configuration could look as follows:
for a `dnf`-compatible repository configuration could look as follows:
.. code:: bash
@ -91,7 +91,7 @@ following optional attributes:
.. note::
If the script is provided as a relative path, it is expected to be found
in the image description directory:
in the image description directory.
.. _supported-repository-paths:
@ -99,14 +99,14 @@ Supported repository paths
^^^^^^^^^^^^^^^^^^^^^^^^^^
The actual location of a repository is specified in the `source` child
element of `repository` via its only attribute `path`. {kiwi} supports the
following paths types:
element of `repository` via its only attribute, `path`. {kiwi} supports the
following path types:
- `http://URL` or `https://URL` or `ftp://URL`: a URL to the repository
available via HTTP(s) or FTP.
available via HTTP(S) or FTP.
- `obs://$PROJECT/$REPOSITORY`: checks whether the repository `$REPOSITORY`
of the project `$PROJECT` available on the Open Build Service (OBS). By
of the project `$PROJECT` is available on the Open Build Service (OBS). By
default, {kiwi} looks for projects on `build.opensuse.org
<https://build.opensuse.org>`_, but this can be overridden using the
runtime configuration file (see :ref:`runtime_config`).
@ -114,7 +114,7 @@ following paths types:
from **different** OBS instances (use direct URLs to the :file:`.repo`
file instead in this case).
- `obsrepositories:/`: special path only available for builds using the Open
- `obsrepositories:/`: a special path only available for builds using the Open
Build Service. The repositories configured for the OBS project where the
{kiwi} image resides are made available inside the appliance. This allows you
to configure the repositories of your image from OBS itself, without modifying

6
doc/source/concept_and_workflow/runtime_configuration.rst
View File

@ -3,8 +3,8 @@
The Runtime Configuration File
------------------------------
{kiwi} supports an additional configuration file for runtime specific
settings which do not belong in the image description but which are
{kiwi} supports an additional configuration file for runtime-specific
settings that do not belong in the image description but which are
persistent and are unsuitable for command-line parameters.
The runtime configuration file must adhere to the `YAML <https://yaml.org/>`_
@ -17,5 +17,5 @@ configuration file in the following locations:
2. :file:`/etc/kiwi.yml`
A default runtime config file in :file:`/etc/kiwi.yml` is provided with
the python3-kiwi package. The file contains all settings as comments
the `python3-kiwi` package. The file contains all settings as comments,
including a short description of each setting.

112
doc/source/concept_and_workflow/shell_scripts.rst
View File

@ -6,7 +6,7 @@ User-Defined Scripts
.. note:: **Abstract**
This chapter describes the purpose of the user-defined scripts
:file:`config.sh`, :file:`image.sh`, :file:`pre_disk_sync.sh` and
:file:`config.sh`, :file:`image.sh`, :file:`pre_disk_sync.sh`, and
:file:`disk.sh`. These scripts can be used to further customize an image in
ways that are not possible via the image description alone.
@ -16,7 +16,7 @@ root environment (chroot) containing an appliance:
post_bootstrap.sh
Runs at the end of the `bootstrap` phase as part of the :ref:`prepare step
<prepare-step>`. The script can be used to configure the package manager with
additional settings that apply in the following chroot-based installation step
additional settings that apply in the following chroot-based installation step,
which completes the installation. The script can also be used for other tasks.
config.sh
@ -28,13 +28,13 @@ config.sh
config-overlay.sh
Available only if `delta_root="true"` is set. In this case, the script runs at
the end of the :ref:`prepare step <prepare-step>` prior the umount of the
the end of the :ref:`prepare step <prepare-step>` prior to the `umount` of the
overlay root tree. It runs after `config.sh` (if specified), and it is the
last entry point to change the delta root tree.
config-host-overlay.sh
Available only if `delta_root="true"` is set. In this case, the script runs at
the end of the :ref:`prepare step <prepare-step>` prior the umount of the
the end of the :ref:`prepare step <prepare-step>` prior to the `umount` of the
overlay root tree. The script is called **NOT CHROOTED** from the host with
the image root directory as its working directory. It runs after `config.sh`
and `config-overlay.sh` (if any or both are specified), and it is the last
@ -44,30 +44,30 @@ images.sh
Executed at the beginning of the :ref:`image creation process <create-step>`.
It runs in the same image root tree created by the prepare step,
but it is invoked whenever an image needs to be created from that root tree.
It is normally used to apply image type specific changes to the root tree, such
It is normally used to apply image-type-specific changes to the root tree, such
as a modification to a config file that must be done when building a live
iso, but not when building a virtual disk image.
ISO but not when building a virtual disk image.
pre_disk_sync.sh
Executed for the disk image type `oem` only, and it runs
right before the synchronization of the root tree into the disk image
loop file. The :file:`pre_disk_sync.sh` can be used to change
loop file. The :file:`pre_disk_sync.sh` can be used to change the
content of the root tree as a last action before the sync to
the disk image is performed. This is useful, for example, for deleting
components from the system which were needed earlier or cannot
be modified afterwards when syncing into a read-only filesystem.
components from the system that were needed earlier or cannot
be modified afterward when syncing into a read-only filesystem.
disk.sh
Executed for the disk image type `oem` only, and it runs after the
synchronization of the root tree to the disk image loop file. The chroot
synchronization of the root tree to the disk image loop file. The `chroot`
environment for this script call is the virtual disk itself and not the root
tree. The script :file:`disk.sh` is normally used to apply changes at parts of
tree. The script :file:`disk.sh` is normally used to apply changes to parts of
the system that are not an element of the file-based root tree, such as the
partition table, the contents of the final initrd, the bootloader, filesystem
attributes, etc.
{kiwi} executes scripts via the operating system if their executable
bit is set (in that case, a shebang is mandatory); otherwise they are
bit is set (in that case, a shebang is mandatory); otherwise, they are
invoked via the Bash shell. If a script exits with a non-zero exit code,
{kiwi} reports the failure and aborts the image creation.
@ -88,12 +88,12 @@ In this mode, a script can be started using the following template:
echo "break"
/bin/bash
Calling the script executes a `screen` session executes, which gives you access
to the break in shell. You can then implement the desired script code in this
environment.. Once the shell is closed the {kiwi} process continues.
Calling the script executes a `screen` session, which gives you access
to the break-in shell. You can then implement the desired script code in this
environment. Once the shell is closed, the {kiwi} process continues.
In addition to providing a fully featured terminal throughout the execution of
the script code, you also have have control of the session during the process of
the script code, you also have control of the session during the process of
the image creation. Listing the active sessions for script execution can be done
as follows:
@ -107,7 +107,7 @@ as follows:
.. note::
As shown above the screen session for executing the script code provides
As shown above, the screen session for executing the script code provides
extended control, which can be considered a security risk. Because of that,
{kiwi} only runs scripts through `screen` when explicitly enabled via the
`--debug` switch. In production, all scripts must run natively and
@ -153,8 +153,8 @@ Functions
^^^^^^^^^
The :file:`.kconfig` file provides a common set of functions. Functions
specific to SUSE Linux Enterprise and openSUSE start with ``suse``, functions
applicable to all Linux distributions start with ``base``.
specific to SUSE Linux Enterprise and openSUSE start with `suse`; functions
applicable to all Linux distributions start with `base`.
The following list describes all functions provided by :file:`.kconfig`:
@ -162,14 +162,14 @@ baseSetRunlevel {value}
Set the default run level.
baseStripAndKeep {list of info-files to keep}
Helper function for the ``baseStrip*`` functions that reads a list of files to
check from stdin for removing params: files which should be kept.
A helper function for the `baseStrip*` functions that reads a list of files to
check from stdin for removing params: files that should be kept.
baseStripLocales {list of locales}
Removes all locales, except for the ones given as the parameter.
Removes all locales except for the ones given as the parameter.
baseStripTranslations {list of translations}
Removes all translations, except those given as the parameter.
Removes all translations except those given as the parameter.
baseStripUnusedLibs
Removes libraries that are not directly linked against applications
@ -179,12 +179,12 @@ baseUpdateSysConfig {filename} {variable} {value}
Updates the contents of a sysconfig variable.
baseSystemdServiceInstalled {service}
Prints the path of the first found systemd unit or mount with name passed
Prints the path of the first found systemd unit or mount with the name passed
as the first parameter.
baseSysVServiceInstalled {service}
Prints the name `${service}` if a SysV init service with the same name is
found; otherwise it prints nothing.
found; otherwise, it prints nothing.
baseSystemdCall {service_name} {args}
Calls `systemctl ${args} ${service_name}` if a systemd unit, a systemd
@ -198,7 +198,7 @@ baseRemoveService {servicename}
baseService {servicename} {on|off}
Activates or deactivates a service via :command:`systemctl`.
The function requires the service name and the value ``on`` or ``off`` as
The function requires the service name and the value `on` or `off` as
parameters.
The following example enables the sshd service on boot:
@ -208,42 +208,42 @@ baseService {servicename} {on|off}
baseService sshd on
suseInsertService {servicename}
Calls baseInsertService. It exists only for
Calls `baseInsertService`. It exists only for
compatibility reasons.
suseRemoveService {servicename}
Calls baseRemoveService. It exists only for
Calls `baseRemoveService`. It exists only for
compatibility reasons.
suseService {servicename} {on|off}
Calls baseService. It exists only for compatibility
Calls `baseService`. It exists only for compatibility
reasons.
suseSetupProduct
Creates the :file:`/etc/products.d/baseproduct` link
pointing to the product referenced either by :file:`/etc/SuSE-brand` or
:file:`/etc/os-release` or the latest `.prod` file available in
:file:`/etc/products.d`
:file:`/etc/products.d`.
baseVagrantSetup
Configures the image to work as a vagrant box by performing the following
changes:
- add the ``vagrant`` user to :file:`/etc/sudoers`
or :file:`/etc/sudoers.d/vagrant`
- add the `vagrant` user to :file:`/etc/sudoers`
or :file:`/etc/sudoers.d/vagrant`.
- insert the insecure vagrant ssh key, apply recommended
ssh settings and start the ssh daemon
- create the default shared folder :file:`/vagrant`
ssh settings, and start the ssh daemon.
- create the default shared folder :file:`/vagrant`.
Debug {message}
Helper function to print the supplied message if the variable DEBUG is
A helper function to print the supplied message if the variable DEBUG is
set to 1 (disabled by default).
Echo {echo commandline}
Helper function to print a message to the controlling terminal.
A helper function to print a message to the controlling terminal.
Rm {list of files}
Helper function to delete files and log the deletion.
A helper function to delete files and log the deletion.
Profile Environment Variables
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@ -287,7 +287,7 @@ $kiwi_type
.. note:: **.profile.extra**
If there is the file :file:`/.profile.extra` available in the initrd, {kiwi}
If the file :file:`/.profile.extra` is available in the initrd, {kiwi}
imports the file importing :file:`/.profile`.
Configuration Tips
@ -295,40 +295,40 @@ Configuration Tips
#. **Locale configuration:**
To set locale, {kiwi} relies on :command:`systemd-firstboot` that writes the
locale configuration file :file:`/etc/locale.conf`. The values for the locale
To set the locale, {kiwi} relies on `systemd-firstboot`, which writes the
locale configuration file, :file:`/etc/locale.conf`. The values for the locale
settings are taken from the description XML file in the `<locale>` element
under `<preferences>`.
Keep im mind that if the build distribution does not use `/etc/locale.conf`,
the :command:`systemd-firstboot` does not have any effect on the locale
Keep in mind that if the build distribution does not use `/etc/locale.conf`,
`systemd-firstboot` does not have any effect on the locale
settings. For example, in the SLE12 distribution,
:command:`systemd-firstboot` is only effective when locales in
:file:`/etc/sysconfig/language` are not set, or when the file does not exist
`systemd-firstboot` is only effective when locales in
:file:`/etc/sysconfig/language` are not set or when the file does not exist
at all. For compatibility reasons, the file :file:`/etc/sysconfig/language`
in SLE12 has precedence over :file:`/etc/locale.conf`, and management tools
can still use `sysconfig` files for locale settings.
In any case, it is possible to configure the locale setting inside the
:file:`config.sh` script in {kiwi} using in distribution-specific way, or by
adding any additional configuration file as part of the overlay root-tree.
:file:`config.sh` script in {kiwi} in a distribution-specific way or by
adding any additional configuration file as part of the overlay root tree.
#. **Stateless systemd UUIDs:**
Machine ID files (:file:`/etc/machine-id`, :file:`/var/lib/dbus/machine-id`)
may be created and set during the image package installation depending on
may be created and set during the image package installation, depending on
the distribution. Those UUIDs must be unique and must be set only once
in each deployment.
If :file:`/etc/machine-id` does not exist or contains the string
`uninitialized` (systemd v249 and later), this triggers firstboot action
`uninitialized` (systemd v249 and later), this triggers a firstboot action
in systemd, and the services are run with `ConditionFirstBoot=yes`. Unless the
file already contains a valid machine ID, systemd generates a machine ID and
write it into the file, creating it if necessary. See the `machine-id man
writes it into the file, creating it if necessary. See the `machine-id man
page <https://www.freedesktop.org/software/systemd/man/machine-id.html>`_
for more details.
Depending on whether firstboot action should be triggered or not,
Depending on whether the firstboot action should be triggered or not,
:file:`/etc/machine-id` can be created, removed, or set to
`uninitialized` by :file:`config.sh`.
@ -344,15 +344,15 @@ Configuration Tips
By default, the root filesystem is mounted read-only by dracut/systemd,
so a missing :file:`/etc/machine-id` will lead to an error on boot.
To force the initial mount to be read-write, add the `rw` option to the kernel commandline.
To force the initial mount to be read-write, add the `rw` option to the kernel command line.
.. note:: Avoid inconsistent :file:`/var/lib/dbus/machine-id`
.. note:: Avoid inconsistent :file:`/var/lib/dbus/machine-id`.
:file:`/etc/machine-id` and :file:`/var/lib/dbus/machine-id`
**must** contain the same unique ID. On modern systems
:file:`/var/lib/dbus/machine-id`, there is already a symlink to
:file:`/etc/machine-id`. However, on older systems there might be two
different files. This is the case for SLE-12 based images. If you are
**must** contain the same unique ID. On modern systems,
:file:`/var/lib/dbus/machine-id` is already a symlink to
:file:`/etc/machine-id`. However, on older systems, there might be two
different files. This is the case for SLE-12-based images. If you are
targeting older operating systems, it is recommended to add the
symlink creation into :file:`config.sh`:

50
doc/source/concept_and_workflow/systemdeps.rst
View File

@ -3,9 +3,9 @@
Host Requirements To Build Images
---------------------------------
Building OS images requires several tools and sub-systems to be present on the
host {kiwi} host. For example, to build a virtual disk image, tools for
partition table setup or tools to create filesystems must to be available on the
Building OS images requires several tools and subsystems to be present on the
{kiwi} host. For example, to build a virtual disk image, tools for
partition table setup or tools to create filesystems must be available on the
host that builds the image.
The number of required components depends on the selected image type and the
@ -13,51 +13,51 @@ features used with the image. It's unreasonable to expect {kiwi} users to know
which exact components are needed to build the image. A mechanism called
`kiwi-systemdeps` is designed to handle the host requirements.
`kiwi-systemdeps` consists out of a collection of sub-packages provided with the
`kiwi-systemdeps` consists of a collection of sub-packages provided with the
`python-kiwi` main package. Each individual package requires a number of tools
and subsystem packages that belongs to the package category. There are the
and subsystem packages that belong to the package category. There are the
following systemdeps packages:
`kiwi-systemdeps-core`:
* Supports building the simple root archive `tbz` image type.
* Installs the package managers which are supported by the target distribution
* Installs the package managers that are supported by the target distribution,
as well as the `tar` archiving tool.
`kiwi-systemdeps-containers`:
* Supports building `OCI` image types used with `docker`, `podman`.
* Installs the distribution specific tool chain to build OCI
* Supports building `OCI` image types used with `docker` and `podman`.
* Installs the distribution-specific toolchain to build OCI-
compliant container images.
`kiwi-systemdeps-containers-wsl`:
* Supports building `appx` and `wsl` image types. The `wsl` type
is the successor for the former `appx` type
* Installs the distribution specific tool chain to build
WSL compliant container images on Windows systems.
is the successor to the former `appx` type.
* Installs the distribution-specific toolchain to build
WSL-compliant container images on Windows systems.
`kiwi-systemdeps-iso-media`:
* Supports building `iso` image types and `oem` install media.
* Installs all tools required to build ISO filesystems.
* Depends on the `-core`, `-filesystems` and `-bootloaders`
* Depends on the `-core`, `-filesystems`, and `-bootloaders`
kiwi-systemdeps packages.
`kiwi-systemdeps-bootloaders`:
* Supports building bootable `oem` and `iso` image types.
* Installs all bootloader tools depending on the host architecture
to allow setup and install of the bootloader. The pulled in
to allow setup and install of the bootloader. The pulled-in
components are required for any image that is able to boot
through some BIOS or firmware.
* Depends on the `-core` kiwi-systemdeps packages.
`kiwi-systemdeps-filesystems`:
* Supports building `fs-type`, `oem`, `pxe`,
`kis` and live `iso` image types.
`kis`, and live `iso` image types.
* Installs all tools to create filesystems supported by {kiwi}.
The pulled in components are needed for any image type that
The pulled-in components are needed for any image type that
needs to create a filesystem. This excludes the archive-based
image types like `docker`, `appx` or `tbz`. The package also
image types like `docker`, `appx`, or `tbz`. The package also
installs tools one level below the actual filesystem creation
toolkit. These are components to manage loop devices as well
as partition table setup and subsystem support like LVM and LUKS.
toolkit. These are components to manage loop devices, as well
as partition table setup and subsystem support, like LVM and LUKS.
* Depends on the `-core` kiwi-systemdeps packages.
`kiwi-systemdeps-disk-images`:
@ -71,18 +71,18 @@ following systemdeps packages:
* Installs the `jing` tool to validate the image description. This is
useful for detailed error reports from {kiwi} if an image
description validation error occurs. In addition, the `anymarkup` Python
module is installed if the the option to install recommended packages
module is installed if the option to install recommended packages
is set. With `anymarkup` available, {kiwi} can also handle image
descriptions in another format than the XML markup (for example,YAML).
descriptions in a format other than the XML markup (for example, YAML).
Depending on the image type the `kiwi-systemdeps`` packages can help
to quickly setup the host system for building images.
Depending on the image type, the `kiwi-systemdeps` packages can help
to quickly set up the host system for building images.
In case the host must support everything, there is also the
main `kiwi-systemdeps` package that has all other
existing systemdeps packages as its dependency.
existing `systemdeps` packages as its dependency.
.. note::
Pulling in all `kiwi-systemdeps` packages can result in a large number
packages installed on the host., because the required packages themselves
Pulling in all `kiwi-systemdeps` packages can result in a large number of
packages installed on the host because the required packages themselves
have other dependencies (for example, java for jing).

8
doc/source/concept_and_workflow/users.rst
View File

@ -22,10 +22,10 @@ supports a list of multiple `user` child elements:
</users>
</image>
Each `user` element represents a specific added or modified user.
Each `user` element represents a specific user to be added or modified.
The following attributes are mandatory:
- `name`: the UNIX username
- `name`: the UNIX username.
- `password`: The password for the user account. It can be provided either
in clear-text form (`pwdformat="plain"`) or in encrypted form
@ -40,12 +40,12 @@ The following attributes are mandatory:
Additionally, the following optional attributes can be specified:
- `home`: the path to the user's home directory
- `home`: The path to the user's home directory.
- `groups`: A comma-separated list of UNIX groups. The first element of the
list is used as the user's primary group. The remaining elements are
appended to the user's supplementary groups. When no groups are assigned,
the system's default primary group is be used.
the system's default primary group will be used.
- `id`: The numeric user ID of the account.

92
doc/source/contributing.rst
View File

@ -18,17 +18,17 @@ Contributing
The Basics
----------
The core appliance builder is developed in Python and follows the test
The core appliance builder is developed in Python and follows the test-
driven development rules.
If you want to implement a bigger feature, consider opening an issue on
GitHub first to discuss the changes. Or join the discussion in the
``#kiwi`` channel on `Riot.im <https://about.riot.im>`_.
GitHub first to discuss the changes. Or, join the discussion in the
`#kiwi` channel on `Riot.im <https://about.riot.im>`_.
Fork the upstream repository
----------------------------
1. On GitHub, navigate to: https://github.com/OSInside/kiwi
1. On GitHub, navigate to: https://github.com/OSInside/kiwi.
2. In the top-right corner of the page, click :command:`Fork`.
@ -44,8 +44,8 @@ Create a local clone of the forked repository
Install Required Operating System Packages
------------------------------------------
{kiwi} requires additional packages at runtime which are not
provided by :command:`pip`. Those will be pulled in by installing
{kiwi} requires additional packages at runtime that are not
provided by `pip`. Those will be pulled in by installing
the following package:
* kiwi-systemdeps
@ -54,14 +54,14 @@ The package is provided on the Open Build Service in the
`Virtualization:Appliances:Builder
<https://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder>`__
project. For manual inspection of the packages
that are pulled in from the above kiwi-systemdeps package, please refer
to the `package/python-kiwi-spec-template` spec file from the checked
that are pulled in from the above `kiwi-systemdeps` package, please refer
to the `package/python-kiwi-spec-template` spec file from the checked-
out Git repository.
Create a Python Virtual Development Environment
-----------------------------------------------
The following commands initializes and activates a development
The following commands initialize and activate a development
environment for Python 3:
.. code:: shell-session
@ -94,7 +94,7 @@ Create a Branch for each Feature or Bugfix
Code changes should be done in an extra Git branch. This allows for
creating GitHub pull requests in a clean way. See also: `Collaborating with
issues and pull requests
<https://help.github.com/en/categories/collaborating-with-issues-and-pull-requests>`_
<https://help.github.com/en/categories/collaborating-with-issues-and-pull-requests>`_.
.. code:: shell-session
@ -104,14 +104,14 @@ Make and commit your changes.
.. note::
You can make multiple commits which is generally useful to
You can make multiple commits, which is generally useful to
give your changes a clear structure and to allow us to better
review your work.
.. note::
Your work is important and must be signed to ensure the integrity of
the repository and the code. Thus we recommend to setup a signing key
the repository and the code. Thus, we recommend setting up a signing key
as documented in :ref:`Signing_Git_Patches`.
.. code:: shell-session
@ -125,7 +125,7 @@ create a pull request into the upstream repository.
$ git push origin my-topic-branch
Thank you much for contributing to {kiwi}. Your time and work effort is very
Thank you much for contributing to {kiwi}. Your time and work effort are very
much appreciated!
@ -135,10 +135,10 @@ Coding Style
{kiwi} follows the general PEP8 guidelines with the following exceptions:
- We do not use free functions at all. Even utility functions must be part
of a class, but should be either prefixed with the `@classmethod` or
of a class but should be either prefixed with the `@classmethod` or
`@staticmethod` decorators (whichever is more appropriate).
- Do not set module and class level variables, put these into the classes'
- Do not set module and class-level variables; put these into the class's
`__init__` method.
- The names of constants are not written in all capital letters.
@ -147,16 +147,16 @@ Documentation
~~~~~~~~~~~~~
{kiwi} uses `Sphinx <https://www.sphinx-doc.org/en/master/>`_ for the API,
user documentation and manual pages
user documentation, and man pages.
.. code:: shell-session
$ make docs
Document all your classes, methods, their parameters and their types using
Document all your classes, methods, their parameters, and their types using
the standard `reStructuredText
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_
syntax as supported by Sphinx, an example class is documented as follows:
syntax as supported by Sphinx. An example class is documented as follows:
.. code:: python
@ -165,7 +165,7 @@ syntax as supported by Sphinx, an example class is documented as follows:
**Example class**
:param str param: A parameter
:param bool : Source file name to compress
:param bool: Source file name to compress
:param list supported_zipper: List of supported compression tools
:attr Optional[str] attr: A class attribute
"""
@ -188,36 +188,36 @@ Try to stick to the following guidelines when documenting source code:
- Classes should be documented directly in their main docstring and not in
`__init__`.
- Document **every** function parameter and every public attribute
- Document **every** function parameter and every public attribute,
including their types.
- Only public methods should be documented, private methods don't have to,
- Only public methods should be documented; private methods don't have to be,
unless they are complex and it is not easy to grasp what they do (which
should be avoided anyway).
Please also document any user-facing changes that you implementing
(e.g. adding a new build type) in the user documentation, which can be
Please also document any user-facing changes that you are implementing
(e.g., adding a new build type) in the user documentation, which can be
found in `doc/source`. General documentation should be put into the
`working_with_kiwi/` subfolder, whereas documentation about more
specialized topics would belong into the `building/` subfolder.
specialized topics would belong in the `building/` subfolder.
Adhere to a line limit of 75 characters when writing the user facing
Adhere to a line limit of 75 characters when writing the user-facing
documentation [#f1]_.
Additional Information
----------------------
The following sections provides further information about the repository
integrity, version, package and documentation management.
The following sections provide further information about the repository
integrity, version, package, and documentation management.
.. _Signing_Git_Patches:
Signing Git Patches
~~~~~~~~~~~~~~~~~~~
To ensure the integrity of the repository and the code base, patches sent
To ensure the integrity of the repository and the codebase, patches sent
for inclusion should be signed with a GPG key.
To prepare Git to sign commits, follow these instructions:
@ -229,14 +229,14 @@ To prepare Git to sign commits, follow these instructions:
$ gpg2 --expert --full-gen-key
#. Either choose a RSA key for signing (option `(4)`) or an ECC key for
signing (option `(10)`). For a RSA key choose a key size of 4096 bits
and for a ECC key choose Curve 25519 (option `(1)`). Enter a reasonable
#. Either choose an RSA key for signing (option `(4)`) or an ECC key for
signing (option `(10)`). For an RSA key, choose a key size of 4096 bits,
and for an ECC key, choose Curve 25519 (option `(1)`). Enter a reasonable
validity period (we recommend 2 to 5 years). Complete the key generation
by entering your name and email address.
#. Add the key ID to your git configuration, by running the following
#. Add the key ID to your git configuration by running the following
:command:`git config` commands:
.. code:: shell-session
@ -244,7 +244,7 @@ To prepare Git to sign commits, follow these instructions:
$ git config --local user.signingkey $YOUR_SIGN_KEY_ID
$ git config --local commit.gpgSign true
Omitting the flag `--local` will make these settings global for all
Omitting the `--local` flag will make these settings global for all
repositories (they will be added to :file:`~/.gitconfig`). You can find
your signkey's ID via:
@ -256,7 +256,7 @@ To prepare Git to sign commits, follow these instructions:
uid [ultimate] YOU <$YOUR_EMAIL>
The key's ID in this case would be `AABBCCDDEEFF0011`. Note that your
signkey will have only a `[S]` after the creation date, not a `[SC]`
sign key will have only a `[S]` after the creation date, not a `[SC]`
(then you are looking at your ordinary GPG key that can also encrypt).
@ -267,16 +267,16 @@ The {kiwi} project follows the `Semantic Versioning <https://semver.org>`_
scheme. We use the :command:`bumpversion` tool for consistent versioning.
Follow these instructions to bump the major, minor, or patch part of the
{kiwi} version. Ensure that your repository is clean (i.e. no modified and
unknown files exist) beforehand running :command:`bumpversion`.
{kiwi} version. Ensure that your repository is clean (i.e., no modified and
unknown files exist) before running :command:`bumpversion`.
* For backwards-compatible bug fixes:
* For backward-compatible bug fixes:
.. code:: shell-session
$ bumpversion patch
* For additional functionality in a backwards-compatible manner. When
* For additional functionality in a backward-compatible manner. When
changed, the patch level is reset to zero:
.. code:: shell-session
@ -290,31 +290,31 @@ unknown files exist) beforehand running :command:`bumpversion`.
$ bumpversion major
Creating a RPM Package
~~~~~~~~~~~~~~~~~~~~~~
Creating an RPM Package
~~~~~~~~~~~~~~~~~~~~~~~
We provide a template for a RPM spec file in
:file:`package/python-kiwi-spec-template` alongside with a rpmlint
We provide a template for an RPM spec file in
:file:`package/python-kiwi-spec-template` alongside a `rpmlint`
configuration file and an automatically updated
:file:`python-kiwi.changes`.
To create the necessary files to build a RPM package via `rpmbuild`, run:
To create the necessary files to build an RPM package via `rpmbuild`, run:
.. code:: shell-session
$ make build
The sources are collected in the :file:`dist/` directory. These can be
directly build it with :command:`rpmbuild`, :command:`fedpkg`, or submitted
directly built with :command:`rpmbuild`, :command:`fedpkg`, or submitted
to the Open Build Service using :command:`osc`.
.. [#f1] Configure your editor to automatically break lines and/or reformat
paragraphs. For Emacs you can use `M-x set-fill-column RET 75` and
paragraphs. For Emacs, you can use `M-x set-fill-column RET 75` and
`M-x auto-fill-mode RET` for automatic filling of paragraphs in
conjunction with `M-x fill-paragraph` (usually bound to `M-q`) to
reformat a paragraph to adhere to the current column width. For
editing reStructuredText we recommend `rst-mode` (built-in to
editing reStructuredText, we recommend `rst-mode` (built into
Emacs since version `23.1`).
Vim users can set the text width via `:tw 75` and then use the
commands `gwip` or `gq`.

14
doc/source/contributing/kiwi_from_python.rst
View File

@ -5,12 +5,12 @@ Using {kiwi} in a Python Project
{kiwi} is provided as a Python module under the **kiwi** namespace.
It is available for the Python 3 version. The following
description applies for {kiwi} version |version|.
description applies to {kiwi} version |version|.
{kiwi} can also function as a module for other Python projects.
The following example demonstrates how to read an existing image
description, add a new repository definition, and export the
modified description on stdout.
modified description on stdout:
.. code:: python
@ -39,15 +39,15 @@ modified description on stdout.
outfile=sys.stdout, level=0
)
Each class in the example is responsible for a single tasks, so they can be
reused in other user cases. Therefore it is possible to use {kiwi} beyond the
main image building scope, for example to manage setup of loop devices,
Each class in the example is responsible for a single task, so they can be
reused in other use cases. Therefore, it is possible to use {kiwi} beyond the
main image building scope, for example, to manage the setup of loop devices,
filesystems, partitions, etc.
This means {kiwi} offers a way to describe a system, but you can choose whether
you want to use the {kiwi} description format or not. The following example
shows how to use {kiwi} to create a simple filesystem image which contains your
host `tmp` directory.
shows how to use {kiwi} to create a simple filesystem image that contains your
host's `tmp` directory.
.. code:: python

30
doc/source/contributing/kiwi_plugin_architecture.rst
View File

@ -11,21 +11,21 @@ Naming conventions
Task plugin file name
The file name of a task plugin must follow the pattern
:file:`<service>_<command>.py`. This allows you to invoke the task
with :command:`kiwi-ng service command ...`
with :command:`kiwi-ng service command ...`.
Task plugin option handling
{kiwi} uses the docopt module to handle options. Each task plugin
must use docopt to allow option handling.
{kiwi} uses the `docopt` module to handle options. Each task plugin
must use `docopt` to allow option handling.
Task plugin class
The implementation of the plugin must be a class that matches the naming
convention :class:`<Service><Command>Task`. The class must inherit from the
:class:`CliTask` base class. On the plugin startup, {kiwi} expects an
implementation of the :file:`process` method.
convention `<Service><Command>Task`. The class must inherit from the
:class:`CliTask` base class. On plugin startup, {kiwi} expects an
implementation of the `process` method.
Task plugin entry point
Registration of the plugin must be done in :file:`pyproject.toml`
using the ``tool.poetry.plugins`` concept.
using the `tool.poetry.plugins` concept.
.. code:: python
@ -49,7 +49,7 @@ Example plugin
which was set up using poetry and pyproject.toml.
1. Assuming the project namespace is **kiwi_relax_plugin**, create the task
plugin directory :file:`kiwi_relax_plugin/tasks`
plugin directory :file:`kiwi_relax_plugin/tasks`.
2. Create the entry point in :command:`pyproject.toml`.
@ -86,12 +86,12 @@ Example plugin
options:
--now
right now. For more details about docopt
right now. For more details about docopt,
see: http://docopt.org
"""
# These imports requires kiwi to be part of your environment
# These imports require kiwi to be part of your environment.
# It can be either installed from pip into a virtual development
# environment or from the distribution package manager
# environment or from the distribution package manager.
from kiwi.tasks.base import CliTask
from kiwi.help import Help
@ -100,16 +100,16 @@ Example plugin
self.manual = Help()
if self.command_args.get('help') is True:
# The following will invoke man to show the man page
# for the requested command. Thus for the call to
# succeed a manual page needs to be written and
# installed by the plugin
# for the requested command. Thus, for the call to
# succeed, a man page needs to be written and
# installed by the plugin.
return self.manual.show('kiwi::relax::justdoit')
print(
'https://genius.com/Frankie-goes-to-hollywood-relax-lyrics'
)
4. Test the plugin
4. Test the plugin.
.. code:: bash

34
doc/source/contributing/schema_extensions.rst
View File

@ -14,10 +14,10 @@ Extending {kiwi} with Custom Operations
is no other plugin interface except for providing additional {kiwi} commands.
Depending on the demand for custom plugins, the interface
to hook in code into other parts of the {kiwi} processing
to hook into code in other parts of the {kiwi} processing
needs to be extended.
This description applies for version |version|.
This description applies to version |version|.
The <extension> Section
-----------------------
@ -25,7 +25,7 @@ The <extension> Section
The main {kiwi} schema supports an extension section that allows you
to specify any XML structure and attributes, as long as they are
attached to a namespace. This means that any custom XML
structure can be implemented similar to the the example below:
structure can be implemented similar to the example below:
.. code:: bash
@ -38,20 +38,20 @@ structure can be implemented similar to the the example below:
</extension>
</image>
* Any toplevel namespace must be unique
* Multiple different toplevel namespaces are allowed,
for example: my_plugin_a, my_plugin_b
* Any top-level namespace must be unique.
* Multiple different top-level namespaces are allowed,
for example, `my_plugin_a`, `my_plugin_b`.
RELAX NG Schema for the Extension
---------------------------------
If an extension section is found, {kiwi} looks up its namespace and uses
the main XML catalog for the schema file to validate the extension data.
The schema file must be a RELAX NG schema in the .rng format. We recommend
to save the schema as :file:`/usr/share/xml/kiwi/my_plugin.rng`
The schema file must be a RELAX NG schema in the `.rng` format. We recommend
saving the schema as :file:`/usr/share/xml/kiwi/my_plugin.rng`.
For the example above, the RELAX NG Schema in the compressed format
:file:`my_plugin.rnc` looks as follows:
For the example above, the RELAX NG Schema in the compressed format,
:file:`my_plugin.rnc`, looks as follows:
.. there is no rnc syntax highlighting, try cpp
.. code:: cpp
@ -80,7 +80,7 @@ For the example above, the RELAX NG Schema in the compressed format
}
}
In order to convert this schema to the .rng format just call:
To convert this schema to the `.rng` format, just call:
.. code:: bash
@ -90,7 +90,7 @@ Extension schema in XML catalog
-------------------------------
As mentioned above, the mapping from the extension namespace to the
correct RELAX NG schema file is handled by a XML catalog file. The
correct RELAX NG schema file is handled by an XML catalog file. The
XML catalog for the example is as follows:
.. code:: bash
@ -102,8 +102,8 @@ XML catalog for the example is as follows:
uri="file:////usr/share/xml/kiwi/my_plugin.rng"/>
</catalog>
For resolving the catalog, {kiwi} uses the :command:`xmlcatalog` command
and the main XML catalog from the system :file:`/etc/xml/catalog`.
For resolving the catalog, {kiwi} uses the `xmlcatalog` command
and the main XML catalog from the system, :file:`/etc/xml/catalog`.
.. note::
@ -111,7 +111,7 @@ and the main XML catalog from the system :file:`/etc/xml/catalog`.
catalog file depends on the distribution and its version. Refer to the
distribution documentation for information on adding XML catalogs.
If the following command provides the information to the correct
If the following command provides the information for the correct
RELAX NG schema file, you are ready for a first test:
.. code:: bash
@ -121,11 +121,11 @@ RELAX NG schema file, you are ready for a first test:
Using the extension
-------------------
In order to test the extension, insert the example extension into one of your
To test the extension, insert the example extension into one of your
image description's :file:`config.xml` file.
The following example reads the name attribute from the title
section of the my_feature root element and prints it:
section of the `my_feature` root element and prints it:
.. code:: python

26
doc/source/contributing/scripts_testing.rst
View File

@ -6,10 +6,10 @@ also: :ref:`working-with-kiwi-user-defined-scripts`). These functions utilize co
to run the individual tasks and verify the final result.
Ensure that you have either :command:`podman` or :command:`docker` installed and
configured on your system. With Podman, the integration tests use :command:`podman` in
configured on your system. With Podman, the integration tests use `podman` in
**rootless mode** by default. You can select
:command:`docker` instead by setting the environment variable
``CONTAINER_RUNTIME`` to ``docker``. Then you can run the integration tests via
``CONTAINER_RUNTIME`` to ``docker``. Then, you can run the integration tests via
the `test_scripts` Makefile target:
.. code:: shell-session
@ -20,7 +20,7 @@ the `test_scripts` Makefile target:
The tests are written using the `pytest-container
<https://github.com/dcermak/pytest_container>`__ plugin. If applicable,
use the utility functions and fixtures of the plugin. For example, the
``auto_container`` and ``auto_container_per_test`` fixtures in conjunction with
`auto_container` and `auto_container_per_test` fixtures in conjunction with
`testinfra <https://testinfra.readthedocs.io/>`__.
@ -28,15 +28,15 @@ Test setup
~~~~~~~~~~
The script tests can be run inside different containers specified in
:file:`test/scripts/conftest.py`. This file contains the ``CONTAINERS`` list
:file:`test/scripts/conftest.py`. This file contains the `CONTAINERS` list
with all currently present images. These images are pulled and built as needed,
and the :file:`functions.sh` is copied into :file:`/bin/`, so it is
available in ``PATH``.
and the :file:`functions.sh` is copied into `/bin/`, so it is
available in `PATH`.
To use any of these containers, you can either define the global variable
``CONTAINER_IMAGES`` in a test module and use the ``auto_container`` fixture, or
`CONTAINER_IMAGES` in a test module and use the `auto_container` fixture, or
`parametrize <https://docs.pytest.org/en/stable/parametrize.html>`__ the
``container`` fixture indirectly:
`container` fixture indirectly:
.. code:: python
@ -53,12 +53,12 @@ To use any of these containers, you can either define the global variable
assert not container_per_test.connection.file("/root/foobar").exists
The example above uses the ``_per_test`` variant of the ``container`` fixture.
The example above uses the `_per_test` variant of the `container` fixture.
It ensures that the container is used only in a single test function. Use this
variant for tests that mutate the system under test, because otherwise it may
lead race conditions that are difficult to debug. For tests that only perform
reads, you can omit the ``_per_test`` suffix, so that the container environment can
shared with other tests. This improves execution speed, but comes at the
variant for tests that mutate the system under test because otherwise, it may
lead to race conditions that are difficult to debug. For tests that only perform
reads, you can omit the `_per_test` suffix so that the container environment can be
shared with other tests. This improves execution speed but comes at the
expense of safety in case of mutation.
For further information, refer to `pytest-container

34
doc/source/image_description.rst
View File

@ -5,8 +5,8 @@ Image Description
.. note::
This document explains the toplevel structure of the
{kiwi} image description document for version |version|
This document explains the top-level structure of the
{kiwi} image description document for version |version|.
.. toctree::
:maxdepth: 1
@ -33,9 +33,9 @@ Image Identity
<description/>
The mandatory :ref:`sec.description` element contains information about the author,
contact, license and the specification about the use case of this
contact, license, and the specification about the use case of this
image. All data together forms the identity card of the image.
There can be only one `description` element
There can be only one `description` element.
Image Preferences
-----------------
@ -46,8 +46,8 @@ Image Preferences
The mandatory :ref:`sec.preferences` element contains information to classify
the image and to describe the layout. All data about the image type, its
version, the partition layout and much more is specified here. There can be
multiple `preferences` elements
version, the partition layout, and much more is specified here. There can be
multiple `preferences` elements.
Image Software Sources
----------------------
@ -56,9 +56,9 @@ Image Software Sources
<repository/>
The mandatory :ref:`sec.repository` element contains information where to find the
The mandatory :ref:`sec.repository` element contains information on where to find the
software packages that are used to build the image. There can be
multiple `repository` elements
multiple `repository` elements.
Image Content Setup
-------------------
@ -70,8 +70,8 @@ Image Content Setup
The mandatory :ref:`sec.packages` element contains information to list which
software should be installed from the configured repositories
into the image. Software can be defined as names for packages,
collections, archives or products. There can be multiple
`packages` elements
collections, archives, or products. There can be multiple
`packages` elements.
Image Users
-----------
@ -81,8 +81,8 @@ Image Users
<users/>
The optional :ref:`sec.users` element contains information about system users
to be created inside of the image. There can be multiple `users`
elements
to be created inside the image. There can be multiple `users`
elements.
Image Namespace
---------------
@ -92,9 +92,9 @@ Image Namespace
<profiles/>
The optional :ref:`sec.profiles` element contains information to create one
or more namespaces to an image description. The namespace can be
or more namespaces for an image description. The namespace can be
used with any of the above elements and therefore tie them into
a namespace which can be selected at call time of {kiwi}
a namespace that can be selected at call time of {kiwi}.
Image Includes
--------------
@ -103,8 +103,8 @@ Image Includes
<include from="file://filename.xml"/>
The optional :ref:`sec.include` element allows to drop in the contents
of the specified :file:`filename.xml` file at the place were the `include`
The optional :ref:`sec.include` element allows you to drop in the contents
of the specified :file:`filename.xml` file at the place where the `include`
statement was specified in the document. The `include` statement is
only allowed as descendant of the root (top-level element) of the
only allowed as a descendant of the root (top-level element) of the
image description.

1040
doc/source/image_description/elements.rst
View File

File diff suppressed because it is too large Load Diff

152
doc/source/image_types_and_results.rst
View File

@ -5,116 +5,116 @@ Image Types
.. note::
Before building an image with {kiwi} it's important to understand
Before building an image with {kiwi}, it's important to understand
the different image types and their meaning. This document provides
an overview about the supported {kiwi} image types, their results
an overview of the supported {kiwi} image types, their results,
and some words about the environment to run the build.
ISO Hybrid Live Image
An iso image which can be dumped on a CD/DVD or USB stick
and boots off from this media without interfering with other
system storage components. A useful pocket system for testing
and demo and debugging purposes. For further details refer
to :ref:`hybrid_iso`
An ISO image that can be dumped on a CD/DVD or USB stick
and boots from this media without interfering with other
system storage components. A useful pocket system for testing,
demo, and debugging purposes. For further details, refer
to :ref:`hybrid_iso`.
Virtual Disk Image
An image representing the system disk, useful for cloud frameworks
like Amazon EC2, Google Compute Engine or Microsoft Azure.
For further details refer to :ref:`simple_disk`
like Amazon EC2, Google Compute Engine, or Microsoft Azure.
For further details, refer to :ref:`simple_disk`.
OEM Expandable Disk Image
An image representing an expandable system disk. This means after
deployment the system can resize itself to the new disk geometry.
The resize operation is configurable as part of the image description
and an installation image for CD/DVD, USB stick and Network deployment
can be created in addition. For further details refer to:
:ref:`expandable_disk`
deployment, the system can resize itself to the new disk geometry.
The resize operation is configurable as part of the image description,
and an installation image for CD/DVD, USB stick, and network deployment
can be created in addition. For further details, refer to:
:ref:`expandable_disk`.
Docker Container Image
An archive image suitable for the docker container engine.
An archive image suitable for the Docker container engine.
The image can be loaded via the `docker load` command and
works within the scope of the container engine.
For further details refer to: :ref:`building_container_build`
For further details, refer to: :ref:`building_container_build`.
WSL Container Image
An archive image suitable for the Windows Subsystem For Linux
container engine. The image can be loaded From a Windows System
that has support for WSL activated. For further details refer
to: :ref:`building_wsl_build`
An archive image suitable for the Windows Subsystem for Linux
container engine. The image can be loaded from a Windows System
that has support for WSL activated. For further details, refer
to: :ref:`building_wsl_build`.
KIS Root File System Image
KIS Root Filesystem Image
An optional root filesystem image associated with a kernel and initrd.
The use case for this component image type is highly customizable.
Many different deployment strategies are possible.
For further details refer to: :ref:`kis`
For further details, refer to: :ref:`kis`.
AWS Nitro Enclave
An initrd based image using the `eif` binary format. The image is
An initrd-based image using the `eif` binary format. The image is
expected to be used in the AWS Nitro Enclave system or for testing
in QEMU. For further details refer to: :ref:`eif`
in QEMU. For further details, refer to: :ref:`eif`.
Image Results
-------------
{kiwi} execution results in an appliance image after a successful run of
:ref:`kiwi_system_build` or :ref:`kiwi_system_create` command.
the :ref:`kiwi_system_build` or :ref:`kiwi_system_create` command.
The result is the image binary plus some additional metadata files
which are needed for image deployment and/or exists for informative
reasons. By default the output files follow this naming convention:
that are needed for image deployment and/or exist for informative
reasons. By default, the output files follow this naming convention:
`<image-name>.\<arch\>-\<version\>.\<extension\>`
where `<image-name>` is the name stated in the :ref:`image-description` as an
attribute of the :ref:`sec.image` element. The `<arch>` is the CPU
architecture used for the build, `<version>` is the image version defined in
:ref:`\<version\><sec.preferences>` element of the image description
the :ref:`<version><sec.preferences>` element of the image description,
and the `<extension>` is dependent on the image type and its definition.
Any {kiwi} appliance build results in, at least, the following output files:
1. The image binary, `<image-name>.\<arch\>-\<version\>.\<image-extension\>`:
This is the file containig the actual image binary, depending
on the image type and its definition it can be a virtual disk image
This is the file containing the actual image binary. Depending
on the image type and its definition, it can be a virtual disk image
file, an ISO image, a tarball, etc.
2. The `<image-name>.<arch>-<version>.packages` file:
This file includes a sorted list of the packages
that are included into the image. In fact this is normalized dump of the
package manager database. It follows the following cvs format where each
that are included in the image. In fact, this is a normalized dump of the
package manager database. It follows the following CSV format, where each
line is represented by:
`<name>|\<epoch\>|\<version\>|\<release\>|\<arch\>|\<disturl\>|\<license\>`
The values represented here are mainly based on RPM packages metadata.
Other package managers may not provide all of these values, in such cases
the format is the same and the fields that cannot be provided are set as
`None` value. This list can be used to track changes across multiple
The values represented here are mainly based on RPM packages' metadata.
Other package managers may not provide all of these values. In such cases,
the format is the same, and the fields that cannot be provided are set as
`None`. This list can be used to track changes across multiple
builds of the same image description over time by diffing the
packages installed.
3. The `<image-name>.<arch>-<version>.verified` file:
This file is the output of a verification done by the package manager
against the package data base. More specific it is the output of
the :command:`rpm` verification process or :command:`dpkg` verification
against the package database. More specifically, it is the output of
the `rpm` verification process or `dpkg` verification,
depending on the packaging technology selected for the image.
In both cases the output follows the RPM verification syntax. This
provides an overview of all packages status right before any boot of
In both cases, the output follows the RPM verification syntax. This
provides an overview of all package statuses right before any boot of
the image.
Depending on the image type, the following output files exists:
Depending on the image type, the following output files exist:
image="tbz"
For this image type the result is mainly a root tree packed in a tarball:
For this image type, the result is mainly a root tree packed in a tarball:
- **root archive**:
:file:`{exc_image_base_name}.x86_64-{exc_image_version}.tar.xz`
image="btrfs|ext2|ext3|ext4|squashfs|xfs"
The image root tree data is packed into a filesystem image of the given
type, hence the resutl for an `ext4` image would be:
type; hence, the result for an `ext4` image would be:
- **filesystem image**:
:file:`{exc_image_base_name}.x86_64-{exc_image_version}.ext4`
@ -128,9 +128,9 @@ image="iso"
image="oem"
An image representing an expandable disk image. {kiwi} can also produce an
installation ISO for this disk image by setting `installiso="true"` in
the :ref:`\<preferences\>\<type\><sec.preferences>`) section or a tarball
including the artifacts for a network deployment by setting `installpxe="true"`.
For further details see :ref:`expandable_disk`. The results for `oem`
the :ref:`\<preferences\>\<type\><sec.preferences>`) section or a tarball,
including the artifacts for a network deployment, by setting `installpxe="true"`.
For further details, see :ref:`expandable_disk`. The results for `oem`
can be:
- **disk image**:
@ -141,9 +141,9 @@ image="oem"
:file:`{exc_image_base_name}.x86_64-{exc_image_version}.install.tar`
The disk image can also be provided in one of the various virtual disk
formats which can be specified in `format` attribute of the
formats, which can be specified in the `format` attribute of the
:ref:`\<preferences\>\<type\><sec.preferences>` section. For further
details see :ref:`simple_disk`. The result for e.g `format="qcow2"`
details, see :ref:`simple_disk`. The result for e.g., `format="qcow2"`
would be:
- **disk image**:
@ -152,8 +152,8 @@ image="oem"
instead of the `.raw` default disk format.
image="docker"
An archive image suitable for the docker container engine. The result is
a loadable (:command:`docker load -i <image>`) tarball:
An archive image suitable for the Docker container engine. The result is
a loadable (`docker load -i <image>`) tarball:
- **container**:
:file:`{exc_image_base_name}.x86_64-{exc_image_version}.docker.tar.xz`
@ -167,15 +167,15 @@ image="oci"
:file:`{exc_image_base_name}.x86_64-{exc_image_version}.oci.tar.xz`
image="appx"
An archive image suitable for the Windows Subsystem For Linux
An archive image suitable for the Windows Subsystem for Linux
container engine. The result is an `appx` binary file:
- **container**:
:file:`{exc_image_base_name}.x86_64-{exc_image_version}.appx`
image="wsl"
An archive image suitable for the Windows Subsystem For Linux
container engine >= v2.4.4. The result is a gzip compressed tar
An archive image suitable for the Windows Subsystem for Linux
container engine >= v2.4.4. The result is a gzip-compressed tar
archive with the `.wsl` extension:
- **container**:
@ -183,7 +183,7 @@ image="wsl"
image="kis"
An optional root filesystem image associated with a kernel and initrd.
All three binaries are packed in a tarball, see :ref:`kis` for further
All three binaries are packed in a tarball. See :ref:`kis` for further
details about the kis archive:
- **kis archive**:
@ -194,7 +194,7 @@ Image Bundle Format
The result files as mentioned above are used in the {kiwi} result bundler.
The `kiwi-ng result bundle` command can be used to copy or package the
mandatory image files to create a customer release. In this process it's
mandatory image files to create a customer release. In this process, it's
possible to apply a specific name pattern suitable for the requirements
of the release. A typical result bundle call can look like the following:
@ -204,19 +204,19 @@ of the release. A typical result bundle call can look like the following:
--bundle-dir=/path/to/image/release_result \
--id=release_identifier
In this call and depending on the image type the required files as they
In this call, and depending on the image type, the required files as they
exist in :file:`/path/to/image/build_result` are copied to
:file:`/path/to/image/release_result/`. The only modification on the file
names is the `--id` information which is appended with a `-` to at the
:file:`/path/to/image/release_result/`. The only modification to the file
names is the `--id` information, which is appended with a `-` at the
end of the version substring. If we take
:file:`{exc_image_base_name}.x86_64-{exc_image_version}.iso` as example.
:file:`{exc_image_base_name}.x86_64-{exc_image_version}.iso` as an example.
This file would be bundled as
:file:`{exc_image_base_name}.x86_64-{exc_image_version}-release_identifier.iso`
:file:`{exc_image_base_name}.x86_64-{exc_image_version}-release_identifier.iso`.
Depending on the use case and the customer requirements this naming
schema and the default way how the kiwi bundler processes the result files
Depending on the use case and the customer requirements, this naming
schema and the default way the kiwi bundler processes the result files
is not appropriate. To allow for a more flexible naming schema when
bundling results, {kiwi} allows to specify a bundle_format per type like
bundling results, {kiwi} allows you to specify a bundle_format per type, like
in the following example:
.. code:: xml
@ -226,38 +226,38 @@ in the following example:
</type>
The specified `name_pattern` is used as the base name for the image
files the bundler uses. As part of the `name_pattern` the following
placeholders which gets replaced by their real value can be used:
files the bundler uses. As part of the `name_pattern`, the following
placeholders, which are replaced by their real value, can be used:
%N
Turns into the contents of the `name` attribute of the `<image>` section
Turns into the contents of the `name` attribute of the `<image>` section.
%P
Turns into the profile name used at build time of the image.
If multiple profiles were used to build the image the result
name consists out of the individual profile names concatenated
If multiple profiles were used to build the image, the result
name consists of the individual profile names concatenated
by a `_` in the order of their specification in the image
description and/or the commandline.
description and/or the command line.
%A
Turns into the architecture name at build time of the image.
Arch names are taken from Python's `platform.machine` information.
%I
Turns into the identifier name given via the `--id` option at
call time of the bundler
Turns into the identifier name given via the `--id` option at the
call time of the bundler.
%T
Turns into the contents of the `image` attribute of the `<type>` section
Turns into the contents of the `image` attribute of the `<type>` section.
%M
Turns into the major number of the `<version>` section
Turns into the major number of the `<version>` section.
%m
Turns into the minor number of the `<version>` section
Turns into the minor number of the `<version>` section.
%p
Turns into the patch number of the `<version>` section
Turns into the patch number of the `<version>` section.
%v
Turns into the version text of the `<version>` section
Turns into the version text of the `<version>` section.

44
doc/source/index.rst
View File

@ -4,7 +4,7 @@ Building Linux System Appliances
================================
.. note::
This documentation covers {kiwi-product} |version|- the command line
This documentation covers {kiwi-product} |version| - the command-line
utility to build Linux system appliances. If you are using a {kiwi}
schema version older than v74, upgrade the kiwi file as follows:
@ -60,19 +60,19 @@ Building Linux System Appliances
The Appliance Concept
---------------------
An appliance is a ready to use image of an operating system including
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
provided as an image file and needs to be deployed to or activated in
the target system or service.
{kiwi} can create appliances in various forms: beside classical installation
ISOs and images for virtual machines it can also build images that boot via
{kiwi} can create appliances in various forms: besides classical installation
ISOs and images for virtual machines, it can also build images that boot via
PXE or Vagrant boxes.
In {kiwi}, the appliance is specified via a collection of human readable files
in a directory, also called the `image description`. At least one XML file
:file:`config.xml` or :file:`.kiwi` is required. In addition there may as
well be other files like scripts or configuration data.
In {kiwi}, the appliance is specified via a collection of human-readable files
in a directory, also called the `image description`. At least one XML file,
:file:`config.xml` or :file:`.kiwi`, is required. In addition, there may as
well be other files, like scripts or configuration data.
Use Cases
---------
@ -89,30 +89,30 @@ Private and Public Clouds
Custom Linux Distribution
Linux distributors provide their distribution based on a collection
of packages and release them on an install media like a DVD or an USB
stick. Typically a lot more software components exists for the
distribution which are not part of the default installation media
of packages and release them on an install medium like a DVD or a USB
stick. Typically, a lot more software components exist for the
distribution that are not part of the default installation media,
or the installation media comes with software and installation
routines that are not matching your target audience. With an
appliance made by {kiwi} you can create an installation
media that matches custom criteria as needed by the customer
and does not require extra post processing steps after the
routines that do not match your target audience. With an
appliance made by {kiwi}, you can create an installation
medium that matches custom criteria as needed by the customer
and does not require extra post-processing steps after the
default installation method provided by the distributor.
Live Systems
The ability to have a Linux OS that runs from a small storage
device like a USB stick or a SD card is the swiss army knife of many
system administrators. The creation of such a live system includes
device like a USB stick or an SD card is the Swiss army knife of many
system administrators. The creation of such a live system includes the
use of technologies that are not part of a standard installation
process. An appliance builder is needed to create this sort of
system.
Embedded Systems
Embedded Systems like the Raspberry Pi come with limited hardware
Embedded systems like the Raspberry Pi come with limited hardware
components. Their boot sequences often do not allow for classic
installation methods through USB or DVD devices. Instead they boot
installation methods through USB or DVD devices. Instead, they boot
through SD card slots or via the network. SoC (System on Chip) devices
also tend to implement non standard boot methods which can only
also tend to implement non-standard boot methods that can only
be implemented through custom OS appliances.
And More
@ -125,7 +125,7 @@ Contact
* `Mailing list <https://groups.google.com/forum/#!forum/kiwi-images>`__
The `kiwi-images` group is an open group and anyone can
The `kiwi-images` group is an open group, and anyone can
`subscribe <mailto:kiwi-images+subscribe@googlegroups.com>`__,
even if you do not have a Google account.

42
doc/source/installation.rst
View File

@ -7,9 +7,9 @@ Installation
This document describes how to install {kiwi}.
Apart from the preferred method to install {kiwi} via a distribution
Apart from the preferred method of installing {kiwi} via a distribution
package manager, it is also available on `pypi <https://pypi.org/project/kiwi/>`__
and can be installed using Python's package manager pip as follows:
and can be installed using Python's package manager, pip, as follows:
.. code:: shell-session
@ -20,7 +20,7 @@ and can be installed using Python's package manager pip as follows:
Installation from OBS
---------------------
The most up to date packages of {kiwi} can be found on the Open Build Service
The most up-to-date packages of {kiwi} can be found on the Open Build Service
in the `Virtualization:Appliances:Builder
<https://download.opensuse.org/repositories/Virtualization:/Appliances:/Builder>`__
project.
@ -31,9 +31,9 @@ To install {kiwi}, follow these steps:
in your browser.
2. Right-click on the link of your preferred operating system and
copy the URL. In Firefox it is the menu :menuselection:`Copy link address`.
copy the URL. In Firefox, it is the menu :menuselection:`Copy link address`.
3. Insert the copied URL from the last step into your shell. The ``DIST``
3. Insert the copied URL from the last step into your shell. The `DIST`
placeholder contains the respective distribution.
Use :command:`zypper addrepo` to add it to the list of your repositories:
@ -52,8 +52,8 @@ To install {kiwi}, follow these steps:
.. note:: Other Distributions
If your distribution is not using :command:`zypper`, please use your
package manager's appropriate command instead. For :command:`dnf`,
If your distribution is not using `zypper`, please use your
package manager's appropriate command instead. For `dnf`,
as an example, that is:
.. code:: shell-session
@ -68,19 +68,19 @@ Installation from Distribution Repositories
-------------------------------------------
Some Linux distributions ship {kiwi} in their official repositories. These
include **openSUSE** and **Fedora** since version 28. Note, these packages tend to
not be as up to date as the packages from OBS, so some features described
include **openSUSE** and **Fedora** since version 28. Note that these packages tend
not to be as up-to-date as the packages from OBS, so some features described
here might not exist yet.
.. note::
There are many packages that contain the name *kiwi* in their name, some
of these are not even python packages. Please double check the packages'
description whether it is actually the {kiwi} Appliance builder before
installing it. Please also note, depending on how the responsible
There are many packages that contain the name *kiwi* in their name; some
of these are not even Python packages. Please double-check the package's
description to see whether it is actually the {kiwi} Appliance builder before
installing it. Please also note that, depending on how the responsible
packager has integrated {kiwi} into the distribution, the install
name can be different from the instructions provided in:
:ref:`installation-from-obs`
:ref:`installation-from-obs`.
To install {kiwi} for the desired distribution, run the following command:
@ -100,7 +100,7 @@ Installation for SUSE Linux Enterprise
--------------------------------------
{kiwi} is available and supported for SUSE Linux Enterprise (SLE).
The recommended and supported way is to install {kiwi} by using zypper.
The recommended and supported way is to install {kiwi} by using `zypper`.
However, if you rely on some plugins for {kiwi}, either the plugin
itself or any dependencies might not be available for your service pack.
@ -108,8 +108,8 @@ itself or any dependencies might not be available for your service pack.
If you want to proceed anyway, keep these things in mind:
* Plugins that are not provided by SLE are not supported.
* You probably need to install dependencies via :command:`pip`.
The :command:`pip` command installs these dependencies from PyPI
* You will probably need to install dependencies via `pip`.
The `pip` command installs these dependencies from PyPI
(the Python Package Index).
However, this approach will not update the RPM database.
* Depending on your security concerns, installing Python packages
@ -129,8 +129,8 @@ There are two places for example appliance descriptions:
The {kiwi} build tests:
The {kiwi} project itself hosts a collection of appliance descriptions
which are used for integration testing of the {kiwi} builder itself.
These descriptions are required to build prior any {kiwi} release
that are used for integration testing of the {kiwi} builder itself.
These descriptions are required to build prior to any {kiwi} release
and are also used as the base for this documentation. Please check
them out when working with this reference guide:
@ -142,8 +142,8 @@ The {kiwi} build tests:
The {kiwi} community descriptions project:
There is a GitHub project hosting example appliance descriptions to be used
with the next generation {kiwi}. Contributions from the community makes up
the contents of this repository and users who need an example for a specific
with the next-generation {kiwi}. Contributions from the community make up
the contents of this repository, and users who need an example for a specific
use case and distribution can clone the project as follows:
.. code:: shell-session

34
doc/source/integration_testing.rst
View File

@ -3,7 +3,7 @@ Building Build Tests
{kiwi} provides a collection of integration test images for
different architectures and distributions. The test descriptions
covers a number of appliance features that can be build with {kiwi}.
cover a number of appliance features that can be built with {kiwi}.
The test descriptions are stored in a directory structure of the
following layout: `build-tests/ARCH/DISTRIBUTION/test-image-NAME`.
To build integration test image(s), the script `build-tests.sh`
@ -11,19 +11,19 @@ exists.
The implementation of `build-tests.sh` calls kiwi's `boxbuild`
command in container mode, which allows calling the script on
actually any host system that allows to run container instances
any host system that allows you to run container instances
via `podman`.
.. warning:: **Architectures**
Cross architecture image building is possible and also supported
via boxbuild, but the performance impact is big even in containers
using qemu-binfmt and even bigger in full qemu arch emulation.
This would slow down building the integration tests a lot and
therefore `build-tests.sh` requires the host architecture to
match with the image target architecture.
Cross-architecture image building is possible and also supported
via boxbuild, but the performance impact is big, even in containers
using qemu-binfmt, and even bigger in full qemu arch emulation.
This would slow down building the integration tests a lot, and
therefore, `build-tests.sh` requires the host architecture to
match the image target architecture.
Prior calling `build-tests.sh` the following requirements must be met:
Prior to calling `build-tests.sh`, the following requirements must be met:
``Tools``
@ -37,8 +37,8 @@ Prior calling `build-tests.sh` the following requirements must be met:
``Source Checkout``
Checkout the kiwi git repo which provides the test descriptions
as well as the `build-tests.sh` script
Check out the kiwi git repo, which provides the test descriptions
as well as the `build-tests.sh` script.
.. code:: bash
@ -46,8 +46,8 @@ Prior calling `build-tests.sh` the following requirements must be met:
``kiwi-boxed-plugin``
Fetch the kiwi-boxed-plugin from pip. It provides the boxbuild
command used by build-tests.sh
Fetch the `kiwi-boxed-plugin` from pip. It provides the boxbuild
command used by `build-tests.sh`.
.. code:: bash
@ -56,9 +56,9 @@ Prior calling `build-tests.sh` the following requirements must be met:
.. warning::
Make sure to be able to execute `kiwi-ng`. In case there was no {kiwi}
installed on your host you will get notified by the kiwi-boxed-plugin
installed on your host, you will be notified by the kiwi-boxed-plugin
installation to update your path to `export PATH:~/.local/bin/kiwi-ng:$PATH`.
If in doubt about all this just install kiwi from pip too.
If in doubt about all this, just install kiwi from pip too.
`pip install --upgrade kiwi`
Building a specific integration test can be done as follows:
@ -83,5 +83,5 @@ can be done as follows:
Building all integration tests can take some time and depends
on the number of tests provided as well as on the build power
of the host system. In general the tests can also run in
parallel or distributed to multiple hosts
of the host system. In general, the tests can also run in
parallel or be distributed to multiple hosts.

42
doc/source/overview.rst
View File

@ -5,7 +5,7 @@ Overview
.. note:: **Abstract**
This document provides a conceptual overview about the steps
This document provides a conceptual overview of the steps
of creating an image with {kiwi}. It also explains the terminology
regarding the concept and process when building system images
with {kiwi} |version|.
@ -18,11 +18,11 @@ Overview
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,
A system image (usually called an "image") is a *complete installation* of a Linux
system within a file. The image represents an operating system and,
optionally, contains the "final" configuration.
{kiwi} creates images in a two step process:
{kiwi} creates images in a two-step process:
1. The first step, the *prepare operation*, generates a so-called
*unpacked image tree* (directory) using the information provided in
@ -41,48 +41,48 @@ Terminology
-----------
Appliance
An appliance is a ready to use image of an operating system
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.
deployed to or activated in the target system or service.
Image
The result of a {kiwi} 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 :file:`config.xml` or :file:`.kiwi` is required. In addition
there may be other files like scripts or configuration data.
These can be used to customize certain parts either of the {kiwi}
build process or of the initial start-up behavior of the image.
A specification to define an appliance. The image description is a
collection of human-readable files in a directory. At least one XML
file, :file:`config.xml` or :file:`.kiwi`, is required. In addition,
there may be other files, like scripts or configuration data.
These can be used to customize certain parts of either the {kiwi}
build process or the initial startup 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 :file:`root.tar.gz` or stored inside a directory named
a file, :file:`root.tar.gz`, or stored inside a directory named
:file:`root`. Additional overlay directories for selected profiles
are supported too and are taken into account if the directory
are also supported 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
directory structures is copied on top of the existing filesystem
(overlayed) of the appliance root. This also includes
permissions and attributes as a supplement.
{kiwi}
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.
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.
System Requirements
-------------------
To use and run {kiwi}, you need:
* A recent Linux distribution, see :ref:`supported-distributions` for
* A recent Linux distribution; see :ref:`supported-distributions` for
details.
* Enough free disk space to build and store the image. We recommend a

38
doc/source/overview/workflow.rst
View File

@ -3,7 +3,7 @@ Basic Workflow
.. note:: **Abstract**
Installation of a Linux system generally occurs by booting the target
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
@ -11,24 +11,24 @@ Basic Workflow
*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
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 "image"), is a *complete installation* of a Linux
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 start-up behavior of the image. Among others, this includes
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 start-up.
configuration at startup.
* automatically configure themselves in a known target environment.
* prompt the user for an interactive system configuration.
@ -41,12 +41,12 @@ This file is validated against the schema documented in:
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 :ref:`description_components` section for further details.
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
concepts of Linux, including the boot process and distribution concepts
such as package management.
.. _description_components:
@ -57,24 +57,24 @@ 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.
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 at the end of the
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.
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.
executable bit is set. Otherwise, it is called by :file:`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``
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
@ -87,11 +87,11 @@ These are the optional components of an image description:
#. CD root user data
For live ISO images and install ISO images an optional cdroot archive
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
: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
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.

2
doc/source/plugins.rst
View File

@ -4,7 +4,7 @@ KIWI Plugins
.. note::
This document provides a list of the existing {kiwi-product} plugins
which provides extended functionality for version |version|.
that provides extended functionality for version |version|.
.. toctree::
:maxdepth: 1

98
doc/source/plugins/self_contained.rst
View File

@ -8,32 +8,32 @@ Building in a Self-Contained Environment
Users building images with {kiwi} face problems if they want
to build an image matching one of the following criteria:
* build should happen as non root user.
* The build should happen as a non-root user.
* build should happen on a host system distribution for which
no {kiwi} packages exists.
* The build should happen on a host system distribution for which
no {kiwi} packages exist.
* build happens on an incompatible host system distribution
compared to the target image distribution. For example
building an apt/dpkg based system on an rpm based system.
* The build happens on an incompatible host system distribution
compared to the target image distribution. For example,
building an apt/dpkg-based system on an rpm-based system.
* run more than one build process at the same time on the
* Run more than one build process at the same time on the
same host.
* run a build process for a different target architecture
compared to the host architecture (Cross Arch Image Build)
* Run a build process for a different target architecture
compared to the host architecture (Cross-Arch Image Build).
This document describes how to perform the build process in
a self contained environment using fast booting virtual
a self-contained environment using fast-booting virtual
machines to address the issues listed above.
The changes on the machine to become a build host will
be reduced to the requirements of the {kiwi} `boxed plugin`
be reduced to the requirements of the {kiwi} `boxed plugin`.
Requirements
------------
Add the {kiwi} repo from the Open Build Service. For details see
Add the {kiwi} repo from the Open Build Service. For details, see
:ref:`installation-from-obs`. The following {kiwi} plugin needs to be
installed on the build system:
@ -45,24 +45,24 @@ Building with the boxbuild command
----------------------------------
The installation of the {kiwi} boxed plugin has registered a new kiwi
command named `boxbuild`. The command implementation uses KVM as
virtualization technology and runs the {kiwi} `build` command inside of
a KVM controlled virtual machine. For running the build process in a
virtual machine it's required to provide VM images that are suitable
to perform this job. We call the VM images `boxes` and they contain
command named `boxbuild`. The command implementation uses KVM as a
virtualization technology and runs the {kiwi} `build` command inside
a KVM-controlled virtual machine. For running the build process in a
virtual machine, it's required to provide VM images that are suitable
to perform this job. We call the VM images `boxes`, and they contain
kiwi itself as well as all other components needed to build appliances.
Those boxes are hosted in the Open Build Service and are publicly
available at the `Subprojects` tab in the: `Virtualization:Appliances:SelfContained <https://build.opensuse.org/project/show/Virtualization:Appliances:SelfContained>`__
project.
As a user you don't need to work with the boxes because this is all done
As a user, you don't need to work with the boxes because this is all done
by the plugin and provided as a service by the {kiwi} team. The `boxbuild`
command knows where to fetch the box and also cares for an update of the
box when it has changed.
Building an image with the `boxbuild` command is similar to building with
the `build` command. The plugin validates the given command call with the
capabilities of the `build` command. Thus one part of the `boxbuild` command
capabilities of the `build` command. Thus, one part of the `boxbuild` command
is exactly the same as with the `build` command. The separation between
`boxbuild` and `build` options is done using the `--` separator. The following
example shows how to build an example from the `kiwi-descriptions` repo:
@ -78,31 +78,31 @@ example shows how to build an example from the `kiwi-descriptions` repo:
.. note::
The provided `--description` and `--target-dir` options are
setup as shared folders between the host and the box. No other
set up as shared folders between the host and the box. No other
data will be shared with the host.
Sharing Backends
----------------
As mentioned above, the `boxbuild` call shares the two host directories
provided in `--description` and `--target-dir` with the box. To do this
provided in `--description` and `--target-dir` with the box. To do this,
the following sharing backends are supported:
``--9p-sharing``
With QEMU's `9pfs` you can create virtual filesystem devices
(virtio-9p-device) and expose them to the box. For more information
With QEMU's `9pfs`, you can create virtual filesystem devices
(virtio-9p-device) and expose them to the box. For more information,
see `9pfs <https://wiki.qemu.org/Documentation/9psetup>`__. Using
this sharing backend does not require any setup procedure from the
user and is also the default for `boxbuild`
user and is also the default for `boxbuild`.
``--sshfs-sharing``
SSHFS is a FUSE-based filesystem client for mounting remote
directories over a Secure Shell connection (SSH). In `boxbuild`
directories over a Secure Shell connection (SSH). In `boxbuild`,
this is used to mount directories from the host into the box.
Because this runs through an SSH connection the host must allow
connections from the box. If you plan to use `sshfs` add the
Because this runs through an SSH connection, the host must allow
connections from the box. If you plan to use `sshfs`, add the
following SSH public key to the :file:`~/.ssh/authorized_keys`
file of the user which is expected to call `boxbuild`
file of the user who is expected to call `boxbuild`:
.. code:: bash
@ -115,30 +115,30 @@ the following sharing backends are supported:
If the `sshfs` backend is used without the host trusting the box,
the `boxbuild` call will become interactive at the time of the sshfs
mount. In this case the user might be asked for a passphrase or
depending on the host `sshd` setup the request will be declined and
the boxbuild fails.
mount. In this case, the user might be asked for a passphrase, or
depending on the host's `sshd` setup, the request will be declined and
the boxbuild will fail.
``--virtiofs-sharing``
QEMU virtio-fs shared file system daemon. Share a host directory tree
with a box through a virtio-fs device. For more information
QEMU virtio-fs shared filesystem daemon. Share a host directory tree
with a box through a virtio-fs device. For more information,
see `virtiofs <https://manpages.ubuntu.com/manpages/jammy/en/man1/virtiofsd.1.html>`__.
Using this sharing backend does not require any setup procedure from the
user
user.
.. warning::
virtiofs support was added but considered experimental and
not yet stable across the distributions. Feedback welcome.
virtiofs support was added but is considered experimental and
not yet stable across the distributions. Feedback is welcome.
Building in Container
---------------------
By default and also as preferred method, boxbuild runs in a KVM
By default, and also as the preferred method, boxbuild runs in a KVM
virtual machine. However, support for building in container
instances via `podman` is also implemented. The boxes built as
instances via `podman` is also implemented. The boxes are built as
virtual machine images and also as OCI containers hosted on the
openSUSE registry. In container mode boxbuild pulls
openSUSE registry. In container mode, boxbuild pulls
the requested box from the remote registry to the local registry
and starts a container instance. The following example shows how
to build the mentioned {kiwi} integration test image in a
@ -153,28 +153,28 @@ container:
.. note::
The provided `--description` and `--target-dir` options are
setup as shared volumes between the host and the box container.
In addition containers also shares the kiwi cache from
set up as shared volumes between the host and the box container.
In addition, containers also share the kiwi cache from
`/var/cache/kiwi` with the host for better performance.
.. warning::
For building in a container several runtime constraints
exists and the isolation model is not as strict as it is
For building in a container, several runtime constraints
exist, and the isolation model is not as strict as it is
when building in a VM. Please read the following information
to get clarity on the existing constraints.
``loop devices``
As kiwi requires loop devices and calls other operations
which requires root privileges, `podman` is started through `sudo`.
that require root privileges, `podman` is started through `sudo`.
As podman runs daemonless, the calling user must have the
privileges to perform the needed kiwi actions. Non
privileges to perform the needed kiwi actions. Non-
privileged builds are therefore not possible in container
mode with kiwi.
``linux capabilities``
Several linux capabilities as they can be found in
https://man7.org/linux/man-pages/man7/capabilities.7.html are
Several Linux capabilities, as they can be found in
https://man7.org/linux/man-pages/man7/capabilities.7.html, are
set when `boxbuild` starts the container:
* AUDIT_WRITE
@ -185,8 +185,8 @@ container:
``host device nodes``
The host device nodes from `/dev` are shared with the container
instance. This is required to work with loop devices
inside of the container. Device isolation is therefore
inside the container. Device isolation is therefore
not possible in container mode with kiwi. The loop device
handling for container based builds, restricts the number of
handling for container-based builds restricts the number of
simultaneous kiwi build processes on this host to the number
of available loop device nodes exposed from the host kernel.

66
doc/source/plugins/stackbuild.rst
View File

@ -5,8 +5,8 @@ Building based on Containers
.. note:: **Abstract**
When building images exposes one of the following
requirements the stackbuild plugin provides an opportunity
When building images, one of the following
requirements of the stackbuild plugin provides an opportunity
to address it:
* Preserve the image rootfs for a later rebuild without
@ -16,12 +16,12 @@ Building based on Containers
* Build an image based on a container stack.
* Transform a container into a {kiwi} image type
* Transform a container into a {kiwi} image type.
Installation
------------
Add the {kiwi} repo from the Open Build Service. For details see
Add the {kiwi} repo from the Open Build Service. For details, see
:ref:`installation-from-obs`. The following {kiwi} plugin needs to be
installed on the build system:
@ -32,29 +32,29 @@ installed on the build system:
Concept
-------
The design of the stackbuild plugin is two fold:
The design of the stackbuild plugin is twofold:
First the plugin comes with a command called `stash` which allows
to store a kiwi built root tree as an OCI container. OCI stands for
*Open Container Interface* and is a defacto standard format in the
container world. Once the container got created it can be managed
First, the plugin comes with a command called `stash` that allows
you to store a kiwi-built root tree as an OCI container. OCI stands for
*Open Container Interface* and is a de facto standard format in the
container world. Once the container has been created, it can be managed
using the preferred container toolchain. The plugin code itself
uses `podman` to work with containers.
As a next step and with the root tree as a container the plugin offers
the opportunity to build images based on one ore more containers.
That's also the reason why the plugin is called *stackbuild* as it
As a next step, and with the root tree as a container, the plugin offers
the opportunity to build images based on one or more containers.
That's also the reason why the plugin is called *stackbuild*, as it
allows you to stack different root containers together.
Consequently the other command provided is named `stackbuild`.
Consequently, the other command provided is named `stackbuild`.
The `stash` and `stackbuild` commands can be used independently
from each other. If there is already a registry with containers
that should be used to build images from, `stackbuild` can
directly consume them.
This concept leads to a number of use cases and a few of them were
This concept leads to a number of use cases, and a few of them were
picked and put into the abstract of this article. For the purpose
of documenting the functionality of the plugin only a part of the
of documenting the functionality of the plugin, only a part of the
possibilities are taken into account as follows:
.. _stash:
@ -62,9 +62,9 @@ possibilities are taken into account as follows:
Create a stash
--------------
The `stash` command creates an OCI compliant container from a given
The `stash` command creates an OCI-compliant container from a given
{kiwi-product} image root tree and registers it in the local
container registry. From there a user can push it to any registry
container registry. From there, a user can push it to any registry
of choice.
The following example creates a stash of a Tumbleweed build
@ -91,16 +91,16 @@ registry:
docker://docker.io/.../twmos-snapshot:2021-10-08
If the `stash` command is called multiple times with the same
container-name this leads to a new layer in the container for
container name, this leads to a new layer in the container for
each call. To inspect the number of layers added to the
container the following command can be used:
container, the following command can be used:
.. code:: bash
$ podman inspect twmos-snapshot
To list all stashes created by the `stash` command the following
command can be used
To list all stashes created by the `stash` command, the following
command can be used:
.. code:: bash
@ -112,21 +112,21 @@ Rebuild from a stash
The `stackbuild` command takes the given container(s) from the local or
remote registry and uses it/them to either rebuild an image from that
data or build a new image on top of that data. If multiple containers
are given the `stackbuild` command stacks them together in the order
as they were provided.
are given, the `stackbuild` command stacks them together in the order
in which they were provided.
.. note::
When using multiple containers the result stack root tree is
When using multiple containers, the result stack root tree is
created from a sequence of rsync commands into the same target
directory. The stackbuild plugin does this with any container
content given and does not check, validate or guarantee that
the selection of containers are actually stackable or leads to
an usable root tree. This means it's in the responsibility of
the caller to make sure the provided containers can actually
content given and does not check, validate, or guarantee that
the selection of containers is actually stackable or leads to a
usable root tree. This means it's the caller's responsibility
to make sure the provided containers can actually
be stacked together in the given order.
To simply rebuild the image from the stash created in :ref:`stash`
To simply rebuild the image from the stash created in :ref:`stash`,
call `stackbuild` as follows:
.. code:: bash
@ -151,16 +151,16 @@ of container images into another image type that is supported by {kiwi}.
The following example demonstrates how an existing container image
from the openSUSE registry can be turned into a virtual machine image.
When moving a container into a virtual machine image the following
aspects has to be taken into account:
When moving a container into a virtual machine image, the following
aspects have to be taken into account:
1. A container image usually has no kernel installed.
2. A container image usually has no bootloader installed.
3. A container image usually has no user configured.
For a VM image the mentioned aspects are mandatory. Therefore
For a VM image, the mentioned aspects are mandatory. Therefore,
the following {kiwi} image description contains this additional
information which the container cannot provide: Create the
information that the container cannot provide: Create the
{kiwi} description as follows:
.. code:: bash

14
doc/source/quickstart.rst
View File

@ -6,7 +6,7 @@ Quick Start
.. note:: **Abstract**
This document describes how to start working with {kiwi},
an OS appliance builder. This description applies for
an OS appliance builder. This description applies to
version |version|.
Before you start
@ -28,7 +28,7 @@ Before you start
.. note::
In case the following procedure causes any trouble
If the following procedure causes any trouble
please take a look at the :ref:`troubleshooting` chapter
and/or reach out at: :ref:`contact`
@ -42,14 +42,14 @@ as follows:
$ tree -L 3 kiwi/build-tests
Take a look which images are available in the example appliances repository
and select one that matches your desired image as close as possible. Or
Take a look at which images are available in the example appliances repository
and select one that matches your desired image as closely as possible. Or
just use the one given in the examples below.
Build your First Image
----------------------
Your first image will be a simple system disk image which can run
Your first image will be a simple system disk image that can run
in any full virtualization system like QEMU. Invoke the following {kiwi}
command in order to build it:
@ -70,8 +70,8 @@ folder that contains the image description which you selected.
Run your Image
--------------
Running an image actually means booting the operating system. In order to
do that attach the disk image to a virtual system. In this example we use
Running an image actually means booting the operating system. To
do that, attach the disk image to a virtual system. In this example, we use
QEMU and boot it as follows:
.. code:: bash

6
doc/source/troubleshooting.rst
View File

@ -5,10 +5,10 @@ Troubleshooting
.. note:: **Abstract**
This document describes situations which leads to issues
during build or boot time of the image build with {kiwi}.
This document describes situations that lead to issues
during build or boot time of the image built with {kiwi}.
The suggested solutions are considered best practice but
are just one out of other possible solution candidates.
are just one of many possible solutions.
.. toctree::
:maxdepth: 1

26
doc/source/troubleshooting/architectures.rst
View File

@ -1,24 +1,24 @@
Architectures
-------------
With regards to the information in :ref:`supported-distributions`
one requirement between the build host and the image when it comes to
architecture support is, that the image architecture should match the
build host architecture. Cross arch building would require any core
tool that is used to build an image to be cross arch capable.
With regards to the information in :ref:`supported-distributions`,
one requirement between the build host and the image, when it comes to
architecture support, is that the image architecture should match the
build host architecture. Cross-arch building would require any core
tool that is used to build an image to be cross-arch capable.
To patch e.g an x86_64 system such that it can build an
To patch, e.g., an x86_64 system such that it can build an
aarch64 image would require some work on binutils and hacks as well as
performance tweaks which is all not worth the effort and still can lead
to broken results. Thus we recommend to provide native systems for the
target architecture and build there. One possible alternative is to
use the kiwi boxed plugin as mentioned above together with a box
created for the desired architecture. However keep in mind the
performance tweaks, which is all not worth the effort and can still lead
to broken results. Thus, we recommend providing native systems for the
target architecture and building there. One possible alternative is to
use the kiwi boxed plugin, as mentioned above, together with a box
created for the desired architecture. However, keep in mind the
performance problematic when running a VM of a different
architecture.
The majority of the image builds are based on the x86 architecture.
As mentioned {kiwi} also supports other architectures, shown in the
As mentioned, {kiwi} also supports other architectures, as shown in the
table below:
.. table::
@ -42,4 +42,4 @@ table below:
The support status for an architecture depends on the distribution.
If the distribution does not build its packages for the desired
architecture, {kiwi} will not be able to build an image for it
architecture, {kiwi} will not be able to build an image for it.

27
doc/source/troubleshooting/boxbuild_tweaks.rst
View File

@ -4,13 +4,13 @@ Boxbuild Tweaks
.. note:: Abstract
This document describes a few ways to modify
box build VMs for testing/debugging.
box-build VMs for testing and debugging.
Increase Box Build Image Size
-----------------------------
In particularly large builds, you may find that the
upstream build boxes aren't quite large enough, and
upstream build boxes are not quite large enough and
fail to build during the final few steps. While it
is a bit of a kludge, it is possible to increase the
size of the build box.
@ -18,10 +18,10 @@ size of the build box.
To do so, follow these steps:
.. note:: For this example, we will assume the box increase
question is an Ubuntu box, located in ~/.kiwi_boxes/ubuntu
in question is an Ubuntu box, located in `~/.kiwi_boxes/ubuntu`.
1. While the VM is offline, locate the VM you want to modify
and resize with `qemu-img`. Here we will increase the size
and resize with `qemu-img`. Here, we will increase the size
by 20G. The VM will have to be told to utilize this space in
the following steps.
@ -29,7 +29,7 @@ To do so, follow these steps:
$ qemu-img resize Ubuntu-Box.x86_64-1.22.04-System-BuildBox.qcow2 +20G
2. When relaunching your `kiwi-ng` box build, make sure you use `--no-snapshot`
2. When relaunching your `kiwi-ng` box build, make sure you use the `--no-snapshot`
and `--box-debug` options within your build command/script. Example:
.. code:: bash
@ -39,14 +39,14 @@ To do so, follow these steps:
--description ./ubuntu-jammy --target-dir /build/kiwi/outputs/
3. When the build fails and drops you into the VM console, you will
need to extend the partition of the VM rootfs, then resize with
`resize2fs`. In this example, `parted` was used and the partition
in question was /dev/vda3.
need to extend the partition of the VM's rootfs, then resize it with
`resize2fs`. In this example, `parted` was used, and the partition
in question was `/dev/vda3`.
.. code:: bash
$ parted
# Can run parted print to check for relevant partitions if needed.
# You can run parted print to check for relevant partitions if needed.
(parted) $ print
(parted) $ resizepart 3 100%
# Exit from parted
@ -55,10 +55,10 @@ To do so, follow these steps:
$ resize2fs /dev/vda3
4. From this point, depending on where your build failed, it may be
possible to continue your build from inside the box, using the
possible to continue your build from inside the box using the
existing 9p mount points defined by your build command. Using the
command above as an example, `/result` within the box maps up to
`/build/kiwi/outputs` on the host, and it's possible to run
command above as an example, `/result` within the box maps to
`/build/kiwi/outputs` on the host, and it's possible to run:
.. code:: bash
@ -66,6 +66,5 @@ To do so, follow these steps:
--root=/result/build/image-root/ --target-dir=/result
5. If the rebuild from within was successful, you can copy the files
from `/result` to `/bundle`, from within the VM, where `/bundle`
from `/result` to `/bundle` from within the VM, where `/bundle`
maps to your `target-dir` on the host.

66
doc/source/troubleshooting/buildhost_constraints.rst
View File

@ -3,58 +3,59 @@
Build Host Constraints
======================
For building images a host system is required that runs the build process.
Tools to create the image are used from that host and this creates an
indirect dependency to the target image. For example; Building an
For building images, a host system is required that runs the build process.
Tools to create the image are used from that host, and this creates an
indirect dependency on the target image. For example, building an
Ubuntu image requires the apt and dpkg tools and metadata to be available
and functional on the host to build an Ubuntu image. There are many more
of those host vs. image dependencies and not all of them can be resolved
of those host vs. image dependencies, and not all of them can be resolved
in a clear and clean way.
The most compatible environment is provided if the build host is of the same
distribution than the target image. In other cases our recommendation is that
the build host is of the same distribution than the target and near to the
distribution as the target image. In other cases, our recommendation is that
the build host is of the same distribution as the target and near to the
major version (+-1) compared to the target. Such an environment can be
found in:
* The Open Build Service `OBS <https://build.opensuse.org>`__.
* The {kiwi} boxed plugin: :ref:`self_contained`
In general, our goal is to support any major distribution with {kiwi}. However
for building images we rely on core tools which are not under our control.
Also several design aspects of distributions like **secure boot** and working
In general, our goal is to support any major distribution with {kiwi}. However,
for building images, we rely on core tools that are not under our control.
Also, several design aspects of distributions like **secure boot** and working
with **upstream projects** are different and not influenced by us. There
are many side effects that can be annoying especially if the build host
is not of the same distribution vendor than the image target.
are many side effects that can be annoying, especially if the build host
is not of the same distribution vendor as the image target.
Package Manager Behavior
------------------------
One of the key requirements for {kiwi} is that the target distribution
consists out of a collection of software packages provided through
software repositories. As of today this applies to every Linux
consists of a collection of software packages provided through
software repositories. As of today, this applies to every Linux
distribution in some shape or form. For the installation of this
software packages there are tools available called `package manager`
software packages, there are tools available called `package manager`,
and {kiwi} implements an API for a variety of package managers to
support the different Linux distributions.
In {kiwi} the package manager tools are called in a way that allows
for a non interactive installation of the packages specified in the
image description. However, {kiwi} does intentionally not configure
In {kiwi}, the package manager tools are called in a way that allows
for a non-interactive installation of the packages specified in the
image description. However, {kiwi} does not intentionally configure
other features of the package manager to keep their distribution
default behavior as much as possible. There are many options that
can be set for a package manager to behave differently. This
part of the troubleshooting exists to inform about the most common
surprises or unexpected behavior of certain package managers and
solutions how to address them.
solutions on how to address them.
.. note::
All of the following information applies to package manager
calls performed inside of the image root tree. Meaning `after`
the image bootstrap phase. During the image bootstrap phase
all package manager calls happens on the build host and their
calls performed inside of the image root tree. Meaning, `after`
the image bootstrap phase. During the image bootstrap phase,
all package manager calls happen on the build host, and their
behavior can only be influenced by changing the setup of the
build host. An isolated build environment is required to
address issues in this area. See :ref:`self_contained` for
details.
@ -66,17 +67,17 @@ hardware was found by the kernel on this system. The package
manager can use this information to match package(s) that holds
a reference to the alias name and installs it automatically.
For example: Automatically install a driver package if the
respective hardware is present. In zypper this behavior is by
default enabled. When building an image this feature can be
respective hardware is present. In zypper, this behavior is by
default enabled. When building an image, this feature can be
unwanted and lead to interesting side effects. As it's required
to build the image on some host, there is also some hardware
available during build. This must not necessarily be the same
available during the build. This must not necessarily be the same
or compatible hardware the image is expected to run on later.
For example: The buildhost has a nvidia graphics card. An
image build process would install the nvidia driver package due
For example, the build host has a NVIDIA graphics card. An
image build process would install the NVIDIA driver package due
to the modalias match. The image is expected to run on a system
without a nvidia card. The build process would install unneeded
software. To switch off modalias matching in zypper follow
without an NVIDIA card. The build process would install unneeded
software. To switch off modalias matching in zypper, follow
these steps:
1. Add a `post_bootstrap.sh` hook script to your image description
@ -86,18 +87,19 @@ these steps:
echo 'ZYPP_MODALIAS_SYSFS=""' > .kiwi.package_manager.env
2. Optionally add a `config.sh` hook script to your image description
2. Optionally, add a `config.sh` hook script to your image description
with the following code:
.. code:: bash
rm .kiwi.package_manager.env
This will delete the custom environment file such that it does
not appear in the final image
This will delete the custom environment file so that it does
not appear in the final image.
3. Rebuild your image. The `.kiwi.package_manager.env` environment
file is used by kiwi and added to the execution environment
of the package manager. The `ZYPP_MODALIAS_SYSFS` variable
can be used to switch off the modalias matching. For more
details on zypper setting please refer to: https://doc.opensuse.org/projects/libzypp/HEAD/zypp-envars.html
details on zypper settings, please refer to: https://doc.opensuse.org/projects/libzypp/HEAD/zypp-envars.html

44
doc/source/troubleshooting/filesystems.rst
View File

@ -3,26 +3,26 @@ Incompatible Filesystem Settings on Host vs. Image
.. note:: **Abstract**
This page provides further information how to solve
image boot problems if the filesystem tool chain on
This page provides further information on how to solve
image boot problems if the filesystem toolchain on
the image build host is incompatible with the
image target distribution
image's target distribution.
When {kiwi} builds an image which requests the creation of a
When {kiwi} builds an image that requests the creation of a
filesystem, the required filesystem creation tool, for
example `mkfs.xfs`, is called from the host on which {kiwi}
gets called. It is expected that the generated filesystem
is compatible with the image target distribution. This
example, `mkfs.xfs`, is called from the host on which {kiwi}
is running. It is expected that the generated filesystem
is compatible with the image's target distribution. This
expectation is not always correct and depends on the
compatibility of the filesystem default settings between
build host and image target. We know about the following
settings that causes an incompatible filesystem which
settings that cause an incompatible filesystem, which
will not be able to be used on boot:
Ext[2,3,4]
Check `/etc/mke2fs.conf` on the build host and make sure
the configured `inode_size` is the same as the setting used
for the target image. To solve an issue of this type use
for the target image. To solve an issue of this type, use
the following filesystem creation option in your {kiwi}
image configuration:
@ -33,12 +33,12 @@ Ext[2,3,4]
XFS
Check the XFS metadata setup on the build host and make sure
the settings are compatible with the target image. XFS has the
default settings compiled in, thus it might be needed to build
default settings compiled-in, thus it might be needed to build
the image first and use the `xfs_info` tool in a `disk.sh` script
to fetch the settings at build time of the image. We know from
to fetch the settings at the build time of the image. We know from
community reports that the setting `sparse=1` will cause issues
on older versions of grub's xfs module, which does not know how
to handle this setting properly. To solve an issue of this type
to handle this setting properly. To solve an issue of this type,
use the following filesystem creation option in your
{kiwi} image configuration:
@ -47,15 +47,15 @@ XFS
<type fscreateoptions="-i sparse=0"/>
btrfs
btrfs and default page sizes (4k vs 64k). By default btrfs
autodetects the sectorsize according to the used kernel page
size. If the sectorsize differs from the page size, the
created filesystem can not be mounted by the image target
btrfs and default page sizes (4k vs 64k). By default, btrfs
autodetects the sector size according to the used kernel page
size. If the sector size differs from the page size, the
created filesystem cannot be mounted by the image's target
kernel. If there is a different kernel page size between the
kernel on the system the image is build on and the later
kernel on the system the image is built on and the later
kernel used for the image, it's required to specify the
filesystem sector size to match with the kernel page size
of the kernel used for the image. This can be done like in
of the kernel used for the image. This can be done as in
the following example:
.. code:: xml
@ -65,9 +65,9 @@ btrfs
.. note::
There can be more inconsistencies in the area of filesystems
which we haven't listed here. In general it's advisable to
build the image in a compatible environment. At best the
that we have not listed here. In general, it's advisable to
build the image in a compatible environment. At best, the
build host distribution is of the same major Linux version
than the image target. For this purpose {kiwi} provides the
so called `boxed-plugin`. Further details can be found
as the image target. For this purpose, {kiwi} provides the
so-called `boxed-plugin`. Further details can be found
in :ref:`self_contained`

28
doc/source/troubleshooting/security.rst
View File

@ -3,46 +3,46 @@ Host Security Settings Conflicts with KIWI
.. note:: **Abstract**
This page provides further information how to solve
This page provides further information on how to solve
image build problems caused by `selinux` security
policies.
Linux systems are protected against write/read or other
operations depending on the application which wants to
operations depending on the application that wants to
access or modify data. The rules for this protection are
provided in security policies. There are several applications
enforcing these security settings, e.g `apparmor` or `selinux`.
In this troubleshooting chapter the focus is set on `selinux`
In this troubleshooting chapter, the focus is on `selinux`.
Protecting files, process groups, kernel filesystems, device
nodes and more from unauthorized access and restrict it to
nodes and more from unauthorized access and restricting it to
a certain set of applications is a nice concept. However, if
taken serious no other application except the ones configured
taken seriously, no other application except the ones configured
in the security policy will function properly.
When building an appliance, the appliance builder has to have
access to a wide range of services. It must be able to
create a new package database elsewhere in the system. It must
be able to create, read and write device nodes, create filesystems,
partitions, bootloader configurations etc etc. The list is very
partitions, bootloader configurations, etc. The list is very
long and no security policy could cover this in a way that it
would not be open to everything which in the end leads to a
would not be open to everything, which in the end leads to a
pointless exercise and no security at all.
This means for users who would like to keep the security settings
of the system enforced and unchanged, the only way to allow {kiwi}
to do its job is to run it through `boxbuild` as explained in
:ref:`self_contained`
:ref:`self_contained`.
For users who can afford to open the system security policy,
the following procedure will make {kiwi} to work:
the following procedure will allow {kiwi} to work:
.. code:: bash
sudo setenforce 0
This action disables selinux temporary. To disable selinux
permanently perform the following steps:
This action disables selinux temporarily. To disable selinux
permanently, perform the following steps:
1. Open the SELinux configuration file: :file:`/etc/selinux/config`
2. Locate the following line: `SELINUX=enforcing`
@ -56,8 +56,8 @@ permanently perform the following steps:
.. note::
similar instructions applies to other application security
Similar instructions apply to other application security
subsystems like `apparmor`. Due to the complexity of these
systems this article just mentions the most common issue
systems, this article only mentions the most common issue
people run into when building images on systems protected
through `selinux`.
by `selinux`.

2
doc/source/working_with_images.rst
View File

@ -3,7 +3,7 @@ Working with Images
.. note::
This document provides a collection of worksheets which
This document provides a collection of worksheets that
describes the creation and setup of appliances to work
within a number of different target environments.

102
doc/source/working_with_images/build_in_buildservice.rst
View File

@ -3,20 +3,20 @@ Building in the Open Build Service
.. note:: **Abstract**
This document gives a brief overview how to build images with
This document gives a brief overview of how to build images with
{kiwi} in version |version| inside of the Open Build Service.
A tutorial on the Open Buildservice itself can be found here:
A tutorial on the Open Build Service itself can be found here:
https://en.opensuse.org/openSUSE:Build_Service_Tutorial
The next generation {kiwi} is fully integrated with the Open Build Service.
In order to start it's best to checkout one of the integration test
The next-generation {kiwi} is fully integrated with the Open Build Service.
To start, it's best to check out one of the integration test
image build projects from the base Testing project
`Virtualization:Appliances:Images:Testing_$ARCH:$DISTRO` at:
https://build.opensuse.org
For example the test images for SUSE on x86 can be found `here
For example, the test images for SUSE on x86 can be found `here
<https://build.opensuse.org/project/show/Virtualization:Appliances:Images:Testing_x86:leap>`__.
@ -26,24 +26,24 @@ Advantages of using the Open Build Service (OBS)
The Open Build Service offers multiple advantages over running {kiwi}
locally:
* OBS will host the latest successful build for you without having to setup
* OBS will host the latest successful build for you without you having to set up
a server yourself.
* As {kiwi} is fully integrated into OBS, OBS will automatically rebuild your
images if one of the included packages or one of its dependencies or {kiwi}
itself get updated.
images if one of the included packages, one of its dependencies, or {kiwi}
itself is updated.
* The builds will no longer have to be executed on your own machine, but
* The builds will no longer have to be executed on your own machine but
will run on OBS, thereby saving you resources. Nevertheless, if a build
fails, you get a notification via email (if enabled in your user's
fails, you will get a notification via email (if enabled in your user's
preferences).
Differences Between Building Locally and on OBS
-----------------------------------------------
Note, there is a number of differences when building images with {kiwi} using
the Open Build Service. Your image that build locally just fine, might not
Note that there are a number of differences when building images with {kiwi} using
the Open Build Service. Your image that built locally just fine might not
build without modifications.
The notable differences to running {kiwi} locally include:
@ -51,14 +51,14 @@ The notable differences to running {kiwi} locally include:
* OBS will pick the {kiwi} package from the repositories configured in your
project, which will most likely not be the same version that you are
running locally.
This is especially relevant when building images for older versions like
This is especially relevant when building images for older versions, like
SUSE Linux Enterprise. Therefore, include the custom appliances
repository as described in the following section:
:ref:`obs-recommended-settings`.
* When {kiwi} runs on OBS, OBS will extract the list of packages from
:file:`config.xml` and use it to create a build root. In contrast to a
local build (where your distributions package manager will resolve the
local build (where your distribution's package manager will resolve the
dependencies and install the packages), OBS will **not** build your image
if there are multiple packages that could be chosen to satisfy the
dependencies of your packages [#f1]_. This shows errors like this:
@ -81,7 +81,7 @@ The notable differences to running {kiwi} locally include:
.. warning:: We strongly encourage you to remove your repositories from
:file:`config.xml` and move them to the repository configuration in
your project's settings. This usually prevents the issue of having the
choice for multiple package version and results in a much smoother
choice for multiple package versions and results in a much smoother
experience when using OBS.
* By default, OBS builds only a single build type and the default
@ -91,7 +91,7 @@ The notable differences to running {kiwi} locally include:
There are two options to build multiple profiles on OBS:
1. Use the `<image>` element and add it bellow the XML
1. Use the `<image>` element and add it below the XML
declaration (`<?xml ..?>`):
.. code:: xml
@ -106,10 +106,10 @@ The notable differences to running {kiwi} locally include:
2. Use the `multibuild <https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.multibuild.html>`_ feature.
The first option is simpler to use, but has the disadvantage that your
appliances are built sequentially. The `multibuild` feature allows to
The first option is simpler to use but has the disadvantage that your
appliances are built sequentially. The `multibuild` feature allows you to
build each profile as a single package, thereby enabling parallel execution,
but requires an additional :file:`_multibuild` file. For the above example
but it requires an additional :file:`_multibuild` file. For the above example,
:file:`config.xml` would have to be adapted as follows:
.. code:: xml
@ -133,11 +133,11 @@ The notable differences to running {kiwi} locally include:
* Subfolders in OBS projects are ignored by default by :command:`osc` and
must be explicitly added via :command:`osc add $FOLDER` [#f2]_. Bear that
must be explicitly added via `osc add $FOLDER` [#f2]_. Bear that
in mind when adding the overlay files inside the :file:`root/` directory
to your project.
* OBS ignores file permissions. Therefore :file:`config.sh` and
* OBS ignores file permissions. Therefore, :file:`config.sh` and
:file:`images.sh` will **always** be executed through BASH (see also:
:ref:`working-with-kiwi-user-defined-scripts`).
@ -150,8 +150,8 @@ Working with OBS
^^^^^^^^^^^^^^^^
Although OBS is an online service, it is not necessary to test every change
by uploading it. OBS will use the same process as ``osc build`` does, so if
your image builds locally via ``osc build`` it should also build online on
by uploading it. OBS will use the same process as `osc build` does, so if
your image builds locally via `osc build`, it should also build online on
OBS.
@ -161,8 +161,8 @@ Repository Configuration
When setting up the project, enable the `images` repository: the `images`
repository's checkbox can be found at the bottom of the selection screen
that appears when clicking `Add from a Distribution` in the `Repositories`
tab. Or specify it manually in the project configuration (it can be
accessed via ``osc meta -e prj``):
tab. Or, specify it manually in the project configuration (it can be
accessed via `osc meta -e prj`):
.. code:: xml
@ -186,9 +186,9 @@ your dependent packages. These repositories can be provided in two ways:
This instructs OBS to inject the repositories from your project into
your appliance.
Additional repositories can be added by invoking ``osc meta -e prj`` and
adding a line of the following form as a child of ``<repository
name="images">``:
Additional repositories can be added by invoking `osc meta -e prj` and
adding a line of the following form as a child of `<repository
name="images">`:
.. code:: xml
@ -233,15 +233,15 @@ your dependent packages. These repositories can be provided in two ways:
</repository>
</project>
Now `Virtualization:Appliances:Builder` is the last repository, which'
Now, `Virtualization:Appliances:Builder` is the last repository whose
repositories are included into the search path. As
`openSUSE:Factory/snapshot` is among these, it can be omitted from the
repository list.
#. Keep the repositories in your :file:`config.xml` configuration file. If
you have installed the latest stable {kiwi} as described in
:ref:`kiwi-installation` then you should add the following repository to
your projects configuration (accessible via :command:`osc meta -e
:ref:`kiwi-installation`, then you should add the following repository to
your project's configuration (accessible via :command:`osc meta -e
prjconf`), so that OBS will pick the latest stable {kiwi} version too:
.. code:: xml
@ -251,26 +251,26 @@ your dependent packages. These repositories can be provided in two ways:
<arch>x86_64</arch>
</repository>
Replace ``$DISTRO`` with the appropriate name for the distribution that
Replace `$DISTRO` with the appropriate name for the distribution that
you are currently building and optionally adjust the architecture.
We recommend to use the first method, as it integrates better into
We recommend using the first method, as it integrates better into
OBS. Note that your image description will then no longer build outside of
OBS though. If building locally is required, use the second method.
OBS, though. If building locally is required, use the second method.
.. warning::
Adding the repositories to project's configuration makes it impossible
Adding the repositories to the project's configuration makes it impossible
to build images for different distributions from the same project.
Since the repositories are added for every package in your project, all
your image builds will share the same repositories, thereby resulting in
conflicts for different distributions.
We recommend to create a separate project for each distribution. If that
We recommend creating a separate project for each distribution. If that
is impossible, you can keep all your repositories (including
`Virtualization:Appliances:Builder`) in :file:`config.xml`. That however
`Virtualization:Appliances:Builder`) in :file:`config.xml`. That, however,
usually requires a large number of workarounds via `Prefer:` settings in
the project configuration and is thus **not** recommended.
@ -278,8 +278,8 @@ OBS though. If building locally is required, use the second method.
Project Configuration
^^^^^^^^^^^^^^^^^^^^^
The Open Build Service will by default create the same output file as {kiwi}
when run locally, but with a custom filename ending (that is unfortunately
The Open Build Service will, by default, create the same output file as {kiwi}
when run locally but with a custom filename ending (that is, unfortunately,
unpredictable). This has the consequence that the download URL of your
image will change with every rebuild (and thus break automated
scripts). OBS can create symbolic links with static names to the latest
@ -289,40 +289,40 @@ build by adding the following line to the project configuration:
Repotype: staticlinks
If build Vagrant images (see :ref:`setup_vagrant`) add the repository-type
If you build Vagrant images (see :ref:`setup_vagrant`), add the repository-type
`vagrant`. OBS creates a `boxes/` subdirectory in your download
repositories, which contains JSON files for Vagrant [#f4]_.
If you have added your repositories to :file:`config.xml`, you probably see
If you have added your repositories to :file:`config.xml`, you will probably see
errors of the following type:
.. code:: bash
unresolvable: have choice for SOMEPACKAGE: SOMEPAKAGE_1 SOMEPACKAGE_2
Instead of starting from scratch and manually adding ``Prefer:`` statements
to the project configuration, we recommend to copy the current project
Instead of starting from scratch and manually adding `Prefer:` statements
to the project configuration, we recommend copying the current project
configuration of the testing project
`Virtualization:Appliances:Images:Testing_$ARCH:$DISTRO` into your own project.
It provides a good starting point and can be adapted to your OBS project.
.. [#f1] This is a design decision made by OBS: as it's purpose is to build
packages in a reproducible fashion it cannot make a decision which
package to choose from multiple available ones. A package manager build
for end-users on the other hand **must** make an a choice, as it would
.. [#f1] This is a design decision made by OBS: as its purpose is to build
packages in a reproducible fashion, it cannot make a decision which
package to choose from multiple available ones. A package manager built
for end users, on the other hand, **must** make a choice, as it would
be otherwise hardly usable.
.. [#f2] :file:`osc` compresses added folders into a `cpio
.. [#f2] `osc` compresses added folders into a `cpio
<https://en.wikipedia.org/wiki/Cpio>`_ archive and decompresses it
before running your builds. The only downside of this is, that the
contents of your overlay is not conveniently visible via the web
before running your builds. The only downside of this is that the
contents of your overlay are not conveniently visible via the web
interface.
.. [#f3] Taken from the project
`Virtualization:Appliances:Images:openSUSE-Tumbleweed
<https://build.opensuse.org/project/show/Virtualization:Appliances:Images:openSUSE-Tumbleweed>`_
<https://build.opensuse.org/project/show/Virtualization:Appliances:Images:openSUSE-Tumbleweed>`_.
.. [#f4] Vagrant uses these JSON files for automatic updates of your
Vagrant boxes.

6
doc/source/working_with_images/build_with_profiles.rst
View File

@ -28,7 +28,7 @@ Consult the manual page of :file:`kiwi` for further details:
Building with the Open Build Service
------------------------------------
The Open Build Service (OBS) support profiles via the `multibuild
The Open Build Service (OBS) supports profiles via the `multibuild
<https://openbuildservice.org/help/manuals/obs-user-guide/cha.obs.multibuild.html>`_
feature.
@ -65,10 +65,10 @@ To enable and use the profiles, follow these steps:
you want OBS to build.
Note, by default, OBS excludes the build **without** any profile
Note that, by default, OBS excludes the build **without** any profile
enabled.
Running a build of a multibuild enabled repository via :file:`osc` can be
Running a build of a multibuild-enabled repository via :file:`osc` can be
achieved via the `-M $PROFILE` flag:
.. code:: shell-session

50
doc/source/working_with_images/build_without_debianbootstrap.rst
View File

@ -5,23 +5,23 @@ Circumvent Debian Bootstrap
.. sidebar:: Abstract
This page provides information how to build Debian based
This page provides information on how to build Debian-based
images without an extra bootstrap process.
When building Debian based images {kiwi} uses `apt` in the
When building Debian-based images, {kiwi} uses `apt` in the
bootstrap and the system phase to create the image root tree.
However, `apt` does not support a native way to bootstrap
an empty root tree. Therefore the bootstrap phase uses
an empty root tree. Therefore, the bootstrap phase uses
apt only to resolve the given bootstrap packages and to
download these packages from the given repositories.
The list of packages is then manually extracted into the
new root tree which is not exactly the same as if `apt`
new root tree, which is not exactly the same as if `apt`
would have installed them natively. For the purpose of
creating an initial tree to begin with, this procedure
is acceptable though.
is acceptable, though.
If, for some reasons, this bootstrap procedure is not
applicable, {kiwi} allows for an alternative process which is
If, for some reason, this bootstrap procedure is not
applicable, {kiwi} allows for an alternative process that is
based on a prebuilt bootstrap-root archive provided as a package.
To make use of a `bootstrap_package`, the name of that package
@ -34,36 +34,36 @@ needs to be referenced in the {kiwi} description as follows:
<package name="b"/>
</packages>
The boostrap process now changes in a way that the provided
bootstrap_package `bootstrap-root` will be installed on the build
host machine. Next {kiwi} searches for a tar archive file
The bootstrap process now changes in a way that the provided
`bootstrap_package`, `bootstrap-root`, will be installed on the build
host machine. Next, {kiwi} searches for a tar archive file,
:file:`/var/lib/bootstrap/bootstrap-root.ARCH.tar.xz`,
where `ARCH` is the name of the host architecture e.g `x86_64`.
If found the archive gets unpacked and serves as the bootstrap
where `ARCH` is the name of the host architecture, e.g., `x86_64`.
If found, the archive is unpacked and serves as the bootstrap
root tree to begin with. The optionally provided additional
bootstrap packages, `a` and `b` in this example will be installed
like system packages via `chroot` and `apt`. Usually no additional
bootstrap packages are needed as they could all be handled as
bootstrap packages, `a` and `b` in this example, will be installed
like system packages via `chroot` and `apt`. Usually, no additional
bootstrap packages are needed, as they could all be handled as
system packages.
How to Create a bootstrap_package
---------------------------------
Changing the setup in {kiwi} to use a `bootstrap_package` rather
then using {kiwi}'s debian bootstrap method to do the job, comes with
the task to create that package providing the bootstrap root tree. There
are more than one way to do this. The following procedure is just one
than using {kiwi}'s Debian bootstrap method to do the job comes with
the task of creating that package, providing the bootstrap root tree. There
is more than one way to do this. The following procedure is just one
example and requires some background knowledge about the Open Build Service
`OBS <https://build.opensuse.org>`__ and its {kiwi} integration.
(`OBS <https://build.opensuse.org>`__) and its {kiwi} integration.
1. Create an OBS project and repository setup that matches your image target
2. Create an image build package
1. Create an OBS project and repository setup that matches your image target.
2. Create an image build package.
.. code:: bash
osc mkpac bootstrap-root
3. Create the following :file:`appliance.kiwi` file
3. Create the following :file:`appliance.kiwi` file:
.. code:: xml
@ -114,10 +114,10 @@ example and requires some background knowledge about the Open Build Service
osc add appliance.kiwi
osc ci
4. Package the image build results into a debian package
4. Package the image build results into a Debian package.
In step 3. the bootstrap root tarball was created but not yet
packaged. A debian package is needed such that it can be
In step 3, the bootstrap root tarball was created but not yet
packaged. A Debian package is needed so that it can be
referenced with the `bootstrap_package` attribute and the repository
providing it. The simplest way to package the `bootstrap-root` tarball
is to create another package in OBS and use the tarball file as

68
doc/source/working_with_images/clone_partitions.rst
View File

@ -6,23 +6,23 @@ Partition Clones
.. sidebar:: Abstract
This page provides details about the partition clone feature
and its use cases
and its use cases.
{kiwi} allows to create block level clones of certain partitions
used in the image. Clones can be created from the `root`, `boot`
{kiwi} allows you to create block-level clones of certain partitions
used in the image. Clones can be created from the `root`, `boot`,
and any other partition listed in the `<partitions>` element.
A partition clone is a simple byte dump from one
block storage device to another. However, this would cause conflicts
during boot of the system because all unique identifiers like
the UUID of a filesystem will no longer be unique. The clone
during boot of the system because all unique identifiers, like
the UUID of a filesystem, will no longer be unique. The clone
feature of {kiwi} takes care of this part and re-creates the
relevant unique identifiers per cloned partition. {kiwi} allows
this also for complex partitions like LVM, LUKS or RAID.
this also for complex partitions like LVM, LUKS, or RAID.
The partition clone(s) will always appear first in the partition table,
followed by the origin partition. The origin partition is the one
whose identifier will be referenced and used by the system. By default
whose identifier will be referenced and used by the system. By default,
no cloned partition will be mounted or used by the system at boot time.
Let's take a look at the following example:
@ -40,7 +40,7 @@ Let's take a look at the following example:
<size unit="G">100</size>
</type>
With the above setup {kiwi} will create a disk image that
With the above setup, {kiwi} will create a disk image that
contains the following partition table:
.. code::
@ -56,64 +56,64 @@ contains the following partition table:
8 1337344 3864575 2 GiB 8300 p.lxrootclone1
9 3864576 6287326 2 GiB 8300 p.lxroot
When booting the system only the origin partitions `p.lxboot`, `p.lxroot`
and `p.lxhome` will be mounted and visible in e.g. :file:`/etc/fstab`,
the bootloader or the initrd. Thus partition clones are present as a data
When booting the system, only the origin partitions `p.lxboot`, `p.lxroot`,
and `p.lxhome` will be mounted and visible in, e.g., :file:`/etc/fstab`,
the bootloader, or the initrd. Thus, partition clones are present as a data
source but are not relevant for the operating system from a functional
perspective.
As shown in the above example there is one clone request for root and boot
and a two clone requests for the home partition. {kiwi} does not sanity-
check the provided number of clones (e.g. whether your partition table
As shown in the above example, there is one clone request for root and boot
and two clone requests for the home partition. {kiwi} does not sanity-
check the provided number of clones (e.g., whether your partition table
can hold that many partitions).
.. warning::
There is a limit how many partitions a partition table can hold.
There is a limit to how many partitions a partition table can hold.
This also limits how many clones can be created.
It's important when using the `root_clone` attribute to specify a size for
the part of the system that represents the root partition. As of today {kiwi}
the part of the system that represents the root partition. As of today, {kiwi}
does not automatically divide the root partition into two identical pieces.
In order to create a clone of the partition a size specification is required.
In the above example the size for root is provided via the `oem-systemsize`
To create a clone of the partition, a size specification is required.
In the above example, the size for root is provided via the `oem-systemsize`
element. Using a root clone and fixed size values has the following consequences:
1. The resize capability must be disabled. This is done via `oem-resize`
1. The resize capability must be disabled. This is done via the `oem-resize`
element. The reason is that only the last partition in the partition
table can be resized without destroying data. If there is a clone of
the root partition it should never be resized because then the two
partitions will be different in size and no longer clones of each other
the root partition, it should never be resized because then the two
partitions will be different in size and no longer be clones of each other.
2. There can be unpartitioned space left. In the above example the overall
2. There can be unpartitioned space left. In the above example, the overall
disk size is set to 100G. The sum of all partition sizes will be smaller
than this value and there is no resize available anymore. Depending
on the overall size setup for the disk this will leave unpartitioned
than this value, and there is no resize available anymore. Depending
on the overall size setup for the disk, this will leave unpartitioned
space free on the disk.
Use Case
--------
Potential use cases for which a clone of one or more partitions
is useful include among others:
is useful include, among others:
Factory Resets:
Creating an image with the option to rollback to the
Creating an image with the option to roll back to the
state of the system at deployment time can be very helpful
for disaster recovery
for disaster recovery.
System Updates with Rollbacks e.g A/B:
Creating an image which holds extra space allowing to rollback
modified data can make a system more robust. For example
in a simple A/B update concept, partition A would get updated
Creating an image that holds extra space allowing to roll back
modified data can make a system more robust. For example,
in a simple A/B update concept, partition A would be updated
but would flip to B if A is considered broken after applying the
update.
.. note::
Most probably any use case based on partition clones requires
Most probably, any use case based on partition clones requires
additional software to manage them. {kiwi} provides the
option to create the clone layout but it does not provide
option to create the clone layout, but it does not provide
the software to implement the actual use case for which the
partition clones are needed.
@ -128,7 +128,7 @@ table. For partition clones, the following naming convention applies:
kiwi_(name)PartClone(id)="(partition_number)"
The `(name)` is either taken from the `name` attribute
of the `<partition>` element or it is a fixed name assigned by {kiwi}.
of the `<partition>` element, or it is a fixed name assigned by {kiwi}.
There are the following reserved partition names for which cloning
is supported:
@ -136,7 +136,7 @@ is supported:
* readonly
* boot
For the mentioned example this will result in the
For the mentioned example, this will result in the
following :file:`/config.partids`:
.. code::

113
doc/source/working_with_images/custom_partitions.rst
View File

@ -6,22 +6,22 @@ Custom Disk Partitions
.. sidebar:: Abstract
This page provides details about the opportunities and limitations
to customize the partition table in addition to the volume management
of customizing the partition table in addition to the volume management
settings from :ref:`custom_volumes`.
{kiwi} has its own partitioning schema which is defined according to several
{kiwi} has its own partitioning schema, which is defined according to several
different user configurations: boot firmware, boot partition,
expandable layouts, etc. Those supported features have an impact on the
partitioning schema.
MBR or GUID partition tables are not flexible, carry limitations and are
tied to some specific disk geometry. Because of that the preferred alternative
MBR or GUID partition tables are not flexible, have limitations, and are
tied to some specific disk geometry. Because of that, the preferred alternative
to disk layouts based on traditional partition tables is using flexible
approaches like logic volumes.
approaches like logical volumes.
However, on certain conditions additional entries to the low level
partition table are needed. For this purpose the `<partitions>` section
exists and allows to add custom entries like shown in the following
However, under certain conditions, additional entries to the low-level
partition table are needed. For this purpose, the `<partitions>` section
exists and allows you to add custom entries, as shown in the following
example:
.. code:: xml
@ -31,38 +31,38 @@ example:
</partitions>
Each `<partition>` entry puts a partition of the configured size in the
low level partition table, creates a filesystem on it and includes
it to the system's fstab file. If parts of the root filesystem are
moved into its own partition like it's the case in the above example,
low-level partition table, creates a filesystem on it, and includes
it in the system's fstab file. If parts of the root filesystem are
moved into their own partition, as in the above example,
this partition will also contain the data that gets installed during
the image creation process to that area.
The following attributes must/can be set to configured a partition entry:
The following attributes must/can be set to configure a partition entry:
name="identifier"
Mandatory name of the partition as handled by {kiwi}.
.. note::
There are the following reserved names which cannot be used
The following reserved names cannot be used
because they are already represented by existing attributes:
`root`, `readonly`, `boot`, `prep`, `spare`, `swap`, `efi_csm`
`root`, `readonly`, `boot`, `prep`, `spare`, `swap`, `efi_csm`,
and `efi`.
partition_name="name"
Optional name of the partition as it appears when listing the
table contents with tools like `gdisk`. If no name is set
{kiwi} constructs a name of the form `p.lx(identifier_from_name_attr)`
table contents with tools like `gdisk`. If no name is set,
{kiwi} constructs a name of the form `p.lx(identifier_from_name_attr)`.
partition_type="type_identifier"
Optional partition type identifier as handled by {kiwi}.
Allowed values are `t.linux` and `t.raid`. If not specified
Allowed values are `t.linux` and `t.raid`. If not specified,
`t.linux` is the default.
size="size_string"
Mandatory size of the partition. A size string can end with `M` or
`G` to indicate a mega-Byte or giga-Byte value. Without a unit
specification mega-Byte is used.
`G` to indicate a megabyte or gigabyte value. Without a unit
specification, megabyte is used.
mountpoint="path"
Optional mountpoint to mount the partition in the system.
@ -73,51 +73,52 @@ filesystem="btrfs|ext2|ext3|ext4|squashfs|xfs
label="string"
Optional filesystem label if a filesystem is provided. If no
label is specified the `name` identifier is set as filesystem
label
label is specified, the `name` identifier is set as the filesystem
label.
clone="number"
Optional setting to indicate that this partition should be
cloned `number` of times. A clone partition is content wise an
exact byte for byte copy of the origin. However, to avoid conflicts at boot
time the UUID of any cloned partition will be made unique. In the
sequence of partitions, the clone(s) will always be created first
cloned `number` of times. A clone partition is content-wise an
exact byte-for-byte copy of the origin. However, to avoid conflicts at boot
time, the UUID of any cloned partition will be made unique. In the
sequence of partitions, the clone(s) will always be created first,
followed by the partition considered the origin. The origin
partition is the one that will be referenced and used by the
system
system.
part_id="number"
Specify the partition number for this partition. This is the number
used for the partition in the partition table. The value impacts the
name of the unix device node associated with the partition. This means
if the disk name is e.g. `/dev/sda` and `part_id="42"` is set the
unix node for this partition will be `/dev/sda42`. Please note that
name of the Unix device node associated with the partition. This means
if the disk name is, e.g., `/dev/sda` and `part_id="42"` is set, the
Unix node for this partition will be `/dev/sda42`. Please note that
the number has no impact on the geometry or order of partitions as
they get created. The partitions in the `<partitions>` section still
gets created in the order as they are listed. Please also note if
custom partition ids are used it is strongly recommended that they
are used across all partitions created by kiwi. The reason for this
is that kiwi uses an incremental counter which by default matches
with the number of the partition in the table. If custom partition
id's are not used for all partitions this results in a mix of
numbers, which works but is not obviously visible by reading the
image description. Because of that also see the information about
the `<type>` attributes `eficsmpart_id`, `efipart_id`,
`rootpart_id` and `bootpart_id`
they are created. The partitions in the `<partitions>` section are still
created in the order in which they are listed. Please also note, if
custom partition IDs are used, it is strongly recommended that they
be used across all partitions created by kiwi. The reason for this
is that kiwi uses an incremental counter that, by default, matches
the number of the partition in the table. If custom partition
IDs are not used for all partitions, this results in a mix of
numbers, which works but is not obviously visible when reading the
image description. Because of that, also see the information about
Despite the customization options of the partition table shown above
the `<type>` attributes `eficsmpart_id`, `efipart_id`,
`rootpart_id`, and `bootpart_id`.
Despite the customization options of the partition table shown above,
there are the following limitations:
1. By default the root partition is always the last one
1. By default, the root partition is always the last one.
Disk imags build with {kiwi} are designed to be expandable.
For this feature to work the partition containing the system
Disk images built with {kiwi} are designed to be expandable.
For this feature to work, the partition containing the system's
rootfs must always be the last one. If this is unwanted for
some reason {kiwi} offers an opportunity for one extra/spare
partition with the option to be also placed at the end of the
table. For details lookup `spare_part` in :ref:`image-description-elements`
some reason, {kiwi} offers an opportunity for one extra/spare
partition with the option to also be placed at the end of the
table. For details, look up `spare_part` in :ref:`image-description-elements`.
2. By default there are no gaps in the partition table
2. By default, there are no gaps in the partition table.
The way partitions are configured is done such that there are no
gaps in the table of the image. However, leaving some space
@ -126,27 +127,27 @@ there are the following limitations:
* **Deploy with unpartitioned free space.**
To leave space unpartitioned on first boot of a disk image
it is possible to configure an `<oem-systemsize>` which is
To leave space unpartitioned on the first boot of a disk image,
it is possible to configure an `<oem-systemsize>` that is
smaller than the disk the image gets deployed to. Details
about this setting can be found in :ref:`image-description-elements`
about this setting can be found in :ref:`image-description-elements`.
* **Build with unpartitioned free space.**
To leave space unpartitioned at build time of the image it
To leave space unpartitioned at build time of the image, it
is possible to disable `<oem-resize>` and configure an
`<oem-systemsize>` which is smaller than the kiwi calculated
`<oem-systemsize>` which is smaller than the kiwi-calculated
disk size or the fixed setting for the disk size via the
`size>` element.
* **Build with unpartitioned free space.**
Setting some unpartitioned free space on the disk can be done using
the `unpartitioned` attribute of `size` element in type's section.
For details see :ref:`disk-the-size-element`
the `unpartitioned` attribute of the `size` element in the type's section.
For details, see :ref:`disk-the-size-element`.
* **Resize built image adding unpartitioned free space.**
A built image can be resized by using the `kiwi-ng image resize` command
and set a new extended size for the disk. See {kiwi} commands docs
and setting a new extended size for the disk. See {kiwi} commands docs
:ref:`here <db_kiwi_image_resize>`.

40
doc/source/working_with_images/custom_volumes.rst
View File

@ -5,14 +5,14 @@ Custom Disk Volumes
.. sidebar:: Abstract
This chapter provides high level explanations on how to handle volumes
or subvolumes definitions for disk images using {kiwi}.
This chapter provides high-level explanations on how to handle volume
or subvolume definitions for disk images using {kiwi}.
{kiwi} supports defining custom volumes by using the logical volume manager
(LVM) for the Linux kernel or by setting volumes at filesystem level when
filesystem supports it (e.g. btrfs).
(LVM) for the Linux kernel or by setting volumes at the filesystem level when
the filesystem supports it (e.g., btrfs).
Volumes are defined in the {kiwi} description file :file:`config.xml`,
Volumes are defined in the {kiwi} description file, :file:`config.xml`,
using `systemdisk`. This element is a child of the `type`.
Volumes themselves are added via (multiple) `volume` child
elements of the `systemdisk` element:
@ -46,7 +46,7 @@ attributes:
.. note:: Special name for the root volume
One can use the `@root` name to refer to the volume mounted at `/`, in
You can use the `@root` name to refer to the volume mounted at `/` in
case some specific size attributes for the root volume have to be
defined. For instance:
@ -54,39 +54,39 @@ attributes:
<volume name="@root" size="4G"/>
In addition to the custom size of the root volume it's also possible
to setup the name of the root volume as follows:
In addition to the custom size of the root volume, it's also possible
to set up the name of the root volume as follows:
.. code:: xml
<volume name="@root=rootlv" size="4G"/>
If no name for the root volume is specified the
default name: **LVRoot** applies.
If no name for the root volume is specified, the
default name, **LVRoot**, applies.
- `freespace`: Optional attribute defining the additional free space added
to the volume. If no suffix (`M` or `G`) is used, the value is considered
to be in megabytes.
- `label`: Optional attribute to set filesystem label of the volume.
- `label`: Optional attribute to set the filesystem label of the volume.
- `copy_on_write`: Optional attribute to set the filesystem copy-on-write
attribute for this volume.
- `quota`: Optional attribute for the `btrfs` filesystem only. Allows
to specify a quota size for the generated volume.
you to specify a quota size for the generated volume.
- `filesystem_check`: Optional attribute to indicate that this
filesystem should perform the validation to become filesystem checked.
The actual constraints if the check is performed or not depends on
systemd and filesystem specific components. If not set or set to
`false` no system component will be triggered to run an eventual
filesystem check, which results in this filesystem to be never checked.
filesystem should perform the validation to become filesystem-checked.
The actual constraints of whether the check is performed or not depends on
systemd and filesystem-specific components. If not set or set to
`false`, no system component will be triggered to run an eventual
filesystem check, which results in this filesystem never being checked.
The latter is the default.
- `arch`: Optional attribute to create the volume only if it matches
the specified host architecture. Multiple architecture names can
be specified as comma separated list.
be specified as a comma-separated list.
.. warning::
The size attributes for filesystem volumes, as for btrfs, are
@ -95,8 +95,8 @@ attributes:
The `systemdisk` element additionally supports the following optional
attributes:
- `name`: The volume group name, by default `kiwiVG` is used. This setting
- `name`: The volume group name, by default, `kiwiVG` is used. This setting
is only relevant for LVM volumes.
- `preferlvm`: Boolean value instructing {kiwi} to prefer LVM even if the
- `preferlvm`: A boolean value instructing {kiwi} to prefer LVM even if the
used filesystem has its own volume management system.

48
doc/source/working_with_images/disk_ramdisk_deployment.rst
View File

@ -1,7 +1,7 @@
.. _ramdisk_deployment:
Deploy and Run System in a RamDisk
==================================
Deploy and Run a System in a Ramdisk
====================================
.. sidebar:: Abstract
@ -27,7 +27,7 @@ the image into a ramdisk serves this purpose.
echo 'add_drivers+=" brd "' > /etc/dracut.conf.d/10-brd.conf
{kiwi} allows to create a bootable ISO image which deploys the image
{kiwi} allows you to create a bootable ISO image that deploys the image
into a ramdisk and activates that image with the following
oem type definition:
@ -46,15 +46,15 @@ oem type definition:
</type>
The type specification above builds an installation ISO image
which deploys the System Image into the specified ramdisk
device (/dev/ram1). The setup of the ISO image boots with a
short boot timeout of 1sec and just runs through the process
without asking any questions. In a ramdisk deployment the
optional target verification, swap space and multipath targets
that deploys the System Image into the specified ramdisk
device (`/dev/ram1`). The setup of the ISO image boots with a
short boot timeout of 1 second and just runs through the process
without asking any questions. In a ramdisk deployment, the
optional target verification, swap space, and multipath targets
are out of scope and therefore disabled.
The configured size of the ramdisk via `oem-ramdisk-size` specifies
the kB size of the OS disk and it must be at least of the size of the
the kB size of the OS disk, and it must be at least of the size of the
System Image. The disk size can be configured dynamically with the
following value in the kernelcmdline attribute:
@ -75,27 +75,27 @@ follows:
or a real machine, must provide enough RAM to hold the image
in the ramdisk as well as have enough RAM available to operate
the OS and its applications. The {kiwi} build image with the
extension .raw provides the System Image which gets deployed
into the RAM space. Substract the size of the System Image
extension .raw provides the System Image that gets deployed
into the RAM space. Subtract the size of the System Image
from the RAM space the machine offers and make sure the result
is still big enough for the use case of the appliance. In
case of a virtual machine, attach enough main memory to fit
this calculation. In case of QEMU this can be done with
the `-m` option
the case of a virtual machine, attach enough main memory to fit
this calculation. In the case of QEMU, this can be done with
the `-m` option.
Like all other oem {kiwi} images, also the ramdisk setup supports
all the deployments methods as explained in :ref:`deployment_methods`
Like all other oem {kiwi} images, the ramdisk setup also supports
all the deployment methods as explained in :ref:`deployment_methods`.
This means it's also possible to dump the ISO image on a USB
stick let the system boot from it and unplug the stick from
the machine because the system was deployed into RAM
stick, let the system boot from it, and unplug the stick from
the machine because the system was deployed into RAM.
.. note:: Limitations Of RamDisk Deployments
.. note:: Limitations Of Ramdisk Deployments
Only standard images which can be booted by a simple root mount
and root switch can be used. Usually {kiwi} calls kexec after deployment
such that the correct, for the image created dracut initrd, will boot
the image. In case of a RAM only system kexec does not work because
it would loose the ramdisk contents. Thus the dracut initrd driving
Only standard images that can be booted by a simple root mount
and root switch can be used. Usually, {kiwi} calls kexec after deployment
such that the correct dracut initrd created for the image will boot
the image. In the case of a RAM-only system, kexec does not work because
it would lose the ramdisk contents. Thus, the dracut initrd driving
the deployment is also the environment to boot the system.
There are cases where this environment is not suitable to boot
the system.

26
doc/source/working_with_images/disk_setup_for_azure.rst
View File

@ -11,24 +11,24 @@ Image Description for Microsoft Azure
* :ref:`simple_disk`
A virtual disk image which is able to boot in the Microsoft Azure
cloud framework has to comply the following constraints:
A virtual disk image that is able to boot in the Microsoft Azure
cloud framework has to comply with the following constraints:
* Hyper-V tools must be installed
* Microsoft Azure Agent must be installed
* Disk size must be set to 30G
* Kernel parameters must allow for serial console
* Hyper-V tools must be installed.
* The Microsoft Azure Agent must be installed.
* The disk size must be set to 30G.
* Kernel parameters must allow for a serial console.
To meet this requirements update the {kiwi} image
To meet these requirements, update the {kiwi} image
description as follows:
1. Software packages
Make sure to add the following packages to the package list
Make sure to add the following packages to the package list:
.. note::
Package names used in the following list matches the
Package names used in the following list match the
package names of the SUSE distribution and might be different
on other distributions.
@ -39,7 +39,7 @@ description as follows:
2. Image Type definition
Update the oem image type setup as follows
Update the oem image type setup as follows:
.. code:: xml
@ -59,6 +59,6 @@ description as follows:
</type>
An image built with the above setup can be uploaded into the
Microsoft Azure cloud and registered as image. For further
information on how to upload to Azure see:
`azurectl <https://github.com/SUSE-Enceladus/azurectl>`_
Microsoft Azure cloud and registered as an image. For further
information on how to upload to Azure, see:
`azurectl <https://github.com/SUSE-Enceladus/azurectl>`_.

42
doc/source/working_with_images/disk_setup_for_ec2.rst
View File

@ -11,27 +11,27 @@ Image Description for Amazon EC2
* :ref:`simple_disk`
A virtual disk image which is able to boot in the Amazon EC2
cloud framework has to comply the following constraints:
A virtual disk image that is able to boot in the Amazon EC2
cloud framework has to comply with the following constraints:
* Xen tools and libraries must be installed
* cloud-init package must be installed
* cloud-init configuration for Amazon must be provided
* Grub bootloader modules for Xen must be installed
* AWS tools must be installed
* Disk size must be set to 10G
* Kernel parameters must allow for xen console
* Xen tools and libraries must be installed.
* The cloud-init package must be installed.
* A cloud-init configuration for Amazon must be provided.
* Grub bootloader modules for Xen must be installed.
* AWS tools must be installed.
* The disk size must be set to 10G.
* Kernel parameters must allow for a Xen console.
To meet this requirements add or update the {kiwi} image
To meet these requirements, add or update the {kiwi} image
description as follows:
1. Software packages
Make sure to add the following packages to the package list
Make sure to add the following packages to the package list:
.. note::
Package names used in the following list matches the
Package names used in the following list match the
package names of the SUSE distribution and might be different
on other distributions.
@ -45,7 +45,7 @@ description as follows:
2. Image Type definition
Update the oem image type setup as follows
Update the oem image type setup as follows:
.. code:: xml
@ -62,13 +62,13 @@ description as follows:
</oemconfig>
</type>
3. Cloud Init setup
3. Cloud-Init setup
Cloud init is a service which runs at boot time and allows
to customize the system by activating one ore more cloud init
modules. For Amazon EC2 the following configuration file
:file:`/etc/cloud/cloud.cfg` needs to be provided as part of the
overlay files in your {kiwi} image description
Cloud-init is a service that runs at boot time and allows
you to customize the system by activating one or more cloud-init
modules. For Amazon EC2, the following configuration file,
:file:`/etc/cloud/cloud.cfg`, needs to be provided as part of the
overlay files in your {kiwi} image description:
.. code:: yaml
@ -127,5 +127,5 @@ description as follows:
ssh_svcname: sshd
An image built with the above setup can be uploaded into the
Amazon EC2 cloud and registered as image. For further information
on how to upload to EC2 see: `ec2uploadimg <https://github.com/SUSE-Enceladus/ec2imgutils>`_
Amazon EC2 cloud and registered as an image. For further information
on how to upload to EC2, see: `ec2uploadimg <https://github.com/SUSE-Enceladus/ec2imgutils>`_.

34
doc/source/working_with_images/disk_setup_for_google.rst
View File

@ -11,24 +11,24 @@ Image Description for Google Compute Engine
* :ref:`simple_disk`
A virtual disk image which is able to boot in the Google Compute Engine
cloud framework has to comply the following constraints:
A virtual disk image that is able to boot in the Google Compute Engine
cloud framework has to comply with the following constraints:
* {kiwi} type must be an expandable disk
* Google Compute Engine init must be installed
* Disk size must be set to 10G
* Kernel parameters must allow for serial console
* {kiwi} type must be an expandable disk.
* Google Compute Engine init must be installed.
* Disk size must be set to 10G.
* Kernel parameters must allow for a serial console.
To meet this requirements update the {kiwi} image
To meet these requirements, update the {kiwi} image
description as follows:
1. Software packages
Make sure to add the following packages to the package list
Make sure to add the following packages to the package list:
.. note::
Package names used in the following list matches the
Package names used in the following list match the
package names of the SUSE distribution and might be different
on other distributions.
@ -39,13 +39,13 @@ description as follows:
2. Image Type definition
To allow the image to be expanded to the configured disk
geometry of the instance started by Google Compute Engine it is
geometry of the instance started by Google Compute Engine, it is
suggested to let {kiwi}'s OEM boot code take over that task. It would
also be possible to try cloud-init's resize module but we found
conflicts when two cloud init systems, `google-compute-engine-init` and
`cloud-init` were used together. Thus for now we stick with {kiwi}'s
boot code which can resize the disk from within the initrd before
the system gets activated through systemd.
also be possible to try cloud-init's resize module, but we found
conflicts when two cloud-init systems, `google-compute-engine-init` and
`cloud-init`, were used together. Thus, for now, we stick with {kiwi}'s
boot code, which can resize the disk from within the initrd before
the system is activated through systemd.
Update the oem image type setup to be changed into an expandable
type as follows:
@ -66,5 +66,5 @@ description as follows:
</type>
An image built with the above setup can be uploaded into the
Google Compute Engine cloud and registered as image. For further information
on how to upload to Google see: `google-cloud-sdk` on software.opensuse.org
Google Compute Engine cloud and registered as an image. For further information
on how to upload to Google, see: `google-cloud-sdk` on software.opensuse.org.

32
doc/source/working_with_images/disk_setup_for_luks.rst
View File

@ -1,33 +1,33 @@
.. _setup_for_luks:
Image Description Encrypted Disk
================================
Image Description for an Encrypted Disk
=======================================
.. sidebar:: Abstract
This page provides further information for handling
disk images with an encrypted root filesystem setup.
The information here is based on top of the following
disk images with an encrypted root filesystem.
The information here is based on the following
article:
* :ref:`simple_disk`
A virtual disk image can be partially or fully encrypted
using the LUKS extension supported by {kiwi}. A fully encrypted
image also includes the data in :file:`/boot` to be encrypted.
image also includes the data in `/boot` to be encrypted.
Such an image requests the passphrase for the master key
to be entered at the bootloader stage. A partialy encrypted
image keeps :file:`/boot` unencrypted and on an extra boot partition.
to be entered at the bootloader stage. A partially encrypted
image keeps `/boot` unencrypted and on an extra boot partition.
Such an image requests the passphrase for the master key later
in the boot process when the root partition gets accessed by
the systemd mount service. In any case the master passphrase
in the boot process when the root partition is accessed by
the systemd mount service. In any case, the master passphrase
is requested only once.
Update the {kiwi} image description as follows:
1. Software packages
Make sure to add the following package to the package list
Make sure to add the following package to the package list:
.. note::
@ -41,9 +41,9 @@ Update the {kiwi} image description as follows:
2. Image Type definition
Update the oem image type setup as follows
Update the oem image type setup as follows:
Full disk encryption including :file:`/boot`:
Full disk encryption, including `/boot`:
.. code:: xml
<type image="oem" filesystem="ext4" luks="linux" bootpartition="false">
@ -52,7 +52,7 @@ Update the {kiwi} image description as follows:
</oemconfig>
</type>
Encrypted root partition with an unencrypted extra :file:`/boot` partition:
Encrypted root partition with an unencrypted extra `/boot` partition:
.. code:: xml
<type image="oem" filesystem="ext4" luks="linux" bootpartition="true">
@ -64,9 +64,9 @@ Update the {kiwi} image description as follows:
.. note::
The value for the `luks` attribute sets the master passphrase
for the LUKS keyring. Therefore the XML description becomes
security critical and should only be readable by trustworthy
people. Alternatively the credentials information can be
for the LUKS keyring. Therefore, the XML description becomes
security-critical and should only be readable by trustworthy
people. Alternatively, the credentials information can be
stored in a key file and referenced as:
.. code:: xml

86
doc/source/working_with_images/disk_setup_for_vagrant.rst
View File

@ -6,7 +6,7 @@ Image Description for Vagrant
.. sidebar:: Abstract
This page provides further information for handling
Vagrant controlled disk images built with {kiwi} and references
Vagrant-controlled disk images built with {kiwi} and references
the following article:
* :ref:`simple_disk`
@ -17,28 +17,28 @@ Virtualization technologies. To run a system, Vagrant needs so-called
**boxes**. A box is a TAR archive containing a virtual disk image and
some metadata.
To build Vagrant boxes, you can use `Packer <https://www.packer.io>`_ which
To build Vagrant boxes, you can use `Packer <https://www.packer.io>`_, which
is provided by Hashicorp itself. Packer is based on the official
installation media (DVDs) as shipped by the distribution vendor.
The {kiwi} way of building images might be helpful, if such a media does not
The {kiwi} way of building images might be helpful if such a media does not
exist or does not suit your needs. For example, if the distribution is
still under development or you want to use a collection of your own
repositories. Note, that in contrast to Packer {kiwi} only supports the
repositories. Note that in contrast to Packer, {kiwi} only supports the
libvirt and VirtualBox providers. Other providers require a different box
layout that is currently not supported by {kiwi}.
In addition, you can use the {kiwi} image description as source for the
`Open Build Service <https://openbuildservice.org>`_ which allows
In addition, you can use the {kiwi} image description as a source for the
`Open Build Service <https://openbuildservice.org>`_, which allows
building and maintaining boxes.
Vagrant expects boxes to be setup in a specific way (for details refer to
Vagrant expects boxes to be set up in a specific way (for details refer to
the `Vagrant box documentation
<https://www.vagrantup.com/docs/boxes/base.html>`_.), applied to the
<https://www.vagrantup.com/docs/boxes/base.html>`_.). applied to the
referenced {kiwi} image description from :ref:`simple_disk`, the following
steps are required:
1. Update the image type setup
1. Update the image type setup.
.. code:: xml
@ -52,11 +52,11 @@ steps are required:
</type>
This modifies the type to build a Vagrant box for the libvirt
provider including a pre-defined disk size. The disk size is
optional, but recommended to provide some free space on disk.
provider, including a pre-defined disk size. The disk size is
optional but recommended to provide some free space on disk.
For the VirtualBox provider, the additional attribute
``virtualbox_guest_additions_present`` can be set to ``true`` when the
`virtualbox_guest_additions_present` can be set to `true` when the
VirtualBox guest additions are installed in the {kiwi} image:
.. code:: xml
@ -74,20 +74,20 @@ steps are required:
</oemconfig>
</type>
The resulting Vagrant box then uses the ``vboxfs`` module for the
synchronized folder instead of ``rsync``, that is used by default.
The resulting Vagrant box then uses the `vboxfs` module for the
synchronized folder instead of `rsync`, which is used by default.
2. Add mandatory packages
2. Add mandatory packages.
.. code:: xml
<package name="sudo"/>
<package name="openssh"/>
3. Add additional packages
3. Add additional packages.
If you have set the attribute ``virtualbox_guest_additions_present`` to
``true``, add the VirtualBox guest additions. For openSUSE the following
If you have set the attribute `virtualbox_guest_additions_present` to
`true`, add the VirtualBox guest additions. For openSUSE, the following
packages are required:
.. code:: xml
@ -96,7 +96,7 @@ steps are required:
<package name="virtualbox-guest-x11"/>
<package name="virtualbox-guest-kmp-default"/>
Otherwise, you must add ``rsync``:
Otherwise, you must add `rsync`:
.. code:: xml
@ -105,7 +105,7 @@ steps are required:
Note that {kiwi} cannot verify whether these packages are installed. If
they are missing, the resulting Vagrant box will be broken.
4. Add Vagrant user
4. Add Vagrant user.
.. code:: xml
@ -116,15 +116,15 @@ steps are required:
This adds the **vagrant** user to the system and applies the
name of the user as the password for login.
5. Configure SSH, the default shared folder and sudo permissions
5. Configure SSH, the default shared folder, and sudo permissions.
Vagrant expects that it can login as the user ``vagrant`` using an
insecure public key [#f1]_. Furthermore, vagrant also usually uses
Vagrant expects that it can log in as the user `vagrant` using an
insecure public key [#f1]_. Furthermore, Vagrant also usually uses
:file:`/vagrant` as the default shared folder and assumes that the
``vagrant`` user can invoke commands via :command:`sudo` without having
`vagrant` user can invoke commands via `sudo` without having
to enter a password.
This can be achieved using the function ``baseVagrantSetup`` in
This can be achieved using the function `baseVagrantSetup` in
:file:`config.sh`:
.. code:: bash
@ -133,15 +133,15 @@ steps are required:
6. Additional customizations:
Additionally to ``baseVagrantSetup``, you might want to also ensure the
In addition to `baseVagrantSetup`, you might want to also ensure the
following:
- If you have installed the Virtualbox guest additions into your box,
then also load the ``vboxsf`` kernel module.
- When building boxes for libvirt, then ensure that the default wired
networking interface is called ``eth0`` and uses DHCP. This is
necessary since libvirt uses ``dnsmasq`` to issue IPs to the VMs. This
step can be omitted for Virtualbox boxes.
- If you have installed the VirtualBox guest additions into your box,
then also load the `vboxsf` kernel module.
- When building boxes for libvirt, ensure that the default wired
networking interface is called `eth0` and uses DHCP. This is
necessary since libvirt uses `dnsmasq` to issue IPs to the VMs. This
step can be omitted for VirtualBox boxes.
An image built with the above setup creates a Vagrant box file with the
extension :file:`.vagrant.libvirt.box` or
@ -154,14 +154,14 @@ command:
.. note::
Using the box with the libvirt provider requires alongside a correct
Using the box with the libvirt provider requires, alongside a correct
Vagrant installation:
- the plugin ``vagrant-libvirt`` to be installed
- the plugin `vagrant-libvirt` to be installed
- a running libvirtd daemon
Once added to Vagrant, boot the box and log in
with the following sequence of :command:`vagrant` commands:
with the following sequence of `vagrant` commands:
.. code:: bash
@ -173,21 +173,21 @@ with the following sequence of :command:`vagrant` commands:
Customizing the embedded Vagrantfile
------------------------------------
.. warning:: This is an advanced topic and not required for most users
.. warning:: This is an advanced topic and not required for most users.
Vagrant ship with an embedded :file:`Vagrantfile` that carries settings
specific to this box, for instance the synchronization mechanism for the
shared folder. {kiwi} generates such a file automatically for you and it
Vagrant ships with an embedded :file:`Vagrantfile` that carries settings
specific to this box, for instance, the synchronization mechanism for the
shared folder. {kiwi} generates such a file automatically for you, and it
should be sufficient for most use cases.
If a box requires different settings in the embedded :file:`Vagrantfile`,
then the user can provide {kiwi} with a path to an alternative via the
attribute `embebbed_vagrantfile` of the `vagrantconfig` element: it
attribute `embedded_vagrantfile` of the `vagrantconfig` element: it
specifies a relative path to the :file:`Vagrantfile` that will be included
in the finished box.
In the following example snippet from :file:`config.xml` we add a custom
In the following example snippet from :file:`config.xml`, we add a custom
:file:`MyVagrantfile` into the box (the file should be in the image
description directory next to :file:`config.sh`):
@ -210,7 +210,7 @@ description directory next to :file:`config.sh`):
The option to provide a custom :file:`Vagrantfile` can be combined with the
usage of *profiles* (see :ref:`image-profiles`), so that
certain builds can use the automatically generated :file:`Vagrantfile` (in
the following example that is the Virtualbox build) and others get a
the following example, that is the VirtualBox build) and others get a
customized one (the libvirt profile in the following example):
.. code:: xml
@ -265,5 +265,5 @@ customized one (the libvirt profile in the following example):
</image>
.. [#f1] The insecure key is removed from the box when the it is first
.. [#f1] The insecure key is removed from the box when it is first
booted via Vagrant.

20
doc/source/working_with_images/iso_to_usb_stick_deployment.rst
View File

@ -1,6 +1,6 @@
.. _iso_to_usb_stick:
Deploy ISO Image on an USB Stick
Deploy ISO Image on a USB Stick
================================
.. sidebar:: Abstract
@ -11,18 +11,18 @@ Deploy ISO Image on an USB Stick
* :ref:`hybrid_iso`
In {kiwi} all generated ISO images are created to be hybrid. This means,
In {kiwi}, all generated ISO images are created to be hybrid. This means,
the image can be used as a CD/DVD or as a disk. This works because
the ISO image also has a partition table embedded. With more and more
computers delivered without a CD/DVD drive this becomes important.
computers delivered without a CD/DVD drive, this becomes important.
The very same ISO image can be copied onto a USB stick and used as a
bootable disk. The following procedure shows how to do this:
1. Plug in a USB stick
1. Plug in a USB stick.
Once plugged in, check which Unix device name the stick was assigned
to. The following command provides an overview about all linux
to. The following command provides an overview of all Linux
storage devices:
.. code:: bash
@ -34,15 +34,15 @@ bootable disk. The following procedure shows how to do this:
.. warning::
Make sure the selected device really points to your stick because
the following operation can not be revoked and will destroy all
data on the selected device
the following operation cannot be revoked and will destroy all
data on the selected device.
.. code:: bash
$ dd if={exc_image_base_name}.x86_64-{exc_image_version}.iso of=/dev/<stickdevice>
3. Boot from your USB Stick
3. Boot from your USB Stick.
Activate booting from USB in your BIOS/UEFI. As many firmware has different
Activate booting from USB in your BIOS/UEFI. As many firmwares have different
procedures on how to do it, look into your user manual.
Many firmware offers a boot menu which can be activated at boot time.
Many firmwares offer a boot menu that can be activated at boot time.

38
doc/source/working_with_images/iso_to_usb_stick_file_based_deployment.rst
View File

@ -1,7 +1,7 @@
.. _iso_as_file_to_usb_stick:
Deploy ISO Image as File on a FAT32 Formated USB Stick
======================================================
Deploy ISO Image as a File on a FAT32 Formatted USB Stick
=========================================================
.. sidebar:: Abstract
@ -13,34 +13,34 @@ Deploy ISO Image as File on a FAT32 Formated USB Stick
In {kiwi}, all generated ISO images are created to be hybrid. This means,
the image can be used as a CD/DVD or as a disk. The deployment of such
an image onto a disk like an USB stick normally destroys all existing
an image onto a disk like a USB stick normally destroys all existing
data on this device. Most USB sticks are pre-formatted with a FAT32
Windows File System and to keep the existing data on the stick untouched
Windows filesystem, and to keep the existing data on the stick untouched,
a different deployment needs to be used.
The following deployment process copies the ISO image as an
additional file to the USB stick and makes the USB stick bootable.
The ability to boot from the stick is configured through a SYSLINUX
feature which allows to loopback mount an ISO file and boot the
feature that allows you to loopback mount an ISO file and boot the
kernel and initrd directly from the ISO file.
The initrd loaded in this process must also be able to loopback
mount the ISO file to access the root filesystem and boot the
live system. The dracut initrd system used by {kiwi} provides this
feature upstream called as "iso-scan". Therefore all {kiwi} generated
live ISO images supports this deployment mode.
feature upstream, called "iso-scan". Therefore, all {kiwi}-generated
live ISO images support this deployment mode.
For copying the ISO file on the USB stick and the setup of the
SYSLINUX bootloader to make use of the "iso-scan" feature an extra tool
For copying the ISO file to the USB stick and the setup of the
SYSLINUX bootloader to make use of the "iso-scan" feature, an extra tool
named `live-grub-stick` exists. The following procedure shows how
to setup the USB stick with `live-grub-stick`:
to set up the USB stick with `live-grub-stick`:
1. Install the `live-grub-stick` package from software.opensuse.org:
1. Install the `live-grub-stick` package from software.opensuse.org.
2. Plug in a USB stick
2. Plug in a USB stick.
Once plugged in, check which Unix device name the FAT32 partition
was assigned to. The following command provides an overview about all
was assigned to. The following command provides an overview of all
storage devices and their filesystems:
.. code:: bash
@ -56,12 +56,12 @@ to setup the USB stick with `live-grub-stick`:
$ sudo live-grub-stick {exc_image_base_name}.x86_64-{exc_image_version}.iso /dev/sdz1
4. Boot from your USB Stick
4. Boot from your USB Stick.
Activate booting from USB in your BIOS/UEFI. As many firmware has different
Activate booting from USB in your BIOS/UEFI. As many firmwares have different
procedures on how to do it, look into your user manual.
EFI booting from iso image is not supported at the moment, for EFI booting
use --isohybrid option with live-grub-stick, however note that all the data
EFI booting from an ISO image is not supported at the moment. For EFI booting,
use the --isohybrid option with live-grub-stick; however, note that all the data
on the stick will be lost.
Many firmware offers a boot menu which can be activated at boot time.
Usually this can be reached by pressing the :kbd:`Esc` or :kbd:`F12` keys.
Many firmwares offer a boot menu that can be activated at boot time.
Usually, this can be reached by pressing the :kbd:`Esc` or :kbd:`F12` keys.

23
doc/source/working_with_images/iso_to_usb_stick_grub2_boot_from_iso.rst
View File

@ -1,6 +1,6 @@
.. _grub_boot_from_iso:
Booting a Live ISO Images from Grub2
Booting Live ISO Images from Grub2
====================================
.. sidebar:: Abstract
@ -14,29 +14,28 @@ Booting a Live ISO Images from Grub2
In {kiwi}, all generated ISO images are created to be hybrid. This means,
the image can be used as a CD/DVD or as a disk. This works because
the ISO image also has a partition table embedded. With more and more
computers delivered without a CD/DVD drive this becomes important.
computers delivered without a CD/DVD drive, this becomes important.
Writing this image to a USB stick will permanently erase all existing
data on the device. Additionally, the stick will no longer be usable for
general data storage. Most USB sticks are pre-formatted with a
FAT32 or exFAT Windows file system and to keep the existing data
FAT32 or exFAT Windows filesystem, and to keep the existing data.
Fortunately Grub2 supports booting directly from ISO files. It does not matter
Fortunately, Grub2 supports booting directly from ISO files. It does not matter
whether it is installed on your computer's hard drive or on a USB stick.
The following deployment process copies the ISO image as an additional file
to the USB stick or hard drive. The ability to boot from the disk is configured
through a Grub2 feature which allows to loopback mount an ISO file and boot the
through a Grub2 feature that allows you to loopback mount an ISO file and boot the
kernel and initrd directly from the ISO file.
The initrd loaded in this process must also be able to loopback
mount the ISO file to access the root filesystem and boot the
live system. FAT32 is widely supported on USB sticks.
For hard drives any filesystem supported by grub is apropriate
too.
For hard drives, any filesystem supported by grub is also appropriate.
The dracut initrd system used by {kiwi} provides this
feature upstream called as "iso-scan/filename". Therefore all {kiwi} generated
live ISO images supports this deployment mode.
feature upstream, called "iso-scan/filename". Therefore, all {kiwi}-generated
live ISO images support this deployment mode.
The following procedure expects an existing Grub2 installation on your
hard drive or USB stick.
@ -50,14 +49,14 @@ hard drive or USB stick.
sudo mkdir /iso
sudo cp some-kiwi-live.iso /iso/
2. Lookup the root filesystem UUID of your current operating system.
2. Look up the root filesystem UUID of your current operating system.
Get this information by running the command:
.. code:: bash
findmnt -n -o UUID /
2. Add the following submenu setup to the :file:`grub.cfg` file:
3. Add the following submenu setup to the :file:`grub.cfg` file:
.. note::
@ -91,7 +90,7 @@ hard drive or USB stick.
initrd $initrd
}
3. Restart your computer and select the added menuentry.
4. Restart your computer and select the added menu entry.
.. note::

170
doc/source/working_with_images/legacy_netboot_root_filesystem.rst
View File

@ -1,6 +1,6 @@
.. _build_legacy_pxe:
Build PXE Root File System Image for the legacy netboot infrastructure
Build PXE Root Filesystem Image for the legacy netboot infrastructure
======================================================================
.. _PXE: https://en.wikipedia.org/wiki/Preboot_Execution_Environment
@ -11,38 +11,38 @@ Build PXE Root File System Image for the legacy netboot infrastructure
.. sidebar:: Abstract
This page explains how to build a file system image for use with
This page explains how to build a filesystem image for use with
{kiwi}'s PXE boot infrastructure. It contains:
* how to build a PXE file system image
* how to setup the PXE file system image on the PXE server
* how to build a PXE filesystem image
* how to set up the PXE filesystem image on the PXE server
* how to run it with QEMU
`PXE`_ is a network boot protocol that is shipped with most BIOS
implementations. The protocol sends a DHCP request to get an IP
address. When an IP address is assigned, it uses the `TFTP`_ protocol
to download a Kernel and boot instructions. Contrary to other images
built with {kiwi}, a PXE image consists of separate boot, kernel and root
filesystem images, since those images need to be made available in
built with {kiwi}, a PXE image consists of separate boot, kernel, and root
filesystem images, since these images need to be made available in
different locations on the PXE boot server.
A root filesystem image which can be deployed via {kiwi}'s PXE
netboot infrastructure represents the system rootfs in a linux
A root filesystem image that can be deployed via {kiwi}'s PXE
netboot infrastructure represents the system's rootfs in a Linux
filesystem. A user could loop mount the image and access the
contents of the root filesystem. The image does not contain
any information about the system disk its partitions or the
bootloader setup. All of these information is provided by a
client configuration file on the PXE server which controlls
any information about the system disk, its partitions, or the
bootloader setup. All of this information is provided by a
client configuration file on the PXE server, which controls
how the root filesystem image should be deployed.
Many different deployment strategies are possible, e.g root over
Many different deployment strategies are possible, e.g., root over
`NBD`_ (network block device), `AoE`_ (ATA over Ethernet), or
NFS for diskless and diskfull clients. This particular
NFS for diskless and diskful clients. This particular
example shows how to build an overlayfs-based union system based
on openSUSE Leap for a diskless client which receives the squashfs
compressed root file system image in a ramdisk overlayed via
on openSUSE Leap for a diskless client that receives the squashfs-
compressed root filesystem image in a ramdisk overlayed via
overlayfs and writes new data into another ramdisk on the same
system. As diskless client, a QEMU virtual machine is used.
system. As a diskless client, a QEMU virtual machine is used.
.. compound:: **Things to know before**
@ -51,18 +51,18 @@ system. As diskless client, a QEMU virtual machine is used.
:ref:`network-boot-server` for instructions.
* The following example assumes you will create the PXE image
on the PXE boot server itself (if not, use :command:`scp` to copy the files
on the remote host).
on the PXE boot server itself (if not, use `scp` to copy the files
to the remote host).
* To let QEMU connect to the network, we recommend to
setup a network bridge on the host system and let QEMU connect
* To let QEMU connect to the network, we recommend setting up
a network bridge on the host system and letting QEMU connect
to it via a custom :file:`/etc/qemu-ifup`. For details, see
https://en.wikibooks.org/wiki/QEMU/Networking
* The PXE root filesystem image approach is considered to be a
* The PXE root filesystem image approach is considered a
legacy setup. The required netboot initrd code will be maintained
outside of the {kiwi} appliance builder code base. If possible,
we recommend to switch to the OEM disk image deployment via
we recommend switching to the OEM disk image deployment via
PXE.
1. Make sure you have checked out the example image descriptions,
@ -102,7 +102,7 @@ system. As diskless client, a QEMU virtual machine is used.
loaded and which kernel parameters are set. A template has been installed
at :file:`/srv/tftpboot/pxelinux.cfg/default` from the ``kiwi-pxeboot``
package. The minimal configuration required to boot the example image
looks like to following:
looks like the following:
.. code:: bash
@ -122,11 +122,11 @@ system. As diskless client, a QEMU virtual machine is used.
IMAGE=/dev/ram1;{exc_image_base_name_pxe}.x86_64;{exc_image_version};192.168.100.2;4096
UNIONFS_CONFIG=/dev/ram2,/dev/ram1,overlay
All PXE boot based deployment methods are controlled by a client
All PXE boot-based deployment methods are controlled by a client
configuration file. The above configuration tells the client where
to find the image and how to activate it. In this case the image
will be deployed into a ramdisk (ram1) and overlay mounted such
that all write operations will land in another ramdisk (ram2).
to find the image and how to activate it. In this case, the image
will be deployed into a ramdisk (`ram1`) and overlay mounted such
that all write operations will land in another ramdisk (`ram2`).
{kiwi} supports a variety of different deployment strategies based
on the rootfs image created beforehand. For details, refer
to :ref:`pxe_legacy_client_config`
@ -143,20 +143,20 @@ system. As diskless client, a QEMU virtual machine is used.
PXE Client Setup Configuration
------------------------------
All PXE boot based deployment methods are controlled by configuration files
All PXE boot-based deployment methods are controlled by configuration files
located in :file:`/srv/tftpboot/KIWI` on the PXE server. Such a configuration
file can either be client-specific (config.MAC_ADDRESS, for example
config.00.AB.F3.11.73.C8), or generic (config.default).
In an environment
with heterogeneous clients, this allows to have a default configuration
suitable for the majority of clients, to have configurations suitable
for a group of clients (for example machines with similar or identical
with heterogeneous clients, this allows for a default configuration
suitable for the majority of clients, configurations suitable
for a group of clients (for example, machines with similar or identical
hardware), and individual configurations for selected machines.
The configuration file contains data about the image and about
configuration, synchronization, and partition parameters.
The configuration file has got the following general format:
The configuration file has the following general format:
.. code:: bash
@ -186,16 +186,16 @@ The configuration file has got the following general format:
The configuration file is sourced by Bash, so the same quoting
rules as for Bash apply.
Not all configuration options needs to be specified. It depends on the
Not all configuration options need to be specified. It depends on the
setup of the client which configuration values are required. The
following is a collection of client setup examples which covers all
following is a collection of client setup examples that cover all
supported PXE client configurations.
Setup Client with Remote Root
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To serve the image from a remote location and redirect all
write operations on a tmpfs, the following setup is required:
write operations to a tmpfs, the following setup is required:
.. code:: bash
@ -215,22 +215,22 @@ write operations on a tmpfs, the following setup is required:
UNIONFS_CONFIG=tmpfs,nbd,overlay
The above setup shows the most common use case where the image built
with {kiwi} is populated over the network using either AoE, NBD or NFS
in combination with overlayfs which redirects all write operations
to be local to the client. In any case a setup of either AoE, NBD or
with {kiwi} is populated over the network using either AoE, NBD, or NFS
in combination with overlayfs, which redirects all write operations
to be local to the client. In any case, a setup of either AoE, NBD, or
NFS on the image server is required beforehand.
Setup Client with System on Local Disk
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To deploy the image on a local disk the following setup
To deploy the image on a local disk, the following setup
is required:
.. note::
In the referenced {exc_description_pxe} XML description the ``pxe``
type must be changed as follows and the image needs to be
rebuild:
In the referenced `{exc_description_pxe}` XML description, the `pxe`
type must be changed as follows, and the image needs to be
rebuilt:
.. code:: xml
@ -242,22 +242,22 @@ is required:
DISK="/dev/sda"
PART="5;S;X,X;L;/"
The setup above will create a partition table on sda with a 5MB swap
partition (no mountpoint) and the rest of the disk will be a Linux(L)
partition with :file:`/` as mountpoint. The (``X``) in the PART setup specifies
a place holder to indicate the default behaviour.
The setup above will create a partition table on `sda` with a 5MB swap
partition (no mountpoint), and the rest of the disk will be a Linux(L)
partition with `/` as its mountpoint. The (`X`) in the `PART` setup specifies
a placeholder to indicate the default behavior.
Setup Client with System on Local MD RAID Disk
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To deploy the image on a local disk with prior software RAID
To deploy the image on a local disk with a prior software RAID
configuration, the following setup is required:
.. note::
In the referenced {exc_description_pxe} XML description the ``pxe``
type must be changed as follows and the image needs to be
rebuild:
In the referenced `{exc_description_pxe}` XML description, the `pxe`
type must be changed as follows, and the image needs to be
rebuilt:
.. code:: xml
@ -269,30 +269,30 @@ configuration, the following setup is required:
IMAGE="/dev/md1;{exc_image_base_name_pxe}.x86_64;{exc_image_version};192.168.100.2;4096"
PART="5;S;x,x;L;/"
The first parameter of the RAID line is the RAID level. So far only raid1
(mirroring) is supported. The second and third parameter specifies the
raid disk devices which make up the array. If a RAID line is present
all partitions in ``PART`` will be created as RAID partitions. The first
RAID is named ``md0``, the second one ``md1`` and so on. It is required to
specify the correct RAID partition in the ``IMAGE`` line according to the
``PART`` setup. In this case ``md0`` is reserved for the SWAP space and ``md1``
The first parameter of the RAID line is the RAID level. So far, only raid1
(mirroring) is supported. The second and third parameters specify the
raid disk devices that make up the array. If a `RAID` line is present,
all partitions in `PART` will be created as RAID partitions. The first
RAID is named `md0`, the second one `md1`, and so on. It is required to
specify the correct RAID partition in the `IMAGE` line according to the
`PART` setup. In this case, `md0` is reserved for the SWAP space, and `md1`
is reserved for the system.
Setup Loading of Custom Configuration File(s)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
In order to load for example a custom :file:`/etc/hosts` file on the client,
To load, for example, a custom :file:`/etc/hosts` file on the client,
the following setup is required:
.. code:: bash
CONF="hosts;/etc/hosts;192.168.1.2;4096;ffffffff"
On boot of the client {kiwi}'s boot code will fetch the :file:`hosts` file
On boot of the client, {kiwi}'s boot code will fetch the :file:`hosts` file
from the root of the server (192.168.1.2) with 4k blocksize and deploy
it as :file:`/etc/hosts` on the client. The protocol is by default tftp
but can be changed via the ``kiwiservertype`` kernel commandline option.
For details, see :ref:`custom-download-server`
it as :file:`/etc/hosts` on the client. The protocol is tftp by default
but can be changed via the `kiwiservertype` kernel command-line option.
For details, see :ref:`custom-download-server`.
Setup Client to Force Reload Image
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -304,7 +304,7 @@ the disk is up-to-date, the following setup is required:
RELOAD_IMAGE=1
The option only applies to configurations with a DISK/PART setup
The option only applies to configurations with a `DISK`/`PART` setup.
Setup Client to Force Reload Configuration Files
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@ -316,16 +316,16 @@ CONF, the following setup is required:
RELOAD_CONFIG=1
By default only configuration files which has changed according to
their checksum value will be reloaded. With the above setup all files
By default, only configuration files that have changed according to
their checksum value will be reloaded. With the above setup, all files
will be reloaded from the PXE server. The option only applies to
configurations with a DISK/PART setup
configurations with a `DISK`/`PART` setup.
Setup Client for Reboot After Deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To reboot the system after the initial deployment process is
done the following setup is required:
done, the following setup is required:
.. code:: bash
@ -334,8 +334,8 @@ done the following setup is required:
Setup custom kernel boot options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To deactivate the kernel mode setting on local
boot of the client the following setup is required:
To deactivate the kernel mode setting on the local
boot of the client, the following setup is required:
.. code:: bash
@ -344,13 +344,13 @@ boot of the client the following setup is required:
.. note::
This does not influence the kernel options passed to the client
if it boots from the network. In order to setup those the PXE
configuration on the PXE server needs to be changed
if it boots from the network. To set up those, the PXE
configuration on the PXE server needs to be changed.
Setup a Custom Boot Timeout
~~~~~~~~~~~~~~~~~~~~~~~~~~~
To setup a 10sec custom timeout for the local boot of the client
To set up a 10-second custom timeout for the local boot of the client,
the following setup is required.
.. code:: bash
@ -359,35 +359,35 @@ the following setup is required.
.. note::
This does not influence the boot timeout if the client boots off
from the network.
This does not influence the boot timeout if the client boots from
the network.
.. _custom-download-server:
Setup a Different Download Protocol and Server
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
By default all downloads controlled by the {kiwi} linuxrc code are
performed by an atftp call using the TFTP protocol. With PXE the download
protocol is fixed and thus you cannot change the way how the kernel and
the boot image (:file:`initrd`) is downloaded. As soon as Linux takes over, the
download protocols http, https and ftp are supported too. {kiwi} uses
the curl program to support the additional protocols.
By default, all downloads controlled by the {kiwi} linuxrc code are
performed by an atftp call using the TFTP protocol. With PXE, the download
protocol is fixed, and thus you cannot change the way the kernel and
the boot image (:file:`initrd`) are downloaded. As soon as Linux takes over, the
download protocols http, https, and ftp are also supported. {kiwi} uses
the `curl` program to support the additional protocols.
To select one of the additional download protocols the following
kernel parameters need to be specified
To select one of the additional download protocols, the following
kernel parameters need to be specified:
.. code:: bash
kiwiserver=192.168.1.1 kiwiservertype=ftp
To set up this parameters edit the file
To set up these parameters, edit the file
:file:`/srv/tftpboot/pxelinux.cfg/default` on your PXE boot server and change
the append line accordingly.
.. note::
Once configured all downloads except for kernel and initrd are
Once configured, all downloads except for kernel and initrd are
now controlled by the given server and protocol. You need to make
sure that this server provides the same directory and file structure
as initially provided by the ``kiwi-pxeboot`` package
as initially provided by the `kiwi-pxeboot` package.

62
doc/source/working_with_images/network_live_iso_boot.rst
View File

@ -13,17 +13,17 @@ Booting a Live ISO Image from Network
In {kiwi}, live ISO images can be configured to boot via the
PXE boot protocol. This functionality requires a network boot
server setup on the system. Details how to setup such a server
server setup on the system. Details on how to set up such a server
can be found in :ref:`network-boot-server`.
After the live ISO was built as shown in :ref:`hybrid_iso`,
After the live ISO is built as shown in :ref:`hybrid_iso`,
the following configuration steps are required to boot from
the network:
1. Extract initrd/kernel From Live ISO
1. Extract initrd/kernel from Live ISO
The PXE boot process loads the configured kernel and initrd from
the PXE server. For this reason, those two files must be extracted
the PXE server. For this reason, these two files must be extracted
from the live ISO image and copied to the PXE server as follows:
.. code:: bash
@ -35,13 +35,13 @@ the network:
.. note::
This step must be repeated with any new build of the live ISO image
This step must be repeated with any new build of the live ISO image.
2. Export Live ISO To The Network
2. Export Live ISO to the Network
Access to the live ISO file must be provided by either `ftp`,
`http`, `https` or `dolly`. The most simple method is to setup a FTP server
e.g. `vsftpd` and copy the live ISO file to the data directory:
`http`, `https`, or `dolly`. The simplest method is to set up a FTP server,
e.g., `vsftpd`, and copy the live ISO file to the data directory:
.. code:: bash
@ -54,13 +54,13 @@ the network:
`wget ftp://IP/image/{exc_image_base_name_live}.x86_64-{exc_image_version}.iso`
before the next step.
3. Setup live ISO boot entry in PXE configuration
3. Set up live ISO boot entry in PXE configuration
.. note::
The following step assumes that the pxelinux.0 loader
The following step assumes that the `pxelinux.0` loader
has been configured on the boot server to boot up network
clients
clients.
Edit the file :file:`/srv/tftpboot/pxelinux.cfg/default` and create
a boot entry of the form:
@ -72,19 +72,19 @@ the network:
append initrd=boot/initrd ip=dhcp root=live:ftp://IP/image/{exc_image_base_name_live}.x86_64-{exc_image_version}.iso
* The `ip=` parameter controls how the dracut network module sets up
the network. Several options exists to control how the network
interface should be setup. Please consult the dracut manual
the network. Several options exist to control how the network
interface should be set up. Please consult the dracut manual
for further information.
* The boot parameter `root=live:PROTOCOL://IP/PATH...` specifies the
remote endpoint and protocol to find the live ISO file. So far
`ftp`, `http`, `https` and `dolly` are supported.
remote endpoint and protocol to find the live ISO file. So far,
`ftp`, `http`, `https`, and `dolly` are supported.
4. Boot from the Network
Within the network which has access to the PXE server and the
IP in the root= option, any network client can now boot the
live system. A test based on QEMU is done as follows:
Within the network that has access to the PXE server and the
IP in the `root=` option, any network client can now boot the
live system. A test based on QEMU can be done as follows:
.. code:: bash
@ -93,7 +93,7 @@ the network:
Available Remote Boot Options
-----------------------------
There are the following kernel boot options available to control
The following kernel boot options are available to control
the behavior of the remote boot process.
rd.kiwi.live.curl_options=
@ -103,32 +103,32 @@ rd.kiwi.live.dolly_options=
Options passed along to the dolly call
rd.kiwi.live.system=
Block device to use for the system. By default this is set to `/dev/ram0`
Block device to use for the system. By default, this is set to `/dev/ram0`.
ramdisk_size=bytes
Size of the ramdisk in bytes. By default this is set to 2097152 (2G)
Size of the ramdisk in bytes. By default, this is set to 2097152 (2G).
rd.kiwi.live.reset
Force reset of the live system. This option only makes sense if
the live system device (rd.kiwi.live.system) points to a persistent
storage device. In this case {kiwi} loads the system only once
storage device. In this case, {kiwi} loads the system only once
and does not overwrite it unless a reset is requested.
Persistent Live System
----------------------
The remote boot process of a live ISO image, places the ISO file
The remote boot process of a live ISO image places the ISO file
into a ramdisk by default. This means all data lives in memory and
is not persistent. In order to boot up the live system from a remote
location and keep it on a persistent storage, it's required to
is not persistent. To boot the live system from a remote
location and keep it on persistent storage, it's required to
pass the `rd.kiwi.live.system` boot option with the device name
pointing to that persistent storage.
.. warning::
All data on the device given via `rd.kiwi.live.system` will be wiped
All data on the device given via `rd.kiwi.live.system` will be wiped.
A test based on QEMU is done as follows:
A test based on QEMU can be done as follows:
Edit the file :file:`/srv/tftpboot/pxelinux.cfg/default` and create
a boot entry of the form:
@ -142,9 +142,9 @@ a boot entry of the form:
* The `rd.live.overlay.persistent` and `rd.live.overlay.cowfs=xfs`
options are standard {kiwi} live ISO options to control if and how a
persistent write partition should be created. The options only take
an effect when booting into a persistent storage device.
effect when booting into a persistent storage device.
Next create a persistent storage disk of 3G and attach it to the
Next, create a persistent storage disk of 3G and attach it to the
QEMU instance.
.. code:: bash
@ -153,7 +153,7 @@ QEMU instance.
$ qemu -boot n -hda mydisk.raw
The live system will be deployed once to the locally attached disk and
boots from it. Any subsequent boot process will not modify the local
will boot from it. Any subsequent boot process will not modify the local
disk unless `rd.kiwi.live.reset` is passed on the kernel command line.
If deployed there is also no need for the network anymore and the
If deployed, there is no need for the network anymore, and the
system could also boot standalone.

50
doc/source/working_with_images/network_overlay_boot.rst
View File

@ -13,11 +13,11 @@ Booting a Root Filesystem from Network
In {kiwi}, the `kiwi-overlay` dracut module can be used to boot
from a remote exported root filesystem. The exported device
is visible as block device on the network client. {kiwi}
supports the two export backends `NBD` (Network Block Device)
and `AoE` (ATA over Ethernet) for this purpose. A system that is
is visible as a block device on the network client. {kiwi}
supports the two export backends, `NBD` (Network Block Device)
and `AoE` (ATA over Ethernet), for this purpose. A system that is
booted in this mode will read the contents of the root filesystem
from a remote location and targets any write action into RAM by
from a remote location and target any write action into RAM by
default. The kernel cmdline option `rd.root.overlay.write` can
be used to specify an alternative device to use for writing.
The two layers (read and write) are combined using the `overlayfs`
@ -25,10 +25,10 @@ filesystem.
For remote boot of a network client, the PXE boot protocol
is used. This functionality requires a network boot server
setup on the system. Details how to setup such a server
setup on the system. Details on how to set up such a server
can be found in :ref:`network-boot-server`.
Before the KIS image can be build, the following configuration step
Before the KIS image can be built, the following configuration step
is required:
* Create dracut configuration to include the `kiwi-overlay` module
@ -40,11 +40,11 @@ is required:
$ cd root/etc/dracut.conf.d
$ echo 'add_dracutmodules+=" kiwi-overlay "' > overlay.conf
Now the KIS image can be build as shown in :ref:`kis`. After the
Now, the KIS image can be built as shown in :ref:`kis`. After the
build, the following configuration steps are required to boot
from the network:
1. Copy initrd/kernel from the KIS build to the PXE server
1. Copy the initrd/kernel from the KIS build to the PXE server
The PXE boot process loads the configured kernel and initrd from
the PXE server. For this reason, the following files must be
@ -59,11 +59,11 @@ from the network:
Access to the root filesystem is implemented using either the
AoE or the NBD protocol. This requires the export of the
root filesystem image as remote block device:
root filesystem image as a remote block device:
Export via AoE:
Install the `vblade` package on the system which is expected
to export the root filesystem
Install the `vblade` package on the system that is expected
to export the root filesystem.
.. note::
@ -79,21 +79,21 @@ from the network:
$ vbladed 0 1 IFACE {exc_image_base_name}.x86_64-{exc_image_version}
The above command exports the given filesystem image file as a block
storage device to the network of the given IFACE. On any machine except
storage device to the network of the given `IFACE`. On any machine except
the one exporting the file, it will appear as :file:`/dev/etherd/e0.1`
once the :command:`aoe` kernel module was loaded. The two numbers,
0 and 1 in the above example, classifies a major and minor number which
is used in the device node name on the reading side, in this
case :file:`e0.1`.
once the `aoe` kernel module has been loaded. The two numbers,
0 and 1 in the above example, classify a major and minor number
that is used in the device node name on the reading side, in this
case, :file:`e0.1`.
.. note::
Only machines in the same network of the given INTERFACE
Only machines in the same network of the given `INTERFACE`
can see the exported block device.
Export via NBD:
Install the `nbd` package on the system which is expected
to export the root filesystem
Install the `nbd` package on the system that is expected
to export the root filesystem.
Once done, export the filesystem from the KIS build above as follows:
@ -115,9 +115,9 @@ from the network:
.. note::
The following step assumes that the pxelinux.0 loader
The following step assumes that the `pxelinux.0` loader
has been configured on the boot server to boot up network
clients
clients.
Edit the file :file:`/srv/tftpboot/pxelinux.cfg/default` and create
a boot entry of the form:
@ -130,8 +130,8 @@ from the network:
append initrd=boot/initrd root=overlay:nbd=server-ip:export
The boot parameter `root=overlay:nbd=server-ip:export` specifies
the NBD server IP address and the name of the export as used in
:file:`/etc/nbd-server/config`
the NBD server's IP address and the name of the export as used in
:file:`/etc/nbd-server/config`.
Using AoE:
.. code:: bash
@ -141,11 +141,11 @@ from the network:
append initrd=boot/initrd root=overlay:aoe=AOEINTERFACE
The boot parameter `root=overlay:aoe=AOEINTERFACE` specifies the
interface name as it was exported by the :command:`vbladed` command
interface name as it was exported by the `vbladed` command.
4. Boot from the Network
Within the network which has access to the PXE server and the
Within the network that has access to the PXE server and the
exported root filesystem image, any network client can now boot the
system. A test based on QEMU can be done as follows:

46
doc/source/working_with_images/setup_network_bootserver.rst
View File

@ -5,20 +5,20 @@ Setting Up a Network Boot Server
.. sidebar:: Abstract
This page provides general information how to setup
This page provides general information on how to set up
a network boot server that provides all services
needed for the PXE boot protocol
needed for the PXE boot protocol.
To be able to deploy a system through the PXE boot protocol, you need
to set up a network boot server providing the services DHCP and tftp.
With `dnsmasq` an utility exists which allows to setup all needed
to set up a network boot server providing the services DHCP and TFTP.
With `dnsmasq`, a utility exists that allows you to set up all needed
services at once:
Installing and Configuring DHCP and TFTP with dnsmasq
-----------------------------------------------------
The following instructions can only serve as an example. Depending on your
network structure, the IP addresses, ranges and domain settings needs to
network structure, the IP addresses, ranges, and domain settings need to
be adapted to allow the DHCP server to work within your network. If you
already have a DHCP server running in your network, make sure that the
`filename` and `next-server` directives are correctly set on this server.
@ -28,17 +28,17 @@ DHCP and TFTP server.
1. Install the `dnsmasq` package.
2. Create the file :file:`/etc/dnsmasq.conf` and insert the following content
2. Create the file :file:`/etc/dnsmasq.conf` and insert the following content:
.. code:: bash
# Don't function as a DNS server.
# Do not function as a DNS server.
port=0
# Log information about DHCP transactions.
log-dhcp
# Set the root directory for files available via FTP,
# Set the root directory for files available via TFTP,
# usually "/srv/tftpboot":
tftp-root=TFTP_ROOT_DIR
@ -46,9 +46,9 @@ DHCP and TFTP server.
dhcp-range=BOOT_SERVER_IP,proxy
In the next step it's required to decide for the boot method. There
is the PXE loader provided via pxelinux.0 from the syslinux package
and there is the GRUB loader provided via the grub package.
In the next step, it's required to decide on the boot method. There
is the PXE loader provided via `pxelinux.0` from the `syslinux` package,
and there is the GRUB loader provided via the `grub` package.
.. note:: Placeholders
@ -56,15 +56,15 @@ DHCP and TFTP server.
your network setup.
2.1. insert the following content to use pxelinux.0:
2.1. insert the following content to use `pxelinux.0`:
.. code:: bash
# The boot filename, Server name, Server Ip Address
# The boot filename, server name, and server IP address
dhcp-boot=pxelinux.0,,BOOT_SERVER_IP
# Disable re-use of the DHCP servername and filename fields as extra
# option space. That's to avoid confusing some old or broken
# option space. This is to avoid confusing some old or broken
# DHCP clients.
dhcp-no-override
@ -82,20 +82,20 @@ DHCP and TFTP server.
.. note::
On boot of a network client with that configuration the default
pxelinux.0 config file is expected at
On boot of a network client with that configuration, the default
`pxelinux.0` config file is expected at
:file:`TFTP_ROOT_DIR/pxelinux.cfg/default`
2.2. insert the following content to use grub:
2.2. insert the following content to use GRUB:
.. code:: bash
# The boot filename, Server name, Server Ip Address
# The boot filename, server name, and server IP address
dhcp-boot=boot/grub2/i386-pc/core.0,,BOOT_SERVER_IP
When using grub the referenced dhcp-boot grub module must be genereated.
To do this change the directory to :file:`TFTP_ROOT_DIR` and create
the :file:`setvars.conf` with the following content:
When using GRUB, the referenced `dhcp-boot` GRUB module must be generated.
To do this, change the directory to :file:`TFTP_ROOT_DIR` and create
the :file:`setvars.conf` file with the following content:
.. code:: bash
@ -103,7 +103,7 @@ DHCP and TFTP server.
set net_default_server=BOOT_SERVER_IP
set prefix=boot/grub2
Now call the following commands to create the grub module
Now, call the following commands to create the GRUB module:
.. code:: bash
@ -116,7 +116,7 @@ DHCP and TFTP server.
.. note::
On boot of a network client with that configuration the grub
On boot of a network client with that configuration, the GRUB
config file is expected at :file:`TFTP_ROOT_DIR/boot/grub2/grub.cfg`
3. Run the dnsmasq server by calling:

32
doc/source/working_with_images/use_suse_media.rst
View File

@ -5,21 +5,21 @@ Using SUSE Product ISO To Build
.. sidebar:: Abstract
This page provides information how to use the SUSE
media ISO with {kiwi}
This page provides information on how to use the SUSE
media ISO with {kiwi}.
When building an image with {kiwi}, the image description usually
points to a number of public/private package source repositories
from which the new image root tree will be created. Alternatively
the vendor provided product ISO image(s) can be used. The contents
of the ISO (DVD) media also provides package source repositories
but organized in a vendor specific structure. As a user it's
important to know about this structure such that the {kiwi}
from which the new image root tree will be created. Alternatively,
the vendor-provided product ISO image(s) can be used. The contents
of the ISO (DVD) media also provide package source repositories
but are organized in a vendor-specific structure. As a user, it's
important to know about this structure so that the {kiwi}
image description can consume it.
To use a SUSE product media the following steps are required:
To use a SUSE product media, the following steps are required:
1. Mount the ISO media from file or DVD drive:
1. Mount the ISO media from the file or DVD drive:
.. code:: bash
@ -27,14 +27,14 @@ To use a SUSE product media the following steps are required:
2. Lookup all `Product` and `Module` directories:
Below `/media/suse` there is a directory structure which
Below `/media/suse`, there is a directory structure that
provides package repositories in directories starting
with `Product-XXX` and `Module-XXX`. It depends on the
package list in the {kiwi} image description from which
location a package or a dependency of the package is
taken. Therefore it is best practice to browse through
taken. Therefore, it is best practice to browse through
all the directories and create a `<repository>` definition
for each of them in the {kiwi} image description like
for each of them in the {kiwi} image description, as
the following example shows:
.. code:: xml
@ -47,13 +47,13 @@ To use a SUSE product media the following steps are required:
<source path="file:///media/suse/Module-Basesystem"/>
</repository>
Once all the individual product and module repos has been created
Once all the individual product and module repos have been created
in the {kiwi} image description, the build process can be started
as usual.
.. note::
Because of the manual mount process the `/media/suse` location
Because of the manual mount process, the `/media/suse` location
stays busy after {kiwi} has created the image. The cleanup of
this resource is a responsibility of the user and not done
by {kiwi}
this resource is the responsibility of the user and not done
by {kiwi}.