diff --git a/docs/RANDOM_SEEDS.md b/docs/RANDOM_SEEDS.md
index c1735b1ac9..e4b4a7a9cb 100644
--- a/docs/RANDOM_SEEDS.md
+++ b/docs/RANDOM_SEEDS.md
@@ -257,7 +257,16 @@ boot, in order to ensure the entropy pool is filled up quickly.
file. If done, `systemd-boot` will use the random seed file even if no
system token is found in EFI variables.
-With the three mechanisms described above it should be possible to provide
+4. A kernel command line option `systemd.random_seed=` may be used to pass in a
+ base64 encoded seed to initialize the kernel's entropy pool from during
+ early service manager initialization. This option is only safe in testing
+ environments, as the random seed passed this way is accessible to
+ unprivileged programs via `/proc/cmdline`. Using this option outside of
+ testing environments is a security problem since cryptographic key material
+ derived from the entropy pool initialized with a seed accessible to
+ unprivileged programs should not be considered secret.
+
+With the four mechanisms described above it should be possible to provide
early-boot entropy in most cases. Specifically:
1. On EFI systems, `systemd-boot`'s random seed logic should make sure good
@@ -267,7 +276,8 @@ early-boot entropy in most cases. Specifically:
2. On virtualized systems, the early `virtio-rng` hookup should ensure entropy
is available early on — as long as the VM environment provides virtualized
RNG devices, which they really should all do in 2019. Complain to your
- hosting provider if they don't.
+ hosting provider if they don't. For VMs used in testing environments,
+ `systemd.random_seed=` may be used as an alternative to a virtualized RNG.
3. On Intel/AMD systems systemd's own reliance on the kernel entropy pool is
minimal (as RDRAND is used on those for UUID generation). This only works if
@@ -286,8 +296,9 @@ This primarily leaves two kind of systems in the cold:
boot. Alternatively, consider implementing a solution similar to
systemd-boot's random seed concept in your platform's boot loader.
-2. Virtualized environments that lack both virtio-rng and RDRAND. Tough
- luck. Talk to your hosting provider, and ask them to fix this.
+2. Virtualized environments that lack both virtio-rng and RDRAND, outside of
+ test environments. Tough luck. Talk to your hosting provider, and ask them
+ to fix this.
3. Also note: if you deploy an image without any random seed and/or without
installing any 'system token' in an EFI variable, as described above, this
@@ -410,6 +421,10 @@ This primarily leaves two kind of systems in the cold:
information to possibly gain too much information about the current state
of the kernel's entropy pool.
+ That said, we actually do implement this with the `systemd.random_seed=`
+ kernel command line option. Don't use this outside of testing environments,
+ however, for the aforementioned reasons.
+
12. *Why doesn't `systemd-boot` rewrite the 'system token' too each time
when updating the random seed file stored in the ESP?*
diff --git a/man/kernel-command-line.xml b/man/kernel-command-line.xml
index 52939deec0..4e431aaefd 100644
--- a/man/kernel-command-line.xml
+++ b/man/kernel-command-line.xml
@@ -468,8 +468,32 @@
systemd.clock-usec=
Takes a decimal, numeric timestamp in µs since January 1st 1970, 00:00am, to set the
- system clock to. The system time is set to the specified timestamp early during
- boot. It is not propagated to the hardware clock (RTC).
+ system clock to. The system time is set to the specified timestamp early during boot. It is not
+ propagated to the hardware clock (RTC).
+
+
+
+ systemd.random-seed=
+
+ Takes a base64 encoded random seed value to credit with full entropy to the kernel's
+ random pool during early service manager initialization. This option is useful in testing
+ environments where delays due to random pool initialization in entropy starved virtual machines shall
+ be avoided.
+
+ Note that if this option is used the seed is accessible to unprivileged programs from
+ /proc/cmdline. This option is hence a security risk when used outside of test
+ systems, since the (possibly) only seed used for initialization of the kernel's entropy pool might be
+ easily acquired by unprivileged programs.
+
+ It is recommended to pass 512 bytes of randomized data (as that matches the Linux kernel pool
+ size), which may be generated with a command like the following:
+
+ dd if=/dev/urandom bs=512 count=1 status=none | base64 -w 0
+
+ Again: do not use this option outside of testing environments, it's a security risk elsewhere,
+ as secret key material derived from the entropy pool can possibly be reconstructed by unprivileged
+ programs.
+