From a43d2229bb3ba6b814d958c6f9d73b74f305ff82 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 23 Mar 2022 12:02:00 +0100 Subject: [PATCH 1/3] docs: make man page links in markdown Links section use teletype font, as we usually do --- docs/BOOT_LOADER_INTERFACE.md | 6 +++--- docs/BOOT_LOADER_SPECIFICATION.md | 6 +++--- docs/PORTABLE_SERVICES.md | 4 ++-- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/BOOT_LOADER_INTERFACE.md b/docs/BOOT_LOADER_INTERFACE.md index 0e0eab7a282..a96c081a86d 100644 --- a/docs/BOOT_LOADER_INTERFACE.md +++ b/docs/BOOT_LOADER_INTERFACE.md @@ -148,6 +148,6 @@ names for them in UIs. [Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)
[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)
-[systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
-[bootctl(1)](https://www.freedesktop.org/software/systemd/man/bootctl.html)
-[systemd-gpt-auto-generator(8)](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) +[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
+[`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)
+[`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) diff --git a/docs/BOOT_LOADER_SPECIFICATION.md b/docs/BOOT_LOADER_SPECIFICATION.md index 375efeb1d19..5c93a0ec724 100644 --- a/docs/BOOT_LOADER_SPECIFICATION.md +++ b/docs/BOOT_LOADER_SPECIFICATION.md @@ -440,6 +440,6 @@ There are a couple of items that are out of focus for this specification: [GUID Partition Table](https://en.wikipedia.org/wiki/GUID_Partition_Table)
[Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE)
[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)
-[systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
-[bootctl(1)](https://www.freedesktop.org/software/systemd/man/bootctl.html)
-[systemd-gpt-auto-generator(8)](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) +[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
+[`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)
+[`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) diff --git a/docs/PORTABLE_SERVICES.md b/docs/PORTABLE_SERVICES.md index 15b47d40f2e..7f67be2b086 100644 --- a/docs/PORTABLE_SERVICES.md +++ b/docs/PORTABLE_SERVICES.md @@ -337,7 +337,7 @@ services copied onto the host. ## Links -[portablectl(1)](https://www.freedesktop.org/software/systemd/man/portablectl.html)
-[systemd-portabled.service(8)](https://www.freedesktop.org/software/systemd/man/systemd-portabled.service.html)
+[`portablectl(1)`](https://www.freedesktop.org/software/systemd/man/portablectl.html)
+[`systemd-portabled.service(8)`](https://www.freedesktop.org/software/systemd/man/systemd-portabled.service.html)
[Walkthrough for Portable Services](https://0pointer.net/blog/walkthrough-for-portable-services.html)
[Repo with examples](https://github.com/systemd/portable-walkthrough) From 8f39ecf6aa5bdfd2498e147476eb4b8f25d817bc Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 23 Mar 2022 12:04:28 +0100 Subject: [PATCH 2/3] docs: link up new image building docs a bit --- docs/DISCOVERABLE_PARTITIONS.md | 7 ++++--- man/machine-id.xml | 14 +++++++------- man/systemd-random-seed.service.xml | 3 ++- 3 files changed, 13 insertions(+), 11 deletions(-) diff --git a/docs/DISCOVERABLE_PARTITIONS.md b/docs/DISCOVERABLE_PARTITIONS.md index 2d95ee44904..85e858921fb 100644 --- a/docs/DISCOVERABLE_PARTITIONS.md +++ b/docs/DISCOVERABLE_PARTITIONS.md @@ -412,6 +412,7 @@ The `gdisk` tool (from version 1.0.5 onward) and its variants (`sgdisk`, [Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)
[Boot Loader Interface](https://systemd.io/BOOT_LOADER_INTERFACE)
-[systemd-boot(7)](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
-[bootctl(1)](https://www.freedesktop.org/software/systemd/man/bootctl.html)
-[systemd-gpt-auto-generator(8)](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) +[Safely Building Images](https://systemd.io/BUILDING_IMAGES)
+[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
+[`bootctl(1)`](https://www.freedesktop.org/software/systemd/man/bootctl.html)
+[`systemd-gpt-auto-generator(8)`](https://www.freedesktop.org/software/systemd/man/systemd-gpt-auto-generator.html) diff --git a/man/machine-id.xml b/man/machine-id.xml index d5d3a1a299c..9bd49582fce 100644 --- a/man/machine-id.xml +++ b/man/machine-id.xml @@ -80,13 +80,13 @@ /etc/machine-id may also be written using any other means. - For operating system images which are created once and used on multiple - machines, for example for containers or in the cloud, - /etc/machine-id should be either missing or an empty file in the generic file - system image (the difference between the two options is described under "First Boot Semantics" below). An - ID will be generated during boot and saved to this file if possible. Having an empty file in place is - useful because it allows a temporary file to be bind-mounted over the real file, in case the image is - used read-only. + For operating system images which are created once and used on multiple machines, for example for + containers or in the cloud, /etc/machine-id should be either missing or an empty + file in the generic file system image (the difference between the two options is described under "First + Boot Semantics" below). An ID will be generated during boot and saved to this file if possible. Having an + empty file in place is useful because it allows a temporary file to be bind-mounted over the real file, + in case the image is used read-only. Also see Safely + Building Images. systemd-firstboot1 may be used to initialize /etc/machine-id on mounted (but not diff --git a/man/systemd-random-seed.service.xml b/man/systemd-random-seed.service.xml index 3137ed0c81d..0a50b51e4d4 100644 --- a/man/systemd-random-seed.service.xml +++ b/man/systemd-random-seed.service.xml @@ -57,7 +57,8 @@ thus — if otherwise entropy-starved — generate the same or at least guessable random seed streams. As a safety precaution crediting entropy is thus disabled by default. It is recommended to remove the random seed from OS images intended for replication on multiple systems, in which case it is safe to enable - entropy crediting, see below. + entropy crediting, see below. Also see Safely Building + Images. See Random Seeds for further information. From 3976da0265198e3d361270e261065573b5061982 Mon Sep 17 00:00:00 2001 From: Lennart Poettering Date: Wed, 23 Mar 2022 12:24:03 +0100 Subject: [PATCH 3/3] docs: extend BUILDING_IMAGES with a section about IMAGE_ID=/IMAGE_VERSION= Also, beef up links everywhere. --- docs/BUILDING_IMAGES.md | 76 +++++++++++++++++++++++++++++++---------- 1 file changed, 58 insertions(+), 18 deletions(-) diff --git a/docs/BUILDING_IMAGES.md b/docs/BUILDING_IMAGES.md index 8b486a94b95..c415eda3ec2 100644 --- a/docs/BUILDING_IMAGES.md +++ b/docs/BUILDING_IMAGES.md @@ -35,24 +35,29 @@ boot. For that it's essential to: ID, for example IPv6 addresses or transient MAC addresses. 2. Remove the `/var/lib/systemd/random-seed` file (see - [`systemd-random-seed(8)`](https://www.freedesktop.org/software/systemd/man/systemd-random-seed.service.html), + [`systemd-random-seed(8)`](https://www.freedesktop.org/software/systemd/man/systemd-random-seed.service.html)), which is used to seed the kernel's random pool on boot. If this file is shipped pre-initialized, every instance will seed its random pool with the same random data that is included in the image, and thus possibly generate - random data that is more similar to other instances booted off the same image - than advisable. + random data that is more similar to other instances booted off the same + image than advisable. 3. Remove the `/loader/random-seed` file (see [`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html) from the UEFI System Partition (ESP), in case the `systemd-boot` boot loader is used in the image. -4. It might also make sense to remove `/etc/hostname` and `/etc/machine-info` +4. It might also make sense to remove + [`/etc/hostname`](https://www.freedesktop.org/software/systemd/man/hostname.html) + and + [`/etc/machine-info`][`systemd-random-seed(8)`](https://www.freedesktop.org/software/systemd/man/machine-info.html) which carry additional identifying information about the OS image. ## Boot Menu Entry Identifiers -The `kernel-install` logic used to generate [Boot Loader Specification Type +The +[`kernel-install(8)`](https://www.freedesktop.org/software/systemd/man/kernel-install.html) +logic used to generate [Boot Loader Specification Type 1](https://systemd.io/BOOT_LOADER_SPECIFICATION) 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 @@ -70,7 +75,8 @@ resources of the OS. If not configured explicitly it defaults to the machine ID. The file `/etc/kernel/entry-token` may be used to configure this string explicitly. Thus, golden image builders should write a suitable identifier into this file, for example the `IMAGE_ID=` or `ID=` field from -`/etc/os-release`. It is recommended to do this before the `kernel-install` +[`/etc/os-release`](https://www.freedesktop.org/software/systemd/man/os-release.html) +(also see below). It is recommended to do this before the `kernel-install` functionality is invoked (i.e. before the package manager is used to install packages into the OS tree being prepared), so that the selected string is automatically used for all entries to be generated. @@ -95,16 +101,18 @@ Specifically, the following mechanisms are in place: 2. PID 1 will initialize `/etc/machine-id` automatically if not initialized yet (see above). -3. The `nss-systemd` glibc NSS module ensures the `root` and `nobody` users and - groups remain resolvable, even without `/etc/passwd` and `/etc/group` around. +3. The + [`nss-systemd(8)`](https://www.freedesktop.org/software/systemd/man/nss-systemd.html) + glibc NSS module ensures the `root` and `nobody` users and groups remain + resolvable, even without `/etc/passwd` and `/etc/group` around. 4. The - [`systemd-sysusers`](https://www.freedesktop.org/software/systemd/man/systemd-sysusers.service.html) + [`systemd-sysusers(8)`](https://www.freedesktop.org/software/systemd/man/systemd-sysusers.service.html) will component automatically populate `/etc/passwd` and `/etc/group` on first boot with further necessary system users. 5. The - [`systemd-tmpfiles`](https://www.freedesktop.org/software/systemd/man/systemd-tmpfiles-setup.service.html) + [`systemd-tmpfiles(8)`](https://www.freedesktop.org/software/systemd/man/systemd-tmpfiles-setup.service.html) component ensures that various files and directories below `/etc/`, `/var/` and other places are created automatically at boot if missing. Unlike the directories/symlinks created by the `switch-root` logic above this logic is @@ -113,8 +121,10 @@ Specifically, the following mechanisms are in place: `/usr/lib/os-release`, ensuring that the OS release information is unconditionally accessible through `/etc/os-release`. -6. The `nss-myhostname` glibc NSS module will ensure the local host name as - well as `localhost` remains resolvable, even without `/etc/hosts` around. +6. The + [`nss-myhostname(8)`](https://www.freedesktop.org/software/systemd/man/nss-myhostname.html) + glibc NSS module will ensure the local host name as well as `localhost` + remains resolvable, even without `/etc/hosts` around. With these mechanisms the hierarchies below `/var/` and `/etc/` can be safely and robustly populated on first boot, so that the OS can safely boot up. Note @@ -170,7 +180,7 @@ it, then format it. `systemd` provides multiple tools to implement the above logic: 1. The - [`systemd-repart`](https://www.freedesktop.org/software/systemd/man/systemd-repart.service.html) + [`systemd-repart(8)`](https://www.freedesktop.org/software/systemd/man/systemd-repart.service.html) component may manipulate GPT partition tables automatically on boot, growing partitions or adding in partitions taking the backing storage size into account. It can also encrypt partitions automatically it creates (even bind @@ -179,11 +189,14 @@ it, then format it. incompletely set up partitions around. 2. The - [`systemd-makefs@(8).service`](https://www.freedesktop.org/software/systemd/man/systemd-growfs.html) + [`systemd-growfs@(8).service`](https://www.freedesktop.org/software/systemd/man/systemd-growfs.html) tool can automatically grow a file system to the partition it is contained - in. The `x-systemd.growfs` `/etc/fstab` mount option is sufficient to enable - this logic for specific mounts. If the file system is already grown it - executes no operation. + 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://systemd.io/DISCOVERABLE_PARTITIONS) for details. If + the file system is already grown it executes no operation. 3. Similar, the `systemd-makefs@.service` and `systemd-makeswap@.service` services can format file systems and swap spaces before first use, if they @@ -196,7 +209,7 @@ While a lot of work has gone into ensuring `systemd` systems can safely boot with unpopulated `/etc/` trees, it sometimes is desirable to set a couple of basic settings *after* `dd`-ing the image to disk, but *before* first boot. For this the tool -[`systemd-firstboot`](https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html) +[`systemd-firstboot(1)`](https://www.freedesktop.org/software/systemd/man/systemd-firstboot.html) can be useful, with its `--image=` switch. It may be used to set very basic settings, such as the root password or hostname on an OS disk image or installed block device. @@ -225,3 +238,30 @@ initialization status of `/etc/machine-id`: if the file already carries a valid ID the system is already past the first boot. If it is not initialized yet it is still considered in the first boot state. For details see [`machine-id(5)`](https://www.freedesktop.org/software/systemd/man/machine-id.html). + +## Image Metadata + +Typically, when operating with golden disk images it is useful to be able to +identify them and their version. For this the two fields `IMAGE_ID=` and +`IMAGE_VERSION=` have been defined in +[`os-release(5)`](https://www.freedesktop.org/software/systemd/man/os-release.html). These +fields may be accessed from unit files and similar via the `%M` and `%A` +specifiers. + +Depending on how the images are put together it might make sense to leave the +OS distribution's `os-release` file as is in `/usr/lib/os-release` but to +replace the usual `/etc/os-release` symlink with a regular file that extends +the distribution's file with one augmented with these two additional +fields. + +## Links + +[`machine-id(5)`](https://www.freedesktop.org/software/systemd/man/machine-id.html) +[`systemd-random-seed(8)`](https://www.freedesktop.org/software/systemd/man/systemd-random-seed.service.html) +[`os-release(5)`](https://www.freedesktop.org/software/systemd/man/os-release.html) +[Boot Loader Specification](https://systemd.io/BOOT_LOADER_SPECIFICATION)
+[Discoverable Partitions Specification](https://systemd.io/DISCOVERABLE_PARTITIONS)
+[`mkosi`](https://github.com/systemd/mkosi) +[`systemd-boot(7)`](https://www.freedesktop.org/software/systemd/man/systemd-boot.html)
+[`systemd-repart(8)`](https://www.freedesktop.org/software/systemd/man/systemd-repart.service.html) +[`systemd-growfs@(8).service`](https://www.freedesktop.org/software/systemd/man/systemd-growfs.html)