Provided by: bit-babbler_0.9_amd64 bug

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)