From a9eec5f71cf0d15e6190fbb501007bd2b5deb4f7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marcus=20Sch=C3=A4fer?= Date: Wed, 15 Dec 2021 22:17:11 +0100 Subject: [PATCH] Update documentation Rework troubleshooting chapter and add an article about app security subsystems like selinux and their potential influence on building images. Also update the quickstart with a reference to the troublshooting chapter. This Fixes #1891 --- doc/source/index.rst | 2 + doc/source/quickstart.rst | 13 +++- doc/source/troubleshooting.rst | 78 ++----------------- doc/source/troubleshooting/architectures.rst | 45 +++++++++++ .../troubleshooting/buildhost_constraints.rst | 28 +++++++ doc/source/troubleshooting/security.rst | 63 +++++++++++++++ 6 files changed, 152 insertions(+), 77 deletions(-) create mode 100644 doc/source/troubleshooting/architectures.rst create mode 100644 doc/source/troubleshooting/buildhost_constraints.rst create mode 100644 doc/source/troubleshooting/security.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index ba026b80..98ed763c 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -116,6 +116,8 @@ Embedded Systems And More ... +.. _contact: + Contact ------- diff --git a/doc/source/quickstart.rst b/doc/source/quickstart.rst index 09115b93..33ebad63 100644 --- a/doc/source/quickstart.rst +++ b/doc/source/quickstart.rst @@ -5,9 +5,9 @@ Quick Start .. note:: **Abstract** - This document describes how to start working with {kiwi}, an OS appliance - builder. - This description applies for version |version|. + This document describes how to start working with {kiwi}, + an OS appliance builder. This description applies for + version |version|. Before you start ---------------- @@ -26,6 +26,12 @@ Before you start $ git clone https://github.com/OSInside/kiwi +.. note:: + + In case the following procedure causes any trouble + please take a look at the :ref:`troubleshooting` chapter + and/or reach out at: :ref:`contact` + Choose a First Image -------------------- @@ -61,7 +67,6 @@ If you don't wish to create a openSUSE Leap {exc_os_version} image, substitute the folder following the ``--description`` option with another folder that contains the image description which you selected. - Run your Image -------------- diff --git a/doc/source/troubleshooting.rst b/doc/source/troubleshooting.rst index 7b537352..516e1b70 100644 --- a/doc/source/troubleshooting.rst +++ b/doc/source/troubleshooting.rst @@ -1,3 +1,5 @@ +.. _troubleshooting: + Troubleshooting =============== @@ -11,77 +13,7 @@ Troubleshooting .. toctree:: :maxdepth: 1 + troubleshooting/buildhost_constraints + troubleshooting/architectures + troubleshooting/security troubleshooting/filesystems - -.. _supported-distributions: - -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 -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: - -* The Open Build Service `OBS `__. -* 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 -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. - -Architectures -------------- - -As described in the section above 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} also supports other architectures, shown in the -table below: - -.. table:: - :align: left - - +--------------+---------------------+ - | Architecture | Supported | - +==============+=====================+ - | x86_64 | yes | - +--------------+---------------------+ - | ix86 | yes **note:distro** | - +--------------+---------------------+ - | s390/s390x | yes **note:distro** | - +--------------+---------------------+ - | arm/aarch64 | yes **note:distro** | - +--------------+---------------------+ - | ppc64 | yes **note:distro** | - +--------------+---------------------+ - -.. admonition:: distro - - 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 diff --git a/doc/source/troubleshooting/architectures.rst b/doc/source/troubleshooting/architectures.rst new file mode 100644 index 00000000..10324971 --- /dev/null +++ b/doc/source/troubleshooting/architectures.rst @@ -0,0 +1,45 @@ +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. + +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} also supports other architectures, shown in the +table below: + +.. table:: + :align: left + + +--------------+---------------------+ + | Architecture | Supported | + +==============+=====================+ + | x86_64 | yes | + +--------------+---------------------+ + | ix86 | yes **note:distro** | + +--------------+---------------------+ + | s390/s390x | yes **note:distro** | + +--------------+---------------------+ + | arm/aarch64 | yes **note:distro** | + +--------------+---------------------+ + | ppc64 | yes **note:distro** | + +--------------+---------------------+ + +.. admonition:: distro + + 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 diff --git a/doc/source/troubleshooting/buildhost_constraints.rst b/doc/source/troubleshooting/buildhost_constraints.rst new file mode 100644 index 00000000..2e7ccb73 --- /dev/null +++ b/doc/source/troubleshooting/buildhost_constraints.rst @@ -0,0 +1,28 @@ +.. _supported-distributions: + +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 +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: + +* The Open Build Service `OBS `__. +* 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 +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. diff --git a/doc/source/troubleshooting/security.rst b/doc/source/troubleshooting/security.rst new file mode 100644 index 00000000..3f576aae --- /dev/null +++ b/doc/source/troubleshooting/security.rst @@ -0,0 +1,63 @@ +Host Security Settings Conflicts with KIWI +========================================== + +.. 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} +to do its job is to run it through `boxbuild` as explained in +:ref:`self_contained` + +For users who can afford to open the system security policy, +the following procedure will make {kiwi} to work: + +.. code:: bash + + sudo setenforce 0 + +This action disables selinux temporary. 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` +3. Change the value to disabled: + + .. code:: bash + + SELINUX=disabled + +4. On the next reboot, SELinux is permanently disabled. + +.. 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`.