is not reset, and carries a valid ID every instance of the system will come
up with the same ID and that will likely lead to problems sooner or later,
as many network-visible identifiers are commonly derived from the machine
- ID, for example IPv6 addresses or transient MAC addresses.
+ 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)
+ [`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`](https://www.freedesktop.org/software/systemd/man/machine-info.html)
which carry additional identifying information about the OS image.
+5. Remove `/var/lib/systemd/credential.secret` which is used for protecting
+ service credentials, see
+ [`systemd.exec(5)`](https://www.freedesktop.org/software/systemd/man/systemd.exec.html#Credentials)
+ and
+ [`systemd-creds(1)`](https://www.freedesktop.org/software/systemd/man/systemd-creds.html)
+ for details. Note that by removing this file access to previously encrypted
+ credentials from this image is lost. The file is automatically generated if
+ a new credential is encrypted and the file does not exist yet.
+
## Boot Menu Entry Identifiers
-The `kernel-install` 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
-allow multiple installations of the same OS on the same system without
-conflicts. However, this is problematic if the machine ID shall be generated
-automatically on first boot: if the ID is not known before the first boot it
-cannot be used to name the most basic resources required for the boot process
-to complete.
+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)
+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
+same system without conflicts. However, this is problematic if the machine ID
+shall be generated automatically on first boot: if the ID is not known before
+the first boot it cannot be used to name the most basic resources required for
+the boot process to complete.
Thus, for images that shall acquire their identity on first boot only, it is
required to use a different identifier for naming boot menu entries. To allow
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`
+this file, for example, the `IMAGE_ID=` or `ID=` field from
+[`/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.
Specifically, the following mechanisms are in place:
-1. The `swich-root` logic in systemd, that is used to switch from the initrd
+1. The `switch-root` logic in systemd, that is used to switch from the initrd
phase to the host will create the basic OS hierarchy skeleton if missing. It
will create a couple of directories strictly necessary to boot up
successfully, plus essential symlinks (such as those necessary for the
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)
- will component automatically populate `/etc/passwd` and `/etc/group` on
+ [`systemd-sysusers(8)`](https://www.freedesktop.org/software/systemd/man/systemd-sysusers.service.html)
+ component will 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
`/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
`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
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://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`
services can format file systems and swap spaces before first use, if they
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.
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)<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>
+[`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>
+[`systemd-growfs@(8).service`](https://www.freedesktop.org/software/systemd/man/systemd-growfs.html)<br>