Training Example: systemd – Review the Data, Give Your Score & Compare to the Real AI Evaluation

[H1] System and Service Manager
systemd is a suite of basic building blocks for a Linux system. It provides a system and service manager that runs as PID 1 and starts the rest of the system.
systemd provides aggressive parallelization capabilities, uses socket and D-Bus activation for starting services, offers on-demand starting of daemons, keeps track of processes using Linux control groups, maintains mount and automount points, and implements an elaborate transactional dependency-based service control logic.
Other parts include a logging daemon, utilities to control basic system configuration like the hostname, date, locale, maintain a list of logged-in users and running containers and virtual machines, system accounts, runtime directories and settings, and daemons to manage simple network configuration, network time synchronization, log forwarding, and name resolution.
[H2] Booting
Automatic Boot Assessment
Boot Components & Root File System Discovery
Boot Loader Interface
Factory Reset
Mount Requirements
TPM2 PCR Measurements Made by systemd
[H2] Concepts
Credentials
Desktop Environment Integration
Portable Services Introduction
Porting systemd To New Distributions
Random Seeds
Safely Building Images
systemd Coredump Handling
[H2] Contributing
Code Quality Tools
Coding Style
Contributing
Governance
Hacking on systemd
Notes for Translators
Porting to New Architectures
Reporting of Security Vulnerabilities
Steps to a Successful Release
Testing systemd Using Sanitizers
Varlink API Style
systemd Community Conduct Guidelines
systemd Repository Architecture
[H2] Documentation for Developers
Backports
Inhibitor Locks
Journal Message Catalogs
Minimal Builds
New Control Group Interfaces
Presets
The Case for the /usr Merge
Writing Desktop Environments
Writing Display Managers
Writing Network Configuration Managers
Writing Resolver Clients
Writing VM and Container Managers
Writing syslog Daemons Which Cooperate Nicely With systemd
systemd File Hierarchy Requirements
systemd Optimizations
systemd-boot UEFI Boot Manager
[H2] Documentation for Developers - external links
Introduction to systemd in French
The 30 Biggest Myths about systemd
[H2] Exec directories
Project IDs for Disk Quotas on Exec Directories
[H2] Interfaces
Appstream Bundle
Container Interface
Control Group APIs and Delegation
File Descriptor Store
Initrd Interface
Journal Export Formats
Journal File Format
Known Environment Variables
Locking Block Device Access
Memory Pressure Handling
Native Journal Protocol
Password Agents
Portability and Stability
Storage Daemons for the Root File System
Using /tmp/ and /var/tmp/ Safely
VM Interface
What Settings Are Currently Available For Transient Units?
[H2] Manual Pages
Directives
Index
[H2] Manuals and Documentation for Users and Administrators
API File Systems
Booting Without /usr is Broken
Compatibility with SysV
Diagnosing Boot Problems
Frequently Asked Questions
My Service Can’t Get Realtime!
Socket Activation with Popular Daemons
Tips And Tricks
[H2] Networking
Predictable Network Interface Names
Running Services After the Network Is Up
systemd-resolved and VPNs
[H2] Project
Brand
GitHub Project Page
Issues
Mailing List
Mastodon
Pull Requests
Releases
mkosi Project - Build Bespoke OS Images
[H2] Publications
Article in The H
Article in The H, Part 2
Bê-á-bá do systemd #1 (Brazilian Portuguese)
Bê-á-bá do systemd #2 (Brazilian Portuguese)
Bê-á-bá do systemd #3 (Brazilian Portuguese)
Bê-á-bá do systemd #4 (Brazilian Portuguese)
Bê-á-bá do systemd #5 (Brazilian Portuguese)
Bê-á-bá do systemd #6 (Brazilian Portuguese)
RHEL9 docs - Configuring basic system settings - Managing systemd
RHEL9 docs - Using systemd unit files to customize and optimize your system
SUSE White Paper on systemd
Évolutions techniques de systemd (French)
[H2] Related Packages
C++ bindings for sd-bus
Erlang bindings for the Journal APIs
Erlang journald backend for Lager
Experimental Qt bindings
GLib bindings
Go Bindings for the Journal API, socket activation and DBUS
Haskell Journal API
Haskell socket activation
Lua Bindinds for systemd APIs
Node.JS bindings for the Journal APIs
Node.JS support for systemd Socket Activation
Node.JS wrapper for sd_notify
Node.JS wrapper for sd_notify (repo)
PHP Bindings for the Journal APIs
Perl bindings for the Journal APIs
Ruby bindings for the Journal APIs
Ruby bindings for the systemd D-Bus APIs
pystemd
python-systemd
[H2] The systemd for Administrators Blog Series
#01: Verifying Bootup
#02: Which Service Owns Which Processes?
#03: How Do I Convert A SysV Init Script Into A systemd Service File?
#04: Killing Services
#05: The Three Levels of “Off”
#06: Changing Roots
#07: The Blame Game
#08: The New Configuration Files
#09: On /etc/sysconfig and /etc/default
#10: Instantiated Services
#11: Converting inetd Services
#12: Securing Your Services
#13: Log and Service Status
#14: The Self-Explanatory Boot
#15: Watchdogs
#16: Gettys on Serial Consoles (and Elsewhere)
#17: Using the Journal
#18: Managing Resources
#19: Detecting Virtualization
#20: Socket Activated Internet Services and OS Containers
#21: Container Integration
A Russian translation
A more complete Russian translation (PDF)
[H2] The systemd for Developers Series
#1: Socket Activation
#2: Socket Activation (Part 2)
#3: Logging to the Journal
[H2] The various distributions
Arch Linux bugtracker
Arch Linux packages
Arch Linux wiki
Debian bugtracker
Debian packages
Debian wiki
Fedora bugtracker
Fedora packages
Fedora sources
Gentoo bugtracker
Gentoo packages
Gentoo wiki
Mageia bugtracker
Mageia wiki
Ubuntu packages
Ubuntu wiki
openSUSE bugtracker
openSUSE instructions
openSUSE packages
[H2] Users, Groups and Home Directories
Converting Existing Users to systemd-homed
Home Directories
JSON Group Records
JSON User Records
Pax Controla Groupiana
User Record Blob Directories
User/Group Name Syntax
User/Group Record Lookup API via Varlink
Users, Groups, UIDs and GIDs on systemd Systems
systemd-homed and JSON User/Group Record Support in Desktop Environments
[H2] Videos for Users and Administrators
Interview about systemd at golem.de (German)
Presentation about kdbus at linux.conf.au 2014
Presentation about recent developments at Devconf 2013
Presentation about systemd at FOSDEM 2011
Presentation about systemd at FOSDEM 2013
Presentation about systemd at FOSDEM 2013 (Slides)
Presentation about systemd at FOSS.in 2012
Presentation about systemd at OSEC Barcamp 2012
Presentation about systemd at OSworld 2014 (systemd cheat-sheet) (Polish)
Presentation about systemd at linux.conf.au 2011
Presentation about systemd at linux.conf.au 2011 (Slides)
Presentation about systemd at the Red Hat Summit 2013
Presentation about the journal at Devconf 2013
[H2] See also
Introductory blog story
Three status updates
The Wikipedia article
Welcome to Fedora 20 (Heisenbug)!
[ OK ] Reached target Remote File Systems.
[ OK ] Listening on Delayed Shutdown Socket.
[ OK ] Listening on /dev/initctl Compatibility Named Pipe.
[ OK ] Reached target Paths.
[ OK ] Reached target Encrypted Volumes.
[ OK ] Listening on Journal Socket.
Mounting Huge Pages File System...
Mounting POSIX Message Queue File System...
Mounting Debug File System...
Starting Journal Service...
[ OK ] Started Journal Service.
Mounting Configuration File System...
Mounting FUSE Control File System...
[ OK ] Created slice Root Slice.
[ OK ] Created slice User and Session Slice.
[ OK ] Created slice System Slice.
[ OK ] Reached target Slices.
[ OK ] Reached target Swap.
Mounting Temporary Directory...
[ OK ] Reached target Local File Systems (Pre).
Starting Load Random Seed...
Starting Load/Save Random Seed...
[ OK ] Mounted Huge Pages File System.
[ OK ] Mounted POSIX Message Queue File System.
[ OK ] Mounted Debug File System.
[ OK ] Mounted Configuration File System.
[ OK ] Mounted FUSE Control File System.
[ OK ] Mounted Temporary Directory.
[ OK ] Started Load Random Seed.
[ OK ] Started Load/Save Random Seed.
[ OK ] Reached target Local File Systems.
Starting Recreate Volatile Files and Directories...
Starting Trigger Flushing of Journal to Persistent Storage...
[ OK ] Started Recreate Volatile Files and Directories.
Starting Record System Reboot/Shutdown in UTMP...
[ OK ] Started Trigger Flushing of Journal to Persistent Storage.
[ OK ] Started Record System Reboot/Shutdown in UTMP.
[ OK ] Reached target System Initialization.
[ OK ] Reached target Timers.
[ OK ] Listening on D-Bus System Message Bus Socket.
[ OK ] Reached target Sockets.
[ OK ] Reached target Basic System.
Starting Permit User Sessions...
Starting D-Bus System Message Bus...
[ OK ] Started D-Bus System Message Bus.
Starting Login Service...
Starting Cleanup of Temporary Directories...
[ OK ] Started Permit User Sessions.
[ OK ] Started Cleanup of Temporary Directories.
Starting Console Getty...
[ OK ] Started Console Getty.
[ OK ] Reached target Login Prompts.
[ OK ] Started Login Service.
[ OK ] Reached target Multi-User System.
Fedora release 20 (Heisenbug)
Kernel 3.9.2-200.fc18.x86_64 on an x86_64 (console)
fedora login:

