bwctld.conf(5)

💖 bwctld.conf — the Bandwidth Control daemon config file (bwctld.conf(5)) 💖

okay bestie, this is the File Formats Manual moment for bwctld.conf, and honestly? it's giving main character energy. buckle up 🎀

---

✨ NAME ✨

bwctld.conf — Bandwidth Control daemon configuration file 🌸

---

🦋 DESCRIPTION 🦋

so bwctld.conf is the configuration file for the bwctld(8) program. it's literally where you tell the server how to, like, be. what addresses and ports it should listen on, where it should send error messages, where it should save files — all that foundational stuff. 💅

the policy rules for bwctld are configured using the bwctld.limits file instead — the details for configuring those policies live in the bwctld.limits(5) manual page. two files, two jobs, no cap.

the format of this file is, and I quote (in vibe):

• 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. (so yes bestie, your comments still take up a line number. iconic but also rude.)
• 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. vibes only.
• 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 👑

okay here's the whole menu, no skips, no "etc." — every single one is right here 🫶

• access_priority priority — the syslog priority to log access messages.
  • Default: LOG_INFO
• allow_unsync — directs bwctld to continue accepting valid requests for throughput tests when the system clock is not synchronized. bwctld prefers to have an NTP synchronized system clock to ensure the two endpoints of the test are actually agreeing to the same scheduled time window for test execution. This option is used to bypass this requirement for systems that either do not have the NTP system calls, or prefer not to configure NTP.
  • > 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.)
  • 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 — syslog facility to log messages.
  • 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. (devs love this one, fr fr 🐛)
  • 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 that's part 1 bestie, don't go anywhere, there's more 💜

• owamp_port owampport — the port number(s) that Owamp receivers get to use 💅 rn bwctld just walks through this range in a straight line, no cap. Gotta be a range, written as low-high, and it's non-negotiable: two valid port numbers with a - between them, and zero whitespace inside it. So 5001-5004 = valid, 5001 - 5004 = absolutely not, bestie 🙈

You must give a range here because this value does double duty — it's used for both the Owamp communication ports and the test ports.

Default:

unset

• peer_port 0 | lowport-highport — the port range used on the local host for peer connections to other bwctld servers 🫶 these connections verify clock timing between servers and swap test results around. It's a required part of the protocol BWCTL uses to run tests, but this option lets sysadmins pin those connections to a specific port range, which is what makes BWCTL work inside a firewall ✨

Two ways to write it:

1. 0 — meaning bwctld lets the system pick the port (ephemeral, whatever it wants 💁)
2. a range — lowport has to be a smaller value than highport, and both have to be valid port values (16-bit unsigned integer values, iykyk)

Default:

0

• ping_cmd pingcmd — the path to the ping command on your system. If ping_cmd has no / character in it, then the PATH of the bwctl environment gets searched to find the ping executable 🦋

Default:

ping

• ping6_cmd ping6cmd — same energy, but for ping6 🌈 if ping6_cmd has no / in it, 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 every single bwctl session wraps up 🎀 these hooks are for saving results into a database, tracking usage, or literally any other task you want. Stack as many as your heart desires by including multiple post_hook entries, periodt.
• priority priority — the Syslog priority used to log error messages.

Default:

LOG_ERR

• root_folly — turns off the checks that disable bwctld when it's running with root permissions 💀 yes there are legitimate reasons to run bwctld as root, but it's risky. Forcing this extra option makes it less likely that root permissions get used by accident.

Default:

unset

• src_node nodename:port — the address and port bwctld listens on for requests 👑 nodename can be a DNS name or the textual representation of the address. You can set just the source address without a port by leaving off the : and the port spec entirely. And if you're giving an IPv6 address, heads up: the accepted format puts the nodename in square brackets, like [fe80::fe9f:62d8] — that keeps the port number distinct from the address spec 💖

Default:

nodename is wildcarded as any currently available address
port is 4823

• sync_fuzz syncfuzz — this value gets added onto the NTP error estimates to make bwctld more tolerant of incomplete NTP configurations, or of the case where the NTP system calls just aren't available 😭 if NTP is unavailable to bwctld, it assumes the clock is accurate to within one second plus the value of sync_fuzz. Specified as a floating point number in seconds — e.g. to say the system is synchronized within one second, you'd specify this option as 1.0 ⭐

Practically speaking, this option 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 something else sets it via one of the other port variables 💅 rn bwctld cycles through this range linearly. test_port must be a range written as low-high: two valid port numbers with a - between them. Whitespace is not allowed inside the test_port. So 5001-5004 = valid, 5001 - 5004 = invalid 🙅

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

Default:

5001-5900

• thrulay_port thrulayport — the port number(s) that Thrulay receivers will use 🦋 rn bwctld cycles through this range linearly. thrulay_port can be a single valid port number, or a range written as low-high — two valid port numbers with a - between them. No whitespace inside the thrulay_port, so 5001-5004 is valid and 5001 - 5004 is not.

You should set this one to a range, because a port can take a few minutes to become free after a test has run — and if the port isn't free when the next test starts, the test fails 😭 with a range, the daemon cycles through them when starting tests, decreasing the chance that a port is still open when the test starts. For best results, make sure this range is different from the one used by iperf_port and nuttcp_port ✨

Default:

unset

• tracepath_cmd tracepathcmd — the path to the tracepath command on the system. If tracepath_cmd contains no /, 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. No / in tracepath6_cmd? Then the PATH of the bwctl environment gets searched for the tracepath6 executable 💜

Default:

tracepath6

• traceroute_cmd traceroutecmd — the path to the traceroute command on the system. If traceroute_cmd has no /, the PATH of the bwctl environment is searched to find the traceroute executable 🎀

Default:

traceroute

• traceroute6_cmd traceroute6cmd — the path to the traceroute6 command on the system. If traceroute6_cmd has no /, the PATH of the bwctl environment is searched to find the traceroute6 executable 🧚

Default:

traceroute6

• user user — the uid the bwctld process should run as 👑 user can be a valid user name on the system, or you can use -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 — no exceptions 💅

Default:

unset

• var_dir vardir — the directory path where the bwctld.pid file gets placed.

Default:

Current directory

---

🌈 SEE ALSO 🌈

bwctl(1), bwctld(8), bwctld.limits(5), bwctld.keys(5), and the http://software.internet2.edu/bwctl/ web site 🫶

For the tea on Iperf3, hit up the https://github.com/esnet/iperf web site 💖

For details on Iperf, see the http://sourceforge.net/projects/iperf web site ✨

For details on Nuttcp, see the http://www.wcisd.hpc.mil/nuttcp/Nuttcp-HOWTO.html web site 🦋

For details on Owamp, see the http://software.internet2.edu/owamp 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 🌈

---

and that's the whole page, bestie 💅 this little masterpiece is from the bwctld.conf(5) manual, dated 2008-10-09 — yes, that date, 12:27:47 -0400 on a Thursday, iconic behavior honestly. go configure something beautiful 🎀✨