bwctlrc(5)

📦 version 1.5.4, in ubuntu jammy

okay so like, this is bwctlrc(5) — it hangs out in the File Formats Manual part of the man pages, and it's literally the whole vibe guide for the Bandwidth Control config file. buckle up bestie, there's a lot here and it's all important 💅

🌸 NAME 🌸

bwctlrc — the Bandwidth Control configuration file. that's the name. iconic. periodt ✨

🦋 DESCRIPTION 🦋

okay so bwctlrc is the config file for the bwctl(8) program. here's the tea: when you ask for a test using bwctl, and there's no local bwctld(8) running, bwctl will just spawn its own lil copy of bwctld all by itself 🫶. this config file is what configures the basic operation of that automatically spawned server. like, for example, it can configure whether to allow the local clock to be unsynchronized, or where the iperf command is located. super practical, no cap 💖

this file can be placed in ~/.bwctlrc, and then it'll be automatically read by bwctl when it spawns off a bwctld. if you put the file somewhere else instead, you can set the BWCTLRC environmental variable to the path to the file, and bwctl will read it from there 🌈

the format of this file is:

  • comment lines are any line where the first non-whitespace character is '#'. these lines are counted for the purposes of returning line numbers in error messages, but are otherwise ignored by the spawned bwctld 👀
  • lines may be continued using the semi-standard '\' character followed immediately by a newline character. this is the only valid place for the '\' character. if it is found elsewhere, a syntax error is reported 💀
  • blank lines are treated as comment lines 🎀
  • all other lines are used to set configuration options. the format of these lines is an initial keyword followed by a variable list of arguments, separated by whitespace ✨

