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

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)