From 4faf993ca5d4b113243cd17601c5cdf5055fb2a0 Mon Sep 17 00:00:00 2001 From: River Date: Thu, 10 Apr 2025 11:09:21 -0400 Subject: [PATCH] Add A/B Updates and Provisioning --- A%2FB-Updates-and-Provisioning.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 A%2FB-Updates-and-Provisioning.md diff --git a/A%2FB-Updates-and-Provisioning.md b/A%2FB-Updates-and-Provisioning.md new file mode 100644 index 0000000..43c9a1b --- /dev/null +++ b/A%2FB-Updates-and-Provisioning.md @@ -0,0 +1,27 @@ +# A/B Updates and Provisioning + +Like Android, HalogenOS uses A/B updates to ensure the system remains bootable if an update fails, is interrupted, or if a partition is tampered with. + +## Updates + +Here's how an update works in HalogenOS: + +- The system notices a new update is available on the server. +- The latest release files are downloaded to a persistent temporary directory. +- Each release file is validated using the release key burned into the system partition. +- The inactive slot is located, and the system partition and verity images are burned. +- A kernel EFI binary pointing to the inactive slot is deployed in the boot partition. +- The new kernel binary is signed using the locally generated secure boot keys. +- The user is prompted to reboot as soon as possible, or a reboot is triggered automatically. +- The new system partition updates the bootloader, and other files on the root partition. +- The stored release files are validated again and used to update the newly inactive slot. + +## Installation + +Since the system only needs one working slot to operate, then installation can be completed by merely flashing a single system partition and verity image, and dropping the appropriate files into the boot partition. The newly booted system will automatically create the second system partition, the root partition with its encryption key, and secure boot keys with which it will sign all the boot EFI binaries. Any files that must reside in `/etc` can either be copied from, or linked to, `/usr/etc` on boot. As such, to reset the system, it is sufficient to destroy the encryption header for the root partition, then reboot. Automatic provisioning will restore the system layout on reboot. + +## Failure Recovery + +When a kernel EFI binary is installed in the boot partition, a counter is appended to its file name. Every time the bootloader loads this kernel, it decrements the counter. Once the system is fully booted and known to work, it re-increments this counter. If the counter for a given kernel ever reaches zero, the bootloader will switch over to the other kernel. From there, a valid system is available, which will automatically repair the broken slot. + +To avoid nullifying the benefits of this scheme, the initial bootloader that handles the A/B logic will be updated infrequently, tested heavily, and written purely in Rust to avoid memory-related failures. The old bootloader can also be maintained on the boot partition as a backup, available to load the OS proper if the user chooses its boot entry. \ No newline at end of file