Ubuntu Manpage: bbctl - query and control tool for BitBabbler hardware RNG devices

NAME

       bbctl - query and control tool for BitBabbler hardware RNG devices

SYNOPSIS

       bbctl [options]

DESCRIPTION

       The  bbctl program can be used to issue command requests to the control socket of software
       controlling a BitBabbler device (such as the seedd(1) daemon).

OPTIONS

The following options are available:

-s, --scan
Scan for active devices. This will report the device identifiers which can be
queried from the owner of the control socket.

-i, --device-id=id
Act on only the specified device. If no devices are explicitly specified then the
default is to act upon all of them. This option may be passed multiple times to
act on some subset of the available devices. The id must be an identifier name as
reported by bbctl --scan, you cannot use device logical or physical addresses here.

-b, --bin-freq
Report the 8-bit symbol frequencies.

-B, --bin-freq16
Report the 16-bit symbol frequencies.

--bin-count
Report the 8-bit symbol counts. Similar to --bin-freq except the bins are reported
in symbol order instead of sorted by frequency.

--bin-count16
Report the 16-bit symbol counts. Similar to --bin-freq16 except the bins are
reported in symbol order instead of sorted by frequency.

--first=n
Show only the first n results. Useful when you don't want to actually see all 65
thousand entries for the 16-bit bins. The default (if neither this nor the --last
option are specified) is to report everything in its full glory. Don't say I
didn't warn you.

--last=n
Show only the last n results. Useful when you don't want to actually see all 65
thousand entries for the 16-bit bins. If used together with the --first option,
then both the requested head and tail of the results will be shown.

-r, --bit-runs
Report on runs of consecutive bits.

-S, --stats
Report general QA statistics.

-c, --control-socket=path
The filesystem path for the service control socket to query. This can belong to
any process that supports the BitBabbler control socket interface and for which the
user running bbctl has permission to connect to.

An address of the form tcp:host:port may be used if the control socket is bound to
a TCP port rather than a unix domain socket path. 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. tcp:[::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)).

-V, --log-verbosity=n
Change the logging verbosity of the control socket owner.

--waitfor=device:passbytes:retry:timeout
This option will make bbctl wait before exiting until the seedd(1) QA checking
reports that at least passbytes of good entropy have been obtained from the given
device. It will check for that every retry milliseconds, waiting for a maximum of
timeout milliseconds before failing.

The device is a QA test identifier as reported by --scan, and must be provided, as
must the expected passbytes count. The retry time is optional, and if not
specified it will default to 1000 milliseconds. If the timeout is 0 (or not
explicitly passed), then this will wait for an unbounded amount of time for the
requested condition to occur.

The passbytes, retry, and timeout parameters may be suffixed with an SI multiplier
(e.g. k, M, G) as a convenience, so a timeout of 30k would wait for 30 seconds.

This option may be passed multiple times to wait for multiple devices, and the
given conditions for each of them will be tested for in the order that they are
specified on the command line. i.e. Later conditions will not be tested for at all
until all prior ones have been met, and the timeout clock for each test only begins
after the previous test has successfully completed.

When all required conditions pass, bbctl will report success with an exit code of
0. If a timeout is exceeded, or any other error occurs which means the test cannot
be successfully completed (like passing a device which does not exist, or querying
a --control-socket which no process provides), then a non-zero exit code will be
returned.

This option mostly exists to make it possible to delay or even prevent other
services from starting until a sufficient amount of entropy has been obtained to
feel comfortable that they can operate securely or as intended. See the notes on
BOOT SEQUENCING in seedd(1) for more details on that. It may be used for other
purposes too, but note that passbytes is an absolute measure of the number of good
bytes seen since seedd was started, it is not relative to the number that were
obtained prior to executing this request.

-v, --verbose
Make more noise about what is going on internally. It may be passed multiple times
to get swamped with even more information.

-?, --help
Show a shorter version of all of this, which may fit on a single page.

--version
Report the bbctl release version.

FILES

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

AUTHOR