UKI Addons Support by Johan-Liebert1 · Pull Request #2448 · bootc-dev/bootc

Johan-Liebert1 · 2026-09-10T10:31:18Z

uki-addon: Update addons on update/switch

Introduce a function to gather all currently installed addons, scoped
and global. On upgrade/switch, gather all installed addons and if an
addon with the same name is found in the upgrade image, update that
particular addon automatically

uki/addon: Support global addons

We were partially supporting global addons, but they were lumped in with
scoped/local addons. Add a new cli option to composefs installs called
--global-uki-addon which would determine which global addon to
install.

cfs/upgrade/switch: Handle UKI Addons

Here is what we do now with UKI Addons

Accept --uki-addon and --global-uki-addon cli options for bootc
switch/upgrade commands
If we find an installed addon with the same name as the one in the new
image, we update it

global-uki-addons: Add prefix to name

Prefix global addon filenames with the bootc identifier in the ESP so
we can distinguish bootc-managed global addons from third-party ones

uki-addon: Add CLI for managing UKI Addons

Add bootc uki-addon subcommand with three operations:

bootc uki-addon list: List installed UKI addons
Supports --json for JSON output
bootc uki-addon add <name> <global|scoped>: Install an addon from
the booted image onto the ESP
bootc uki-addon remove <name> [deployment_id]: Remove an addon

Add Display and Serialize to UkiAddonType/UkiAddonsList

supakeen · 2026-09-11T11:11:42Z

Can we install UKI addons as part of a deployment with bootc install? These are (sometimes) used to have addons for mount options so the UKI isn't tightly coupled to a specific disk layout.

cgwalters · 2026-09-11T19:39:42Z

