Skip to content

Conversation

@poettering
Copy link
Collaborator

This is used by systemd/systemd#36314 to make networking boot work nicely within the BLS constructs.

The "uki" stanza also should have uses in a world where a single UKI shall be invoked by multiple locally defined menu entries, for example on nixos or ostree systems, where each commit shall synthesize a separate menu entry, often referencing the same UKI.


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
Member

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
Collaborator Author

@poettering poettering Feb 13, 2025

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?

poettering added a commit to poettering/systemd that referenced this pull request Feb 13, 2025
This one is between "efi" and "linux": we'll recognize such entries as
linux, but we'll just invoke them as EFI binaries.

This creates a high-level concept for invoking UKIs via indirection of a
bls type #1 entry, for example to permit invocation from a non-standard
path or for giving entries a different name.

Companion BLS spec PR:

uapi-group/specifications#135
poettering added a commit to poettering/systemd that referenced this pull request Feb 13, 2025
poettering added a commit to poettering/systemd that referenced this pull request Feb 13, 2025
This one is between "efi" and "linux": we'll recognize such entries as
linux, but we'll just invoke them as EFI binaries.

This creates a high-level concept for invoking UKIs via indirection of a
bls type #1 entry, for example to permit invocation from a non-standard
path or for giving entries a different name.

Companion BLS spec PR:

uapi-group/specifications#135
poettering added a commit to poettering/systemd that referenced this pull request Feb 13, 2025

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
Member

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
Collaborator Author

@poettering poettering Feb 13, 2025

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
Member

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. :)

poettering added a commit to poettering/systemd that referenced this pull request Feb 13, 2025
This one is between "efi" and "linux": we'll recognize such entries as
linux, but we'll just invoke them as EFI binaries.

This creates a high-level concept for invoking UKIs via indirection of a
bls type #1 entry, for example to permit invocation from a non-standard
path or for giving entries a different name.

Companion BLS spec PR:

uapi-group/specifications#135
poettering added a commit to poettering/systemd that referenced this pull request Feb 13, 2025
poettering added a commit to poettering/systemd that referenced this pull request Feb 13, 2025
This one is between "efi" and "linux": we'll recognize such entries as
linux, but we'll just invoke them as EFI binaries.

This creates a high-level concept for invoking UKIs via indirection of a
bls type #1 entry, for example to permit invocation from a non-standard
path or for giving entries a different name.

Companion BLS spec PR:

uapi-group/specifications#135
poettering added a commit to poettering/systemd that referenced this pull request Feb 13, 2025
poettering added a commit to poettering/systemd that referenced this pull request Feb 17, 2025
This one is between "efi" and "linux": we'll recognize such entries as
linux, but we'll just invoke them as EFI binaries.

This creates a high-level concept for invoking UKIs via indirection of a
bls type #1 entry, for example to permit invocation from a non-standard
path or for giving entries a different name.

Companion BLS spec PR:

uapi-group/specifications#135
poettering added a commit to poettering/systemd that referenced this pull request Feb 17, 2025
poettering added a commit to poettering/systemd that referenced this pull request Feb 20, 2025
This one is between "efi" and "linux": we'll recognize such entries as
linux, but we'll just invoke them as EFI binaries.

This creates a high-level concept for invoking UKIs via indirection of a
bls type #1 entry, for example to permit invocation from a non-standard
path or for giving entries a different name.

Companion BLS spec PR:

uapi-group/specifications#135

(Let's rename LOADER_UNIFIED_LINUX to LOADER_TYPE2_UKI at the same time
to reduce confusion what is what)
poettering added a commit to poettering/systemd that referenced this pull request Feb 20, 2025
poettering added a commit to poettering/systemd that referenced this pull request Feb 20, 2025
This one is between "efi" and "linux": we'll recognize such entries as
linux, but we'll just invoke them as EFI binaries.

This creates a high-level concept for invoking UKIs via indirection of a
bls type #1 entry, for example to permit invocation from a non-standard
path or for giving entries a different name.

Companion BLS spec PR:

uapi-group/specifications#135

(Let's rename LOADER_UNIFIED_LINUX to LOADER_TYPE2_UKI at the same time
to reduce confusion what is what)
poettering added a commit to poettering/systemd that referenced this pull request Feb 20, 2025
poettering added a commit to poettering/systemd that referenced this pull request Feb 21, 2025
This one is between "efi" and "linux": we'll recognize such entries as
linux, but we'll just invoke them as EFI binaries.

This creates a high-level concept for invoking UKIs via indirection of a
bls type #1 entry, for example to permit invocation from a non-standard
path or for giving entries a different name.

Companion BLS spec PR:

uapi-group/specifications#135

(Let's rename LOADER_UNIFIED_LINUX to LOADER_TYPE2_UKI at the same time
to reduce confusion what is what)
poettering added a commit to poettering/systemd that referenced this pull request Feb 21, 2025
@septatrix
Copy link

I think it would be helpful and reduce confusion if the design decisions mentioned in the above reviewed (uki vs uki-url, ":", and http/https) would be added as footnotes or in a closing section similar to the FAQ section of DDI and "Additional discussion" section of the version number spec


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

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

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

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

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

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

julian-klode pushed a commit to ubuntu/stubble that referenced this pull request Aug 1, 2025
This one is between "efi" and "linux": we'll recognize such entries as
linux, but we'll just invoke them as EFI binaries.

This creates a high-level concept for invoking UKIs via indirection of a
bls type #1 entry, for example to permit invocation from a non-standard
path or for giving entries a different name.

Companion BLS spec PR:

uapi-group/specifications#135

(Let's rename LOADER_UNIFIED_LINUX to LOADER_TYPE2_UKI at the same time
to reduce confusion what is what)
julian-klode pushed a commit to ubuntu/stubble that referenced this pull request Aug 1, 2025
Copy link
Member

@keszybz keszybz left a comment

Choose a reason for hiding this comment

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

OK, I think we should merge this.

(I'm still not 100% convinced that : needs to be added, but I don't think it makes sense to bike-shed this.)

This is used by systemd/systemd#36314 to make
networking boot work nicely within the BLS constructs.

The "uki" stanza also should have uses in a world where a single UKI
shall be invoked by multiple locally defined menu entries, for example
on nixos or ostree systems, where each commit shall synthesize a
separate menu entry, often referencing the same UKI.
@poettering
Copy link
Collaborator Author

I made the suggested changes, and will merge now, since they appear minor, and noone seems opposed.

@poettering poettering merged commit 3f2bd82 into uapi-group:main Sep 26, 2025
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Development

Successfully merging this pull request may close these issues.

5 participants