docs: add a components part

documentation/_static/css/coreos.css

@@ -0,0 +1,6 @@
+
+/* Make tables more convenient by wrapping line instead of using an
+   horizontal scrollbar */
+.wy-table-responsive table td, .wy-table-responsive table th {
+    white-space: normal;
+}

documentation/components/core/efibootguard.rst

@@ -0,0 +1,104 @@
+.. index:: EFIBOOTGUARD
+
+Bootloader: EFIBootGuard
+************************
+
+CoreOS use `EFIBootGuard <https://github.com/siemens/efibootguard>`_ as a
+bootloader. EFIBootGuard is the components responsible to find and load the
+right Unified Kernel Image (UKI).
+
+Installation
+------------
+
+EFIBootGuard is an UEFI application. It's installed inside the EFI System
+Partition at:
+
+.. list-table::
+   :widths: 25 25
+   :header-rows: 1
+
+   * - Platform Architecture
+     - Path
+   * - ARM32
+     - /EFI/BOOT/bootarm.efi
+   * - ARM64
+     - /EFI/BOOT/bootaa64.efi
+   * - x86_64
+     - /EFI/BOOT/bootax64.efi
+
+Workflow
+--------
+
+Configuration lookup
+~~~~~~~~~~~~~~~~~~~~
+
+When started, EFIBootGuard will scan all vFAT partition to list all the valid 
+boot partition.
+
+A valid boot partition is a vFAT partition that contain a valid BGENV.DAT file.
+
+This file contains the following parameters:
+
+- Path to a Kernel file
+- Parameter to pass to the kernel
+- Flag for in progress update
+- Update Status (OK, INSTALLED, TESTING, FAILED)
+- Watchdog timeout
+- Revision numbers
+- User data (not used)
+
+Consistency of the configuration is guaranteed by a CRC check.
+
+.. hint::
+   CoreOS use a signed Unified Kernel Image that embed the parameters to pass
+   to the Linux Kernel. Parameters from the UKI always override parameters
+   set inside the EFIBootGuard configuration file.
+
+   This is a security measure to ensure that only a signed kernel parameters is
+   used (secure boot).
+
+Booting
+~~~~~~~
+
+EFIBootGuard will try to load a kernel using the parameters from the
+configuration with the higher revision number.
+
+Update Handling
+~~~~~~~~~~~~~~~
+
+Before booting, EFIBootGuard will check the state flags inside the configuration
+file.
+
+If it's OK it means that it's a valid configuration.
+
+If the state is INSTALLED, it's mean that a new image was flash but was never
+booted. EFIBootGuard will change the state to TESTING then boot the kernel.
+
+If the state is TESTING, it's mean that the kernel was already booted one time,
+but the running system has not marked the update as working. EFIBootGuard will
+set the status to FAILED and set the revision number to 0 and boot another 
+configuration.
+
+.. hint::
+   To mark the update as working from a running system, you can use the
+   following command::
+
+    bg_setenv --confirm
+
+   This should be done after an update to tell the bootloader that the new
+   system image is working. CoreOS doesn't do it automatically for now.
+
+Known Issues
+------------
+
+.. list-table::
+   :widths: 15 85
+   :header-rows: 1
+
+   * - Bugs
+     - Description
+   * - `#370558 <https://tp.gad.local/entity/370558>`_
+     - On machine use a Marvel CN913x CPU like the cn9130-cf-pro machine, the version
+       of U-Boot provided don't provide the UEFI api needed by EFIBootGuard to update
+       his configuration file at boot time. EFIBootGuard is not able to detect
+       a failed update.

documentation/components/core/index.rst

@@ -0,0 +1,15 @@
+
+======================
+CoreOS Core Components
+======================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   Firmware: U-Boot <u-boot>
+   Bootloader: EFIBootGuard <efibootguard>
+   Kernel: Unified Kernel Image <kernel>
+   Init System: SystemD <systemd>

documentation/components/core/kernel.rst

