<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>
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>
<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>
<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>
['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', [], ''],
--- /dev/null
+<?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>
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
<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>
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>
<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>
<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>
<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>
projects / thirdparty / systemd.git / commitdiff
