HalogenOS/image-builder
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add A/B Updates and Provisioning

River 2025-04-10 11:09:21 -04:00
parent 2ca356ec24
commit 4faf993ca5
1 changed files with 27 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
A%2FB-Updates-and-Provisioning.md Normal file

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