HalogenOS Image Builder

This repository is the primary set of instrumentation used to build and distribute signed updates and installation images for HalogenOS.

What is it?

This repo holds a set of files necessary for creating bootable HalogenOS images. This includes:

• A Docker Compose file, defining a Gentoo build environment and a web server for distribution
• Scripts that build, sign, and distribute HalogenOS images
• Package lists
• Configuration files
• Submodules that contain code for binaries

These files allow a server to build a working image, sign it with a release key, and distribute it to clients running HalogenOS configured to update from that server. Performing updates on the server side allows for easier testing, development, and reproducibility, while removing complexity and performance demands from clients.

Configurations

There are a few overridable variables that control configuration elements of HalogenOS. These are set at build time, and are permanently immutable throughout the lifetime of the OS, unless the values are changed, the image is rebuilt with the same keys and URL, and the installation is updated.

• MINOR: Default is 00. It is a decimal number representing how many releases have been built before the current one on a given calendar day. Increment by 1 every time an image finishes building.
• DISTURL: Unset by default. The URL that HalogenOS files will be served at. If it is not set, OTA updates from a server are disabled, but updating can be done manually as long as the images are signed.
• TPM: Default is true. This will control automatic decryption of the root partition. Disable if your system does not have TPM 2.0, or if you would rather manually input your root encryption password.
• SECBOOT: Default is true. This will control whether or not Secure Boot keys are generated and enrolled. Disable if your system does not support Secure Boot.
• REQSIG: Default is true. This will control whether or not update images and overlays require signatures. Disable ONLY for testing or development purposes.

Disabling SECBOOT or REQSIG sets a flag in the system partition indicating that the installation has a fundamentally insecure configuration, as important system files could be tampered with easily.

Signing Keys

Unless you disable REQSIG, HalogenOS will require a signing key for updates and for overlays. If you do disable REQSIG, HalogenOS will still attempt to verify updates and overlays, but will not enforce these checks, and will not panic if there is no public signing key. To totally disable the inclusion of the signing key, you must remove signing_key_public from build in compose.yml.