bwctlrc - Bandwidth Control
configuration file
The bwctlrc file is a configuration file for the bwctl(8)
program. If a test is requested using bwctl, and there is not a local
bwctld(8) running, bwctl will spawn its own copy of bwctld. This
configuration file is used to configure the basic operation of the
automatically spawned server. For example, it can be used to configure
whether to allow the local clock to be unsynchroznied, or where the iperf
command is located.
This file can be placed in ~/.bwctlrc, where it will be
automatically read by bwctl when it spawns off a bwctld. If the file is put
elsewhere, the BWCTLRC environmental variable can be set to the path to the
file and bwctl will read it.
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.
- access_priority
priority
- Syslog priority to log access messages.
- 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.
- 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.
- disable_iperf
- Prevent bwctl from executing Iperf tests
- disable_iperf3
- Prevent bwctl from executing Iperf3 tests
- disable_nuttcp
- Prevent bwctl from executing Nuttcp tests
- disable_owamp
- Prevent bwctl from executing Owamp tests
- disable_ping
- Prevent bwctl from executing Ping tests
- disable_tracepath
- Prevent bwctl from executing Tracepath tests
- disable_traceroute
- Prevent bwctl from executing Traceroute tests
- facility
facility
- Syslog facility to log messages.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- owamp_port
owampport
- The port number(s) that Owamp receivers will use. Currently,
bwctld simply cycles through this range linearly. owamp_port
must be specified 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 owamp_port. For example,
"5001-5004" would be valid, but "5001 -
5004" would be invalid.
This value must be set to a range because it is used for both the
Owamp communication and test ports.
- Default:
- unset
- peer_port
0 | lowport-highport
- Specify the port range that will be used on the local host for peer
connections to other bwctld servers. These connections are used to
verify clock timing between the servers and to exchange test results. This
is a required part of the protocol used by BWCTL to run tests.
However, this option allows system administrators to limit these
connections to a specific port range, which should allow BWCTL to
work in a firewall environment. This option can be specified in two ways.
First, as a 0, which would indicate that bwctld should allow the
system to pick the port (ephemeral). Second, as a range. lowport
must be a smaller value than highport and both numbers must be
valid port values. (16-bit unsigned integer values)
- ping_cmd
pingcmd
- The path to the ping command on the system. If the ping_cmd
does not contain a '/' character, then the PATH of the bwctl
environment will be searched to find the ping executable.
- ping6_cmd
ping6cmd
- The path to the ping6 command on the system. If the
ping6_cmd does not contain a '/' character, then the PATH of the
bwctl environment will be searched to find the ping6
executable.
- post_hook
/path/to/script
- Specifies a script to run after each bwctl session has finished. These
hooks can be used to save the results into a database, track usage or any
number of other tasks. You can specify as many hooks as you want by
including multiple post_hook entries.
- priority
priority
- Syslog priority to log error messages.
- root_folly
- 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 root permissions are accidently used.
- src_node
nodename:port
- Specify the address and port on which bwctld will listen for
requests. nodename can be specified using a DNS name or using the
textual representation of the address. It is possible to set the source
address without setting the port by simply leaving off the ':' and
port specification. If an IPv6 address is specified, note that the
accepted format contains nodename in square brackets as:
[fe80::fe9f:62d8]. This ensures the port number is distinct from the
address specification.
- Default:
- nodename is wildcarded as any currently available address
port is 4823
- sync_fuzz
syncfuzz
- This value is added to the NTP error estimates to increase the tolerance
of bwctld to incomplete NTP configurations, or if the NTP system
calls are not available. If NTP is unavailable to bwctld it assumes
the clock is accurate to within one second plus the value of
sync_fuzz. This option is specified as a floating point number in
seconds. For example, to indicate that the system is synchronized within
one second, you could specify this option as 1.0.
Practically, this option is used to determine 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
otherwise set using one of the other port variables. Currently,
bwctld simply cycles through this range linearly. test_port
must be specified 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 test_port. For example,
"5001-5004" would be valid, but "5001 -
5004" would be invalid.
This value must be set to a range because it is used for both the
Owamp communication and test ports.
- Default:
- 5001-5900
- thrulay_port
thrulayport
- The port number(s) that Thrulay receivers will use. Currently,
bwctld simply cycles through this range linearly.
thrulay_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 thrulay_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
nuttcp_port.
- Default:
- unset
- tracepath_cmd
tracepathcmd
- The path to the tracepath command on the system. If the
tracepath_cmd does not contain a '/' character, then the PATH of
the bwctl environment will be searched to find the tracepath
executable.
- tracepath6_cmd
tracepath6cmd
- The path to the tracepath6 command on the system. If the
tracepath6_cmd does not contain a '/' character, then the PATH of
the bwctl environment will be searched to find the
tracepath6 executable.
- traceroute_cmd
traceroutecmd
- The path to the traceroute command on the system. If the
traceroute_cmd does not contain a '/' character, then the PATH of
the bwctl environment will be searched to find the
traceroute executable.
- traceroute6_cmd
traceroute6cmd
- The path to the traceroute6 command on the system. If the
traceroute6_cmd does not contain a '/' character, then the PATH of
the bwctl environment will be searched to find the
traceroute6 executable.
- user
user
- Specifies the uid the bwctld process should run as. user can
be specified using a valid user name on the system or by using -uid. This
option is only used if bwctld is started as root. If the given
user has root permissions, the root_folly option must
also be specified.
- var_dir
vardir
- Directory path where the bwctld.pid file will be placed.
bwctl(1), bwctld(8), bwctld.limits(5), bwctld.keys(5), and the
http://software.internet2.edu/bwctl/ web site.
For details on Iperf3, see 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.
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.