[H1] Automatic Boot Assessment
systemd provides support for automatically reverting back to the previous
version of the OS or kernel in case the system consistently fails to boot. The
UAPI.1 Boot Loader Specification
describes how to annotate boot loader entries with a counter that specifies how
many attempts should be made to boot it. This document describes how systemd
implements this scheme.
The many different components involved in the implementation may be used
independently and in combination with other software to, for example, support
other boot loaders or take actions outside of the boot loader.
Here’s a brief overview of the complete set of components:
The
kernel-install(8)
script can optionally create boot loader entries that carry an initial boot
counter (the initial counter is configurable in /etc/kernel/tries).

The
systemd-boot(7)
boot loader optionally maintains a per-boot-loader-entry counter described by
the UAPI.1 Boot Loader Specification
that is decreased by one on each attempt to boot the entry, prioritizing
entries that have non-zero counters over those which already reached a
counter of zero when choosing the entry to boot.

The boot-complete.target target unit (see
systemd.special(7))
serves as a generic extension point both for units that are necessary to
consider a boot successful (e.g. systemd-boot-check-no-failures.service
described below), and units that want to act only if the boot is
successful (e.g. systemd-bless-boot.service described below).

The
systemd-boot-check-no-failures.service(8)
service is a simple service health check tool. When enabled it becomes an
indirect dependency of systemd-bless-boot.service (by means of
boot-complete.target, see below), ensuring that the boot will not be
considered successful if there are any failed services.

