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.

[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.

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.