👑 CONFIGURATION OPTIONS 👑

  • access_priority priority — the syslog priority to log access messages with.
    • Default: LOG_INFO
  • allow_unsync — directs bwctld to keep accepting valid requests for throughput tests even when the system clock is not synchronized 🕰️. bwctld prefers to have an NTP synchronized system clock, because that's what makes sure the two endpoints of the test are actually agreeing to the same scheduled time window for test execution. this option is used to bypass that requirement for systems that either don't have the NTP system calls, or just prefer not to configure NTP. no judgment 💜
    • Note: if the difference between the system clocks on the two endpoints is too great, the eventual throughput test will fail when the endpoints attempt to run the test at different times 😭. the threshold for this difference is controlled using the sync_fuzz option. (if you set allow_unsync, you should set sync_fuzz to a reasonable value for your system.)
    • Default: unset (set if the operating system does have the NTP system calls)
  • auth_mode authmode — specify the authentication modes the server is willing to use for communication. auth_mode should be set as a character string, with any or all of the characters "AEO". the modes are:
    • A — [A]uthenticated. this mode encrypts the control connection 🔐
    • E — [E]ncrypted. this mode encrypts the control connection. if the test supports encryption, this mode will additionally encrypt the test stream. (encryption of the test stream is not currently supported, so this mode is currently identical to authenticated. yeah. we know. 🙈)
    • O — [O]pen. no encryption of any kind is done 🫥
    • the server can specify all the modes with which it is willing to communicate. the most strict mode that both the server and the client are willing to use will be selected 👑
    • Default: "AEO"
  • bottleneck_capacity bottleneckcapacity — this value is used in the algorithm to dynamically set the TCP send/recv window sizes. this option is likely to be removed in the future once a dynamic bottleneck_capacity algorithm is incorporated into the code 💀. (this option only really works when the local NIC is the bottleneck.) if this option is not specified, the dynamic window calculation requested by the -W option to bwctl is not done, and the advisory value is used.
    • Default: unset
  • control_timeout controltimeout — number of seconds to wait for protocol messages before timing out ⏳. this value should be significantly larger than what typical users specify for the -I flag of bwctl, or bwctl will have to open a new control connection for each new test it requests 😤.
    • Default: 7200 (picked to be the same as the default for TCP keepalive)
  • die_by dieby — number of seconds to wait for child processes to gracefully terminate before killing them with SIGKILL 💀. this is in response to the master process receiving SIGTERM or SIGHUP.
    • Default: 5
  • disable_iperf — prevent bwctl from executing Iperf tests 🚫
    • Default: unset
  • disable_iperf3 — prevent bwctl from executing Iperf3 tests 🚫
    • Default: unset
  • disable_nuttcp — prevent bwctl from executing Nuttcp tests 🚫
    • Default: unset
  • disable_owamp — prevent bwctl from executing Owamp tests 🚫
    • Default: unset
  • disable_ping — prevent bwctl from executing Ping tests 🚫
    • Default: unset
  • disable_tracepath — prevent bwctl from executing Tracepath tests 🚫
    • Default: unset
  • disable_traceroute — prevent bwctl from executing Traceroute tests 🚫
    • Default: unset
  • facility facility — the syslog facility to log messages to 📝
    • Default: LOG_DAEMON
  • group group — specifies the gid the bwctld process should run as 👥. group can be specified using a valid group name on the system, or by using -gid. this option is only used if bwctld is started as root 👑.
    • Default: unset
  • iperf_cmd iperfcmd — the path to the Iperf command on the system 🛠️. if the iperf_cmd does not contain a '/' character, then the PATH of the bwctld environment will be searched to find the Iperf executable.
    • Default: iperf
  • iperf_port iperfport — the port number(s) that Iperf receivers will use 🔌. currently, bwctld simply cycles through this range linearly. iperf_port can be specified as a single valid port number, or as a range as low-high. the range must be specified as two valid port numbers with the '-' character separating them. whitespace is not allowed within the iperf_port. for example, "5001-5004" would be valid, but "5001 - 5004" would be invalid 🙅‍♀️
    • this value should be set to a range, because it can take a few minutes for a port to become free after a test has run 😮‍💨. if the port is not free when the next test starts, the test will fail. if set to a range, the daemon will cycle through them when starting tests, decreasing the chance that a port will still be open when the test starts. for best results, ensure that this range is different from that of nuttcp_port and thrulay_port ✨
    • Default: unset
  • iperf3_port iperf3port — the port number(s) that Iperf3 receivers will use 🔌. currently, bwctld simply cycles through this range linearly. iperf3_port can be specified as a single valid port number, or as a range as low-high. the range must be specified as two valid port numbers with the '-' character separating them. whitespace is not allowed within the iperf3_port. for example, "5001-5004" would be valid, but "5001 - 5004" would be invalid 🙅‍♀️
    • this value should be set to a range, because it can take a few minutes for a port to become free after a test has run 😮‍💨. if the port is not free when the next test starts, the test will fail. if set to a range, the daemon will cycle through them when starting tests, decreasing the chance that a port will still be open when the test starts. for best results, ensure that this range is different from that of nuttcp_port and thrulay_port ✨
    • Default: unset
  • log_location — directs the bwctld process to report source code file and line number information with error messages 📍. this is a particularly useful option to set when sending in messages as part of a bug report 🐛.
    • Default: unset
  • nuttcp_cmd nuttcpcmd — the path to the Nuttcp command on the system 🛠️. if the nuttcp_cmd does not contain a '/' character, then the PATH of the bwctl environment will be searched to find the Nuttcp executable.
    • Default: nuttcp
  • nuttcp_port nuttcpport — the port number(s) that Nuttcp receivers will use 🔌. currently, bwctld simply cycles through this range linearly. nuttcp_port can be specified as a single valid port number, or as a range as low-high. the range must be specified as two valid port numbers with the '-' character separating them. whitespace is not allowed within the nuttcp_port. for example, "5001-5004" would be valid, but "5001 - 5004" would be invalid 🙅‍♀️
    • this value should be set to a range, because it can take a few minutes for a port to become free after a test has run 😮‍💨. if the port is not free when the next test starts, the test will fail. if set to a range, the daemon will cycle through them when starting tests, decreasing the chance that a port will still be open when the test starts. for best results, ensure that this range is different from that of iperf_port and thrulay_port ✨
    • Default: unset
  • owamp_cmd owampcmd — the path to the owping command on the system 🛠️. if the owamp_cmd does not contain a '/' character, then the PATH of the bwctl environment will be searched to find the owping executable.
    • Default: owping
  • owamp_server_cmd owampservercmd — the path to the owampd command on the system 🛠️. if the owamp_server_cmd does not contain a '/' character, then the PATH of the bwctl environment will be searched to find the owampd executable.
    • Default: owampd

and yeah, that's the first half of the option buffet — there's literally more coming, so don't go anywhere bestie 🫶

  • owamp_port, owampport — the port number(s) that Owamp receivers are gonna use. rn bwctld literally just cycles through this range linearly, no thoughts head empty. owamp_port has to be specified as a range, written like low-high. That means two valid port numbers with the - character separating them. Whitespace is NOT allowed anywhere inside owamp_port. So "5001-5004" is valid, but "5001 - 5004" is invalid. 💀

You have to give it a range bc this value gets used for both the Owamp communication and the test ports. It's giving dual purpose bestie.

  • Default: unset
  • peer_port 0 | lowport-highport — this one sets the port range used on the local host for peer connections to other bwctld servers. Those connections are how the servers verify clock timing with each other and swap test results. It's a required part of the protocol BWCTL uses to run tests, no skipping. But this option lets system administrators limit those connections to a specific port range, which should let BWCTL work inside a firewall environment. 🫶

