Ubuntu Manpage: bwctld.conf - Bandwidth Control daemon configuration file

Provided by: bwctl-server_1.4.1~rc2-1_amd64

NAME

       bwctld.conf - Bandwidth Control daemon configuration file

DESCRIPTION

       The  bwctld.conf  file  is  the configuration file for the bwctld(8) program. 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:

              •      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:
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.

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:
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

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.

Default:
5001

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

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

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.

Default:
5003

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

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) $               bwctld.conf(5)

NAME

DESCRIPTION

CONFIGURATION OPTIONS

SEE ALSO

ACKNOWLEDGMENTS