man: document the systemd-random-seed rework

This commit is contained in:
Lennart Poettering 2019-07-22 14:19:33 +02:00
parent c7bb4dfcf4
commit 39867bb9fb
6 changed files with 243 additions and 31 deletions

View File

@ -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>
@ -124,6 +124,19 @@
and the firmware's boot loader list.</para></listitem>
</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>
@ -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>

View File

@ -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>

View File

@ -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', [], ''],

View File

@ -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>

View File

@ -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>

View File

@ -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>