You can specify it two ways:

  1. As a 0 — which means bwctld should let the system pick the port (ephemeral).
  2. As a range. lowport must be a smaller value than highport, and both numbers have to be valid port values. (16-bit unsigned integer values, periodt.)
  • Default: 0
  • ping_cmd pingcmd — the path to the ping command on the system. If ping_cmd does not contain a / character, then the PATH of the bwctl environment gets searched to find the ping executable. iykyk.
    • Default: ping
  • ping6_cmd ping6cmd — the path to the ping6 command on the system. If ping6_cmd does not contain a / character, then the PATH of the bwctl environment gets searched to find the ping6 executable. ✨
    • Default: ping6
  • post_hook /path/to/script — names a script to run after each bwctl session has finished. These hooks are iconic for saving results into a database, tracking usage, or literally any number of other tasks. You can specify as many hooks as you want by including multiple post_hook entries. stack them like bracelets 💅
  • priority priority — the syslog priority used to log error messages.
    • Default: LOG_ERR
  • root_folly — this one disables the checks that disable bwctld if it is run with root permissions. There are legitimate reasons to run bwctld as root, but it is risky. Forcing this additional option will make it less likely that root permissions are accidentally used. So like… be so serious when you touch this one. 🙈
    • Default: unset
  • src_node nodename:port — specify the address and port that bwctld will listen on for requests. nodename can be given as a DNS name or as the textual representation of the address. You can totally set just the source address without the port by simply leaving off the : and the port specification. 🎀

If you're specifying an IPv6 address, note that the accepted format puts nodename in square brackets, like this: [fe80::fe9f:62d8]. That's so the port number stays distinct from the address specification. no cap.

  • Default: nodename is wildcarded as any currently available address, and port is 4823
  • sync_fuzz syncfuzz — this value gets added to the NTP error estimates to make bwctld more tolerant of incomplete NTP configurations, or of NTP system calls just not being available. If NTP is unavailable to bwctld, it assumes the clock is accurate to within one second plus the value of sync_fuzz. 🌸

Specify it as a floating point number in seconds. For example, to say the system is synchronized within one second, you'd specify this option as 1.0.

Practically speaking, this option is what determines the size of the time window buffer before and after each throughput test.

  • Default: 0.0
  • test_port testport — the port number(s) that receivers of all test types will use, unless it's otherwise set using one of the other port variables. rn bwctld just cycles through this range linearly. test_port must be specified as a range, written as low-high. Two valid port numbers, - character separating them. No whitespace inside test_port. "5001-5004" is valid, "5001 - 5004" is invalid. 💀

This value must be set to a range because it's used for both the Owamp communication and test ports.

  • Default: 5001-5900
  • thrulay_port thrulayport — the port number(s) that Thrulay receivers will use. rn bwctld just cycles through this range linearly. thrulay_port can be specified as a single valid port number, or as a range written as low-high. Two valid port numbers, - separating them. No whitespace inside thrulay_port. "5001-5004" valid, "5001 - 5004" invalid. 🙅

You should set this to a range, because it can take a few minutes for a port to become free after a test has run. If the port isn't free when the next test starts, the test will fail. If it's set to a range, the daemon cycles through them when starting tests, which decreases the chance that a port will still be open when the test starts. For best results, make sure this range is different from the one for iperf_port and nuttcp_port. 👑

  • Default: unset
  • tracepath_cmd tracepathcmd — the path to the tracepath command on the system. If tracepath_cmd doesn't contain a / character, then the PATH of the bwctl environment gets searched to find the tracepath executable.
    • Default: tracepath
  • tracepath6_cmd tracepath6cmd — the path to the tracepath6 command on the system. If tracepath6_cmd doesn't contain a / character, then the PATH of the bwctl environment gets searched to find the tracepath6 executable.
    • Default: tracepath6
  • traceroute_cmd traceroutecmd — the path to the traceroute command on the system. If traceroute_cmd doesn't contain a / character, then the PATH of the bwctl environment gets searched to find the traceroute executable.
    • Default: traceroute
  • traceroute6_cmd traceroute6cmd — the path to the traceroute6 command on the system. If traceroute6_cmd doesn't contain a / character, then the PATH of the bwctl environment gets searched to find the traceroute6 executable.
    • Default: traceroute6
  • user user — specifies the uid the bwctld process should run as. user can be given as a valid user name on the system, or by using -uid. This option is only used if bwctld is started as root. And if the given user has root permissions, the root_folly option must also be specified. 😭
    • Default: unset
  • var_dir vardir — directory path where the bwctld.pid file will be placed. that's it, that's the whole job 🍓
    • Default: Current directory

🌈 SEE ALSO ✨

💖 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. 💜

okay bestie that's the whole page, we did it 🎉 this version is dated 2008-10-09 12:27:47 -0400 (Thu, 09 Oct 2008) and it's the bwctlrc(5) man page — go forth and configure responsibly, mwah 💅✨

📦 where this page comes from