The
systemd-bless-boot.service(8)
service automatically marks a boot loader entry, for which boot counting as
mentioned above is enabled, as “good” when a boot has been determined to be
successful, thus turning off boot counting for it.

The
systemd-bless-boot-generator(8)
generator automatically pulls in systemd-bless-boot.service when use of
systemd-boot with boot counting enabled is detected.
[H2] Details
As described in the
UAPI.1 Boot Loader Specification,
the boot counting data is stored in the file name of the boot loader entries as
a plus (+), followed by a number, optionally followed by - and another
number, right before the file name suffix (.conf or .efi).
The first number is the “tries left” counter encoding how many attempts to boot
this entry shall still be made. The second number is the “tries done” counter,
encoding how many failed attempts to boot it have already been made. Each time
a boot loader entry marked this way is booted the first counter is decremented,
and the second one incremented. (If the second counter is missing, then it is
assumed to be equivalent to zero.) If the boot attempt completed successfully
the entry’s counters are removed from the name (entry state “good”), thus
turning off boot counting for the future.
[H2] Walkthrough
Here’s an example walkthrough of how this all fits together.
The user runs echo 3 >/etc/kernel/tries to enable boot counting.

A new kernel is installed. kernel-install is used to generate a new boot
loader entry file for it. Let’s say the version string for the new kernel is
4.14.11-300.fc27.x86_64, a new boot loader entry
/boot/loader/entries/4.14.11-300.fc27.x86_64+3.conf is hence created.

The system is booted for the first time after the new kernel has been
installed. The boot loader now sees the +3 counter in the entry file
name. It hence renames the file to 4.14.11-300.fc27.x86_64+2-1.conf
indicating that at this point one attempt has started.
After the rename completed, the entry is booted as usual.

Let’s say this attempt to boot fails. On the following boot the boot loader
will hence see the +2-1 tag in the name, and will hence rename the entry file to
4.14.11-300.fc27.x86_64+1-2.conf, and boot it.

Let’s say the boot fails again. On the subsequent boot the loader will hence
see the +1-2 tag, and rename the file to
4.14.11-300.fc27.x86_64+0-3.conf and boot it.

If this boot also fails, on the next boot the boot loader will see the tag
+0-3, i.e. the counter reached zero. At this point the entry will be
considered “bad”, and ordered after all non-bad entries. The next newest
boot entry is now tried, i.e. the system automatically reverted to an
earlier version.
The above describes the walkthrough when the selected boot entry continuously
fails. Let’s have a look at an alternative ending to this walkthrough. In this
scenario the first 4 steps are the same as above:
as above

as above

as above

as above

Let’s say the second boot succeeds. The kernel initializes properly, systemd
is started and invokes all generators.

One of the generators started is systemd-bless-boot-generator which
detects that boot counting is used. It hence pulls
systemd-bless-boot.service into the initial transaction.

systemd-bless-boot.service is ordered after and Requires= the generic
boot-complete.target unit. This unit is hence also pulled into the initial
transaction.

The boot-complete.target unit is ordered after and pulls in various units
that are required to succeed for the boot process to be considered
successful. One such unit is systemd-boot-check-no-failures.service.

The graphical desktop environment installed on the machine starts a
service called graphical-session-good.service, which is also ordered before
boot-complete.target, that registers a D-Bus endpoint.

systemd-boot-check-no-failures.service is run after all its own
dependencies completed, and assesses that the boot completed
successfully. It hence exits cleanly.

graphical-session-good.service waits for a user to log in. In the user
desktop environment, one minute after the user has logged in and started the
first program, a user service is invoked which makes a D-Bus call to
graphical-session-good.service. Upon receiving that call,
graphical-session-good.service exits cleanly.

This allows boot-complete.target to be reached. This signifies to the
system that this boot attempt shall be considered successful.

Which in turn permits systemd-bless-boot.service to run. It now
determines which boot loader entry file was used to boot the system, and
renames it dropping the counter tag. Thus
4.14.11-300.fc27.x86_64+1-2.conf is renamed to
4.14.11-300.fc27.x86_64.conf. From this moment boot counting is turned
off for this entry.

