ostree/docs/bootloaders.md

nav_order
120

Bootloaders

{: .no_toc }

1. TOC {:toc}

OSTree and bootloaders

The intended design of OSTree is that it just writes new files into /boot/loader/entries. There is a legacy GRUB script (shipped on Fedora as ostree-grub2) that is intended only for the cases where the system GRUB does not support the blscfg verb.

In the happy path then, the flow of an OS update is just:

• ostree writes a new set of files in /boot/loader/entries (during ostree-finalize-staged.service on system shutdown)
• On system start, GRUB reads those files

And that's it.

OSTree and grub

For historical reasons, OSTree defaults to detecting the bootloader; if some GRUB files are present then OSTree will default to executing grub2-mkconfig.

OSTree and aboot

The Android bootloader is another bootloader than may be used with ostree. It still uses the files in /boot/loader/entries as metadata, but the boootloader does not read these files. Android bootloaders package their kernel+initramfs+cmdline+dtb in a signed binary blob called an Android Boot Image. This binary blob then is written to either partition boot_a or boot_b depending on which slot is suitable.

Android bootloaders by design inject kargs into the cmdline, some patches may be required in the Android bootloader implementation to ensure that the firmware does not switch between system_a and system_b partitions by populating a root= karg, or that a ro karg that is incompatible with ostree is not inserted. Conversly leaving the androidboot.slot_suffix= karg injecting functionality is required but this is commonplace for any Android Bootloader that does AB updates.

We have two accompanying scripts that work with this type of environment:

aboot-update is used to generate Android Boot Images to be delivered to the client.

aboot-deploy reads what the current slot is according to the androidboot.slot_suffix= karg, writes to the alternate boot_a or boot_b slot and sets a symlink either /ostree/root.a or /ostree/root.b so that it is known which userspace directory to boot into based on the androidboot.slot_suffix= karg, on subsequent boots.

+-----------------------------+                            +---------------------------------+
|                             |    +------------------+    |                                 |
|  firmware appends:          |    |                  |    |                                 |
|                             +--->+ boot_a partition +--->+                                 |
|  androidboot.slot_suffix=_a |    |                  |    |                  /ostree/root.a |
|                             |    +------------------+    |                                 |
|  or                         |                            | system_a partition              |
|                             |    +------------------+    |                                 |
|  androidboot.slot_suffix=_b |    |                  |    |                  /ostree/root.b |
|                             +--->+ boot_b partition +--->+                                 |
|  to cmdline                 |    |                  |    |                                 |
|                             |    +------------------+    |                                 |
+-----------------------------+                            +---------------------------------+

GRUB and os-prober

A specific component of GRUB that can significantly impede the reliability of OS updates is the os-prober aspect, which scans all system block devices. If one doesn't care about dual booting, avoiding this is a good idea.

Anaconda

Until very recently, the Anaconda project only supported setting up the bootloader (e.g. GRUB) on its own, which requires grub2-mkconfig etc. As of recently, Anaconda now supports bootupd.

bootupd

As of recently, the bootupd project ships static grub configs and in this case, the sysroot.bootloader should be set to none (except on s390x). And assuming that the system grub has the blscfg support, which it does on Fedora derivatives per above.