Skip to content

bls: introduce "uki" and "uki-url" keys to the BLS spec #135

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
poettering merged 1 commit into from
Sep 26, 2025
Merged

bls: introduce "uki" and "uki-url" keys to the BLS spec #135

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 34 additions & 4 deletions specs/boot_loader_specification.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,6 +279,36 @@ The following keys are recognized:
* `efi` refers to an arbitrary EFI program. If this key is set, and the system
is not an EFI system, this entry should be hidden.

* `uki` is a combination of the `linux` key, the `efi` key and Type #2 semantics: if this key is used the
specified path shall refer to a [unified kernel image (UKI)](unified_kernel_image.md). This informs the
boot loader to use UKI semantics (as exposed by Type #2) even though it is referenced via a Type #1
entry. This is useful to parameterize the UKI differently, to place it in a directory other than
`/EFI/Linux`, or to share a single UKI image among multiple menu entries.

If this key is set, and the system is not an EFI system, this entry should be hidden.

Example: `uki /fooos/bar.efi`

* `uki-url` is similar to `uki`, but takes an RFC 3986 URI instead of a file path. It may be used to
Copy link
Copy Markdown
Member

@behrmann behrmann Feb 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Since the RFC is referenced here, I wonder, does it need both keys uki and uki-url? Since the URIs have a scheme, uki-url file:///fooos/bar.efi should have the same semantics as above, no? One could document that without a scheme prefixed file:// is implied.

Copy link
Copy Markdown
Collaborator Author

@poettering poettering Feb 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

file:// is weird, it has a "host" anchor which noone knows what it's relative to. the type 1 stanzas such as linux/initrd/efi so far made very clear that they are relative to the ESP or the partition the snippets are placed in. you cannot really express that with file://.

the reason i split uki from uki-url is mostly for the same disambiguation reasons described above, also i figured it's a good idea to distinguish "network boot" from "regular boot" with a very high-level construct, i.e. via a stanza. or to say this differently, if we'd shoehorn uri support into uki, then people would want it for initrd and linux and efi too, and I'd really like to avoid that. or with other words: i think it should be a property of an entry as a whole whether it is network based, not of the individual files listed therein, if that makes sense?

Copy link
Copy Markdown
Member

@behrmann behrmann Feb 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm fine with that reasoning.

My implicit assumption was, that file:// in this context would anchor at the ESP like the other ones, since everything else would be confusing, i.e. seeing the firmware as a host on its own, with the ESP as its root.

When people would ask for network support for linux, initrd and friends, I'd politely point them to ipxe. :)

Copy link
Copy Markdown

@arianvp arianvp Jun 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

IPXE supports specifiers in URLs e.g.

#!ipxe
initrd http://myserver.com/initrd?uuid=${uuid}&mac=${mac:hexhyp}
kernel https://myserver.com/vmlinuz?uuid=${uuid}&mac=${mac:hexhyp}

which is great in datacenters as you can serve specific images for specific servers dynamically and assign roles to specific servers in your control plane and then just reboot to re-provision
e.g. with https://matchbox.psdn.io/matchbox/

Can we do something similar here?

Copy link
Copy Markdown

@arianvp arianvp Jun 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So a specifier for the machine-id and maybe the SMBIOS UUID (Though perhaps those are the same when SMBIOS UUID is available?)

Copy link
Copy Markdown

@arianvp arianvp Jun 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fits in nicely with: systemd/systemd#32086 because then the machine id and the SMBIOS UUID match

Copy link
Copy Markdown

@arianvp arianvp Jun 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Though I guess if you already have a machine-id stanza in your boot entry you might as well manually copy it into the uki-url field as well...

reference remotely stored UKIs, which shall be downloaded using network boot support of the boot loader or
firmware on activation.

Example: `uki-url http://example.com/fooos.efi`

Optionally, in place of an URL a simple filename prefixed with `:` may be specified. In this case, if the
Copy link
Copy Markdown
Member

@keszybz keszybz Feb 13, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Normally URLs work the way that a relative path is relative to the originating document, with no special prefix. This : is rather ugly… If we have a separate uki-url key, then we don't need specify :. In fact, it'd be better to follow normal HTTP rules, and allow /some/path to refer to the an absolute path on the same server, foo/bar to refer to a path relative to the bootloader (our "originating document"), and http://some.address/full/url for full URLs.

Copy link
Copy Markdown
Collaborator Author

@poettering poettering Feb 13, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the only reason i did the : thing is that I am talking about url here, not http. So this could in theory be anything, i.e. nvmet:, iscsi: nfs: or ftp: or even file: or anyhting else even.

But if you read the rfc spec you'll find that they generically only say <scheme>:<scheme specific part> as syntax, which makes it really hard to distinguish simple file names from full urls... i.e. is "nvmet:192.168.1.1" a file or an url? it's not that obvious to me...

for web stuff, they know they know much better what to look for in an url than what we do, i.e. they know it's pretty much about http:// and https://, so they can look for that. but for boot stuff it would suck to build such a db of url prefixes, I doubt it's realistic.

hence i opted for the : prefix, because the URI RFC says the scheme must be ALPHA *( ALPHA / DIGIT / "+" / "-" / "." ), i.e. not :. And thus there is no ambiguity anymore, for any string we can clearly say "this should be interpreted as URI" and "that should be interpreted as filename".

does that make sense?

boot loader itself was booted via the network and knows its originating URL it shall replace the last
path component of that URL (i.e. the filename part) with the specified filename.

Example: `uki-url :fooos.efi`

This example would mean: if the boot loader was acquired from `http://example.com/somedir/fooosbootldr.img`
Comment thread
keszybz marked this conversation as resolved.
such a line would be treated equivalent to `uki-url http://example.com/somedir/fooos.efi`.

If this key is set, and the system is not an EFI system, or the boot loader/firmware does not support
network booting, this entry *shall* be hidden. Similarly, if the `:` syntax is used, but the boot loader
was not invoked via network booting (or doesn't know its originating URL) entries of this type *shall* be
hidden.

* `options` shall contain kernel parameters to pass to the Linux kernel to
spawn. This key is optional and may appear more than once in which case all
specified parameters are combined in the order they are listed.
Expand Down Expand Up @@ -318,10 +348,10 @@ key. Here is an example for a complete drop-in file:
linux /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/linux
initrd /6a9857a393724b7a981ebb5b8495b9ea/3.8.0-2.fc19.x86_64/initrd

On EFI systems all Linux kernel images should be EFI images. In order to
increase compatibility with EFI systems it is highly recommended only to
install EFI kernel images, even on non-EFI systems, if that's applicable and
supported on the specific architecture.
On EFI systems all Linux kernel images *should* be EFI PE images, or in case of the `uki` or `uki-url` key
*must* be EFI PE images conforming to the [UKI Specification](unified_kernel_image.md). In order to increase
compatibility with EFI systems it is highly recommended only to install EFI kernel images, even on non-EFI
systems, if that's applicable and supported on the specific architecture.

Conversely, in order to increase compatibility it is recommended to install
generic kernel images that make few assumptions about the firmware they run on,
Expand Down