morgan/systemd
1
0
Fork 0
mirror of https://github.com/morgan9e/systemd synced 2026-04-14 00:14:32 +09:00
Code Issues Packages Projects Releases Wiki Activity

docs: reference UAPI specs by their number when linked

Browse Source
This commit is contained in:
Lennart Poettering
2025-11-23 17:16:09 +01:00
parent 19deb47ade
commit 81b52a013c
10 changed files with 29 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/AUTOMATIC_BOOT_ASSESSMENT.md
View File

@@ -9,7 +9,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later
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
[Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification/#boot-counting)
[UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification/#boot-counting)
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.
@@ -28,7 +28,7 @@ Here's a brief overview of the complete set of components:
* The
[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
boot loader optionally maintains a per-boot-loader-entry counter described by
the [Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification/#boot-counting)
the [UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification/#boot-counting)
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.
@@ -61,7 +61,7 @@ Here's a brief overview of the complete set of components:
## Details
As described in the
[Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification/#boot-counting),
[UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification/#boot-counting),
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`).

6
docs/BOOT_LOADER_INTERFACE.md
View File

@@ -136,7 +136,7 @@ the identifiers as passed in `LoaderEntries`, `LoaderEntryDefault`,
names for them in UIs.
1. When boot loader entries are defined through the
[Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification/)
[BOOT.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/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.
@@ -167,8 +167,8 @@ names for them in UIs.
## Links
[Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification)<br>
[Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification)<br>
[UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification)<br>
[UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification)<br>
[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
[`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)<br>
[`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html)

8
docs/BUILDING_IMAGES.md
View File

@@ -66,7 +66,7 @@ boot. For that it's essential to:
The
[`kernel-install(8)`](https://www.freedesktop.org/software/systemd/man/kernel-install.html)
logic used to generate
[Boot Loader Specification Type #1](https://uapi-group.org/specifications/specs/boot_loader_specification/#type-1-boot-loader-specification-entries)
[UAPI.1 Boot Loader Specification Type #1](https://uapi-group.org/specifications/specs/boot_loader_specification/#type-1-boot-loader-specification-entries)
entries by default uses the machine ID as stored in `/etc/machine-id` for
naming boot menu entries and the directories in the ESP to place kernel images in.
This is done in order to allow multiple installations of the same OS on the
@@ -207,7 +207,7 @@ it, then format it.
in. The `x-systemd.growfs` mount option in `/etc/fstab` is sufficient to
enable this logic for specific mounts. Alternatively appropriately set up
partitions can set GPT partition flag 59 to request this behaviour, see the
[Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification)
[UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification)
for details. If the file system is already grown it executes no operation.
3. Similar, the `systemd-makefs@.service` and `systemd-makeswap@.service`
@@ -268,8 +268,8 @@ fields.
[`machine-id(5)`](https://www.freedesktop.org/software/systemd/man/machine-id.html)<br>
[`systemd-random-seed(8)`](https://www.freedesktop.org/software/systemd/man/systemd-random-seed.service.html)<br>
[`os-release(5)`](https://www.freedesktop.org/software/systemd/man/os-release.html)<br>
[Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification)<br>
[Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification)<br>
[UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification)<br>
[UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification)<br>
[`mkosi`](https://github.com/systemd/mkosi)<br>
[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)<br>
[`systemd-repart(8)`](https://www.freedesktop.org/software/systemd/man/systemd-repart.service.html)<br>

10
docs/ENVIRONMENT.md
View File

@@ -234,7 +234,7 @@ All tools:
file may be checked for by services run during system shutdown in order to
request the appropriate operation from the boot loader in an alternative
fashion. Note that by default only boot loader entries which follow the
[Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification)
[UAPI.1 Boot Loader Specification](https://uapi-group.org/specifications/specs/boot_loader_specification)
and are placed in the ESP or the Extended Boot Loader partition may be
selected this way. However, if a directory `/run/boot-loader-entries/`
exists, the entries are loaded from there instead. The directory should
@@ -518,7 +518,7 @@ disk images with `--image=` or similar:
to load the embedded Verity signature data. If enabled (which is the
default), Verity root hash information and a suitable signature is
automatically acquired from a signature partition, following the
[Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification).
[UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification).
If disabled any such partition is ignored. Note that this only disables
discovery of the root hash and its signature, the Verity data partition
itself is still searched in the GPT image.
@@ -540,7 +540,7 @@ disk images with `--image=` or similar:
* `$SYSTEMD_DISSECT_FSTYPE_<DESIGNATOR>=` – overrides the file system time to
use when mounting the partition of the indicated designator. The
`<DESIGNATOR>` string shall be one of `ROOT`, `USR`, `HOME`, `SRV`, `ESP`,
`XBOOTLDR`, `TMP`, `VAR` as per the [Discoverable Partitions
`XBOOTLDR`, `TMP`, `VAR` as per the [UAPI.2 Discoverable Partitions
Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification/). If
unspecified the image dissection logic will automatically probe the file
system type (subject to `$SYSTEMD_DISSECT_FILE_SYSTEMS`, see above), except
@@ -560,8 +560,8 @@ disk images with `--image=` or similar:
* `$SYSTEMD_DISSECT_VERITY_GUESS` – takes a boolean. Controls whether to guess
the Verity root hash from the partition UUIDs of a suitable pair of data
partition and matching Verity partition: the UUIDs two are simply joined and
used as root hash, in accordance with the recommendations in [Discoverable
Partitions
used as root hash, in accordance with the recommendations in [UAPI.2
Discoverable Partitions
Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification). Defaults
to true.

2
docs/MOUNT_REQUIREMENTS.md
View File

@@ -11,7 +11,7 @@ This document describes the requirements placed by systemd
on the time when various parts of the file system hierarchy
must be available and mounted during boot.
This document should be read in conjunction with
[Linux File System Hierarchy](https://uapi-group.org/specifications/specs/linux_file_system_hierarchy/),
[UAPI.9 Linux File System Hierarchy](https://uapi-group.org/specifications/specs/linux_file_system_hierarchy/),
which describes the role of the mount points discussed here.
If the file system backing a mount point is located on external or remote media

2
docs/PORTABLE_SERVICES.md
View File

@@ -162,7 +162,7 @@ Specifically, the following requirements are made for an image that can be attac
an image with a partition table understood by the Linux kernel with only a
single partition defined, or alternatively, a GPT partition table with a set
of properly marked partitions following the
[Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification).
[UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification).
3. The image must at least contain one matching unit file, with the right name
prefix and suffix (see above).

2
docs/PORTING_TO_NEW_ARCHITECTURES.md
View File

@@ -27,7 +27,7 @@ architecture.
partitions. Use `systemd-id128 new -p` to generate new suitable UUIDs you
can use for this. Make sure to register your new types in the various
functions in `gpt.c`. Also make sure to update the tables in
[Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification)
[UAPI.2 Discoverable Partitions Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification)
and `man/systemd-gpt-auto-generator.xml` accordingly.
3. If your architecture supports UEFI, make sure to update the `efi_arch`

2
docs/RELEASE.md
View File

@@ -13,7 +13,7 @@ SPDX-License-Identifier: LGPL-2.1-or-later
4. Update hwdb (`ninja -C build update-hwdb`, `ninja -C build update-hwdb-autosuspend`, commit separately).
5. Update syscall numbers (`ninja -C build update-syscall-tables update-syscall-header`).
6. [RC1] Update library numbers in `meson.build`
7. Update version number in `meson.version` (e.g. from `256~devel` to `256~rc1` or from `256~rc3` to `256`). Note that this uses a tilde (\~) instead of a hyphen (-) because tildes sort lower in version comparisons according to the [version format specification](https://uapi-group.org/specifications/specs/version_format_specification/), and we want `255~rc1` to sort lower than `255`.
7. Update version number in `meson.version` (e.g. from `256~devel` to `256~rc1` or from `256~rc3` to `256`). Note that this uses a tilde (\~) instead of a hyphen (-) because tildes sort lower in version comparisons according to the [UAPI.10 Version Format Specification](https://uapi-group.org/specifications/specs/version_format_specification/), and we want `255~rc1` to sort lower than `255`.
8. Check dbus docs with `ninja -C build update-dbus-docs`
9. Check manpages list with `ninja -C build update-man-rules`
10. Update translation strings (`ninja -C build systemd-pot`, `ninja -C build systemd-update-po`) - drop the header comments from `systemd.pot` + re-add SPDX before committing. If the only change in a file is the 'POT-Creation-Date' field, then ignore that file.

14
docs/ROOTFS_DISCOVERY.md
View File

@@ -15,13 +15,13 @@ components:
i.e. [`systemd-boot`](https://www.freedesktop.org/software/systemd/man/latest/systemd-boot.html)
that provides interactive and programmatic control of what precisely to
boot. It takes care of enumerating all possible boot targets (implementing
the [Boot Loader
the [UAPI.1 Boot Loader
Specification](https://uapi-group.org/specifications/specs/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.
2. A [unified kernel image
2. A [UAPI.5 Unified Kernel Image
("UKI")](https://uapi-group.org/specifications/specs/unified_kernel_image/),
i.e. an UEFI PE executable that combines
[`systemd-stub`](https://www.freedesktop.org/software/systemd/man/latest/systemd-stub.html),
@@ -133,7 +133,7 @@ the same disk. Specifically:
ESP as well, in particular below the `/loader/` subdirectory.
2. The UKIs may either be placed in the ESP (below the `/EFI/Linux/`
subdirectory), or in the [Extended Boot Loader
subdirectory), or in the [UAPI.1 Extended Boot Loader
Partition](https://uapi-group.org/specifications/specs/boot_loader_specification/#the-partitions)
("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
@@ -146,7 +146,7 @@ the same disk. Specifically:
3. 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 [Discoverable Partitions
discovered and mounted, see the [UAPI.2 Discoverable Partitions
Specification](https://uapi-group.org/specifications/specs/discoverable_partitions_specification/)
for details.
@@ -179,8 +179,8 @@ each of these resources:
[`bootctl`](https://www.freedesktop.org/software/systemd/man/latest/bootctl.html),
`efibootmgr` or `kernel-bootcfg`.
2. The `systemd-boot` boot loader may be configured via [`Boot Loader
Specification Type #1`](https://uapi-group.org/specifications/specs/boot_loader_specification/)
2. The `systemd-boot` boot loader may be configured via [UAPI.1 Boot Loader
Specification Type #1](https://uapi-group.org/specifications/specs/boot_loader_specification/)
entries to acquire UKIs or similar from other locations.
3. The `initrd` part of the UKI understands the `root=` (and `mount.usr=`)
@@ -220,7 +220,7 @@ local disk. This can happen at each of these three components:
`rootfs` from HTTP
sources](https://www.freedesktop.org/software/systemd/man/latest/systemd-import-generator.html),
either in a GPT disk image (specifically:
[DDIs](https://uapi-group.org/specifications/specs/discoverable_disk_image/),
[UAPI.3 DDIs](https://uapi-group.org/specifications/specs/discoverable_disk_image/),
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

6
docs/TPM2_PCR_MEASUREMENTS.md
View File

@@ -17,7 +17,7 @@ to systemd's UEFI-mode measurements, and if the latter are not done the former
aren't made either.
See
[Linux TPM PCR Registry](https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/)
[UAPI.7 Linux TPM PCR Registry](https://uapi-group.org/specifications/specs/linux_tpm_pcr_registry/)
for an overview of PCRs.
systemd will measure to PCRs 5 (`boot-loader-config`), 11 (`kernel-boot`),
@@ -108,8 +108,8 @@ trailing NUL bytes).
### PCR 11, `EV_IPL`, PE section name
A measurement is made for each PE section of the UKI that is defined by the
[UKI
specification](https://uapi-group.org/specifications/specs/unified_kernel_image/),
[UAPI.5 UKI
Specification](https://uapi-group.org/specifications/specs/unified_kernel_image/),
in the canonical order described in the specification.
Happens once for each UKI-defined PE section of the UKI, in the canonical UKI