@@ -0,0 +1,27 @@
+.. index:: UKI
+
+Kernel: Unified Kernel Image
+*****************************
+
+CoreOS use by default a `Unified Kernel Image (UKI) <https://github.com/siemens/efibootguard/blob/master/docs/UNIFIED-KERNEL.md>`_
+generated by tools from the EFIBootGuard project.
+
+An UKI is a EFI app that load in memory multiple artifacts needed by the Linux
+Kernel before loading and booting the Linux Kernel itself:
+
+* The kernel commands line is always loaded from the UKI
+* A device-tree file: UKI can contain multiple UKI and will load the one
+  matching the device-tree file passed by the firmware. 
+
+Known Issues and unimplemented feature
+--------------------------------------
+
+.. note::
+
+   Bundling an INITRD image into the UKI is not implemented yet.
+
+.. danger::
+
+   The Unified Kernel Image is signed but CoreOS currently provide no way to
+   verify the integrity of the choosed ROOTFS partition as CoreOS doesn't
+   provide an end-to-end secure boot solution yet.

documentation/components/core/systemd.rst

@@ -0,0 +1,7 @@
+.. index:: SYSTEMD
+
+Init System: SystemD
+********************
+
+`SystemD <https://www.freedesktop.org/wiki/Software/systemd/>`_ is used as
+init system in CoreOS.

documentation/components/core/u-boot.rst

@@ -0,0 +1,46 @@
+.. index:: UBOOT
+
+Firmware: U-Boot
+****************
+
+.. hint::
+   CoreOS should work with any UEFI compliant firmware. Using U-Boot is not 
+   mandatory.
+
+`U-Boot <https://u-boot.readthedocs.io/en/latest/>`_ is built by default with
+UEFI enabled and secure boot enabled. UEFI secure boot related keys are
+installed at build time and can't be changed from the U-Boot command line.
+
+Workflow
+--------
+
+U-Boot will boot the default UEFI application from the EFI System Partition.
+
+The path to the default UEFI application is architecture dependent:
+
+.. list-table::
+   :widths: 25 25
+   :header-rows: 1
+
+   * - Platform Architecture
+     - Path
+   * - ARM32
+     - /EFI/BOOT/bootarm.efi
+   * - ARM64
+     - /EFI/BOOT/bootaa64.efi
+   * - x86_64
+     - /EFI/BOOT/bootax64.efi
+
+Known Issues
+------------
+
+.. danger::
+
+   The U-Boot configuration used by CoreOS currently was not reviewed for
+   security issue and is not safe (access to u-boot command line is allowed).
+
+.. danger::
+
+   CoreOS U-Boot configuration enable UEFI Secure Boot but the U-Boot binary
+   itself is not validated. Thus we don't provide a full end-to-end secure boot
+   solution yet.

documentation/components/optional/index.rst

@@ -0,0 +1,14 @@
+
+==========================
+CoreOS Optional Components
+==========================
+
+|
+
+.. toctree::
+   :caption: Table of Contents
+   :numbered:
+
+   Network Manager: NetworkManager <networkmanager>
+   SSH Server: OpenSSH <openssh>
+   Container: Podman <podman>

documentation/components/optional/networkmanager.rst

@@ -0,0 +1,10 @@
+.. index:: NETWORKMANAGER
+
+Network Manager: NetworkManager
+*******************************
+
+You can add `NetworkManager <https://networkmanager.dev/>`_ to an image that
+inherit from `coreos-image` by adding::
+
+    IMAGE_FEATURES += "networkmanager"
+

documentation/components/optional/openssh.rst

@@ -0,0 +1,9 @@
+.. index:: OPENSSH
+
+SSH Server: OpenSSH
+*******************
+
+You can add an `OpenSSH <https://www.openssh.com/>`_ based ssh server to an
+image that inherit from `coreos-image` by adding::
+
+    IMAGE_FEATURES += "ssh-server"

documentation/components/optional/podman.rst

@@ -0,0 +1,9 @@
+.. index:: PODMAN
+
+Container: Podman
+*****************
+
+You can add `Podman <https://podman.io/>`_ to an image that inherit from
+`coreos-image` by adding::
+
+    IMAGE_FEATURES += "podman"

documentation/conf.py

@@ -112,6 +112,10 @@ except ImportError:
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
+html_css_files = [
+    'css/coreos.css',
+]
+
 # Hide 'Created using Sphinx' text
 html_show_sphinx = False
 

documentation/index.rst

@@ -26,6 +26,14 @@ same structures.
    Setting up a CoreOS based distro <using-coreos>
    Building and using a Container Image <using-container>
 
+.. toctree::
+   :maxdepth: 1
+   :caption: Software Components
+
+   Core Components <components/core/index>
+   Optional Components <components/optional/index>
+
+
 .. toctree::
    :maxdepth: 1
    :caption: Manuals