2012-06-25 14:13:17 +04:00
<?xml version="1.0"?>
<!-- * - nxml - * -->
2019-03-14 16:40:58 +03:00
< !DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
2023-12-25 17:48:33 +03:00
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
2020-11-09 07:23:58 +03:00
<!-- SPDX - License - Identifier: LGPL - 2.1 - or - later -->
2023-08-22 19:52:02 +03:00
<refentry id= "systemd-random-seed.service" conditional= 'ENABLE_RANDOMSEED'
xmlns:xi="http://www.w3.org/2001/XInclude">
2012-06-25 14:13:17 +04:00
2015-02-04 05:14:13 +03:00
<refentryinfo >
<title > systemd-random-seed.service</title>
<productname > systemd</productname>
</refentryinfo>
2012-06-25 14:13:17 +04:00
2015-02-04 05:14:13 +03:00
<refmeta >
<refentrytitle > systemd-random-seed.service</refentrytitle>
<manvolnum > 8</manvolnum>
</refmeta>
2012-06-25 14:13:17 +04:00
2015-02-04 05:14:13 +03:00
<refnamediv >
<refname > systemd-random-seed.service</refname>
<refname > systemd-random-seed</refname>
2022-12-20 19:16:47 +03:00
<refpurpose > Load and save the OS system random seed at boot and shutdown</refpurpose>
2015-02-04 05:14:13 +03:00
</refnamediv>
2012-06-25 14:13:17 +04:00
2015-02-04 05:14:13 +03:00
<refsynopsisdiv >
<para > <filename > systemd-random-seed.service</filename> </para>
2023-04-25 17:51:09 +03:00
<para > <filename > /usr/lib/systemd/systemd-random-seed</filename> </para>
2015-02-04 05:14:13 +03:00
</refsynopsisdiv>
2012-06-25 14:13:17 +04:00
2015-02-04 05:14:13 +03:00
<refsect1 >
<title > Description</title>
2012-06-25 14:13:17 +04:00
2019-07-22 15:19:33 +03:00
<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,
man: "the initial RAM disk" → "the initrd"
In many places we spelled out the phrase behind "initrd" in full, but this
isn't terribly useful. In fact, no "RAM disk" is used, so emphasizing this
is just confusing to the reader. Let's just say "initrd" everywhere, people
understand what this refers to, and that it's in fact an initramfs image.
Also, s/i.e./e.g./ where appropriate.
Also, don't say "in RAM", when in fact it's virtual memory, whose pages
may or may not be loaded in page frames in RAM, and we have no control over
this.
Also, add <filename></filename> and other minor cleanups.
2022-09-15 15:43:59 +03:00
but this may be changed with <varname > $SYSTEMD_RANDOM_SEED_CREDIT</varname> , see below. On disk the random
2019-07-22 15:19:33 +03:00
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
man: "the initial RAM disk" → "the initrd"
In many places we spelled out the phrase behind "initrd" in full, but this
isn't terribly useful. In fact, no "RAM disk" is used, so emphasizing this
is just confusing to the reader. Let's just say "initrd" everywhere, people
understand what this refers to, and that it's in fact an initramfs image.
Also, s/i.e./e.g./ where appropriate.
Also, don't say "in RAM", when in fact it's virtual memory, whose pages
may or may not be loaded in page frames in RAM, and we have no control over
this.
Also, add <filename></filename> and other minor cleanups.
2022-09-15 15:43:59 +03:00
initrd phase has finished and the <filename > /var/</filename> file system has been mounted. 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
2019-07-22 15:19:33 +03:00
<citerefentry > <refentrytitle > systemd-boot</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry> , with
its <command > bootctl random-seed</command> functionality.</para>
2020-07-06 11:49:59 +03:00
<para > When loading the random seed from disk, the file is immediately updated with a new seed retrieved
2019-07-22 15:19:33 +03:00
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
2022-03-23 14:04:28 +03:00
entropy crediting, see below. Also see <ulink url= "https://systemd.io/BUILDING_IMAGES" > Safely Building
Images</ulink> .</para>
2019-07-22 19:13:26 +03:00
<para > See <ulink url= "https://systemd.io/RANDOM_SEEDS" > Random Seeds</ulink> for further
information.</para>
2019-07-22 15:19:33 +03:00
</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,
2023-08-22 19:52:36 +03:00
regardless of these checks, as long as the random seed file exists.</para>
<xi:include href= "version-info.xml" xpointer= "v243" /> </listitem>
2019-07-22 15:19:33 +03:00
</varlistentry>
</variablelist>
2015-02-04 05:14:13 +03:00
</refsect1>
2012-06-25 14:13:17 +04:00
2015-02-04 05:14:13 +03:00
<refsect1 >
<title > See Also</title>
2023-12-22 21:09:32 +03:00
<para > <simplelist type= "inline" >
<member > <citerefentry > <refentrytitle > systemd</refentrytitle> <manvolnum > 1</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > random</refentrytitle> <manvolnum > 4</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > systemd-boot</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > systemd-stub</refentrytitle> <manvolnum > 7</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > bootctl</refentrytitle> <manvolnum > 4</manvolnum> </citerefentry> </member>
<member > <citerefentry > <refentrytitle > systemd-boot-random-seed.service</refentrytitle> <manvolnum > 8</manvolnum> </citerefentry> </member>
</simplelist> </para>
2015-02-04 05:14:13 +03:00
</refsect1>
2012-06-25 14:13:17 +04:00
</refentry>