On the following boot (and all subsequent boots after that) the entry is
now seen with boot counting turned off, no further renaming takes place.
[H2] How to adapt this scheme to other setups
Of the stack described above many components may be replaced or augmented. Here
are a couple of recommendations.
To support alternative boot loaders in place of systemd-boot two scenarios
are recommended:
a. Boot loaders already implementing the Boot Loader Specification can
simply implement the same rename logic, and thus integrate fully with
the rest of the stack.
b. Boot loaders that want to implement boot counting and store the counters
elsewhere can provide their own replacements for
systemd-bless-boot.service and systemd-bless-boot-generator, but should
continue to use boot-complete.target and thus support any services
ordered before that.

To support additional components that shall succeed before the boot is
considered successful, simply place them in units (if they aren’t already)
and order them before the generic boot-complete.target target unit,
combined with Requires= dependencies from the target, so that the target
cannot be reached when any of the units fail. You may add any number of
units like this, and only if they all succeed the boot entry is marked as
good. Note that the target unit shall pull in these boot checking units, not
the other way around.
Depending on the setup, it may be most convenient to pull in such units
through normal enablement symlinks, or during early boot using a
generator,
or even during later boot. In the last case, care must be taken to ensure
that the start job is created before boot-complete.target has been
reached.

To support additional components that shall only run on boot success, simply
wrap them in a unit and order them after boot-complete.target, pulling it
in.
Such unit would be typically wanted (or required) by one of the
bootup targets,
for example, multi-user.target. To avoid potential loops due to conflicting
default dependencies
ordering, it is recommended to also add an explicit dependency (e.g.
After=multi-user.target) to the unit. This overrides the implicit ordering
and allows boot-complete.target to start after the given bootup target.
[H2] FAQ

I have a service which — when it fails — should immediately cause a
reboot. How does that fit in with the above? — That’s orthogonal to
the above, please use FailureAction= in the unit file for this.

Under some condition I want to mark the current boot loader entry as bad
right-away, so that it never is tried again, how do I do that? — You may
invoke /usr/lib/systemd/systemd-bless-boot bad at any time to mark the
current boot loader entry as “bad” right-away so that it isn’t tried again
on later boots.

[H1] Boot Components & Root File System Discovery
The recommended way to boot a systemd based
UEFI system consists primarily of three
components:
A boot loader,
i.e. systemd-boot
that provides interactive and programmatic control of what precisely to
boot. It takes care of enumerating all possible boot targets (implementing
the UAPI.1 Boot Loader
Specification),
potentially presenting it to the user in a menu, but otherwise picking an
item automatically, implementing boot counting and automatic rollback if
desired.

A UAPI.5 Unified Kernel Image
(“UKI”),
i.e. an UEFI PE executable that combines
systemd-stub,
a Linux kernel, and an initial RAM disk (“initrd”) into one. UKIs are
self-descriptive: the aforementioned boot loader enumerates these UKIs and
automatically extracts all information necessary to determine which menu
entries to generate for them. Within the UKI runtime (very early during
kernel initialization) the transition from the UEFI firmware code to the
Linux code takes place, i.e. it executes the fundamental
ExitBootServices() UEFI call that ends PC firmware control,
and lets the Linux kernel take over.

A root file system (“rootfs”): this is where the regular OS is
located. The primary job of the early userspace that is contained in the
initrd that itself is part of the UKI, is to find, set up, and pivot into
the rootfs.
[!NOTE]
The above is how systemd upstream recommends a system is put together. However,
distributions differ from this, sometimes massively – in particular when
their focus is on supporting legacy (i.e. non-UEFI) hardware platforms. We
believe the above three components are all that’s really necessary for a
robust, simple and comprehensive system, but downstreams might see things
differently. The above however is supposed to be a guideline for distribution
developers.
[H2] Execution Environments
Note that these three components are executed within very distinct execution
environments, with very different APIs, drivers and file system access:

Component
Environment

Boot Loader: systemd-boot
UEFI APIs, simple VFAT file system access

UKI initially: systemd-stub
UEFI APIs, simple VFAT file system access

UKI finally: initrd
Linux APIs, complex storage and file systems

Root File System: rootfs
Linux APIs, full OS functionality

[H2] Structure & Auxiliary Resources
Each of the three components is primarily encapsulated in a single object each:
The boot loader is primarily a single PE UEFI binary, called either
systemd-boot.efi or BOOTX64.EFI depending on context (the latter name
contains an architecture identifier, and is different for non-x86-64
architectures).

The UKI is primarily a single PE UEFI binary (i.e. a .efi file).

The rootfs is typically a Linux file system, on a GPT partition table
disk. Typically, the rootfs is placed within some form of container that
ensures security of the file system, i.e. authenticity, confidentiality
and integrity via dm-verity, dm-crypt, dm-integrity or a combination
thereof.
While these three objects are generally enough to boot an OS successfully, in
many cases some parameterization and modularization of the boot is necessary,
hence each of these components is often combined with certain optional,
auxiliary resources:
The boot loader can read a configuration file
loader.conf,
find additional drivers, or key material for SecureBoot enrollment in the
same file system it itself is placed in.

