bwctld(8)

📦 version 1.5.4, in ubuntu jammy

💖 bwctld — the Bandwidth Control server, bestie edition 💖

okay so real talk, this one lives in section 8 of the System Manager's Manual (that's the big-kid sysadmin section, iykyk), and it's genuinely iconic. grab a strawberry 🍓, sit down, we're gonna go through the whole thing.

✨ NAME ✨

bwctld — the Bandwidth Control server. that's it, that's the vibe. 👑

🌸 SYNOPSIS 🌸

bwctld [ -a auth_mode ] [ -c conf_dir ] [ -e facility ] [ -f ] [ -G group ] [ -h ] [ -R var_dir ] [ -S nodename:port ] [ -U user ] [ -v ] [ -Z ]

🦋 DESCRIPTION 🦋

so bwctld is a server program, and its whole job is scheduling and running tests. which tests, you ask? literally all of these: Iperf, Thrulay or Nuttcp, Ping, Traceroute, Tracepath, and Owamp. like, the entire measurement friend group. 💅

and honestly? running the tests is only, like, half the story. the main function of bwctld is deciding which tests are even allowable, based on the policy restrictions that the system administrator configured. it's giving bouncer at the club, but for network measurements. 🚫✨

bwctld was designed to be run as a stand-alone daemon process. it uses the classic accept/fork model for handling new requests. no cap, that's the architecture. 🧚

and here's the thing you actually need to remember: most of the command line options for bwctld have analogous options in the bwctld.conf file. and when they disagree? the command line takes precedence. periodt. 💖

💅 OPTIONS 💅

  • -a auth_mode — pick the authentication modes the server is willing to use for communication. auth_mode gets set as a character string containing any or all of the characters "AEO". here's the decoder ring:
    • A — [A]uthenticated. this mode encrypts the control connection. 🔐
    • E — [E]ncrypted. this mode encrypts the control connection too. and if the test supports encryption, this mode will additionally encrypt the test stream. ⚠️ heads up though: encryption of the test stream is not currently supported, so this mode is currently identical to authenticated. so like, E is lowkey just A in a cuter outfit rn. 😭
    • O — [O]pen. no encryption of any kind is done. it's giving exposed. 🙈

the server can specify all the modes with which it is willing to communicate. then the most strict mode that both the server and the client are willing to use gets selected. compromise, but make it secure. 🫶

Default: "AEO".

  • -c conf_dir — specify the directory that holds the bwctld configuration files. 📁

Default: the current working directory.

  • -e facility — the syslog facility to which messages are logged. 📝

Default: LOG_DAEMON

  • -f — this lets the bwctld daemon run with root permissions. and bestie, there are legitimate reasons to run bwctld as root, but it is risky. forcing this extra option just makes it less likely that root permissions get used accidentally. it's a seatbelt, not a personality. 🚗💀
  • -G group — specify the gid for the bwctld process. group can be given as a valid group name, or by using -gid. ⚠️ this option is only used if bwctld is started as root.
  • -h — print a help message. your fave, honestly. 🆘
  • -R var_dir — specify the directory to hold the bwctld.pid file. 🗂️

Default: the current directory.

  • -S nodename:port — specify the address and port on which bwctld will listen for requests. nodename can be given as a DNS name or as the textual representation of the address. and get this — you can set the source address without setting the port, simply by leaving off the ':' and the port specification. 🎯
if you're specifying an IPv6 address, note that the accepted format contains nodename in square brackets, like this: [fe80::fe9f:62d8]. that's what keeps the port number distinct from the address specification. brackets are the moment. 💅

Default: nodename is wildcarded as any currently available address. port is 4823.

  • -U user — specify the uid for the bwctld process. user can be given as a valid user name, or by using -uid. ⚠️ this option is only used if bwctld is started as root.
  • -v — set verbose output. ⚠️ messages will only go to syslog unless the -Z option is also specified. no -Z, no terminal tea. ☕
  • -Z — run the master bwctld process in the foreground. in this mode, error messages are printed to stderr as well as being sent to syslog. plus, normal terminal controls are available — i.e., <Cntr-C> will cause the daemon to kill its child processes and exit. this one is useful for debugging. 🐛🔍

⏰ REQUIREMENTS ⏰

the bwctld daemon prefers a reasonably synchronized clock. it's out here scheduling tests, and it needs to be sure it has the same idea of when a test should take place as the peer test system does. like, you can't show up to brunch at a different time than your bestie and expect it to work. 😭

so, bwctld attempts to use NTP specific system calls to determine the accuracy of the local clock. 🕰️

but if those system calls are unavailable, or the administrator has set the allow_unsync option in the bwctld.conf file, then bwctld will blindly accept tests, assuming the clock is synchronized to within the sync_fuzz value — which is also defined in the bwctld.conf file.

⚠️ and if that assumption does not hold true? the test will eventually fail. and the truly painful part: because the time offset isn't detected early, this test will have taken up a schedule slot. wasted slot. tragic. 💀

📂 FILES 📂

  • bwctld.pid
  • bwctld.conf
  • bwctld.limits
  • bwctld.keys

👀 SEE ALSO 👀

there are more details on configuring the bwctld daemon in the bwctld.conf(5) manual page. ✨

details on configuring the policy live in the bwctld.limits(5) and bwctld.keys(5) manual pages. 🔑

info on the client is in the bwctl(1) manual page. 🫶

and for more of an overview of the full functionality and architecture, see the http://software.internet2.edu/bwctl/ web site. 🌐

🎀 ACKNOWLEDGMENTS 🎀

this material is based in part on work supported by the National Science Foundation (NSF) under Grant No. ANI-0314723. 🏛️

any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the NSF. (standard disclaimer, but we respect it. 🫡)

okay that's the whole page, bestie!! 🦋✨ this one's stamped with $Date$ and it belongs to the bwctld(8) manual, so if you ever forget any of it, just man 8 bwctld and it'll all come running back. slay, stay synchronized, and don't run as root unless you meant to. 💖👑🌈

📦 where this page comes from