Pull request #65: Docs/improvements

Merge in ICO/coreos from docs/improvements to master

* commit 'ddf9f9ce44a97ac467c97d90eced9b4924cc389f':
  docs: add a components part
  docs: update the boot chapter to reflect current boot flow

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/boot/bootflow-generic.dot

@@ -5,6 +5,5 @@ digraph G {
     
     os [label = "Operating System";shape = rect;];
     
-    fw -> btl -> os [style = dashed;];
+    fw -> btl -> os;
-    fw -> os;
 }

documentation/boot/bootflow-uboot.dot

@@ -3,7 +3,9 @@ digraph G {
     
     uboot [label = "u-boot with EFI/EBBR support";shape = rect;];
     
+    btl [label = "EFIBootGuard";shape = rect;];
+
     kernel [label = "OS (EFI Stub + Kernel + Initramfs";shape = rect;];
     
-    rom -> uboot -> kernel;
+    rom -> uboot -> btl -> kernel;
 }

documentation/boot/overview.rst

@@ -76,7 +76,7 @@ legacy like:
 - Fixed offsets to firmware data
 
 We require the firmware to provide a DeviceTree based system description and not
-an ACPI based table (as allowed by the specification)
+an ACPI based table (as allowed by the specification).
 
 We also require the firmware to implement the UEFI Secure Boot functionality.
 
@@ -84,15 +84,12 @@ ARM64 / AArch64 based machine
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The firmware for ARM64 should implement a subset of the UEFI specification, as
-defined by the EBBR Specification. The part of the specification marked as
+defined by the EBBR Specification.
-legacy or deprecated must not be used.
-
-This means:
-- Only GPT partionning disk are supported
-- No fixed offsets to firmware data
 
 We require the firmware to provide a DeviceTree based system description and not
-an ACPI based table (as allowed by the specification)
+an ACPI based table (as allowed by the specification). The DeviceTree provided
+by the firmware can be very minimal as it can be replaced at boot time
+by a device-tree contained inside the Operating System Image.
 
 We also require the firmware to implement the UEFI Secure Boot functionality.
 
@@ -105,38 +102,13 @@ The firmware for AMD64 should implement the UEFI specification.
 Bootloader
 ==========
 
-CoreOS only support `systemd-boot` as bootloader. The usage of the bootloader
+CoreOS only support `efibootguard` as bootloader. The usage of the bootloader
-is optional. It's primary use case is for system that don't use a firmware
+is mandated.
-provided by CoreOS.
 
 
 Operating system
 ================
 
-The operating system image is an UEFI application that contain the kernel. We
+The operating system image is an UEFI application that contain the kernel. It's
-support two method to create this image:
+a Unified Kernel Image generated by tools from the EFIBootGuard project.
 
-Unified Kernel Images (UKI)
----------------------------
-
-This is the most secure method. The UEFI entry point is provided by
-`systemd-stub` and the image contains the Linux Kernel, the boot arguments of
-the kernel, the os-release file and an initrd ram disk.
-
-This allows to have all these part authenticated via UEFI secure boot.
-
-.. warning::
-   UKI are not supported for ARM32 target at the moment, due to a bug in objcopy.
-   See https://sourceware.org/bugzilla/show_bug.cgi?id=26218
-
-.. note::
-    UKI has the advantages to be discoverable by the bootloader without any
-    configuration file, and doesn't need a firmware that is able to set the
-    kernel command line.
-
-Kernel built with the built-in EFI sub
---------------------------------------
-
-This method use the EFI stub provided by the kernel. The initramfs image has to
-be bundled with the Kernel, using `INITRAMFS_IMAGE_BUNDLE`, as otherwise it 
-will not be authenticated by UEFI secure boot.

documentation/boot/uboot-dts-handling.dot

@@ -1,16 +0,0 @@
-digraph G {
-    start [label = "boot";];
-    
-    mb [label = "Detect the main board name";shape = rect;];
-    
-    mbdts [label = "Load main board device tree";shape = rect;];
-    
-    ext [label = "Detect the extension module name";shape = rect;];
-    extdts [label = "Load a device tree overlay for each module";shape = rect;];
-    
-    dtsprocess [label = "Add and remove device tree node as needed (DT Fixup)";shape = rect;];
-    
-    stop [label = "Start UEFI application";];
-    
-    start -> mb -> mbdts -> ext -> extdts -> dtsprocess -> stop;
-}

documentation/boot/uboot.rst

@@ -21,13 +21,10 @@ to be changed at runtime.
 Device tree handling
 ====================
 
-As per the EBBR specification, the firmware is responsible to provide the
+As per the EBBR specification, the firmware is responsible to provide a
-device tree to the kernel.
+device tree to the kernel. Not that it's OK to export the device tree used by
-
+U-Boot internally as it will be replaced by a propper device tree at a later
-This means that loading the main device tree and all the device tree overlay are
+stage. This avoid the need to load the device tree from a boot partition.
-is the responsibility of the firmware.
-
-.. graphviz:: uboot-dts-handling.dot
 
 Features to implement per machine
 =================================
@@ -35,19 +32,11 @@ Features to implement per machine
 The u-boot provided by CoreOS should implement the following features for each
 supported machine:
 
-board_fit_config_name_match
-----------------------------
-
-This allows u-boot to select the device tree to use dynamically using board
-detection. See `README.multi-dtb-fit`
-
-
 extension_board_scan
 --------------------
 
 The extension_board_scan function has to be implemented. This function should
-return the list of add-ons board detected, with the filename of the
+return the list of add-ons board detected.
-correspondig device-tree overlay.
 
 DT Fixup
 --------
@@ -55,53 +44,3 @@ DT Fixup
 U-Boot can create, modify and remove node from the device tree dynamically
 before starting the kernel. This can be used to pass dynamic information stored
 inside a "board descriptor" eeprom or CPLD to the Kernel.
-
-Custom Features that are generic
-================================
-
-The u-boot provided by CoreOS should implement the following custom features:
-
-File authentication
--------------------
-
-In order to be able to authenticate device tree, device-tree overlay file or
-other file needed by the firmware, we need a command to authenticate a file that
-was previously loaded is the `load` command. 
-
-.. note::
-
-    My proposal is to use the UEFI Capsule format, to reuse theses function from
-    u-boot:
-
-    - **efi_capsule_authenticate**: Authenticate the UEFI capsule using a x509
-      certificate built into u-boot
-    - **efi_remove_auth_hdr**: Can be used to point a pointer to the start of the
-      content of an authenticated capsule.
-    
-    An UEFI Capsule is a generic container that can be signed using a x.509
-    private key. The public key is stored inside u-boot (it's not the same as
-    the keys used for UEFI secure-boot). See
-    https://u-boot.readthedocs.io/en/v2022.10/develop/uefi/uefi.html?highlight=capsule#enabling-capsule-authentication
-
-
-extension_overlay_cmd
----------------------
-
-A custom command should be made for `extension_overlay_cmd`. The extension
-subsystem use the command defined as extension_overlay_cmd to load
-the overlay `${extension_overlay_name}` into `extension_overlay_addr`
-
-This should reuse the file authentication mechanismus.
-
-.. note::
-
-    A concept on where and how to securly store device tree and overlay needed
-    by the kernel has to be written.
-    
-    My proposal is to use the UEFI Capsule format, to reuse theses function from
-    u-boot:
-
-    - **efi_capsule_authenticate**: Authenticate the UEFI capsule using a x509
-      certificate built into u-boot
-    - **efi_remove_auth_hdr**: Can be used to point a pointer to the start of the
-      content of an authenticated capsule.

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