5 Troubleshooting #

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 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 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 major version (+-1) compared to the target. Such an environment can be found in:

In general, our goal is to support any major distribution with KIWI NG. 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 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.

5.1.1 Package Manager Behavior #

 

One of the key requirements for KIWI NG 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 distribution in some shape or form. For the installation of this software packages there are tools available called package manager and KIWI NG implements an API for a variety of package managers to support the different Linux distributions.

In KIWI NG 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 NG does intentionally not 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.

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 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 Section 6.1, “Building in a Self-Contained Environment” for details.

5.1.1.1 zypper: modalias matching #

 

A module alias is an identifier that exists if the respective 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 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 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 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 these steps:

1. Add a post_bootstrap.sh hook script to your image description with the following code:

   echo 'ZYPP_MODALIAS_SYSFS=""' > .kiwi.package_manager.env

2. Optionally add a config.sh hook script to your image description with the following code:

   rm .kiwi.package_manager.env

   This will delete the custom environment file such 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

With regards to the information in Section 5.1, “Build Host Constraints” 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 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 problematic when running a VM of a different architecture.

The majority of the image builds are based on the x86 architecture. As mentioned KIWI NG also supports other architectures, shown in the table below:

Note

Abstract

This page provides further information 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 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

Protecting files, process groups, kernel filesystems, device nodes and more from unauthorized access and restrict it to a certain set of applications is a nice concept. However, if taken serious 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 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 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 NG to do its job is to run it through boxbuild as explained in Section 6.1, “Building in a Self-Contained Environment”

For users who can afford to open the system security policy, the following procedure will make KIWI NG to work:

sudo setenforce 0

This action disables selinux temporary. To disable selinux permanently perform the following steps:

Note

similar instructions applies to other application security subsystems like apparmor. Due to the complexity of these systems this article just mentions the most common issue people run into when building images on systems protected through selinux.

Note

Abstract

This page provides further information how to solve image boot problems if the filesystem tool chain on the image build host is incompatible with the image target distribution

When KIWI NG builds an image which requests the creation of a filesystem, the required filesystem creation tool, for example mkfs.xfs, is called from the host on which KIWI NG gets called. It is expected that the generated filesystem is compatible with the image 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 will not be able to be used on boot:

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 build host distribution is of the same major Linux version than the image target. For this purpose KIWI NG provides the so called boxed-plugin. Further details can be found in Section 6.1, “Building in a Self-Contained Environment”