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
This commit is contained in:
Marcus Schäfer
parent
af27425a85
commit
a9eec5f71c
@ -116,6 +116,8 @@ Embedded Systems
|
||||
And More
|
||||
...
|
||||
|
||||
.. _contact:
|
||||
|
||||
Contact
|
||||
-------
|
||||
|
||||
|
||||
@ -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
|
||||
--------------
|
||||
|
||||
|
||||
@ -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 <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
|
||||
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
|
||||
|
||||
45
doc/source/troubleshooting/architectures.rst
Normal file
45
doc/source/troubleshooting/architectures.rst
Normal file
@ -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
|
||||
28
doc/source/troubleshooting/buildhost_constraints.rst
Normal file
28
doc/source/troubleshooting/buildhost_constraints.rst
Normal file
@ -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 <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
|
||||
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.
|
||||
63
doc/source/troubleshooting/security.rst
Normal file
63
doc/source/troubleshooting/security.rst
Normal file
@ -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`.
|
||||
Loading…
Reference in New Issue
Block a user