systemd-stub can find additional parameters (“system
credentials”), configuration
(“confext”),
drivers/firmware (“sysext”) and other resources (“EFI Addons”) placed next
to the location it itself is placed in. We typically call these companion
resources “sidecars”.

The rootfs often is a combination of one file system for /usr/
(“usrfs”) and one for the actual root /, and possibly further,
auxiliary file systems, for example /home/ or /srv/.
[!NOTE]
Depending on the execution environment the first component (the boot loader)
might be dispensable. Specifically, on disk images intended solely for use in
VMs, it might make sense to tell the firmware to directly boot a UKI,
letting the VMM’s image selection functionality play the role of the boot loader.
[!NOTE]
Depending on the execution environment the last component (the rootfs)
might also be dispensable. Specifically, for simpler fixed-purpose, stateless
applications it might be sufficient to run everything needed directly from
the initrd file system embedded in the UKI, and never transition out of
this. In this case, conceptually the initrd is only an initrd from kernel
PoV, but is already the rootfs from a userspace PoV. We usually call these
types of setups Unified System Image (“USI”), as opposed to UKI.
[IMG: Schematic Chart of Root File System Discovery]
[H2] Automatic Discovery on Disks
In the most common case all three components and their sidecars are placed on
the same disk. Specifically:
The boot loader is placed in the “EFI System Partition” (ESP), typically at
the paths /EFI/BOOT/BOOTX64.EFI (this is a generic entrypoint binary that
the firmware executes when you just point it to a disk to boot without any
further details) and /EFI/systemd/systemd-bootx64.efi (this is a more
specific entrypoint that can be registered persistently in the firmware, to
give it an explicit starting point). The ESP is a concept defined by the
UEFI specification and is what the firmware initially looks for and
mounts. Since VFAT is the only relevant file system type UEFI firmwares have
to support the ESP is generally a VFAT file system. The aforementioned
auxiliary, optional resources the boot loader may consume are placed in the
ESP as well, in particular below the /loader/ subdirectory.

The UKIs may either be placed in the ESP (below the /EFI/Linux/
subdirectory), or in the UAPI.1 Extended Boot Loader
Partition
(“XBOOTLDR”), which can be placed on the same disk as the ESP and is also
VFAT. XBOOTLDR is an optional concept and it’s only raison d’être is that
ESPs sometimes are sized too small by vendors, and do not have enough space
for multiple UKIs. XBOOTLDR hence serves as a conceptual extension of the
size-constrained ESP. Sidecars for the UKIs are typically placed in a
directory next to the UKI they are for, whose name however is suffixed by
.d/, i.e. a UKI foo.efi has its sidecars in foo.efi.d/.

The rootfs is placed on the same disk as the ESP/XBOOTLDR, in a partition
marked with a special GPT partition type. Various other well-known types of
partitions can be placed next to the rootfs and are automatically
discovered and mounted, see the UAPI.2 Discoverable Partitions
Specification
for details.
In this common case, discovery of all three components and their sidecars is
fully automatic. Each component derives automatically where to find its
auxiliary resources as well as the next step to transition to, entirely based
on the place itself is running from. There’s a full chain of automatic
discovery in place:
The firmware picks the disk to boot from (possibly by interactive choice of
the user), accesses the ESP on it, and invokes the boot loader from it.

The boot loader then looks for UKIs, both on the ESP it was invoked from,
and in the XBOOTLDR partition next to it on the same disk.

The UKI’s initrd then looks for the rootfs, on the same disk the
UKI was invoked from, i.e. it looks for a partition marked as root next to
the ESP/XBOOTLDR partition. (This information is passed from UKI to
userspace via the
LoaderDevicePartUUID EFI
variable.)
In more complex setups it is possible to specify in more detail where to find
each of these resources:
Firmware typically provides a basic boot menu which may be used to choose
between various relevant boot loaders/entrypoints on multiple disks. This
is sometimes configurable from the firmware setup tool, as well as from
userspace via tools such as
bootctl,
efibootmgr or kernel-bootcfg.

The systemd-boot boot loader may be configured via UAPI.1 Boot Loader
Specification Type #1
entries to acquire UKIs or similar from other locations.

The initrd part of the UKI understands the root= (and mount.usr=)
kernel command line switches to look for the rootfs/usrfs at a
particular place.
While it is recommended to keep all three components closely together it is
possible via these mechanisms to place all three at completely disparate
locations, too.
[H2] Network Boot
In many cases it is essential to boot an OS from the network instead of a
local disk. This can happen at each of these three components:
Many UEFI firmwares support HTTP(S) network boot (usually requires enabling
in firmware setup). If this is available, it permits downloading a disk image
from an HTTP server (the URL can either be configured in the firmware setup,
or be acquired in a DHCP lease). The disk image is then set up as a RAM
disk, and then processed much like a regular disk: an ESP is searched for
and the /EFI/BOOT/BOOTX64.EFI entrypoint binary is invoked.

UKIs can be placed on the same downloaded disk image, within the ESP. If
multiple different UKIs shall be made accessible from the same boot menu
this would potentially increase the size of the disk image to prohibitive sizes.
In order to address this, it is possible to embed Boot
Loader Specification Type #1 entry files in the ESP instead, which may carry
references to the UKIs to download and invoke once a choice is made. These
references can either be full URLs or alternatively simple filenames which
are then automatically appended to the URL that was used by the firmware
to acquire the initial boot disk.

The rootfs can be acquired automatically from a networked source too in a
flexible fashion. For example, the initrd contained in the UKI might
support NVMe-over-TCP or iSCSI block devices to boot from, supporting the
whole Linux storage stack. systemd also natively supports downloading the
rootfs from HTTP
sources,
either in a GPT disk image (specifically:
UAPI.3 DDIs,
with .raw suffix) or in a .tar file, which are placed in system RAM and
then booted into (these downloads can be downloaded in compressed form and
are automatically decompressed on-the-fly). This of course requires
sufficient RAM to be available on the target system, and also means that
persistency of modifications of the file system is not possible. If this
mode is used, the URL to acquire the rootfs disk image from can be derived
automatically from the URL that was used to acquire the UKI itself. (This
information is passed from UKI to userspace via the LoaderDevicePartURL
EFI variable.)
Similarly to the disk-based boot scheme described in the previous section,
discovery of the boot source can be fully automatic, with each
component taking the source of the preceding component into account:
the boot loader can automatically download UKIs from the same source
it itself was downloaded from. Moreover the initrd of the UKI can
automatically downloads the rootfs from the same source it itself was
downloaded from.
Also, much like in the disk-based boot scheme, it is possible to
specify a different source for a component to replace the automatically-derived URL.
On top of that it is of course possible to mix disk-based and network-based boot:
for example place the boot loader on the local disk,
but use UKIs and rootfs from networked sources;
or alternatively place both boot loader and UKIs on the local disk,
and only the rootfs on the network.
[H2] Trust & Security
In a modern world of boot integrity, all three of the relevant components as well
as (most of) their sidecars require cryptographic protection. Specifically:
The boot loader is typically authenticated by the firmware before invocation
via UEFI Secure Boot, i.e. checked against a cryptographic certificate list
persistently stored in the firmware. Note that the various auxiliary
resources the systemd-boot boot loader reads are not individually
authenticated (i.e. loader.conf as well as Type #1 Boot Loader
Specification entries). Because of this they can typically only be used in a
very restricted fashion, i.e. configure some UI details as well as menu
entries. Some options available are ignored if Secure Boot mode is
enabled. Moreover, even if the text strings shown in the menu entries might
not be authenticated, the binaries that are invoked once they are selected
are, as are all their parameters.

The UKIs are also authenticated by the firmware via UEFI Secure Boot, and so
are EFI Addons. confext and sysext sidecars are protected via
dm-verity and a signature of the root hash is validated against keys in
the kernel’s keyrings. System credentials are authenticated via secrets
stored in the TPM.

Authentication of the rootfs and usrfs is more variable: depending on
setup this is either done via dm-verity (either pinned by root hash from
the UKI, or authenticated by signature provided to the kernel, checked
against the kernel’s built-in keyring) or dm-crypt+dm-integrity
(protected by TPM or user provided password/FIDO/PKCS#11), or in the network
case at download time via detached signatures (currently only GPG) or via
HTTPS certificate validation. Note that by default the automatic discovery
mechanism of the rootfs and its auxiliary file systems does not insist on
cryptographic protection and authentication before use. However, the
systemd.image_policy=
kernel command line switch may be used to control precisely what kind of
protection to require for each such partition.
Note that UEFI Secure Boot is problematic in various ways: it is generally
bound to a certificate list maintained centrally by Microsoft, and thus implies
a complex (and expensive) code signing bureaucracy, that in many cases is
undesirable, particularly in a community Linux world. Moreover, because the
certificate list managed by Microsoft is very large, its security value is
limited: it mostly acts more as denylist of known-bad software rather than as
allowlist of known-good. (If you enroll your own list, things are much better,
but see below.)
[H3] Shim
To make the code signing more palatable to the Linux world the shim project
has been developed, which is often used as initial component of the OS boot
(i.e. the firmware would invoke shim as component 0, before the components 1,
2, 3 described above). shim is primarily relevant for two reasons: it adds
a second set of certificates on top of the UEFI Secure Boot list, maintained by
the OS vendor, and it optionally provides functionality to maintain a local set
of keys (“MOK”) in addition to the Microsoft and OS vendor keys.
[H3] Automatic Enrollment of Secure Boot Certificates
The systemd-boot boot loader also supports automatic enrollment of
alternative SecureBoot certificates: if the system is booted in the
firmware-provided Secure Boot “Setup Mode”, it can automatically enroll
certificates placed inside the ESP into the firmware, replacing any existing
ones if there are any. This mechanism massively enhances the security value of
Secure Bo

[H1] The Boot Loader Interface
systemd can interface with the boot loader
to receive performance data and other information,
and pass control information.
This is only supported on EFI systems.
Data is transferred between the boot loader and systemd in EFI variables.
All EFI variables use the vendor UUID 4a67b082-0a4c-41cf-b6c7-440b29bb8c4f.
Variables will be listed below using the Linux efivarfs naming,
<name>-<vendoruuid>.
The EFI Variable LoaderTimeInitUSec-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains the timestamp in microseconds when the loader was initialized.
This value is the time spent in the firmware for initialization.
It is formatted as numeric, NUL-terminated, decimal string, in UTF-16.

The EFI Variable LoaderTimeExecUSec-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains the timestamp in microseconds when the loader finished its work and is about to execute the kernel.
The time spent in the loader is the difference between LoaderTimeExecUSec and LoaderTimeInitUSec.
This value is formatted the same way as LoaderTimeInitUSec.

The EFI variable LoaderDevicePartUUID-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains the partition GUID of the ESP the boot loader was run from
formatted as NUL-terminated UTF16 string, in normal GUID syntax.

The EFI variable LoaderConfigTimeout-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains the boot menu timeout currently in use.
It may be modified both by the boot loader and by the host.
The value should be formatted as numeric, NUL-terminated, decimal string, in UTF-16.
The time is specified in seconds.
In addition some non-numeric string values are also accepted.
A value of menu-force will disable the timeout and show the menu indefinitely.
If set to 0 or menu-hidden the default entry is booted immediately without showing a menu.
Unless a value of menu-disabled is set,
the boot loader should provide a way to interrupt this
by for example listening for key presses for a brief moment before booting.

Similarly, the EFI variable LoaderConfigTimeoutOneShot-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains a boot menu timeout for a single following boot.
It is set by the OS in order to request display of the boot menu on the following boot.
When set overrides LoaderConfigTimeout.
It is removed automatically after being read by the boot loader,
to ensure it only takes effect a single time.
This value is formatted the same way as LoaderConfigTimeout.
If set to 0 the boot menu timeout is turned off,
and the menu is shown indefinitely.

The EFI variable LoaderEntries-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
may contain a series of boot loader entry identifiers,
one after the other, each individually NUL terminated.
This may be used to let the OS know which boot menu entries were discovered by the boot loader.
A boot loader entry identifier should be a short, non-empty alphanumeric string
(possibly containing -, too).
The list should be in the order the entries are shown on screen during boot.
See below regarding the recommended vocabulary for boot loader entry identifiers.

The EFI variable LoaderEntryPreferred-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains the preferred boot loader entry to use.
This takes boot assessment into account by not selecting boot entries that have
been marked as bad,
see Automatic Boot Assessment
for more details on boot assessment.
If no entry was selected by the preferred setting (from either the EFI var or
the config file), then the boot loader will look at the default setting, which
does not skip entries that were marked as bad.
It contains a NUL-terminated boot loader entry identifier.

The EFI variable LoaderEntryDefault-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains the default boot loader entry to use.
This ignores boot assessment and can select boot entries that have been marked
as bad by boot assessment,
see Automatic Boot Assessment
for more details on boot assessment as well as the documentation on the
LoaderEntryPreferred EFI var.
It contains a NUL-terminated boot loader entry identifier.

The EFI variable LoaderEntrySysFail-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
specifies the boot loader entry to be used in case of a system failure.
System failure (SysFail) boot entries
can optionally modify the automatic selection order in the event of a failure,
such as a boot firmware update failure with the failure status recorded in the EFI system table.
If a system failure occurs and LoaderEntrySysFail is set,
systemd-boot will use this boot entry,
and store the actual SysFail reason in the LoaderSysFailReason EFI variable.

The EFI variable LoaderSysFailReason-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains the system failure reason.
This variable is used in cooperation with LoaderEntrySysFail boot entry.
If system failure doesn’t occur, LoaderSysFailReason is not set.

Similarly, the EFI variable LoaderEntryOneShot-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains the default boot loader entry to use for a single following boot.
It is set by the OS
in order to request booting into a specific menu entry on the following boot.
When set overrides LoaderEntryPreferred and LoaderEntryDefault.
It is removed automatically after being read by the boot loader,
to ensure it only takes effect a single time.
This value is formatted the same way as LoaderEntryDefault and LoaderEntryPreferred.

The EFI variable LoaderEntrySelected-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains the boot loader entry identifier that was booted.
It is set by the boot loader and read by the OS
in order to identify which entry has been used for the current boot.

The EFI variable LoaderFeatures-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains a 64-bit unsigned integer with a number of flags bits
that are set by the boot loader and passed to the OS
and indicate the features the boot loader supports.
Specifically, the following bits are defined:

1 << 0 → The boot loader honours LoaderConfigTimeout when set.
1 << 1 → The boot loader honours LoaderConfigTimeoutOneShot when set.
1 << 2 → The boot loader honours LoaderEntryDefault when set.
1 << 3 → The boot loader honours LoaderEntryOneShot when set.
1 << 4 → The boot loader supports boot counting as described in Automatic Boot Assessment.
1 << 5 → The boot loader supports looking for boot menu entries in the Extended Boot Loader Partition.
1 << 6 → The boot loader supports passing a random seed to the OS.
1 << 7 → The boot loader supports loading of drop-in drivers from the /EFI/systemd/drivers/ directory on the ESP,
see systemd-boot(7).
1 << 8 → The boot loader supports the sort-key field defined by the
Boot Loader Specification.
1 << 9 → The boot loader supports the @saved pseudo-entry
1 << 10 → The boot loader supports the devicetree field defined by the
Boot Loader Specification.
1 << 11 → The boot loader support automatic enrollment of SecureBoot keys,
see systemd-boot(7).
1 << 12 → The boot loader will set EFI variable ShimRetainProtocol-605dab50-e046-4300-abb6-3dd810dd8b23
for shim to make its protocol available to the booted binary.
1 << 13 → The boot loader honours menu-disabled option when set.
1 << 14 → The boot loader supports multi-profile Unified Kernel Images (UKIs)
1 << 15 → The boot loader sets the LoaderDeviceURL variable when appropriate.
1 << 16 → The boot loader supports the uki field defined by the
Boot Loader Specification.
1 << 17 → The boot loader supports the uki-url field defined by the
Boot Loader Specification.
1 << 18 → The boot loader reports active TPM2 PCR banks in the
EFI variable LoaderTpm2ActivePcrBanks-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f.
1 << 19 → The boot loader supports the LoaderEntryPreferred variable when set.

The EFI variable LoaderSystemToken-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains binary random data,
persistently set by the OS installer.
Boot loaders that support passing random seeds to the OS
should use this data and combine it with the random seed file read from the ESP.
By combining this random data with the random seed read off the disk
before generating a seed to pass to the OS and a new seed to store in the ESP
the boot loader can protect itself from situations where
“golden” OS images that include a random seed are replicated and used on multiple systems.
Since the EFI variable storage is usually independent
(i.e. in physical NVRAM) of the ESP file system storage,
and only the latter is part of “golden” OS images,
this ensures that different systems still come up with different random seeds.
Note that the LoaderSystemToken is generally only written once,
by the OS installer,
and is usually not touched after that.

The EFI variable LoaderDeviceURL-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains the URL the boot loader was downloaded from,
in UTF-16 format.
Only set in case of network boots.

The EFI variable LoaderTpm2ActivePcrBanks-4a67b082-0a4c-41cf-b6c7-440b29bb8c4f
contains a hexadecimal string representation of a bitmask with values defined by
the TCG EFI ProtocolSpecification for TPM 2.0 as EFI_TCG2_BOOT_HASH_ALG_*.
If no TPM2 support or no active banks were detected, will be set to 0.
If LoaderTimeInitUSec and LoaderTimeExecUSec are set, systemd-analyze
will include them in its boot-time analysis. If LoaderDevicePartUUID is set,
systemd will mount the ESP that was used for the boot to /boot, but only if
that directory is empty, and only if no other file systems are mounted
there. The systemctl reboot --boot-loader-entry=… and systemctl reboot
--boot-loader-menu=… commands rely on the LoaderFeatures ,
LoaderConfigTimeoutOneShot, LoaderEntries, LoaderEntryOneShot
variables.
[H2] Boot Loader Entry Identifiers
While boot loader entries may be named relatively freely,
it’s highly recommended to follow these rules when picking identifiers for the entries,
so that programs (and users) can derive basic context and meaning from the identifiers
as passed in LoaderEntries, LoaderEntryPreferred, LoaderEntryDefault,
LoaderEntryOneShot, LoaderEntrySelected,
and possibly show nicely localized names for them in UIs.
When boot loader entries are defined through the
BOOT.1 Boot Loader Specification
files, the identifier should be derived directly from the file name,
but with the .conf (Type #1 snippets) or .efi (Type #2 images)
suffix removed.

Entries automatically discovered by the boot loader
(as opposed to being configured in configuration files)
should generally have an identifier prefixed with auto-.

Boot menu entries referring to Microsoft Windows installations
should either use the identifier windows
or use the windows- prefix for the identifier.
If a menu entry is automatically discovered,
it should be prefixed with auto-, see above.
(Example: this means an automatically discovered Windows installation
might have the identifier auto-windows or auto-windows-10 or so.).

Similarly, boot menu entries referring to Apple macOS installations
should use the identifier osx or one that is prefixed with osx-.
If such an entry is automatically discovered by the boot loader use auto-osx as identifier,
or auto-osx- as prefix for the identifier, see above.

If a boot menu entry encapsulates the EFI shell program,
it should use the identifier efi-shell
(or when automatically discovered: auto-efi-shell, see above).

If a boot menu entry encapsulates a reboot into EFI firmware setup feature,
it should use the identifier reboot-to-firmware-setup
(or auto-reboot-to-firmware-setup in case it is automatically discovered).
[H2] Links
UAPI.1 Boot Loader Specification
UAPI.2 Discoverable Partitions Specification
systemd-boot(7)
bootctl(1)
systemd-gpt-auto-generator(8)