|
Bandwidth Test Controller (BWCTL)
|
|
bwctld.conf(5) Manual Page
bwctld.conf(5) bwctld.conf(5)
NAME
bwctld.conf - Bandwidth Control daemon configuration file
DESCRIPTION
The bwctld.conf file is the configuration file for the bwctld(8) pro-
gram. It is used to configure the basic operation of the server. For
example, what addresses and ports it should listen on, where it should
send error messages, and where it should save files.
The policy rules for bwctld are configured using the bwctld.limits
file; the details for configuring those policies are described in the
bwctld.limits(5) manual page.
The format of this file is as follows:
? Comment lines are any line where the first non-whitespace
character is '#'. These lines are counted for the pur-
poses of returning line numbers in error messages but are
otherwise ignored by bwctld.
? Lines may be continued using the semi-standard '\' char-
acter 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 through-
put 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 sys-
tem 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 connec-
tion.
E [E]ncrypted. This mode encrypts the control connection.
If the test supports encryption, this mode will addition-
ally encrypt the test stream. (Encryption of the test
stream is not currently supported, so this mode is cur-
rently 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 speci-
fied, 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)
data_dir datadir
Directory path where output data files will be placed. (bwctld
does not currently save the results of the Iperf tests. This
option is a place holder for when it does.)
Default:
Current directory
die_by dieby
Number of seconds to wait for child processes to gracefully ter-
minate before killing them with SIGKILL. This is in response to
the master process receiving SIGTERM or SIGHUP.
Default:
30
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.
Default:
5001
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
peer_ports 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 at least allows system
administrators to limit these connections to a specific port
range which should allow BWCTL to work in a firewall environ-
ment. 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
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 that bwctld will listen for
requests on. 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
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
verbose
If this option is present, it directs the bwctld process to gen-
erate more verbose messages to syslog.
Default:
unset
SEE ALSO
bwctl(1), bwctld(8), bwctld.limits(5), bwctld.keys(5), and the
http://e2epi.internet2.edu/bwctl/ web site.
For details on Iperf, see the http://dast.nlanr.net/Projects/Iperf/ web
site.
ACKNOWLEDGMENTS
This material is based in part on work supported by the National Sci-
ence Foundation (NSF) under Grant No. ANI-0314723. Any opinions, find-
ings 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: 2005/09/07 23:36:18 $ bwctld.conf(5)
Man(1) output converted with
man2html
|
|
| Bandwidth Test Controller (BWCTL) |
16 February, 2004 |
|
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.
|
|
