diff options
| -rw-r--r-- | man/bootctl.xml | 22 | ||||
| -rw-r--r-- | man/loader.conf.xml | 16 | ||||
| -rw-r--r-- | man/rules/meson.build | 1 | ||||
| -rw-r--r-- | man/systemd-boot-system-token.service.xml | 76 | ||||
| -rw-r--r-- | man/systemd-boot.xml | 102 | ||||
| -rw-r--r-- | man/systemd-random-seed.service.xml | 57 |
6 files changed, 243 insertions, 31 deletions
diff --git a/man/bootctl.xml b/man/bootctl.xml index 46b9738b14..28826d621c 100644 --- a/man/bootctl.xml +++ b/man/bootctl.xml @@ -45,15 +45,15 @@ <varlistentry> <term><option>--esp-path=</option></term> <listitem><para>Path to the EFI System Partition (ESP). If not specified, <filename>/efi/</filename>, - <filename>/boot/</filename>, and <filename>/boot/efi</filename> are checked in turn. It is recommended to mount - the ESP to <filename>/efi/</filename>, if possible.</para></listitem> + <filename>/boot/</filename>, and <filename>/boot/efi/</filename> are checked in turn. It is + recommended to mount the ESP to <filename>/efi/</filename>, if possible.</para></listitem> </varlistentry> <varlistentry> <term><option>--boot-path=</option></term> <listitem><para>Path to the Extended Boot Loader partition, as defined in the <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>. If not - specified, <filename>/boot/</filename> are checked. It is recommended to mount the Extended Boot + specified, <filename>/boot/</filename> is checked. It is recommended to mount the Extended Boot Loader partition to <filename>/boot/</filename>, if possible.</para></listitem> </varlistentry> @@ -125,6 +125,19 @@ </varlistentry> <varlistentry> + <term><option>random-seed</option></term> + + <listitem><para>Generates a random seed and stores it in the EFI System Partition, for use by the + <command>systemd-boot</command> boot loader. Also, generates a random 'system token' and stores it + persistently as an EFI variable, if one has not been set before. If the boot loader finds the random + seed in the ESP and the system token in the EFI variable it will derive a random seed to pass to the + OS and a new seed to store in the ESP from the combination of both. The random seed passed to the OS + is credited to the kernel's entropy pool by the system manager during early boot, and permits + userspace to boot up with an entropy pool fully initialized very early on. Also see + <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.</para></listitem> + </varlistentry> + + <varlistentry> <term><option>list</option></term> <listitem><para>Shows all available boot loader entries implementing the <ulink @@ -165,7 +178,8 @@ <para> <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, - <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink> + <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>, + <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> </para> </refsect1> </refentry> diff --git a/man/loader.conf.xml b/man/loader.conf.xml index 38a80861b8..cef20b59d8 100644 --- a/man/loader.conf.xml +++ b/man/loader.conf.xml @@ -153,6 +153,22 @@ <listitem><para>Takes a boolean argument. Enable (the default) or disable the "Reboot into firmware" entry.</para></listitem> </varlistentry> + + <varlistentry> + <term>random-seed-mode</term> + + <listitem><para>Takes one of <literal>off</literal>, <literal>with-system-token</literal> and + <literal>always</literal>. If <literal>off</literal> no random seed data is read off the ESP, nor + passed to the OS. If <literal>with-system-token</literal> (the default) + <command>systemd-boot</command> will read a random seed from the ESP (from the file + <filename>/loader/random-seed</filename>) only if the <varname>LoaderSystemToken</varname> EFI + variable is set, and then derive the random seed to pass to the OS from the combination. If + <literal>always</literal> the boot loader will do so even if <varname>LoaderSystemToken</varname> is + not set. This mode is useful in environments where protection against OS image reuse is not a + concern, and the random seed shall be used even with no further setup in place. User <command>bootctl + random-seed</command> to initialize both the random seed file in the ESP and the system token EFI + variable.</para></listitem> + </varlistentry> </variablelist> </refsect1> diff --git a/man/rules/meson.build b/man/rules/meson.build index 7e32e732c1..3b63311d7b 100644 --- a/man/rules/meson.build +++ b/man/rules/meson.build @@ -655,6 +655,7 @@ manpages = [ ['systemd-bless-boot-generator', '8', [], 'ENABLE_EFI'], ['systemd-bless-boot.service', '8', [], 'ENABLE_EFI'], ['systemd-boot-check-no-failures.service', '8', [], ''], + ['systemd-boot-system-token.service', '8', [], 'ENABLE_EFI'], ['systemd-boot', '7', ['sd-boot'], 'ENABLE_EFI'], ['systemd-cat', '1', [], ''], ['systemd-cgls', '1', [], ''], diff --git a/man/systemd-boot-system-token.service.xml b/man/systemd-boot-system-token.service.xml new file mode 100644 index 0000000000..b2948a5c4b --- /dev/null +++ b/man/systemd-boot-system-token.service.xml @@ -0,0 +1,76 @@ +<?xml version='1.0'?> <!--*-nxml-*--> +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> +<!-- SPDX-License-Identifier: LGPL-2.1+ --> + +<refentry id="systemd-boot-system-token.service" conditional='ENABLE_EFI' + xmlns:xi="http://www.w3.org/2001/XInclude"> + + <refentryinfo> + <title>systemd-boot-system-token.service</title> + <productname>systemd</productname> + </refentryinfo> + + <refmeta> + <refentrytitle>systemd-boot-system-token.service</refentrytitle> + <manvolnum>8</manvolnum> + </refmeta> + + <refnamediv> + <refname>systemd-boot-system-token.service</refname> + <refpurpose>Generate an initial boot loader system token and random seed</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <para><filename>systemd-boot-system-token.service</filename></para> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para><filename>systemd-boot-system-token.service</filename> is a system service that automatically + generates a 'system token' to store in an EFI variable in the system's NVRAM and a random seed to store + on the EFI System Partition ESP on disk. The boot loader may then combine these two randomized data + fields by cryptographic hashing, and pass it to the OS it boots as initialization seed for its entropy + pool. The random seed stored in the ESP is refreshed on each reboot ensuring that multiple subsequent + boots will boot with different seeds. The 'system token' is generated randomly once, and then + persistently stored in the system's EFI variable storage.</para> + + <para>The <filename>systemd-boot-system-token.service</filename> unit invokes the <command>bootctl + random-seed</command> command, which updates the random seed in the ESP, and initializes the 'system + token' if it's not initialized yet. The service is conditionalized so that it is run only when all of the + below apply:</para> + + <itemizedlist> + <listitem><para>A boot loader is used that implements the <ulink + url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink> (which defines the 'system + token' concept).</para></listitem> + + <listitem><para>Either a 'system token' was not set yet, or the boot loader has not passed the OS a + random seed yet (and thus most likely has been missing the random seed file in the + ESP).</para></listitem> + + <listitem><para>The system is not running in a VM environment. This case is explicitly excluded since + on VM environments the ESP backing storage and EFI variable storage is typically not physically + separated and hence booting the same OS image in multiple instances would replicate both, thus reusing + the same random seed and 'system token' among all instances, which defeats its purpose. Note that it's + still possible to use boot loader random seed provisioning in this mode, but the automatic logic + implemented by this service has no effect then, and the user instead has to manually invoke the + <command>bootctl random-seed</command> acknowledging these restrictions.</para></listitem> + </itemizedlist> + + <para>For further details see + <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, regarding + the command this service invokes.</para> + </refsect1> + + <refsect1> + <title>See Also</title> + <para> + <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry> + </para> + </refsect1> + +</refentry> diff --git a/man/systemd-boot.xml b/man/systemd-boot.xml index 2575ab3fe5..3142b56d66 100644 --- a/man/systemd-boot.xml +++ b/man/systemd-boot.xml @@ -28,13 +28,14 @@ manager. It provides a graphical menu to select the entry to boot and an editor for the kernel command line. <command>systemd-boot</command> supports systems with UEFI firmware only.</para> - <para>systemd-boot loads boot entry information from the EFI system partition (ESP), usually mounted at - <filename>/efi/</filename>, <filename>/boot/</filename>, or <filename>/boot/efi/</filename> during OS - runtime, as well as from the Extended Boot Loader partition if it exists (usually mounted to - <filename>/boot/</filename>). Configuration file fragments, kernels, initrds and other EFI images to boot - generally need to reside on the ESP or the Extended Boot Loader partition. Linux kernels must be built - with <option>CONFIG_EFI_STUB</option> to be able to be directly executed as an EFI image. During boot - systemd-boot automatically assembles a list of boot entries from the following sources:</para> + <para><command>systemd-boot</command> loads boot entry information from the EFI system partition (ESP), + usually mounted at <filename>/efi/</filename>, <filename>/boot/</filename>, or + <filename>/boot/efi/</filename> during OS runtime, as well as from the Extended Boot Loader partition if + it exists (usually mounted to <filename>/boot/</filename>). Configuration file fragments, kernels, + initrds and other EFI images to boot generally need to reside on the ESP or the Extended Boot Loader + partition. Linux kernels must be built with <option>CONFIG_EFI_STUB</option> to be able to be directly + executed as an EFI image. During boot <command>systemd-boot</command> automatically assembles a list of + boot entries from the following sources:</para> <itemizedlist> <listitem><para>Boot entries defined with <ulink @@ -57,17 +58,50 @@ <listitem><para>A reboot into the UEFI firmware setup option, if supported by the firmware</para></listitem> </itemizedlist> - <para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> - may be used to copy kernel images onto the ESP or the Extended Boot Loader Partition and to generate - description files compliant with the Boot Loader - Specification. <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <para><command>systemd-boot</command> supports the following features:</para> + + <itemizedlist> + <listitem><para>Basic boot manager configuration changes (such as timeout + configuration, default boot entry selection, …) may be made directly from the boot loader UI at + boot-time, as well as during system runtime with EFI variables.</para></listitem> + + <listitem><para>The boot manager integrates with the <command>systemctl</command> command to implement + features such as <command>systemctl reboot --boot-loader-entry=…</command> (for rebooting into a + specific boot menu entry, i.e. "reboot into Windows") and <command>systemctl reboot + --boot-loader-menu=…</command> (for rebooting into the boot loader menu), by implementing the <ulink + url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. See + <citerefentry><refentrytitle>systemctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> for + details.</para></listitem> + + <listitem><para>An EFI variable set by the boot loader informs the OS about the ESP partition used + during boot. This is then used to automatically mount the correct ESP partition to + <filename>/efi/</filename> or <filename>/boot/</filename> during OS runtime. See + <citerefentry><refentrytitle>systemd-gpt-auto-generator</refentrytitle><manvolnum>8</manvolnum></citerefentry> + for details.</para></listitem> + + <listitem><para>The boot manager provides information about the boot time spent in UEFI firmware using + the <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. This + information can be displayed using + <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + </para></listitem> + + <listitem><para>The boot manager implements boot counting and automatic fallback to older, working boot + entries on failure. See <ulink url="https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT">Automatic Boot + Assessment</ulink>.</para></listitem> + + <listitem><para>The boot manager optionally reads a random seed from the ESP partition, combines it + with a 'system token' stored in a persistant EFI variable and derives a random seed to use by the OS as + entropy pool initializaton, providing a full entropy pool during early boot.</para></listitem> + </itemizedlist> + + <para><citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry> may be used from a running system to locate the ESP and the Extended Boot Loader Partition, list available entries, and install <command>systemd-boot</command> itself.</para> - <para>systemd-boot will provide information about the time spent in UEFI firmware using the <ulink - url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>. This information can be displayed - using <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry>. - </para> + <para><citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry> + may be used to copy kernel images onto the ESP or the Extended Boot Loader Partition and to generate + description files compliant with the Boot Loader + Specification.</para> </refsect1> <refsect1> @@ -238,7 +272,9 @@ Loader Specification</ulink> are read from <filename>/loader/entries/</filename> on the ESP and the Extended Boot Loader partition. Unified kernel boot entries following the <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink> are read from - <filename>/EFI/Linux/</filename> on the ESP and the Extended Boot Loader partition.</para> + <filename>/EFI/Linux/</filename> on the ESP and the Extended Boot Loader partition. Optionally, a random + seed for early boot entropy pool provisioning is stored in <filename>/loader/random-seed</filename> in + the ESP.</para> </refsect1> <refsect1> @@ -346,10 +382,39 @@ <listitem><para>Information about the time spent in various parts of the boot loader. Set by the boot loader. Use <citerefentry><refentrytitle>systemd-analyze</refentrytitle><manvolnum>1</manvolnum></citerefentry> - to view this data. These variables are defined by the <ulink - url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.</para></listitem> + to view this data. </para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderRandomSeed</varname></term> + + <listitem><para>A binary random seed <command>systemd-boot</command> may optionally pass to the + OS. This is a volatile EFI variable that is hashed at boot from the combination of a random seed + stored in the ESP (in <filename>/loader/random-seed</filename>) and a "system token" persistently + stored in the EFI variable <varname>LoaderSystemToken</varname> (see below). During early OS boot the + system manager reads this variable and passes it to the OS kernel's random pool, crediting the full + entropy it contains. This is an efficient way to ensure the system starts up with a fully initialized + kernel random pool — as early as the initial RAM disk phase. <command>systemd-boot</command> reads + the random seed from the ESP, combines it with the "system token", and both derives a new random seed + to update in-place the seed stored in the ESP, and the random seed to pass to the OS from it via + SHA256 hashing in counter mode. This ensures that different physical systems that boot the same + "golden" OS image — i.e. containing the same random seed file in the ESP — will still pass a + different random seed to the OS. It is made sure the random seed stored in the ESP is fully + overwritten before the OS is booted, to ensure different random seed data is used between subsequent + boots.</para></listitem> + </varlistentry> + + <varlistentry> + <term><varname>LoaderSystemToken</varname></term> + + <listitem><para>A binary random data field, that is used for generating the random see to pass to the + OS (see above). Note that this random data is generally only generated once, during OS installation, + and is then never updated again.</para></listitem> </varlistentry> </variablelist> + + <para>Many of these variables are defined by the <ulink + url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink>.</para> </refsect1> <refsect1> @@ -413,6 +478,7 @@ <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, <citerefentry><refentrytitle>loader.conf</refentrytitle><manvolnum>5</manvolnum></citerefentry>, <citerefentry><refentrytitle>systemd-bless-boot.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-boot-system-token.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <citerefentry><refentrytitle>kernel-install</refentrytitle><manvolnum>8</manvolnum></citerefentry>, <ulink url="https://systemd.io/BOOT_LOADER_SPECIFICATION">Boot Loader Specification</ulink>, <ulink url="https://systemd.io/BOOT_LOADER_INTERFACE">Boot Loader Interface</ulink> diff --git a/man/systemd-random-seed.service.xml b/man/systemd-random-seed.service.xml index 35c6e2fd0b..8714c4280d 100644 --- a/man/systemd-random-seed.service.xml +++ b/man/systemd-random-seed.service.xml @@ -29,21 +29,60 @@ <refsect1> <title>Description</title> - <para><filename>systemd-random-seed.service</filename> is a - service that restores the random seed of the system at early boot - and saves it at shutdown. See - <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> - for details. Saving/restoring the random seed across boots - increases the amount of available entropy early at boot. On disk - the random seed is stored in - <filename>/var/lib/systemd/random-seed</filename>.</para> + <para><filename>systemd-random-seed.service</filename> is a service that loads an on-disk random seed + into the kernel entropy pool during boot and saves it at shutdown. See + <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for + details. By default, no entropy is credited when the random seed is written into the kernel entropy pool, + but this may be changed with <varname>$SYSTEMD_RANDOM_SEED_CREDIT</varname>, see below. On disk the random + seed is stored in <filename>/var/lib/systemd/random-seed</filename>.</para> + + <para>Note that this service runs relatively late during the early boot phase, i.e. generally after the + initial RAM disk (initrd) completed its work, and the <filename>/var/</filename> file system has been + mounted writable. Many system services require entropy much earlier than this — this service is hence of + limited use for complex system. It is recommended to use a boot loader that can pass an initial random + seed to the kernel to ensure that entropy is available from earliest boot on, for example + <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, with + its <command>bootctl random-seed</command> functionality.</para> + + <para>When loading the random seed from disk its file is immediately updated with a new seed retrieved + from the kernel, in order to ensure no two boots operate with the same random seed. This new seed is + retrieved synchronously from the kernel, which means the service will not complete start-up until the + random pool is fully initialized. On entropy-starved systems this may take a while. This functionality is + intended to be used as synchronization point for ordering services that require an initialized entropy + pool to function securely (i.e. services that access <filename>/dev/urandom</filename> without any + further precautions).</para> + + <para>Care should be taken when creating OS images that are replicated to multiple systems: if the random + seed file is included unmodified each system will initialize its entropy pool with the same data, and + 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.</para> + </refsect1> + + <refsect1> + <title>Environment</title> + + <variablelist class='environment-variables'> + <varlistentry> + <term><varname>$SYSTEMD_RANDOM_SEED_CREDIT</varname></term> + <listitem><para>By default, <filename>systemd-random-seed.service</filename> does not credit any + entropy when loading the random seed. With this option this behaviour may be changed: it either takes + a boolean parameter or the special string <literal>force</literal>. Defaults to false, in which case + no entropy is credited. If true, entropy is credited if the random seed file and system state pass + various superficial concisistency checks. If set to <literal>force</literal> entropy is credited, + regardless of these checks, as long as the random seed file exists.</para></listitem> + </varlistentry> + </variablelist> </refsect1> <refsect1> <title>See Also</title> <para> <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>, - <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> + <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>, + <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, + <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>4</manvolnum></citerefentry> </para> </refsect1> |