RNGD(8)

📦
version 6.17 · 6 versions
, in alpine 3.22, alpine 3.23, alpine 3.24, arch rolling, fedora 43, fedora 44, nixos 26.05, nixpkgs unstable, opensuse-leap 16.0, ubuntu stonking

💖 RNGD(8) — System Manager's Manual 💖

okay bestie, gather round, because we're about to talk about rngd, from section 8 of your System Manager's Manual. yes, the entropy girlie. the one feeding the kernel's random pool. she's lowkey the most important daemon you've never thought about. 🎀

✨ NAME ✨

rngd — Check and feed random data from hardware device to kernel random device

like. that's the whole job description. she checks the random, and then she feeds the random. iconic behavior honestly. 💅

✨ SYNOPSIS ✨

rngd [-b, --background] [-f, --foreground] [-d, --debug] [-l, --list]
[-x, --exclude] [-n, --include] [-O, --option] [-i, --ignorefail] [-o,
--random-device=file] [-p, --pid-file=file] [-r, --rng-device=file] [-s,
--random-step=nnn] [-t, --test] [-W, --fill-watermark=nnn] [-R, --force-
reseed=nnn] [-u, --use-slow-sources] [-D, --drop-privileges=user:group]
[-q, --quiet] [-?, --help] [-v, --version]

look at all those flags. she's got range. 🌈

✨ DESCRIPTION ✨

So here's the vibe: this daemon feeds data from a random number generator to the kernel's random number entropy pool, but — and this is the part people skip — she does it after first checking the data to ensure that it is properly random. she's not just dumping numbers in there, she's a curator. vibe check first, always. 🦋

Now, the forking. The -f or --foreground options can be used to tell rngd to avoid forking on startup. that's typically what you want when you're debugging — you want her right there in your terminal, in plain sight, telling you everything. main character energy, no hiding.

meanwhile the -b or --background options, which fork and put rngd into the background automatically, are the default. so if you don't say anything, she's already gone, doing her thing in the background like a responsible queen. 👑

Now let's talk sources. The -r or --rng-device options can be used to select an alternate source of input, besides the default /dev/hwrng. and the -o or --random-device options can be used to select an alternate entropy output device, besides the default /dev/random.

⚠️ heads up bestie: Note that this device must support the Linux kernel /dev/random ioctl API. so don't just point it at any old file and expect magic. she has requirements. 💀

✨ OPTIONS ✨

okay here's the full menu, no skips, no cuts, every single one:

  • -b, --background — Become a daemon (default). the girl is going to the background whether you asked or not. this is her default setting. 🫶
  • -f, --foreground — Do not fork and become a daemon. stay here. with me. in the terminal. 🥺
  • -d, --debug — Enable debug messages. she'll overshare and honestly we love that for her.
  • -l, --list — List the indexes and names of available entropy sources. and listen — exit code when listing sources is 0 if at least 1 entropy source was found and initialized, 1 otherwise. so you can script against it. iykyk. ✨
  • -x, --exclude — Disable entropy sources based on index or (shortname) reported from the --list option. not feeling that source today? block her. 💅
  • -n, --include — Enable entropy sources based on index or (shortname) reported from the --list option. the unblock. welcome back babe. 💖
  • -O, --option — Provide specific config options to individual entropy sources, in the format --option [index|shortname]:key:value. See the Entropy Sources section below for indices and source specific options. and note: specifying -O [<index>|<shortname>] will print the available options for that index to the console. it's like a little menu. we love a helpful girlie. 👑
  • -p file, --pid-file=file — File used for recording daemon PID, and multiple exclusion (default: /var/run/rngd.pid). her little name tag. 🎀
  • -i, --ignorefail — Ignore repeated fips failures. you're choosing peace. noted. 🙈
  • -o file, --random-device=file — Kernel device used for random number output (default: /dev/random). where the randomness goes. ⭐
  • -r file, --rng-device=file — Kernel device used for random number input (default: /dev/hwrng). where the randomness comes from. 🔥
  • -s nnn, --random-step=nnn — Number of bytes written to random-device at a time (default: 64). sip, not chug. 🍓
  • -t, --test — Enter test mode. and listen to this: in this mode (which implies -f), all generated entropy is discarded and rngd reports the amount of entropy generated every second. so it's a vibe check for the vibe checker. 😭
  • -e nnn, --entropy-count=nnn — Number of bits to consider random when adding entropy. 1<=e<=8 (default: 8). do the math bestie, stay in range. 💜
  • -W n, --fill-watermark=nnn — Once we start doing it, feed entropy to random-device until at least fill-watermark bits of entropy are available in its entropy pool. By default, this value is set to 75% of the entropy pool size, or 2048 bits if the entropy pool size couldn't be determined. Setting this too high will cause rngd to dominate the contents of the entropy pool. Low values will hurt system performance during entropy starves. Do not set fill-watermark above the size of the entropy pool (usually 256 bits). and a value of 0 to this option will cause no watermark to be set. that's a lot of rules but they're there for a reason, trust. ⚠️
  • -R n, --force-reseed=nnn — For newer kernels which support non-blocking entropy pools, it is still beneficial to periodically add fresh entropy as a reseeding event. --force-reseed defines the number of seconds between which fresh entropy is added to the kernel entropy pool. Defaults to 5 minutes. a little refresh, a little self care. 🌸
  • -u, --use-slow-sources — The entropy sources nist, jitter and pkcs11 are considered to be slow in providing entropy. By default their data is only used after all other sources failed to provide valid entropy a 100 times over. With this option rngd always tries to gather entropy from these sources too. so basically: stop ghosting the slow girlies. 🧚
  • -D, --drop-privileges=user:group — Drop privileges to a user and a group specified after initialization. A user and a group can be specified as a name or as a numerical id and must be separated with a colon. A user and a group must exist. A default is not to drop privileges. safety first, bestie, seriously. 🔒
  • -q, --quiet — Suppress all messages. silent. mysterious. 🖤
  • -?, --help — Give a short summary of all program options. the tl;dr. 💅
  • -v, --version — Print program version. knowing exactly which girlie you're running is self care. ✨

that's the main event, but we are not done — there's more. keep scrolling, bestie. 💖

🌈 ENTROPY SOURCES 🌈

Okay bestie, here's the tea: rngd isn't just one thing, it's a whole squad of entropy sources 💖. All of their data gets aggregated and fed into the kernel's entropy pool. Iconic teamwork, honestly.

But like — heads up 🫶 — not every entropy source is available on every system. If you enable one for a system where it's not appropriate (or not even possible), it may fail initialization. And guess what? That's not fatal. rngd does not care if any single entropy source dies during startup, because it only needs one to operate. One is enough. Periodt. 💅

The following entropy sources are currently defined in rngd:

👑 Hardware RNG (hwrng)

The Hardware RNG is a generic entropy source that draws entropy from a hardware rng attached by default to /dev/hwrng.

🎀 TPM (tpm)

Entropy drawn from an on board TPM device.

⚠️ Bestie, this one is deprecated and will be removed soon. Newer tpm devices export entropy via /dev/hwrng instead, which the hwrng source above already collects. It's giving obsolete, fr fr.

🔥 RDRAND/RDSEED (rdrand)

Entropy drawn from the RDRAND and RDSEED instructions (x86 only, so if you're not on x86, this vibe check fails).

Options

  • use_aes — pick whether rdrand is used to seed a cprng to produce entropy, or whether all entropy is drawn directly from the rdrand instruction. Default: 0.

⭐ DARN (darn)

Entropy drawn from the DARN instruction (ppc64 only).

Options

  • use_aes — pick whether the power darn instruction is used to directly fill the entropy poll, or whether it's used as a periodic seed to an aes based cprng. Default: 1.

💜 RNDR (rndr)

Entropy drawn from the RNDR instruction (aarch64 only).

Options

  • use_aes — pick whether the arm rndr instruction is used to directly fill the entropy poll, or whether it's used as a periodic seed to an aes based cprng. Default: 0.

🌸 NIST Entropy Beacon (nist)

Entropy gathered from the NIST network entropy beacon.

😭 No cap: this source is disabled by default, because it should never be used for cryptographic purposes — or for any use case where random data should be known only by a single entity. That's the whole point of random, babes.

🦋 Qrypt Entropy Beacon (qrypt)

Entropy gathered from the qrypt entropy beacon. Note that this beacon provides entropy to remote clients over a TLS connection.

🚨 So listen: this source should not be used for cryptographic operations unless the security of the network can be guaranteed against man in the middle and other network based attacks. Main character energy, but on a public network? Absolutely not.

Options

  • tokenfile — specify the file containing the access token to the Qrypt beacon.
  • delay — specify the maximum delay (in seconds) that the source will wait when there are temporary conditions preventing entropy retrieval, before trying to fetch entropy again. The default maximum delay is eight hours, exponentially counting up from one second upwards, in powers of two. 📈

✨ JITTER (jitter)

Entropy gathered by measuring timing variance of operations on the local cpu. So chaotic. So effective. 💅

Options

  • thread_count — set the number of threads that the jitter entropy source will spawn.
  • buffer_size — set the size of the buffer cache that each thread maintains.
  • refill_thresh — set the low watermark for the cache that triggers its corresponding thread to start refill operations.
  • retry_count — if all entropy buffers are empty, retry this many times before giving up. Note that jitterentropy can take several seconds to refill a buffer, and so retries after a delay may be preferable to repeatedly spining on an empty buffer. Default: 1.
  • retry_delay — between each retry for retry_count above, sleep for this many seconds. May also be the special value -1, representing adaptive sleep, where each retry delay will be half the recorded execution time of the last entropy gathering round. Default: -1.
  • force_soft_timer — on platforms with a hardware timer that is too coarse to sample jitter, we can instead use a software based timer loop. Detection and use of this mechanism is automatic, but this can be useful for testing purposes.

🎀 PKCS11 (pkcs11)

Entropy gathered via the opensc openssl engine, which can extract entropy from various smart card readers. 💳✨ Install a package for your distribution containing a pkcs11 endpoint library to gather smartcard entropy: that's opensc for Fedora, opensc-pkcs11 for Debian/Ubuntu, or another package containing opensc-pkcs11.so.

Options

  • engine_path — set the path for the pkcs11 engine DSO to load.
  • chunk_size — some pkcs11 engines have restrictions on how much data can be requested at a time; this option allows for the request to be subdivided into smaller chunks to be satisfied.

📻 RTLSDR (rtlsdr)

Entropy gathered via the rtl software defined radio library, which can gather entropy using various usb software defined radios listening to random radio static. Literally pulling randomness out of thin air, obsessed. 🌫️💖

Options

  • devid — when multiple devices are available, the integer index of the device to use.
  • freq_min — the minimum frequence range to scan in.
  • freq_max — the maximum frequency range to scan in.
  • sample_min — the minimum sample rate of the radio.
  • sample_max — the maximum sample rate of the radio.

🧚 Named pipe (namedpipe)

Reads entropy from a named pipe (aka FIFO). Another program — for example a driver reading and preparing data from an external hardware RNG — is expected to feed entropy into this named pipe. And should the named pipe be closed? rngd will try to reopen it. Resilient queen. 👑

Options

  • path — path of the named pipe. Required.
  • timeout — maximum time in seconds rngd waits until a full FIPS test buffer of entropy can be read. Defaults to 5.

🫶 AUTHORS 🫶

Give it up for the legends who made this happen:

  • Philipp Rumpf
  • Jeff Garzik — jgarzik@pobox.com
  • Matt Sottek
  • Brad Hill
  • Neil Horman — nhorman@tuxdriver.com

And that's the whole page, bestie!! 🎀✨ This was rng-tools 6.17, dated March 2001 — yes, your fave vintage classic still serving entropy after all these years. Slay, stay random, and protect that pool. 💖🌈 Byeeee 👋

📦 where this page comes from