.. 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.
