Provided by: bit-babbler_0.9_amd64 
NAME
seedd - read entropy from BitBabbler hardware RNG devices
SYNOPSIS
seedd [options]
DESCRIPTION
The seedd program can be run as a foreground process or as a daemon to collect entropy
from one or more BitBabbler devices, either streaming it to stdout for general purpose
use, making it available on a UDP socket, or directly seeding the kernel entropy pool with
it on demand.
USAGE
The number of configurable options for seedd has now outgrown what most people will care
about or want to use, which would normally be less than ideal for something like this, but
it does have a rather diverse range of user needs, and it is important that we support
those well.
Unless you fall into the special use category, then the following examples are probably
about all (or still more than) you might ever need:
Show all available BitBabbler devices, in detail:
seedd -sv (or --scan --verbose)
Output 1 million bytes to a file, drawn from all available devices:
seedd -b 1000000 > random-bytes.out
Stream entropy continuously to stdout (with no control socket):
seedd -o -c none | your-thing-reading-stdin
Run as a daemon, feeding entropy to the OS kernel pool:
seedd -k -d
To read from only specific devices, add the --device-id option too.
OPTIONS
The following options are available:
-s, --scan
Scan the system for available BitBabbler devices, reporting them in a human
readable format.
--shell-mr
Scan the system for available BitBabbler devices, reporting them in a machine
readable format that is suitable for importing into shell scripts.
-C, --config=file
Read configuration options from a file. Details of the contents of that file is
described in the CONFIGURATION FILE FORMAT section below. This option may be
passed multiple times to import configuration from multiple files, and precedence
of the options set in them is the same as if they were passed on the command line
at the point where this option is used. Where option settings are duplicated, the
last one seen is the one which will be applied. Which means if you want options on
the command line to override any setting in the config file(s), they must be passed
after this option.
Options which are cumulative will continue to accumulate wherever they are seen, so
for example, passing an additional --device-id on the command line will simply add
an extra device, it will not override the use of any devices defined in the
configuration file. But you can still override any per-device options which may be
set there. The only exception to this is --verbose, where the verbosity level
selected on the command line will always override any setting from a configuration
file regardless of the order they appear in.
-i, --device-id=id
Select a BitBabbler device to read from by its unique ID. If no devices are
explicitly specified then the default is to use all of them (including any devices
that may be plugged in at a later time).
This option may be passed multiple times to attach to multiple devices. It is not
an error to specify a device that is not currently present on the system. If
hotplug support was enabled at compile time and available on the system at runtime,
then such devices will be added to the pool at runtime if they are later plugged
in.
The id may be the device serial number, or its logical address in the form:
[busnum:]devnum
or on systems where knowing the USB topology is supported, its physical address in
the form
busnum-port[.port ...]
For a logical address the busnum part is optional, but if devnum is not unique
across all buses, then exactly which device will be selected if it is not fully
specified becomes a matter of chance. All of the available IDs which can be used
to refer to a device will be reported by the --scan option. Bus, device, and port
numbers are expected to be decimal integers.
The logical address isn't usually very useful to use when hotplug activity is
expected, since it is allocated dynamically and is 'unpredictable' for most
purposes here.
-d, --daemon
Fork to the background and run as a daemon process. If this option is not
specified then seedd will remain in the foreground. This option will be ignored if
seedd is started by systemd(1) as a service using the notify start-up type.
-b, --bytes=n
Send n bytes of entropy to stdout. The process will exit when that is completed.
This option will be ignored if either the --kernel or --udp-out options are used.
A suffix of 'k', 'M', or 'G' will multiply n by the respective power of two. If
this option is not used, then entropy will be output until the process is
explicitly terminated (or receives SIGPIPE). Passing this option implies --stdout,
and also --control-socket=none unless the control socket option is explicitly
passed to enable it.
-o, --stdout
Stream entropy directly to stdout. If the --bytes option is not used, this will
output an unlimited stream of entropy until the process is halted.
-k, --kernel
Feed entropy directly to the kernel /dev/random pool on demand.
--ip-freebind
If enabled, this option allows binding to an IP address that is non-local or does
not (yet) exist. This permits the --udp-out and TCP --control-socket options to be
configured to listen on an IP socket without requiring the underlying network
interface to be up, or the specified IP address configured, at the time that seedd
will try to bind to it. Which can be useful if you want seedd to be started as
early as possible when the system is booted, without waiting for network
configuration to occur.
This option has no effect if seedd is not configured to listen and provide a
service on any IP address, and it is not supported on all platforms. A warning
will be logged if it is enabled on an unsupported platform, but that is not a fatal
error (however actually attempting to bind to an unconfigured address quite likely
still will be on most sane platforms).
On Linux, any user may enable this option. On OpenBSD it requires superuser
privilege, and on FreeBSD it requires PRIV_NETINET_BINDANY privileges. It is a
fatal error to attempt to enable this with insufficient privilege.
If this option is not enabled, then it is a fatal error for the --udp-out service
or a TCP --control-socket to be bound to an address which is not already configured
when seedd is started. This is a configurable option because in different
circumstances both behaviours can be the more desirable choice. There is value in
strong sanity checking of an address which is always supposed to already be
available for use.
-u, --udp-out=host:port
Bind a UDP socket to the given address, which clients can use to request blocks of
entropy directly from the internal pool. The host part can be a DNS hostname or
address literal. If an IPv6 address literal is used it should be enclosed in
square brackets (e.g. [::1]:2020 to bind to port 2020 on the local IPv6 interface).
The port can be a port number or a service name (as defined in /etc/services or
other system name-service databases which are queried by getaddrinfo(3)).
To obtain entropy from this port, write the desired number of bytes to it as a two-
octet network-order short integer. It will reply with a datagram containing the
requested number of bytes of entropy. Requests for 1 to 32768 bytes will be
honored as soon as there is sufficient entropy in the internal pool to do so.
Requests outside of that range are invalid and will simply be ignored. Note that
no access control is placed on the socket, so if it uses a publicly accessible
address anyone will be able to read entropy from it (and potentially to use it as a
traffic amplifier if requests use a forged source address).
This facility is mainly provided for use on operating systems like Windows, where
the native interfaces may be of questionable usefulness or quality and cannot be
audited - but it is generic and so can be used on any system where obtaining
entropy directly from the BitBabbler devices might be desirable. On Linux systems
we do recommend using the system /dev/(u)random interfaces though, since that will
mix in other entropy and transparently benefit all existing applications. They
aren't mutually exclusive though, you can use both this and the --kernel option
together too.
-c, --control-socket=path
Set the filesystem path for the query and control socket that may be used to obtain
information and statistics about the performance of the BitBabbler devices and
control some aspects of the running process. The special value of 'none' may be
passed to disable the creation of a control socket. Mostly this option is useful
if you have more than one seedd process running which are each controlling
different sets of devices.
On systems where unix domain sockets are not available, or if you wish to make the
control socket visible to other machines on the network, you can instead use a
string of the form tcp:host:port, where the host and port parts are as described in
the --udp-out option above. Note that there is no access control when a TCP socket
is used, so any user on any machine that is able to connect to this port will be
able to do anything the control socket allows.
If this option is used to change the default control-socket address, then you will
also need to explicitly specify the new address to other tools accessing it too,
like bbctl(1) and the munin plugin.
--socket-group=group
Permit access to the control socket by members of the named group. If this option
is not specified, then only the owner of the seedd process will be able to connect
to that socket. The adm group may be a reasonable choice to set this to on many
systems (it is the default used by the Debian package init scripts), but you are
free to use any group for this which best suits local access policies.
This option has no effect if a TCP port is used for the control socket instead of a
unix domain socket path.
-v, --verbose
Make more noise about what is going on internally. If used (once) with the --scan
option this will show more information about each device, but otherwise it's mostly
only information useful for debugging. It may be passed multiple times to get
swamped with even more information.
As an exception to the handling of most cumulative options, this one will override
any previous verbose setting read from a configuration file, not accumulate
additional verbosity on top of that.
--version
Report the seedd release version.
--gen-conf
Output text (to stdout) suitable for use as a configuration file based on the
command line options that were passed. None of those options will actually be
acted upon, seedd will simply exit after it has output a configuration which would
do the same thing as that set of options.
Any command line options which have no equivalent configuration file option will
simply be ignored (i.e. --scan, --shell-mr, --bytes, --stdout).
The --help and --version options should not be used together with this one, since
they too will short-circuit and exit before the action of this option is performed.
Any unknown or illegal options passed after this one on the command line will cause
seedd to exit with a failure (non-zero) return code and without emitting the usual
usage help text or any otherwise resulting configuration options. This allows its
use to be safely scripted when the input and output cannot or will not be
immediately examined for proper sanity.
-?, --help
Show a shorter version of all of this, which may fit on a single page, FSVO of page
size.
Pool options
These options may be used to control the behaviour of the entropy collection pool. You
normally shouldn't need to change or set any of these options unless you have very special
requirements and know exactly what you are doing and why.
-P, --pool-size=n
Specify the size of the internal entropy pool. Entropy read from a BitBabbler will
gather in that pool after health and sanity checking. When multiple BitBabbler
devices are in use, entropy from each group of devices will be mixed into it.
Entropy read from stdout, or the UDP socket, or delivered to the kernel will be
drawn from this pool. Fresh entropy will continue to be mixed into it while it is
not being drained faster than it can be filled. The default pool size is 64kB,
which provides a reasonable balance between what a single BitBabbler running at
1Mbps can fill completely about twice per second, and what most reasonable
consumers might ever want to draw from it 'instantly'. There probably aren't many
good reasons to make it much larger, but making it smaller will increase the number
of input bits mixed into each output bit if the pool is not being drained
completely faster than it can fill. We do not rely on this mixing to obtain good
quality entropy from each BitBabbler device but it doesn't hurt to be mixing more
good entropy into it while the demand is exceeded by supply.
--kernel-device=path
Set the device node used to feed fresh entropy to the OS kernel. You normally
shouldn't ever need to set this explicitly, as the default should be correct for
the platform we are running on. This option has no effect unless the --kernel
option is being used.
--kernel-refill=sec
Set the maximum time in seconds before fresh entropy will be added to the OS kernel
pool, even when it has not been drained below its usual refill threshold. This
option has no effect unless the --kernel option is being used.
When feeding the OS pool, seedd will be woken to immediately add more entropy to it
any time that it falls below the configured minimum watermark (which on Linux is
set by /proc/sys/kernel/random/write_wakeup_threshold and can be configured
persistently in /etc/sysctl.d/bit-babbler-sysctl.conf).
In addition to that, it will also wake up periodically to mix fresh entropy into
the OS pool even if it is not being consumed (testing that the output of the device
is still passing all the QA testing in the process). This option configures how
long it will wait since the last time fresh entropy was added before doing that.
If set to 0, then we will never add more entropy unless explicitly woken by the OS
pool falling below its watermark. The default is 60 seconds, and there probably
aren't many reasons to reduce that, but you may want to increase or disable it on
low power systems which you don't want to be waking up just to do this.
The main downside to increasing it is that on relatively quiet systems it may take
(significantly) longer for the long term QA tests (in particular the 16 bit tests)
to accumulate enough results for analysis, and you lose some of the confidence that
comes with a higher rate of continual sampling from the device. This option lets
you choose the right balance for your own use. If unsure, leaving it at its
default setting is probably the right answer.
-G, --group-size=group_number:size
Set the size of a single pool group. When multiple BitBabbler devices are
available, there is a choice of whether to optimise for throughput or for
redundancy. For example a pair of devices both running at 1Mbps can together
produce an effective throughput of 2Mbps of entropy if their streams are output
independently of each other, but they can also be mixed together in parallel to
provide a stronger guarantee of entropy at 1Mbps with the stream being at least as
unpredictable as the most unpredictable device. With more than two devices a
combination of both strategies may be used.
Devices that are placed in the same group will not add entropy to the pool until
every device in that group has contributed at least size bytes to it. If the
devices are not running at the same bit rate, the faster device(s) will continue to
mix entropy into the group until every device has contributed. This option enables
configuration of that block size. The group_number is an arbitrary integer
identifier (which will be passed to the --group option for the device(s) to add to
it). The size may be followed by a suffix of 'k', 'M', or 'G' to multiply it by
the respective power of two. The group size will be rounded up to the nearest
power of two. Default is for groups to be the same size as the pool, but they may
be set either smaller or larger than it if desired. The two values are separated
by a colon with no other space between them.
Per device options
The following options may be used multiple times to individually configure each device
when more than one BitBabbler is available. If passed before any --device-id option, then
they set new default values which will apply to every device. If passed after one of
those options they will only be applied to the immediately preceding device.
-r, --bitrate=Hz
Select the device bitrate in bits per second. The available bitrates are
determined by an integer clock divider, so not every rate is exactly achievable.
An unsupported rate will be rounded up to the next higher rate. For convenience
the rate may be followed by an SI multiplier (eg. 2.5M for 2500000).
--latency=ms
Override the calculated value for the USB latency timer. This controls the maximum
amount of time that the device will wait if there is any data in its internal
buffer (but less than a full packet), before sending it to the host. If this timer
expires before a packet can be filled, then a short packet will be sent to the
host. The default value is chosen to ensure that we do not send more short packets
than necessary for the selected bitrate, since that will increase the number of
packets sent and the amount of CPU time which must be spent processing them, to
transfer the same amount of data.
Unless you are experimenting with changes to the low level code, there is probably
no reason to ever use this option to override the latency manually.
-f, --fold=n
Set the number of times to fold the BitBabbler output before adding it to the pool.
Each fold will take the first half of the block that was read and XOR it with the
bits in the second half. This will halve the throughput, but concentrate the
available entropy more densely into the bits that remain.
There are two main things this is expected to do based on the BitBabbler design.
It will better mix the low-frequency noise that is captured with that of the higher
frequencies, allowing it to sample at higher bitrates without narrowing the noise
bandwidth available to influence adjacent bits. It will help to break up any
transient local correlations that might occur in the physical processes from which
ambient environmental noise is collected.
Folding should never reduce the real entropy of each sample, but when all is
working exactly as it should, it may not do anything to increase it either.
Mathematically, an XOR summation is expected to exponentially smooth any bias in a
stream of independent bits, with the result having at least as much entropy as the
least predictable of either of the two inputs (in the same way that a one time pad
is no less secure despite the plaintext having much less entropy than the pad
does).
-g, --group=n
The entropy pooling group to add this device to. See the --group-size option for a
discussion of pool groups. You do not need to declare or define a group in any way
before using this option, devices that have the same group number specified will be
simply be grouped together. By default, all devices are placed in group 0 if this
is not set explicitly for them.
The group 0 is special in that its size can be set explicitly, but it does not wait
for all devices in it to have contributed entropy before mixing into the common
pool, which is functionally equivalent to all of those devices being placed into
separate groups that are the same size.
Normally if a single device in a group fails QA testing, then the entire group will
stop contributing to the pool until it is removed or further extended testing
confirms that failure to be an anomaly and not a persistent condition. For group 0
(and devices in other separate groups), a failed device will not prevent the
remaining devices from continuing to contribute entropy if their own output is
still passing the QA testing.
--enable-mask=mask
Select a subset of the generators on BitBabbler devices with multiple entropy
sources. The argument is a bitmask packed from the LSB, with each bit position
controlling an individual source, enabling it when set to 1.
--idle-sleep=initial:max
This option permits tuning how the devices back off from generating entropy at the
maximum rate, when it is not being consumed from the output pool. When the output
pool is not full, entropy will be read from the devices as quickly as possible to
try to refill it. Once it is full, they will begin to be throttled according to
the following algorithm:
The initial value is the number of milliseconds to sleep when the output pool first
becomes full again. If this value is 0, then the device will immediately remain
idle until the output pool is no longer full. Otherwise, reading from the device
will pause for either this number of milliseconds, or until the pool is no longer
full, whichever comes first. If that timeout expires and the pool is still full,
another block of entropy will be generated and mixed into the pool, then the
timeout will be doubled. This process will continue until the timeout reaches the
max value (which is also in milliseconds), at which point it will not increase any
further. The device will always be woken immediately any time the output pool is
not full, and the timeout cycle will begin again from the initial value each time
that occurs.
As a special case, if the max value is set to 0, with an initial value that is not
zero, the exponential back off will occur as above until the timeout reaches or
exceeds 512 ms, at which point further activity will again be suspended
indefinitely until the output pool is no longer full. This allows for a mode of
operation where the device will still go into a hard suspend when no entropy is
being consumed from the output pool, but only after mixing several blocks of
entropy from each device that is configured this way into it.
The default configuration used if this is not set explicitly is initial=100 and
max=60000. Usually the only reason to change this is if you are trying to minimise
the power usage on a low power system which you don't want continually waking up to
generate entropy that nothing is using. For that use, if you are feeding the OS
kernel pool, you will probably also want to set the --kernel-refill option to a
suitable value, since it will cause the devices to wake up independently of what is
set here (by reading from the output pool, making it be no longer full). Dialling
the verbosity up to level 6 (with -vvvvvv) while tweaking this will let you watch
how the reads from the devices are actually throttled.
When setting this, either of initial or max may be omitted (in which case they will
retain their default value), but the ':' must always be included. It probably
doesn't make a lot of sense to set this differently for each device (especially not
for devices which are grouped together), but that is permitted if you really have
some reason to want to do that.
--suspend-after=ms
Set the minimum expected device idle time for which we should allow the device to
be suspended. On Linux, USB devices that are idle can automatically be suspended
into a low power state, but in order to qualify as being 'idle' for that purpose,
we need to release our claim on the device. Full details of the OS part of that
can be found here:
https://www.kernel.org/doc/Documentation/usb/power-management.txt
The default is 0, which means seedd will never release a device it has claimed.
The benefit of this is that no other process can claim it while it is released
(accidentally or otherwise), which would prevent us from being able to use it again
when we do require entropy from it. It also ensures there is minimal latency when
we are woken up to read entropy from it again.
Setting this to a value greater than zero means that when the output pool is full,
and we are expecting to sleep for at least that amount of time before reading from
the device again, then the claim on the device will be released, and the OS will be
able to suspend it until we need it again. If the pool is drained and requires
more entropy before that time, then we will still reclaim the device immediately
and begin reading from it again, but there will be a small amount of additional
latency while it wakes up and is reinitialised for use. This option should usually
be set in conjunction with --idle-sleep and --kernel-refill which control how often
the device will be woken again to refresh the entropy pools when it might otherwise
have remained idle. If they never allow it to sleep for longer than this time,
then this option will have no effect.
It probably doesn't make much sense to set this below about 10000 (10 seconds)
otherwise the overhead of releasing, reclaiming, and reinitialising the device
might actually use more power than suspending it saves. And it definitely doesn't
make much sense to set it to a value less than what is configured for the
autosuspend_delay_ms option in the kernel, since while we will release the device
any time that we expect to sleep for this long (regardless of whether we actually
do or not), the kernel will not actually suspend it until the autosuspend_delay_ms
time has elapsed after we have released it. So if it doesn't get to actually
suspend it, we would just be chewing extra CPU cycles, and adding extra latency to
obtaining entropy when it is needed, for no net gain.
--low-power
This is a convenience option, which is equivalent to setting:
--kernel-refill=3600 --idle-sleep=100:0 --suspend-after=10000
And which in turn means:
We will wake up to mix more entropy into the kernel pool at least once an hour
(though it is likely that most systems will already drain it below its threshold
and so wake us to refill it before that time expires anyway).
We will mix at least 6 blocks of fresh entropy into the seedd output pool each time
we are woken, before suspending indefinitely again (until either we are woken by
the kernel needing entropy or by the timeout above expiring, or until something
else consumes entropy from the output pool - such as from the UDP socket if that is
enabled). This is based on doubling the initial --idle-sleep timeout each time the
output pool remains full, until we exceed the minimum amount of time that really
will perform a sleep (512ms), and then sleeping until explicitly woken again after
that.
We will release the device, giving the OS the opportunity to suspend it, each time
it does become fully idle (since an indefinite sleep is considered to be longer
than any fixed amount of time).
Any or all of those options may still be customised by passing them explicitly
after this option on the command line (in the same way that passing them twice
would also override the first instance).
This isn't necessarily the configuration offering the lowest possible power
consumption, but it's intended to strike a reasonable balance for systems where
keeping idle power consumption low is a more important concern than continually
mixing in additional fresh entropy or minimising the latency if demand for entropy
suddenly surges (which is what the normal defaults are more oriented toward). At
the very least it should be a reasonable starting point to begin experimenting from
on low power systems.
Note that although this option may be specified per-device, the --kernel-refill
time is a global option, and that setting will be applied if the configuration for
any device uses this option, even if that device isn't currently available for use.
That normally shouldn't be a problem though, since the question of whether
minimising power use is more important than other considerations is usually a
system-wide one anyway.
--limit-max-xfer
Limit the maximum transfer chunk size to 16kB. On Linux, prior to kernel 3.3,
individual bulk transfer requests were somewhat arbitrarily limited to 16kB. With
kernels later than that, larger transfers were supported, and we will make use of
those to optimise transfer speeds for large requests at high bitrates when a new
enough kernel and libusb with support for this are both available.
Unfortunately, the USB chipsets on some motherboards are still buggy when these
larger transfers are used, and there is no easy way for us to automatically detect
those, since the symptoms they exhibit do vary and aren't always directly visible
to our code. Ideally any problems like that should be reported to the kernel
maintainers, where they can be fixed, or worked around for device specific quirks,
but this option allows you to explicitly request that the transfer size be limited
on machines where you are experiencing problems with that.
If in doubt, it is safe to use this option on any system, the impact on transfer
speed is relatively minimal unless you are trying to obtain huge numbers of bits as
quickly as possible. But it's not the default, since at present only a very small
number of systems are still known to be affected, and that number should continue
to decrease over time.
--no-qa
Disable gating entropy output on the result of quality and health checking. You
pretty much never want to use this unless you are generating streams to stdout for
no other reason than to analyse their quality with some other tool, such as
dieharder(1) or the NIST test suite or similar. For that type of use we definitely
don't want to be filtering out blocks which have already failed our own internal
quality analysis, otherwise the value of such testing will be almost as tainted as
that of the people who say "after whitening our RNG with SHA-1 it now passes all of
the statistical tests perfectly!", and there's already more than enough fossils in
that tarpit.
It is not possible to disable this for data which is passed directly to the kernel
entropy pool, there is absolutely no reason to ever want to do that, nor does it
disable the gating for bits requested from the UDP socket interface. It does not
actually disable the QA checks from being performed (so the results of them will
still be seen in the monitoring output and can generate external alerts if this
mode was entered 'by accident'). It just permits any failing blocks to still pass
through to stdout, so other tools can heap all the scorn on the output that it
deserves if it is failing.
Extended QA options
Since we already have some high quality QA analysis running on the output of the
BitBabbler devices, it makes sense to also be able to use that to sample, analyse, and
monitor the quality of entropy from other independent sources and downstream points that
end user applications may be obtaining it from too.
--watch=path:delay:block_size:bytes
Monitor an external device. This option does not directly effect the operation of
collecting entropy from BitBabbler devices, or contribute in any way to the entropy
that is output, either to stderr or the kernel. What it does do is leverage the
quality assurance and health checking algorithms, and the trend monitoring
functionality that this software provides, to also permit continuous supervision of
other sources which are expected to be statistically random.
For example it can be used to regularly sample from /dev/urandom or even from
/dev/random to ensure the quality of their output is really what you expect it to
be. There's little point to putting the most awesome entropy that the universe can
conjure in, if what's coming out and feeding the applications that are consuming it
is totally predictable garbage.
If this is used to monitor a limited source of blocking entropy, such as
/dev/random then you'll want to be judicious in selecting the rate of reading from
it, so as not to consume all the available entropy that you were aiming to gain by
feeding it from a BitBabbler in the first. If it's reading from an 'unlimited'
source backed by a PRNG, such as /dev/urandom, then the only real consideration is
how much of the other system resources do you want to consume in drinking from the
firehose.
The path is the filesystem path to read from, it can be anything which can be
opened and read from like a normal unix file. The delay is the amount of time, in
milliseconds, to wait between reading blocks of data from it. The block_size is
the number of bytes to read in a single block each time the watch process wakes up
to read more. The total amount of data to read can by limited to bytes, once that
limit is reached, the watch process for path will end (but all other processing
will continue as per normal).
All qualifiers except the path are optional, and separated by colons with no other
space between them, but all options must be explicitly set up to the last one that
is provided. The delay may be followed by a suffix of 'k', 'M', or 'G' to multiply
it by the respective power of 10, or by 'ki', 'Mi', or 'Gi' for powers of two if
you're into that kind of thing. The block_size and bytes options may be similarly
suffixed, but like all good sizes on computers are always a power of two if so.
CONFIGURATION FILE FORMAT
In addition to use of the command line options, seedd configuration may be supplied by
"INI" format files encoded as Sections, Options and Values. Since there is no standard
definition for that format, the general rules applicable here are as follows:
A Section definition begins on a line where its name is enclosed in square brackets. The
Section name itself may contain any characters except square brackets. Any characters
following the closing square bracket on the same line will simply be ignored, but a well
formed file should not rely on that always remaining true.
All following Option/Value pairs belong to that Section until the next Section header
occurs. Option names may include any characters except whitespace. Leading and trailing
whitespace around Option names and Values is ignored. Internal whitespace in Option
values is preserved. Options must be defined on a single line, and everything (except
leading and trailing whitespace) following the Option name up to the end of the line is
part of the Value. Quote characters (of any sort) have no special meaning and will be
included as a literal part of the value.
Comments must appear on their own line, with the first (non-whitespace) character of the
line being '#'.
If Options are duplicated in a configuration file, either in a single file or when
multiple configuration files are used, then any options which are repeated will override
the values which were set for them previously. Options specified on the command line have
a similar precedence, with the exception of --verbose, they must come after all --config
files if they are to override them and not be overridden by them.
The following Sections and Options may be used. See the equivalent command line options
(as indicated) for a full description of their behaviour. In most cases, the option names
are the same as the long form of the command line option. It is an error for an unknown
Section or Option to be present.
[Service] section
The Service section is used to configure process-wide behaviour using the following
options:
daemon
Fork to the background and run as a daemon process (--daemon).
kernel
Feed entropy to the OS kernel (--kernel).
ip-freebind
Allow binding to an IP address that is non-local or does not (yet) exist
(--ip-freebind).
udp-out host:port
Provide a UDP socket for entropy output (--udp-out).
control-socket path
Where to create the service control socket (--control-socket).
socket-group group
Give users in this system group permission to access the control socket
(--socket-group).
verbose level
Set the logging verbosity level. A level of 2 is equivalent to using -vv (--verbose).
[Pool] section
The Pool section is used to configure the entropy collection pool. You normally shouldn't
need to change or set any of these options unless you have very special requirements and
know exactly what you are doing and why.
size n
The size of the internal entropy pool in bytes (--pool-size).
kernel-device path
The device node used to feed fresh entropy to the OS kernel (--kernel-device). This
option has no effect unless the --kernel option is being used.
kernel-refill sec
The maximum time in seconds before fresh entropy will be added to the OS kernel, even
when it hasn't drained below its usual refill threshold (--kernel-refill). This
option has no effect unless the --kernel option is being used.
[PoolGroup:n] sections
Defines an entropy collecting group and the size of its pool (--group-size). The group
number n is an integer value used by the per-device --group option to assign a device to
that group. Any number of groups may be defined, but each must have a unique value of n.
size n
The size of the group pool (--group-size).
[Devices] section
The Devices section configures the defaults to use for all BitBabbler devices which don't
override them in a per-device section (or on the command line). All options set here do
the same thing as the command line options with the same name when passed before any
--device-id option.
bitrate Hz
The rate in bits per second at which to clock raw bits out of the device (--bitrate).
latency ms
Override the calculated value for the USB latency timer (--latency).
fold n
Set the number of times to fold the BitBabbler output before adding it to the pool
(--fold).
group n
The entropy [PoolGroup:n] to add the device to (--group).
enable-mask mask
Select a subset of the generators on BitBabbler devices with multiple entropy sources.
The argument is an integer bitmask packed from the LSB, with each bit position
controlling an individual source, enabling it when set to 1 (--enable-mask).
idle-sleep initial:max
Configure how devices back off from generating entropy at the maximum rate when it is
not actually being consumed by anything (--idle-sleep).
suspend-after ms
The threshold in milliseconds where if we expect the device to be idle for longer than
that, we will release our claim on it, allowing the OS to put it into a low power mode
while it is not being used (--suspend-after).
low-power
Enable options for better power saving on lightly loaded systems (--low-power).
limit-max-xfer
Limit the maximum transfer chunk size to 16kB (--limit-max-xfer).
no-qa
Disable gating entropy output on the result of quality and health checking (--no-qa).
[Device:id] sections
Sections with a Device: prefix can be used to both enable and configure individual
devices. It is the equivalent of passing --device-id=id on the command line. If any
options are specified for this section, that is equivalent to passing them after the
--device-id option in that they will only apply to this device and no others. All the
options for the [Devices] section above may be used here.
If no [Device:] sections are defined, the default is to operate on all of the devices
which are available. It is not an error to define these sections for devices which are
not, or may not be, present at any given time.
[Watch:id] sections
Sections of this type can be used to run our QA testing on some other external source of
random bits, provided we can read them as if they were a file or named pipe or device
node. Any number of [Watch:] sections may be defined, each just needs its own unique
label after the Watch: prefix to identify it. The id has no use or meaning other than to
make each watch section name unique. The options below correspond to the component parts
of the argument passed with --watch on the command line.
path device
The path to the device/pipe/file to read bits from. This option must be set for every
watch section.
delay ms
How long to wait before reading the next block of bits, in milliseconds. Default is
0.
block-size bytes
The number of bytes to read between each delay period. Default is 64k.
max-bytes bytes
The maximum number of bytes to read in total. Default is 0 which implies reading an
'infinite' number of bits for as long as the process keeps running, which is probably
what you usually want when using this.
CONTINUOUS MONITORING
The query and control socket enables device performance and QA statistics to be examined
in real-time. The bbctl(1) tool can be used to produce human readable reports on demand
from the information it provides, but it can also be queried directly by other tools that
want that information in a more machine readable form (see the json_protocol document for
a full description of that). For users of munin, a plugin is provided which will
continuously graph the status of each device, and which can be used to trigger an alert if
an abnormal condition occurs.
The munin plugin requires the perl JSON::XS module (provided by the libjson-xs-perl
package on Debian systems), and it must be explicitly enabled on each system where it is
desired to run. Typically that will require doing something like this:
# munin-node-configure --shell
# ln -s /usr/share/munin/plugins/bit_babbler /etc/munin/plugins/bit_babbler
# service munin-node restart
If munin-node-configure does not report that plugin autoconfiguration succeeded, the most
likely reason is that JSON::XS is not available. There are a few options to configure the
plugin's behaviour, these are all documented in /etc/munin/plugin-conf.d/bit-babbler
(where they should be set if desired). The munin-node service needs to be restarted for
changes to its plugins to take effect.
BOOT SEQUENCING
When seedd is being used to feed entropy to the OS kernel, there are two main
considerations to deal with. On modern systems where the kernel random source is used by
almost every process, if only for ASLR, we want that to be well seeded with the best
entropy available as early as is possible. And ideally we also want any services which do
have a critical need for high quality entropy to not be started until that can be
guaranteed by proper QA testing of the entropy stream.
Historically, the mechanics of ensuring all that was not just an OS-specific detail, but
it also varied, sometimes greatly, even between different flavours of the various OS
platforms. So it was up to the higher level packaging for each OS variant, and the users
of them, to implement something appropriate for each environment. That is still largely
true, but for people using Linux distributions where the init(1) process is provided by
systemd now, we can in theory provide some defaults which should suit most users and still
be fairly easily customisable for specific use case requirements as well. Since
configuring systemd correctly for anything not completely trivial is still something of a
black art, which a lot of services (and even the systemd provided ones) seem to still get
wrong to some degree or another, it does make sense for us to provide a tested
configuration - along with some guidance to users of other platforms and init systems
about what they should be aiming for. What follows is a description of the boot
sequencing options implemented for a systemd environment, but the general requirements of
that should be broadly applicable too since they don't do anything magical which couldn't
be done in another alternative environment.
By default we provide two systemd "service units" to implement the requirements outlined
above.
The seedd daemon service (seedd.service)
This unit provides the ordinary functionality of ensuring that seedd is started at the
earliest possible time in the boot sequence where its requirements are able to be met.
For that reason its requirements should be (and deliberately have been) kept as minimal as
reasonably possible. It needs access to some low-level system libraries, to its
seedd.conf configuration file (though that could be eliminated at the cost of some user-
friendliness by hardcoding the options to run it with in the unit itself), to a writable
directory where it will create its control-socket, and to the system device files where
the BitBabbler and kernel random devices will be found.
Since the BitBabbler devices can be hotplugged, we don't actually need to wait for them to
be present to start this - and in practice with the current unit configuration, seedd is
almost certain to be started before the USB devices have been probed and announced to the
system, or before even udev is running to notify it about them. This means it will be
ready to use them at the soonest possible moment that they do become available.
This unit is installed by default, but it must still be explicitly enabled, either by the
distro packaging (which we do recommend does this, and which the Debian packages indeed
do), or by the local admin if they manually installed this software from source
themselves. It is the equivalent of what the SysV init script provided for Debian based
systems will do on systems which aren't using systemd as their init system. It is always
safe for seedd to be running even when no BitBabbler devices are currently available in
the system, it just won't do much unless also configured to watch some external source.
Waiting for initial kernel seeding (seedd-wait.service)
This optional unit is also installed by default, but it generally should not be enabled
automatically by distro packaging, only at the explicit request of a local admin. It
provides a boot sequence point with some more complete and useful guarantees:
- That seedd has successfully been started and is running.
- That at least one BitBabbler device (or more depending on the configuration used for
seedd) is available and operating correctly, and able to provide the system with fresh
QA checked entropy.
- That good quality entropy obtained from the available device(s) has been provided as
initial seed material to the OS kernel.
If simply enabled on its own, this unit will delay starting anything which is scheduled to
be started later than seedd in the boot sequence (or more specifically, anything which
wouldn't be started until after all of the local mount points in /etc/fstab have been
mounted - which should be before most services that aren't part of the early boot
initialisation), until the three conditions above have been met. It will wait for up to
30 seconds for that to occur before timing out and entering a failed state, after which
the rest of the boot sequence will then still continue normally.
This provides a reasonable compromise between a guarantee that good entropy will actually
be used if it is possible to obtain it, and not rendering the system completely unable to
boot if for some reason it is not. If you wish to enable it, you can do that with:
# systemctl enable seedd-wait.service
If you wish to change the timeout period, you will need to edit or override this unit to
change either or both of the timeout used in --waitfor and the TimeoutStartSec option. It
should be long enough for devices to become available, and have enough entropy read from
them to be QA checked for use as early seed material, but not so long that booting is
delayed needlessly when it is clear that nothing is likely to change if we just wait
longer.
When failure is not an option
If a stronger guarantee than the above really is needed, either system-wide or just for
particular services, then declaring a Requires relationship with this unit will prevent
anything which does so from starting, both before this task has completed and if this task
should fail. For example if you wanted to prevent apache2(8) from starting if this unit's
checks should fail, then you could do:
# systemctl add-requires apache2.service seedd-wait
Or equivalently (which is what the above command does):
# mkdir /etc/systemd/system/apache2.service.requires
# ln -s /lib/systemd/system/seedd-wait.service /etc/systemd/system/apache2.service.requires
Which will work for older systems where systemctl does not yet support the add-requires
command, and with generated units (such as those for services which still provide only a
SysV init script), which at the time of writing systemctl failed to support. Any number
of other units may have a Requires dependency retrofitted like this, or may even include
it in their own unit file if appropriate.
Go big or go visit the server room
If you want the strongest guarantee for all normal services running on the system, so that
none of them will be started if this initial boot test fails, then you can do something
like the following, which if it fails will put the system into a minimal single-user mode
with only an emergency admin shell available to someone with console access who knows the
root password:
# mkdir /etc/systemd/system/seedd-wait.service.d/
# cat > /etc/systemd/system/seedd-wait.service.d/failure.conf <<EOF
[Unit]
OnFailure=emergency.target
OnFailureJobMode=replace-irreversibly
EOF
For most users, this is probably a good approximation to the limit of overkill, but for
people who do have special requirements, which are stricter than the defaults are, this
all should give a reasonable overview of the sort of things that are possible to configure
how you need them to be. It's not exhaustive, but it should give you some starting points
to branch out from.
But I don't use systemd ...
For people who aren't using systemd (and even for people who are), it is also possible to
do all the things shown here by making your own call to bbctl --waitfor (which is what
seedd-wait.service does) after seedd has started and before whatever it is that you need
this guarantee for. It can also be used to wait for some quantity of good entropy to be
seen at any device which seedd performs QA analysis on, including external sources
monitored with a --watch. See the bbctl(1) man page for more details.
FILES
/etc/bit-babbler/seedd.conf
The default configuration file used when automatically starting as a daemon at
system boot time.
/run/bit-babbler/seedd.socket
The default --control-socket path if not explicitly specified. This may be under
/var/run on platforms which don't (yet) provide a /run top level directory (or a
TCP socket on platforms which don't support unix domain sockets). It is set at
compile time by SEEDD_CONTROL_SOCKET.
/usr/lib/sysctl.d/bit-babbler-sysctl.conf
/etc/sysctl.d/bit-babbler-sysctl.conf
Configuration for kernel system variables. Mostly used to adjust the low-water
mark for the Linux kernel entropy pool, which controls when it will wake seedd for
an immediate top up.
/lib/udev/rules.d/60-bit-babbler.rules
The default udev(7) rules granting direct device access to users in the group
bit-babbler, enabling USB autosuspend when the device is idle, and invoking bbvirt
to handle device hotplug for virtual machines. These can be overridden by creating
/etc/udev/rules.d/60-bit-babbler.rules and populating it with your own rules.
/etc/munin/plugin-conf.d/bit-babbler
The munin-node configuration for continuous monitoring.
/lib/systemd/system/seedd.service
Unit file for the seedd daemon process. When enabled on systems where systemd
provides init(1) this will start the daemon as early as possible in the boot
sequence, using the configuration options that are defined in the
/etc/bit-babbler/seedd.conf file.
/lib/systemd/system/seedd-wait.service
An optional extra unit file, which if enabled will pause the boot sequence until
sufficient initial fresh entropy has been supplied to the OS kernel. By default it
will wait for up to 30 seconds for this to occur before signalling a "failed" state
and then allowing the boot process to still continue. This means that in normal
circumstances processes which need to consume entropy will not be started before
the OS has been well seeded, but failure of a BitBabbler device, or simply booting
without one attached, will not render the system completely unbootable or unusable.
It will just delay that from completing until the timeout failure of this service
occurs.
As an even stronger option, if particular services do need or want to be maximally
paranoid about only starting after the OS kernel has been seeded with fresh
entropy, then they can declare a Requires relationship with this unit, which will
ensure that they will only be started if the initial fresh seed entropy could be
obtained.
The latter option, particularly, should be used with some caution, as it will
effectively make having a functioning BitBabbler device (and an active and
correctly configured seedd service) become a "master key", without which the system
will not become "normally functional" at boot. So this can be both a feature, and
a way to accidentally lock yourself out.
This functionality is limited to ensuring that a freshly booted machine will be
initially seeded with a good source of genuinely unknowable entropy (as opposed to
seeding itself from a file of stored entropy saved when it was last running, and
whatever it is able to collect from other sources in the small amount of time it
has before other services consuming it are normally started). It will not halt or
otherwise interrupt any already running services which required it after that
condition has been met, even if the BitBabbler device is subsequently unplugged,
SEE ALSO
bbctl(1), bbvirt(1).
AUTHOR
seedd was written by Ron <ron@debian.org>. You can send bug reports, feature requests,
praise and complaints to support@bitbabbler.org.
Jan 11, 2018 SEEDD(1)