+pub(crate) enum UkiAddonCliOpts {
+    /// List all installed UKI Addons
+    List {
+        /// Output in JSON format


cgwalters · 2026-09-11T19:42:07Z

+    /// This option can be provided multiple times if multiple addons are to be installed.
+    #[clap(long = "uki-addon")]
+    #[serde(default)]
+    pub(crate) scoped: Option<Vec<String>>,


BTW ideally we validate these eagerly at install time

Yeah. I'll add these to the UKI installation flow we have currently

On second thoughts, would you be fine with this as a follow up? This PR's getting huge as is, and this requires some refactoring in the prepare_install function

Oh yeah for sure can be a followup

cgwalters · 2026-09-11T19:43:40Z

Can we install UKI addons as part of a deployment with bootc install?

That's in the docs here right?

cgwalters · 2026-09-11T19:44:38Z

Or well actually, I think what you may be asking about is external UKI addons (i.e. not included in the container image), in which case it would totally make sense to do.

supakeen · 2026-09-12T05:54:06Z

Or well actually, I think what you may be asking about is external UKI addons (i.e. not included in the container image), in which case it would totally make sense to do.

Yea I wasn't super clear but that was what I was thinking about 🙂

cgwalters

How about bootc install --included-uki-addon foo --external-uki-addon /path/to/external.efi i.e. we always disambiguate between internal and external?

cgwalters · 2026-09-15T14:44:35Z

+# Global addon: lives in loader/addons/, loaded by every UKI ergo every deployment
+mkdir -p /out/loader/addons
+ukify build --cmdline 'custom_param=value' \
+    --output /out/loader/addons/site-config.addon.efi


Uh is /loader right here?

yes, the global addons go in /boot/loader/addons where /boot is the ESP. I made this changes in finalize-uki

One thing I find hard to understand here is where the somewhat bespoke build system we've grown stops and where the actual APIs we're offering starts.

It feels weird to me to use /boot/loader here, shouldn't the addons live literally right next to the UKI?

It feels weird to me to use /boot/loader here, shouldn't the addons live literally right next to the UKI?

that's true for scoped UKI addons, but global addons do live in /boot/loader

From https://www.freedesktop.org/software/systemd/man/latest/systemd-stub.html

Addon files are sorted, loaded, and measured into TPM PCR 12 (if a TPM is present) and appended to the kernel command line. UKI command line options are listed first, then options from addons in /loader/addons/*.addon.efi, and finally UKI-specific addons. [...] Additionally, files /loader/addons/*.addon.efi are loaded and verified as PE binaries, and ".cmdline", ".dtb", ".initrd", and ".ucode" sections are parsed from them.

Johan-Liebert1 · 2026-09-15T15:27:30Z

How about bootc install --included-uki-addon foo --external-uki-addon /path/to/external.efi i.e. we always disambiguate between internal and external?

I don't understand what we mean by external here? I'm guessing it doesn't mean "global" addons

cgwalters · 2026-09-15T15:41:11Z

external ➡️ #2448 (comment)

Introduce a function to gather all currently installed addons, scoped and global. On upgrade/switch, gather all installed addons and if an addon with the same name is found in the upgrade image, update that particular addon automatically Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

We were partially supporting global addons, but they were lumped in with scoped/local addons. Add a new cli option to composefs installs called `--global-uki-addon` which would determine which global addon to install. Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Here is what we do now with UKI Addons - Accept `--uki-addon` and `--global-uki-addon` cli options for bootc switch/upgrade commands - If we find an installed addon with the same name as the one in the new image, we update it Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Assisted-by: AI Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Prefix global addon filenames with the bootc identifier in the ESP so we can distinguish bootc-managed global addons from third-party ones Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Add `bootc uki-addon` subcommand with three operations: - `bootc uki-addon list`: List installed UKI addons Supports `--json` for JSON output - `bootc uki-addon add <name> <global|scoped>`: Install an addon from the booted image onto the ESP - `bootc uki-addon remove <name> [deployment_id]`: Remove an addon Add Display and Serialize to UkiAddonType/UkiAddonsList Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

- Add GC tests for Addons - Add CLI tests Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Mark UKI Addons as experimental Assisted-by: Claude-Code (Opus) Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

UkiAddonOpts is now flattened into both upgrade and switch commands, which don't have a --composefs-backend flag. The `requires = "composefs_backend"` constraint causes a panic at clap validation time because the referenced argument doesn't exist in those command contexts. This is generally safe as the options are ignored for ostree installs anyway Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Extract cmdline parsing from write_pe_to_esp into parse_uki_cmdline so it runs for both the UKI and UKI addons. The `composefs=` parameter can now be found in the main UKI or a scoped addon - At most one composefs= cmdline across all PE binaries (UKI + addons). A second one is rejected even if the digest matches. - Global UKI addons must never contain `composefs=` cmdline - At least one `composefs=` cmdline must be found or the install fails Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Before removing a scoped addon, parse its PE binary and check for a composefs= kernel parameter. If found, early exit as removing that addon would make the system unbootable Global addons are not checked because `composefs=` is rejected at install time for global addons Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Test that bootc rejects composefs= in the wrong places - Build a global addon containing composefs= from `bootc compute-composefs-digest`, attempt switch with --global-uki-addon, assert failure - Build a scoped addon containing composefs= alongside the UKI (which already has it), attempt switch with --uki-addon, assert failure due to duplicate composefs= It's a shame that we can't test UKI Addon only cmdline without piling on a bunch of hacks since `bootc container ukify` unconditionally puts the cmdline inside the UKI Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

This option lists all the UKI Addons across all deployments. Also, it associates global addons with the deployments that reference them. It is useful for GC-ing global UKI Addons if no deployments refer to them Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Similar to how we GC UKIs and scoped UKI Addons, GC Global UKI addons if we have no EROFS images remaining that hold a reference to them, which means that the deployments that depended on the Global addons have been removed Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Johan-Liebert1 requested a review from cgwalters September 10, 2026 10:31

github-actions Bot added area/install Issues related to `bootc install` area/documentation Updates to the documentation labels Sep 10, 2026

Johan-Liebert1 mentioned this pull request Sep 10, 2026

Install UKI Addons globally #1780

Closed

Johan-Liebert1 force-pushed the uki-addon-full-support branch 2 times, most recently from 2579e09 to e31ce45 Compare September 11, 2026 07:44

cgwalters reviewed Sep 11, 2026

View reviewed changes

Johan-Liebert1 force-pushed the uki-addon-full-support branch 3 times, most recently from 3422e57 to 4b63be2 Compare September 15, 2026 12:58

Johan-Liebert1 requested a review from cgwalters September 15, 2026 13:00

cgwalters reviewed Sep 15, 2026

View reviewed changes

Johan-Liebert1 added 4 commits September 16, 2026 07:55

tmt: Add tests for UKI Addons

66b1170

Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Johan-Liebert1 force-pushed the uki-addon-full-support branch from 4b63be2 to bcafaf3 Compare September 16, 2026 02:25

Johan-Liebert1 added 7 commits September 16, 2026 07:58

uki-addon: Add docs for UKI Addons

0ccb297

Assisted-by: AI Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

global-uki-addons: Add prefix to name

2778544

Prefix global addon filenames with the bootc identifier in the ESP so we can distinguish bootc-managed global addons from third-party ones Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

tmt: Update UKI Addon tests

69b2385

- Add GC tests for Addons - Add CLI tests Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

manpage: Update manpages for uki-addons

dfcf909

Mark UKI Addons as experimental Assisted-by: Claude-Code (Opus) Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

uki-addon: Remove addon dir if empty

256fdb6

Signed-off-by: Pragyan Poudyal <pragyanpoudyal41999@gmail.com>

Johan-Liebert1 added 4 commits September 16, 2026 07:58

Johan-Liebert1 force-pushed the uki-addon-full-support branch from bcafaf3 to 77db443 Compare September 16, 2026 02:28

kitten-lily mentioned this pull request Sep 16, 2026

Track bootc UKI addon support starlit-os/krytis#545

Open

4 tasks

Johan-Liebert1 requested a review from cgwalters September 16, 2026 09:31

Johan-Liebert1 force-pushed the uki-addon-full-support branch from 77db443 to b3b9d76 Compare September 16, 2026 10:21

Johan-Liebert1 force-pushed the uki-addon-full-support branch from b3b9d76 to 3ca9715 Compare September 16, 2026 11:40

Uh oh!

Conversation

Johan-Liebert1 commented Sep 10, 2026

Uh oh!

supakeen commented Sep 11, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

cgwalters commented Sep 11, 2026

Uh oh!

cgwalters commented Sep 11, 2026

Uh oh!

supakeen commented Sep 12, 2026

Uh oh!

cgwalters left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Johan-Liebert1 commented Sep 15, 2026

Uh oh!

cgwalters commented Sep 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants