<para>These commands are available for all boot loaders that
implement the <ulink
- url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot
+ url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot
Loader Specification</ulink>, such as
<command>systemd-boot</command>.</para>
<term><option>list</option></term>
<listitem><para>Shows all available boot loader entries implementing the <ulink
- url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>, as well as any
+ url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink>, as well as any
other entries discovered or automatically generated by a boot loader implementing the <ulink
url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.
JSON output may be requested with <option>--json=</option>.</para>
<title>Boot Loader Interface Commands</title>
<para>These commands are available for all boot loaders that implement the <ulink
- url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> and the <ulink
+ url="https://uapi-group.org/specifications/specs/boot_loader_specification">
UAPI.1 Boot Loader Specification</ulink> and the <ulink
url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>, such as
<command>systemd-boot</command>.</para>
boot loader entry. These special IDs are resolved to the current values of the EFI variables
<varname>LoaderEntryDefault</varname>, <varname>LoaderEntrySysFail</varname>, <varname>LoaderEntryOneShot</varname>
and <varname>LoaderEntrySelected</varname>, see <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">
- Boot Loader Specification</ulink> for details.
+ UAPI.1 Boot Loader Specification</ulink> for details.
These special IDs are primarily useful as a quick way to persistently make the currently booted boot loader
entry the default choice, or to upgrade the default boot loader entry for the next boot to the default boot
loader entry for all future boots, but may be used for other operations too.</para>
are applied to file system in the indicated disk image. This option is similar to
<option>--root=</option>, but operates on file systems stored in disk images or block devices. The
disk image should either contain just a file system or a set of file systems within a GPT partition
- table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
+ table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions
Specification</ulink>. For further information on supported disk images, see
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
switch of the same name.</para>
<varlistentry>
<term><option>--make-entry-directory=yes|no</option></term>
<listitem><para>Controls creation and deletion of the <ulink
- url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> Type #1 entry
+ url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink> Type #1 entry
directory on the file system containing resources such as kernel and initrd images during
<option>install</option> and <option>remove</option>, respectively. The directory is named after the
entry token, as specified with <option>--entry-token=</option> parameter described below, and is
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
- <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member>
+ <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink></member>
<member><ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink></member>
<member><citerefentry><refentrytitle>systemd-boot-random-seed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
</simplelist></para>
are applied to file system in the indicated disk image. This option is similar to
<option>--root=</option>, but operates on file systems stored in disk images or block devices. The
disk image should either contain just a file system or a set of file systems within a GPT partition
- table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
- Specification</ulink>. For further information on supported disk images, see
+ table, following the <ulink
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2
+ Discoverable Partitions Specification</ulink>. For further information on supported disk images, see
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
switch of the same name.</para>
<para>Operating systems using the
<citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry> system and
- service manager are organized based on a file system hierarchy inspired by UNIX,
- as described in <ulink url="https://uapi-group.org/specifications/specs/linux_file_system_hierarchy/">
- Linux File System Hierarchy</ulink>.
- Additional requirements on <emphasis>when</emphasis> given parts of the hierarchy
- must be available during boot are listed in
- <ulink url="https://systemd.io/MOUNT_REQUIREMENTS/">Mount Requirements</ulink>.</para>
+ service manager are organized based on a file system hierarchy inspired by UNIX, as described in <ulink
+ url="https://uapi-group.org/specifications/specs/linux_file_system_hierarchy/"> UAPI.9 Linux File System
+ Hierarchy</ulink>. Additional requirements on <emphasis>when</emphasis> given parts of the hierarchy
+ must be available during boot are listed in <ulink url="https://systemd.io/MOUNT_REQUIREMENTS/">Mount
+ Requirements</ulink>.</para>
<para>Many of the paths described here can be queried
with the
option is similar to <option>--root=</option>, but operates on file systems stored in disk images or
block devices, thus providing an easy way to extract log data from disk images. The disk image should
either contain just a file system or a set of file systems within a GPT partition table, following
- the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
+ the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions
Specification</ulink>. For further information on supported disk images, see
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
switch of the same name.</para>
<para>The third argument directly refers to the path where to place kernel images, initrd
images and other resources for
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot
Loader Specification</ulink> Type #1 entries (the "entry directory"). If other boot loader schemes
are used the parameter may be ignored.</para>
<filename>$BOOT/<replaceable>ENTRY-TOKEN</replaceable>/<replaceable>KERNEL_VERSION</replaceable>/<replaceable>INITRD-FILE</replaceable></filename>.
This can also be used to prepend microcode before the actual initrd. It also creates a boot
loader entry according to the
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink>
(Type #1) in
<filename>$BOOT/loader/entries/<replaceable>ENTRY-TOKEN</replaceable>-<replaceable>KERNEL-VERSION</replaceable>.conf</filename>.
The title of the entry is the <replaceable>PRETTY_NAME</replaceable> parameter specified in
<refsect1>
<title>The <varname>$BOOT</varname> partition</title>
- <para>The partition where the kernels and <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot
+ <para>The partition where the kernels and <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot
Loader Specification</ulink> snippets are located is called <varname>$BOOT</varname>.
<command>kernel-install</command> determines the location of this partition by checking
<filename>/efi/</filename>, <filename>/boot/</filename>, and <filename>/boot/efi/</filename> in turn. The
<term><option>--make-entry-directory=yes|no|auto</option></term>
<listitem>
<para>Controls creation and deletion of the
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink>
Type #1 entry directory on the file system containing resources such as kernel and initrd images
during <option>add</option> and <option>remove</option>, respectively. The directory is named after
the entry token, and is placed immediately below the boot root directory. When
are applied to the file system in the indicated disk image. This option is similar to
<option>--root=</option>, but operates on file systems stored in disk images or block devices. The
disk image should either contain just a file system or a set of file systems within a GPT partition
- table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
+ table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions
Specification</ulink>. For further information on supported disk images, see
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
switch of the same name.</para>
<varlistentry>
<term>bls</term>
<listitem>
- <para>Standard <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
+ <para>Standard <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader
Specification</ulink> Type #1 layout, compatible with
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>:
entries in
<term>uki</term>
<listitem>
<para>Standard <ulink
- url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
+ url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader
Specification</ulink> Type #2 layout, compatible with
<citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>:
unified kernel images under <filename>$BOOT/EFI/Linux</filename> as
<member><citerefentry project='man-pages'><refentrytitle>depmod</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
- <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member>
+ <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink></member>
</simplelist></para>
</refsect1>
and type #2 (<filename><replaceable>ESP</replaceable>/EFI/Linux/*.uki</filename>
and <filename><replaceable>XBOOTLDR</replaceable>/EFI/Linux/*.uki</filename>).
Those files are described by the
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader
Specification</ulink>.</para>
<para>Note: the behaviour of <command>systemd-boot</command> is also influenced by EFI variables. Some of
<constant>x86</constant> (32-bit, aka i386) and <constant>x86-64</constant> (64-bit, aka amd64).</para>
<para>Most of the partition type UUIDs listed above are defined in the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions
Specification</ulink>.</para>
<xi:include href="version-info.xml" xpointer="v245"/></listitem>
<listitem><para>Configures the No-Auto, Read-Only and Grow-File-System partition flags (bit 63, 60
and 59) of the partition table entry, as defined by the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>. Only
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions Specification</ulink>. Only
available for partition types supported by the specification. This option is a friendly way to set
bits 63, 60 and 59 of the partition flags value without setting any of the other bits, and may be set
via <varname>Flags=</varname> too, see above.</para>
associated with it.</para>
<para>For example, distributions can use this to implement <varname>$BOOT</varname> as defined in the
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification/">Boot Loader
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification/">UAPI.1 Boot Loader
Specification</ulink>. Distributions may prefer to use the ESP as <varname>$BOOT</varname> whenever
possible, but to adhere to the spec XBOOTLDR must sometimes be used instead. So, they should create
two definitions: the first defining an ESP big enough to hold just the bootloader, and a second for
<listitem>
<para>Path to the Extended Boot Loader partition, as defined in the
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>.
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink>.
If not specified, <filename>/boot/</filename> is checked. It is recommended to mount the Extended Boot
Loader partition to <filename>/boot/</filename>, if possible.</para>
</listitem>
</para>
<para>To load a kernel, an enumeration is performed following the
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>,
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink>,
and the default boot entry is loaded. For this step to succeed, the system must be using UEFI
and the boot loader entries must be configured appropriately. <command>bootctl list</command>
may be used to list boot entries, see
are applied to file system in the indicated disk image. This option is similar to
<option>--root=</option>, but operates on file systems stored in disk images or block devices. The
disk image should either contain just a file system or a set of file systems within a GPT partition
- table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
+ table, following the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions
Specification</ulink>. For further information on supported disk images, see
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
switch of the same name.</para>
<para>This command analyzes the specified image policy string, as per
<citerefentry><refentrytitle>systemd.image-policy</refentrytitle><manvolnum>7</manvolnum></citerefentry>. The
policy is normalized and simplified. For each currently defined partition identifier (as per the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable
Partitions Specification</ulink>) the effect of the image policy string is shown in tabular form.</para>
<example>
detects that <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> style
boot counting is used.</para>
- <para>Internally, the service operates based on the <varname>LoaderBootCountPath</varname> EFI variable (of the
- vendor UUID <constant>4a67b082-0a4c-41cf-b6c7-440b29bb8c4f</constant>), which is passed from the boot loader to the
- OS. It contains a file system path (relative to the EFI system partition) of the <ulink
- url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> compliant boot loader entry
- file or unified kernel image file that was used to boot up the
- system. <command>systemd-bless-boot.service</command> removes the two "tries done" and "tries left" numeric boot
- counters from the filename, which indicates to future invocations of the boot loader that the entry has completed
- booting successfully at least once. (This service will hence rename the boot loader entry file or unified kernel
- image file on the first successful boot.)</para>
+ <para>Internally, the service operates based on the <varname>LoaderBootCountPath</varname> EFI variable
+ (of the vendor UUID <constant>4a67b082-0a4c-41cf-b6c7-440b29bb8c4f</constant>), which is passed from the
+ boot loader to the OS. It contains a file system path (relative to the EFI system partition) of the
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader
+ Specification</ulink> compliant boot loader entry file or unified kernel image file that was used to boot
+ up the system. <command>systemd-bless-boot.service</command> removes the two "tries done" and "tries
+ left" numeric boot counters from the filename, which indicates to future invocations of the boot loader
+ that the entry has completed booting successfully at least once. (This service will hence rename the boot
+ loader entry file or unified kernel image file on the first successful boot.)</para>
</refsect1>
<refsect1>
<itemizedlist>
<listitem><para>Boot entries defined with <ulink
- url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> Type #1
+ url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink> Type #1
description files located in <filename>/loader/entries/</filename> on the ESP and the Extended Boot
Loader Partition. These usually describe Linux kernel images with associated initrd images, but
alternatively may also describe other arbitrary EFI executables.</para></listitem>
- <listitem><para>Unified kernel images, <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot
+ <listitem><para>Unified kernel images, <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot
Loader Specification</ulink> Type #2, which are executable EFI binaries in
<filename>/EFI/Linux/</filename> on the ESP and the Extended Boot Loader Partition.</para></listitem>
<citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>.</para>
<para>Boot entry description files following the <ulink
- url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> are read from
+ url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink> are read from
<filename>/loader/entries/</filename> on the ESP and the Extended Boot Loader partition.</para>
<para>Unified kernel boot entries following the <ulink
- url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> are read from
+ url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink> are read from
<filename>/EFI/Linux/</filename> on the ESP and the Extended Boot Loader partition.</para>
<para>Optionally, a random seed for early boot entropy pool provisioning is stored in
<title>Boot Counting</title>
<para><command>systemd-boot</command> implements a simple boot counting mechanism on top of the <ulink
- url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>, for automatic and unattended
+ url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink>, for automatic and unattended
fallback to older kernel versions/boot loader entries when a specific entry continuously fails. Any boot loader
entry file and unified kernel image file that contains a <literal>+</literal> followed by one or two numbers (if
two they need to be separated by a <literal>-</literal>), before the <filename>.conf</filename> or
<member><citerefentry><refentrytitle>systemd-boot-random-seed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
- <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member>
+ <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink></member>
<member><ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink></member>
<member><ulink url="https://systemd.io/TPM2_PCR_MEASUREMENTS">TPM2 PCR Measurements Made by systemd</ulink></member>
</simplelist></para>
<option>--tpm2-public-key-pcrs=</option>, <option>--tpm2-signature=</option> described below.
</para>
- <para>See <ulink url="https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/">Linux TPM
- PCR Registry</ulink> for an authoritative list of PCRs and how they are updated. The table below
+ <para>See <ulink url="https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/">UAPI.7 Linux
+ TPM PCR Registry</ulink> for an authoritative list of PCRs and how they are updated. The table below
contains a quick reference, describing in particular the PCRs modified by systemd.</para>
<table>
through the certificates measured into PCR 7. Validation through certificates hashes is typically
preferable over validation through direct measurements as it is less brittle in context of OS/firmware
updates: the measurements will change on every update, but signatures should remain unchanged. See the
- <ulink url="https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/">Linux TPM PCR
+ <ulink url="https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/">UAPI.7 Linux TPM PCR
Registry</ulink> for more discussion.</para>
</refsect2>
</refsect1>
<orderedlist>
<listitem><para>OS disk images containing a GPT partition table envelope, with partitions marked
- according to the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
+ according to the <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions
Specification</ulink>.</para></listitem>
<listitem><para>OS disk images containing just a plain file-system without an enveloping partition
<listitem><para>Mount the specified OS image to the specified directory. This will dissect the image,
determine the OS root file system — as well as possibly other partitions — and mount them to the
specified directory. If the OS image contains multiple partitions marked with the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions Specification</ulink>
multiple nested mounts are established. This command expects two arguments: a path to an image file
and a path to a directory where to mount the image.</para>
<option>--mount</option> or <option>--copy-to</option>) the file systems contained in the OS image
are automatically grown to their partition sizes, if bit 59 in the GPT partition flags is set for
partition types that are defined by the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>. This
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions Specification</ulink>. This
behavior may be switched off using <option>--growfs=no</option>. File systems are grown automatically
on access if all of the following conditions are met:</para>
<orderedlist>
<option>--verity-data=</option> specifies a path to a file with the Verity data to use for the OS
image, in case it is stored in a detached file. It is recommended to embed the Verity data directly
in the image, using the Verity mechanisms in the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>.
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions Specification</ulink>.
</para>
<xi:include href="version-info.xml" xpointer="v247"/></listitem>
<member><citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd.v</refentrytitle><manvolnum>7</manvolnum></citerefentry></member>
- <member><ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink></member>
+ <member><ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions Specification</ulink></member>
<member><citerefentry project='man-pages'><refentrytitle>mount</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>umount</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
<member><citerefentry project='man-pages'><refentrytitle>fdisk</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
are applied to file system in the indicated disk image. This is similar to <option>--root=</option>
but operates on file systems stored in disk images or block devices. The disk image should either
contain just a file system or a set of file systems within a GPT partition table, following the
- <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
+ <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions
Specification</ulink>. For further information on supported disk images, see
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
switch of the same name.</para>
(XBOOTLDR), and swap partitions and creates mount and swap units for them, based on the partition type
GUIDs of GUID partition tables (GPT). See <ulink url="https://uefi.org/specifications">UEFI
Specification</ulink>, chapter 5 for more details. It implements the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable
Partitions Specification</ulink>.</para>
<para>Note that this generator has no effect on non-GPT systems. It will also not create mount point
<entry>…</entry>
<entry>Root partitions for other architectures</entry>
<entry><filename>/</filename></entry>
- <entry>The first partition with the type UUID matching the architecture, located on the same disk as the ESP used for booting, is used as the root file system <filename>/</filename>. For the full list and constant values, see <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>.</entry>
+ <entry>The first partition with the type UUID matching the architecture, located on the same disk as the ESP used for booting, is used as the root file system <filename>/</filename>. For the full list and constant values, see <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions Specification</ulink>.</entry>
</row>
<row>
<entry><constant>SD_GPT_HOME</constant></entry>
<para>Mount and automount units for the EFI System Partition (ESP) and Extended Boot Loader Partition
(XBOOTLDR) are generated on EFI systems. If the disk contains an XBOOTLDR partition, as defined in the
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader
Specification</ulink>, it is made available at <filename>/boot/</filename>. This generator creates an
automount unit; the mount will only be activated on-demand when accessed. The mount point will be created
if necessary.</para>
automatic discovery of the root partition based on GPT partition information is enabled. This is a
superset of <varname>root=gpt-auto</varname>, as it automatically configures Verity partitions
(including signature-based setup) following the logic defined for that in the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification/">Discoverable
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification/">UAPI.2 Discoverable
Partitions Specification</ulink>. Moreover it takes the configured image policy and image filter into
account for all partition types, including the root file system. <literal>root=dissect</literal> will
wait for the factory reset phase to be completed if it is in effect before activating the root file
version 255.</para>
<para><command>var-partition-uuid</command> prints a UUID which, following the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable
Partitions Specification</ulink>, should be used as the GPT partition UUID for
<filename>/var/</filename>, being derived from the GPT partition type, keyed by the local
<filename>/etc/machine-id</filename>. Added in version 257.</para>
from downloaded disk images. This is only supported for <literal>raw</literal> disk images.</para>
<para>Note when this option is used with the purpose of mounting a disk image conforming to the
- <ulink url="https://uapi-group.org/specifications/specs/discoverable_disk_image/">Discoverable
+ <ulink url="https://uapi-group.org/specifications/specs/discoverable_disk_image/">UAPI.3 Discoverable
Disk Image Specification</ulink> as root file system, and the automatic GPT partition discovery
logic as implemented by
<citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry>
<para><command>systemd-measure</command> is a tool that may be used to pre-calculate and sign the
expected TPM2 PCR 11 values that should be seen when a Linux <ulink
- url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified Kernel Image
+ url="https://uapi-group.org/specifications/specs/unified_kernel_image/">UAPI.5 Unified Kernel Image
(UKI)</ulink> based on
<citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> is
booted up. It accepts paths to the ELF kernel image file, initrd image file, devicetree file, kernel
file descriptors for the file systems contained therein to clients, via a Varlink IPC API.</para>
<para>The disk images provided must contain a raw file system image or must follow the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification/">Discoverable
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification/">UAPI.2 Discoverable
Partitions Specification</ulink>. Before mounting any file systems authenticity of the disk image is
established in one or a combination of the following ways:</para>
partition of type
0fc63daf-8483-4772-8e79-3d69d8477de4.</para></listitem>
- <listitem><para>A GUID partition table (GPT) with a marked
- root partition which is mounted as the root directory of the
- container. Optionally, GPT images may contain a home and/or
- a server data partition which are mounted to the appropriate
- places in the container. All these partitions must be
- identified by the partition types defined by the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
- Partitions Specification</ulink>.</para></listitem>
+ <listitem><para>A GUID partition table (GPT) with a marked root partition which is mounted as the
+ root directory of the container. Optionally, GPT images may contain a home and/or a server data
+ partition which are mounted to the appropriate places in the container. All these partitions must
+ be identified by the partition types defined by the <ulink
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2
+ Discoverable Partitions Specification</ulink>.</para></listitem>
<listitem><para>No partition table, and a single file system spanning the whole image.</para></listitem>
</itemizedlist>
or credentials) or bind encryption to booted kernels.</para>
<para>For further details about the UKI concept, see the <ulink
- url="https://uapi-group.org/specifications/specs/unified_kernel_image/">UKI specification</ulink>.</para>
+ url="https://uapi-group.org/specifications/specs/unified_kernel_image/">UAPI.5 UKI specification</ulink>.</para>
</refsect1>
<refsect1>
<member><citerefentry><refentrytitle>systemd.exec</refentrytitle><manvolnum>5</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-creds</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-sysext</refentrytitle><manvolnum>8</manvolnum></citerefentry></member>
- <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member>
+ <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink></member>
<member><ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink></member>
<member><citerefentry><refentrytitle>ukify</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>systemd-measure</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<orderedlist>
<listitem><para>Plain directories or btrfs subvolumes containing the OS tree</para></listitem>
<listitem><para>Disk images with a GPT disk label, following the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink></para></listitem>
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions Specification</ulink></para></listitem>
<listitem><para>Disk images lacking a partition table, with a naked Linux file system (e.g. erofs,
squashfs or ext4)</para></listitem>
</orderedlist>
are applied to file system in the indicated disk image. This is similar to <option>--root=</option>
but operates on file systems stored in disk images or block devices. The disk image should either
contain just a file system or a set of file systems within a GPT partition table, following the
- <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
- Specification</ulink>. For further information on supported disk images, see
+ <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2
+ Discoverable Partitions Specification</ulink>. For further information on supported disk images, see
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
switch of the same name.</para>
are applied to file system in the indicated disk image. This is similar to <option>--root=</option>
but operates on file systems stored in disk images or block devices. The disk image should either
contain just a file system or a set of file systems within a GPT partition table, following the
- <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
+ <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions
Specification</ulink>. For further information on supported disk images, see
<citerefentry><refentrytitle>systemd-nspawn</refentrytitle><manvolnum>1</manvolnum></citerefentry>'s
switch of the same name.</para>
<para>Set the linux kernel image to use for direct kernel boot.
If a directory type image is used and <option>--linux=</option> was omitted, vmspawn will search for boot loader entries
according to the
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink> assuming
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink> assuming
XBOOTLDR to be located at /boot and ESP to be /efi respectively.
If no kernel was installed into the image then the image will fail to boot.</para>
<listitem>
<para>Set the initrd to use for direct kernel boot.
If the <option>--linux=</option> supplied is a
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink>
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink>
Type #2 entry, then this argument is not required.
If no initrd was installed into the image then the image will fail to boot.</para>
<member><citerefentry project='debian'><refentrytitle>mkosi</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><citerefentry><refentrytitle>importctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
- <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader Specification</ulink></member>
+ <member><ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader Specification</ulink></member>
</simplelist></para>
</refsect1>
</refentry>
or loopback file instead of a directory. The device node or file system image file needs to contain a
file system without a partition table, or a file system within an MBR/MS-DOS or GPT partition table
with only a single Linux-compatible partition, or a set of file systems within a GPT partition table
- that follows the
- <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">
- Discoverable Partitions Specification</ulink>.</para>
+ that follows the <ulink
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2
+ Discoverable Partitions Specification</ulink>.</para>
<para>When <varname>DevicePolicy=</varname> is set to <literal>closed</literal> or
<literal>strict</literal>, or set to <literal>auto</literal> and <varname>DeviceAllow=</varname> is
<title>Description</title>
<para>In systemd, whenever a disk image (DDI) implementing the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable
Partitions Specification</ulink> is activated, a filter may be specified controlling which partitions to
consider for mounting. Such a disk image dissection filter is a string that contains per-partition-type
patterns, separated by colons (<literal>:</literal>). The individual rules consist of a partition
<title>Description</title>
<para>In systemd, whenever a disk image (DDI) implementing the <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
- Partitions Specification</ulink> is activated, a policy may be specified controlling which partitions to
- mount and what kind of cryptographic protection to require. Such a disk image dissection policy is a
- string that contains per-partition-type rules, separated by colons (<literal>:</literal>). The individual
- rules consist of a partition identifier, an equal sign (<literal>=</literal>), and one or more flags
- which may be set per partition. If multiple flags are specified per partition they are separated by a
- plus sign (<literal>+</literal>).</para>
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2
+ Discoverable Partitions Specification</ulink> is activated, a policy may be specified controlling which
+ partitions to mount and what kind of cryptographic protection to require. Such a disk image dissection
+ policy is a string that contains per-partition-type rules, separated by colons
+ (<literal>:</literal>). The individual rules consist of a partition identifier, an equal sign
+ (<literal>=</literal>), and one or more flags which may be set per partition. If multiple flags are
+ specified per partition they are separated by a plus sign (<literal>+</literal>).</para>
<para>The partition identifiers currently defined are: <option>root</option>, <option>usr</option>,
<option>home</option>, <option>srv</option>, <option>esp</option>, <option>xbootldr</option>,
<para>The variable part of the filenames in the <literal>.v/</literal> directories are filtered and
compared primarily with a version comparison, implementing <ulink
- url="https://uapi-group.org/specifications/specs/version_format_specification/">Version Format
+ url="https://uapi-group.org/specifications/specs/version_format_specification/">UAPI.10 Version Format
Specification</ulink>. However, additional rules apply:</para>
<itemizedlist>
<listitem><para>A file <literal>https://download.example.com/foobarOS_47.root.xz</literal> should be
downloaded, decompressed and written to a previously unused partition with GPT partition type UUID
4f68bce3-e8cd-4db1-96e7-fbcaf984b709 for x86-64, as per <ulink
- url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
- Specification</ulink>.</para></listitem>
+ url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2
+ Discoverable Partitions Specification</ulink>.</para></listitem>
<listitem><para>Similarly, a file <literal>https://download.example.com/foobarOS_47.verity.xz</literal>
should be downloaded, decompressed and written to a previously empty partition with GPT partition type
for x86-64 root file systems).</para></listitem>
<listitem><para>Finally, a file <literal>https://download.example.com/foobarOS_47.efi</literal> (a
- unified kernel, as per <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
+ unified kernel, as per <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader
Specification</ulink> Type #2) should be downloaded, decompressed and written to the $BOOT file system,
i.e. to <filename>EFI/Linux/foobarOS_47.efi</filename> in the ESP or XBOOTLDR partition.</para></listitem>
</orderedlist>
<entry><literal>@a</literal></entry>
<entry>GPT partition flag NoAuto</entry>
<entry>Either <literal>0</literal> or <literal>1</literal></entry>
- <entry>Controls NoAuto bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry>
+ <entry>Controls NoAuto bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry>
</row>
<row>
<entry><literal>@g</literal></entry>
<entry>GPT partition flag GrowFileSystem</entry>
<entry>Either <literal>0</literal> or <literal>1</literal></entry>
- <entry>Controls GrowFileSystem bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry>
+ <entry>Controls GrowFileSystem bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions Specification</ulink>; only relevant if target resource type chosen as <constant>partition</constant></entry>
</row>
<row>
<entry><literal>@r</literal></entry>
<entry>Read-only flag</entry>
<entry>Either <literal>0</literal> or <literal>1</literal></entry>
- <entry>Controls ReadOnly bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions Specification</ulink> and other output read-only flags, see <varname>ReadOnly=</varname> below</entry>
+ <entry>Controls ReadOnly bit of the GPT partition flags, as per <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions Specification</ulink> and other output read-only flags, see <varname>ReadOnly=</varname> below</entry>
</row>
<row>
<para>If set to <constant>root</constant>, <constant>esp</constant>, <constant>xbootldr</constant>,
the specified <varname>Path=</varname> will be resolved relative to the mount point of the
corresponding partition, as defined by the
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader
Specification</ulink>.</para>
<para>If set to <constant>boot</constant>, the specified <varname>Path=</varname> will be resolved
relative to the mount point of the $BOOT partition (i.e. the ESP or XBOOTLDR), as defined by the
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader
Specification</ulink>.</para>
<para>If set to <constant>explicit</constant>, the specified <varname>Path=</varname> will be
overall <varname>PartitionFlags=</varname> flags setting and the individual flag settings
<varname>PartitionNoAuto=</varname> and <varname>PartitionGrowFileSystem=</varname> are used (or the
wildcards for them), then the latter override the former, i.e. the individual flag bit overrides the
- overall flags value. See <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable
+ overall flags value. See <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable
Partitions Specification</ulink> for details about these flags.</para>
<para>Note that these settings are not used for matching, they only have effect on newly written
<listitem><para>Controls whether to mark the resulting file, subvolume or partition read-only. If the
target type is <constant>partition</constant> this controls the ReadOnly partition flag, as per
- <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">Discoverable Partitions
+ <ulink url="https://uapi-group.org/specifications/specs/discoverable_partitions_specification">UAPI.2 Discoverable Partitions
Specification</ulink>, similar to the <varname>PartitionNoAuto=</varname> and
<varname>PartitionGrowFileSystem=</varname> flags described above. If the target type is
<constant>regular-file</constant>, the writable bit is removed from the access mode. If the
InstancesMax=2</programlisting></para>
<para>The above installs a unified kernel image into the $BOOT partition, as per
- <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">Boot Loader
+ <ulink url="https://uapi-group.org/specifications/specs/boot_loader_specification">UAPI.1 Boot Loader
Specification</ulink> Type #2. This defines three possible patterns for the names of the kernel
images, as per <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot Assessment</ulink>,
and ensures when installing new kernels, they are set up with 3 tries left. No more than two parallel
<para><command>ukify</command> is a tool whose primary purpose is to combine components (usually a
kernel, an initrd, and the
<citerefentry><refentrytitle>systemd-stub</refentrytitle><manvolnum>7</manvolnum></citerefentry> UEFI
- stub) to create a <ulink url="https://uapi-group.org/specifications/specs/unified_kernel_image/">Unified
+ stub) to create a <ulink url="https://uapi-group.org/specifications/specs/unified_kernel_image/">UAPI.5 Unified
Kernel Image (UKI)</ulink> — a single PE binary that boots the system. When the UKI is executed, the stub
extracts and boots the embedded linux kernel. The UKI can be started directly by the firmware or through
a boot loader. When used with <ulink url="https://www.qemu.org/docs/master/">qemu</ulink>, a UKI can also
projects / thirdparty / systemd.git / commitdiff
