Provided by: bwctl-server_1.5.4+dfsg1-1build1_amd64 bug

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