BBCTL(1)

📦 version 0.9, in ubuntu jammy

💖 BBCTL(1) — the BitBabbler control tool, bestie edition 💖

okay so. this is bbctl, from the General Commands Manual, and it's basically the little remote control for your BitBabbler hardware RNG situation. sit down, hydrate, let's go 🫶

✨ NAME ✨

bbctl — query and control tool for BitBabbler hardware RNG devices 🎀

🌸 SYNOPSIS 🌸

bbctl [options]

that's it. that's the whole vibe. just options, no positional nonsense, we love a low-maintenance girlboss 👑

💅 DESCRIPTION 💅

The bbctl program can be used to issue command requests to the control socket of software controlling a BitBabbler device — think the seedd(1) daemon, that kind of thing. it talks to the socket, the socket talks back, everybody's happy ✨

🦋 OPTIONS 🦋

okay bestie here's the whole menu, no skips, all sixteen of them, we're eating today 🍓

  • -s, --scan — Scan for active devices. this reports the device identifiers that can be queried from the owner of the control socket. your starting point, fr fr 🔍
  • -i, --device-id=id — Act on only the specified device. if you don't explicitly specify any devices, the default is to act upon all of them. you can pass this option multiple times to act on some subset of the available devices. the id must be an identifier name as reported by bbctl --scan — and no, you literally cannot use device logical or physical addresses here. that's the rule 💀
  • -b, --bin-freq — Report the 8-bit symbol frequencies. numbers go brrr 📊
  • -B, --bin-freq16 — Report the 16-bit symbol frequencies. same energy, twice the bits ✨
  • --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. it's giving "order, but not the frequency one" 🎀
  • --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. yes this is the big one, 65 thousand entries, we'll get to that 🌈
  • --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. head AND tail, we contain multitudes 🫶
  • -r, --bit-runs — Report on runs of consecutive bits. little bitty marathons 🏃‍♀️
  • -S, --stats — Report general QA statistics. the report card, the vibe check, the whole thing 📋
  • -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. permissions check, bestie, we don't skip it 🔐

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)). yes we cited getaddrinfo(3), we're thorough like that 💅

  • -V, --log-verbosity=n — Change the logging verbosity of the control socket owner. you're adjusting their volume, not yours. iconique 🎚️
  • --waitfor=device:passbytes:retry:timeout — okay this one is the main character. 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. no cap, forever, we'll be here 🕰️

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. cute AND practical ✨

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. it's a queue, bestie, no cutting 🚦

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. important, don't misread it, i'm begging 🙈

  • -v, --verbose — Make more noise about what is going on internally. it may be passed multiple times to get swamped with even more information. pass it again. pass it again. chaos 🌊
  • -?, --help — Show a shorter version of all of this, which may fit on a single page. the tl;dr of the tl;dr 🎀
  • --version — Report the bbctl release version. the classic. the icon ⭐

🎀 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. compile-time tea ☕

🔥 SEE ALSO 🔥

seedd(1). that's the one. go read it 🫶

👑 AUTHOR 👑

seedd was written by Ron <ron@debian.org>. You can send bug reports, feature requests, praise and complaints to support@bitbabbler.org. praise and complaints in the same inbox is so real, honestly 🌈

💜 and that's the whole page, bestie. go query something. go wait for entropy. go be the main character of your own boot sequence.

this came out of the General Commands Manual as page BBCTL(1), dated January 24, 2018 — mwah, love that for us 💅✨

📦 where this page comes from