man/systemd-random-seed.service.xml

   1 <?xml version="1.0"?>
   2 <!--*-nxml-*-->
   3 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   4   "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   5 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
   6 <refentry id="systemd-random-seed.service" conditional='ENABLE_RANDOMSEED'>
   7
   8   <refentryinfo>
   9     <title>systemd-random-seed.service</title>
  10     <productname>systemd</productname>
  11   </refentryinfo>
  12
  13   <refmeta>
  14     <refentrytitle>systemd-random-seed.service</refentrytitle>
  15     <manvolnum>8</manvolnum>
  16   </refmeta>
  17
  18   <refnamediv>
  19     <refname>systemd-random-seed.service</refname>
  20     <refname>systemd-random-seed</refname>
  21     <refpurpose>Load and save the system random seed at boot and shutdown</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <para><filename>systemd-random-seed.service</filename></para>
  26     <para><filename>/usr/lib/systemd/random-seed</filename></para>
  27   </refsynopsisdiv>
  28
  29   <refsect1>
  30     <title>Description</title>
  31
  32     <para><filename>systemd-random-seed.service</filename> is a service that loads an on-disk random seed
  33     into the kernel entropy pool during boot and saves it at shutdown. See
  34     <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry> for
  35     details. By default, no entropy is credited when the random seed is written into the kernel entropy pool,
  36     but this may be changed with <varname>$SYSTEMD_RANDOM_SEED_CREDIT</varname>, see below.  On disk the random
  37     seed is stored in <filename>/var/lib/systemd/random-seed</filename>.</para>
  38
  39     <para>Note that this service runs relatively late during the early boot phase, i.e. generally after the
  40     initial RAM disk (initrd) completed its work, and the <filename>/var/</filename> file system has been
  41     mounted writable. Many system services require entropy much earlier than this — this service is hence of
  42     limited use for complex system. It is recommended to use a boot loader that can pass an initial random
  43     seed to the kernel to ensure that entropy is available from earliest boot on, for example
  44     <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>, with
  45     its <command>bootctl random-seed</command> functionality.</para>
  46
  47     <para>When loading the random seed from disk, the file is immediately updated with a new seed retrieved
  48     from the kernel, in order to ensure no two boots operate with the same random seed. This new seed is
  49     retrieved synchronously from the kernel, which means the service will not complete start-up until the
  50     random pool is fully initialized. On entropy-starved systems this may take a while. This functionality is
  51     intended to be used as synchronization point for ordering services that require an initialized entropy
  52     pool to function securely (i.e. services that access <filename>/dev/urandom</filename> without any
  53     further precautions).</para>
  54
  55     <para>Care should be taken when creating OS images that are replicated to multiple systems: if the random
  56     seed file is included unmodified each system will initialize its entropy pool with the same data, and
  57     thus — if otherwise entropy-starved — generate the same or at least guessable random seed streams. As a
  58     safety precaution crediting entropy is thus disabled by default. It is recommended to remove the random
  59     seed from OS images intended for replication on multiple systems, in which case it is safe to enable
  60     entropy crediting, see below.</para>
  61
  62     <para>See <ulink url="https://systemd.io/RANDOM_SEEDS">Random Seeds</ulink> for further
  63     information.</para>
  64   </refsect1>
  65
  66   <refsect1>
  67     <title>Environment</title>
  68
  69     <variablelist class='environment-variables'>
  70       <varlistentry>
  71         <term><varname>$SYSTEMD_RANDOM_SEED_CREDIT</varname></term>
  72         <listitem><para>By default, <filename>systemd-random-seed.service</filename> does not credit any
  73         entropy when loading the random seed. With this option this behaviour may be changed: it either takes
  74         a boolean parameter or the special string <literal>force</literal>. Defaults to false, in which case
  75         no entropy is credited. If true, entropy is credited if the random seed file and system state pass
  76         various superficial concisistency checks. If set to <literal>force</literal> entropy is credited,
  77         regardless of these checks, as long as the random seed file exists.</para></listitem>
  78       </varlistentry>
  79     </variablelist>
  80   </refsect1>
  81
  82   <refsect1>
  83     <title>See Also</title>
  84     <para>
  85       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
  86       <citerefentry><refentrytitle>random</refentrytitle><manvolnum>4</manvolnum></citerefentry>,
  87       <citerefentry><refentrytitle>systemd-boot</refentrytitle><manvolnum>7</manvolnum></citerefentry>,
  88       <citerefentry><refentrytitle>bootctl</refentrytitle><manvolnum>4</manvolnum></citerefentry>
  89     </para>
  90   </refsect1>
  91
  92 </refentry>