Internet2

Bandwidth Test Controller (BWCTL)

About    |    Downloads      |     Manual Pages     |     Cookbook (PDF)    |    License

bwctld(8)							     bwctld(8)



NAME
       bwctld - Bandwidth Control server.

SYNOPSIS
       bwctld  [  -a  auth_mode	 ] [ -c conf_dir ] [ -e facility ] [ -f ] [ -G
       group ] [ -h ] [ -R var_dir ] [ -S nodename:port ] [ -U user ] [ -v ] [
       -Z ]

DESCRIPTION
       bwctld  is a server program designed to schedule and run Iperf, Thrulay
       or Nuttcp, Ping, Traceroute, Tracepath, and Owamp tests.

       Aside from actually running network measurement tests, the  main	 func-
       tion of bwctld is to determine which tests are allowable based upon the
       policy restrictions configured by the system administrator.

       bwctld was designed to be run as a stand-alone daemon process. It  uses
       the classic accept/fork model of handling new requests.

       Most  of	 the command line options for bwctld have analogous options in
       the bwctld.conf file. The command line takes precedence.

OPTIONS
       -a auth_mode
	      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".

       -c conf_dir
	      Specify the directory that holds the bwctld configuration files.

	      Default:
		     Current working directory.

       -e facility
	      Syslog facility to which messages are logged.

	      Default:
		     LOG_DAEMON

       -f     Enables the bwctld daemon to 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.

       -G group
	      Specify  the  gid for the bwctld process. group can be specified
	      using a valid group name or by using -gid. This option  is  only
	      used if bwctld is started as root.

       -h     Print a help message.

       -R var_dir
	      Specify the directory to hold the bwctld.pid file.

	      Default:
		     Current directory

       -S 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  simply  by  leaving
	      off the ’:’ and port specification. If an IPv6 address is speci-
	      fied, note that the accepted format contains nodename in	square
	      brackets, such as: [fe80::fe9f:62d8]. This ensures the port num-
	      ber is distinct from the address specification.

	      Default:
		     nodename  is  wildcarded  as  any	 currently   available
		     address.  port is 4823.

       -U user
	      Specify  the  uid	 for the bwctld process. user can be specified
	      using a valid user name or by using -uid. This  option  is  only
	      used if bwctld is started as root.

       -v     Set  verbose  output. Messages will only go to syslog unless the
	      -Z option is specified.

       -Z     Run the master bwctld process in the foreground. In  this	 mode,
	      error  messages  are  printed to stderr as well as being sent to
	      syslog. Also, normal terminal  controls  are  available.	(i.e.,
	      	will cause the daemon to kill it’s child processes and
	      exit.) This is useful for debugging.


REQUIREMENTS
       The bwctld daemon  prefers  a  reasonably  synchronized	clock.	It  is
       scheduling  tests  and  needs to be sure it has the same idea of when a
       test should take place as does the peer test system.  Therefore, bwctld
       attempts	 to use NTP specific system calls to determine the accuracy of
       the local clock. If those system calls are unavailable, or the adminis-
       trator  has  set	 the allow_unsync option in the bwctld.conf file, then
       bwctld will blindly accept tests assuming the clock is synchronized  to
       within  the  sync_fuzz  value  that  is also defined in the bwctld.conf
       file. If this assumption does not hold true, then the test will eventu-
       ally  fail.  Unfortunately,  because  the  time	offset is not detected
       early, this test will have taken up a schedule slot.

FILES
       bwctld.pid
       bwctld.conf
       bwctld.limits
       bwctld.keys

SEE ALSO
       There are  more	details	 on  configuring  the  bwctld  daemon  in  the
       bwctld.conf(5) manual page. Details on configuring the policy is in the
       bwctld.limits(5) and bwctld.keys(5) manual pages.  Information  on  the
       client  is in the bwctl(1) manual page.	For more of an overview of the
       full	 functionality	    and	      architecture	 see	   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 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$			     bwctld(8)