Provided by: bwctl-server_1.5.4+dfsg1-1_amd64 
NAME
bwctlrc - Bandwidth Control configuration file
DESCRIPTION
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.
CONFIGURATION OPTIONS
access_priority priority
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.
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
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)
Default:
0
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.
Default:
ping
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.
Default:
ping6
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.
Default:
LOG_ERR
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.
Default:
unset
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.
Default:
tracepath
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.
Default:
tracepath6
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.
Default:
traceroute
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.
Default:
traceroute6
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.
Default:
unset
var_dir vardir
Directory path where the bwctld.pid file will be 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 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.
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.
$Date: 2008-10-09 12:27:47 -0400 (Thu, 09 Oct 2008) $ bwctlrc(5)