Internet2

Bandwidth Test Controller (BWCTL)

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

bwctld.limits(5)					      bwctld.limits(5)



NAME
       bwctld.limits - Bandwidth Control daemon policy configuration file

DESCRIPTION
       The  bwctld.limits  file is used to define the policy configuration for
       the bwctld program. It allows the system administrator to allocate  the
       resources in a variety of ways.

       There are two parts to the policy configuration:

       Authentication
	      Who is making the request? This can be very specific to an indi-
	      vidual user or it can be more general in that the connection  is
	      coming from some particular network.

       Authorization
	      Now that the connection has been generally identified, what will
	      bwctld allow it to do?

       The authentication is done by assigning a userclass to each new connec-
       tion as it comes in. Each userclass has a set of limits associated with
       it. The userclasses are hierarchical, so a  connection  must  pass  the
       limit  restrictions  of	the  given  userclass  as  well	 as all parent
       classes.

       Within the bwcltd.limits file, assign lines are used to assign a	 user-
       class to a given connection. limit lines are used to define a userclass
       and set the limits associated with that userclass.  The	file  is  read
       sequentially,  and  it is not permitted to use a classname before it is
       defined using a limit line.

       The format of this file is:

	      ·	     Comment lines are any line where the first non-whitespace
		     character is ’#’.	These lines are counted to return 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. This is the only
		     valid  place  for the ’\’ character. If it is found else-
		     where a syntax error is reported.

	      ·	     Blank lines are treated as comment lines.

	      ·	     All other lines must conform to the  syntax  of  a	 limit
		     line or an assign line.

CONFIGURATION OPTIONS
       limit  This  directive  is  used	 to define the userclass hierarchy. It
	      defines the classname as well as the limits associated with that
	      class.  A	 classname may only be defined once. The format of the
	      limit directive is:

	      limit classname with limtype=value[,limtype=value]*

	      classname defines the name of the class with the	given  limits.
	      Whitespace  is  used  as	a  separator but is otherwise ignored.
	      classname may be used  as	 a  directory  name  component	within
	      bwctld,  so  take	 care  not  to	use  characters	 that would be
	      invalid. (i.e. ’*’ or ’/’ would be particularly bad.)

	      limtype and value indicate the  particular  type	of  limit  and
	      value  to	 apply	to  this userclass. The available settings for
	      limtype are:


	      ---------------------------------------------------------------
	      limtype		valid values		       default
	      allow_open_mode	on/off			       on
	      allow_tcp		on/off			       on
	      allow_udp		on/off			       off
	      bandwidth		integer (b/s)		       0 (unlimited)
	      duration		integer (seconds)	       0 (unlimited)
	      event_horizon	integer (seconds)	       0 (unlimited)
	      max_time_error	integer (seconds)	       0 (unlimited)
	      parent		previously defined classname   null
	      pending		integer			       0 (unlimited)

	      allow_open_mode
		     This limit is only useful if the class is assigned	 to  a
		     netmask.  It is used to limit specific IP/netmask identi-
		     ties to only encrypted or authenticated mode transactions
		     or to allow open mode.

	      allow_tcp
		     Allow TCP Iperf tests for userclass.

	      allow_udp
		     Allow UDP Iperf tests for userclass.

	      bandwidth
		     Maximum  amount of bandwidth to allow userclass to use in
		     a UDP Iperf test.	0 indicates unlimited by  policy,  but
		     remember  this  is checked all the way to the root of the
		     hierarchy. (If you want an unlimited userclass, your root
		     must  be  unlimited, and the whole path down to the given
		     userclass.)

	      duration
		     Maximum duration of a single Iperf test  for  this	 user-
		     class.

	      event_horizon
		     Maximum  window  into  the	 future to look when trying to
		     schedule a test for this userclass.

	      max_time_error
		     Maximum amount of time error to allow for tests  in  this
		     class.  The  time error is the sum of the errors reported
		     by NTP on the two involved systems.  The larger the  time
		     error, the larger the duration of the reservation because
		     the time error is used to	ensure	tests  don’t  overlap.
		     There  is	a  limit on this to defend against DOS attacks
		     where a client could report large errors to ensure	 other
		     clients can not allocate test reservations.

	      parent The first limit line cannot have a parent since none have
		     been defined yet. As such, the  first  line  defines  the
		     root  of your class hierarchy.  All remaining limit lines
		     MUST assign a parent.  (It is hierarchical, after all.)

	      pending
		     Maximum number of pending	reservations  for  this	 user-
		     class.

       assign The  assign  directive  is used to assign a userclass to a given
	      connection. Basically, it	 authenticates	the  connection.   The
	      format of the assign directive is:

	      assign authtype [args] classname

	      authtype	identifies  the	 type  of  authentication  being used.
	      Whitespace is used as a  separator  but  is  otherwise  ignored.
	      classname	 must  have  been  previously  defined	with the limit
	      directive earlier in the file.

	      The available settings for authtype are:

	      default
		     Used if no other assignment matches. It takes no args.

	      net subnet
		     Assign a specific subnet to a  given  userclass.	subnet
		     must  be  specified  using VLSM notation (IP/nbits).  The
		     only arg is the subnet.  For example:

		     127.0.0.1/32
			     would match only the loopback IPv4 address.

		     ::1/128
			     would match only the loopback IPv6 address.

		     192.168.1.0/24
			     would match all hosts on the  192.168.1.XXX  net-
			     work.

		     There  must  be  no set bits in the non-masked portion of
		     the address  part	of  the	 subnet	 specification.	 i.e.,
		     192.168.1.1/24  would be an invalid subnet due to the bit
		     set in the fourth octet.

	      user user
		     Assign a specific user to a given	userclass.   The  user
		     must be defined in the bwctld.keys file.

AUTHENTICATION PROCESS
       bwctld determines if it should allow a connection from the client based
       upon the authentication mode of the request and the source  IP  address
       of  the	connection.  If	 the  client connection is in authenticated or
       encrypted mode, the daemon does not do any  filtering  based  upon  the
       source  address	of the connection. (See the -A option to bwctl and the
       authmode option in bwctld.conf.)	 In these modes,  bwctld  simply  uses
       the  identity  of  the connection to determine the userclass limits. If
       the connection is made in open mode,  then bwctld first uses the source
       address	to  determine  if  bwctld should allow an open mode connection
       from that subnet at all. (This is the purpose  of  the  allow_open_mode
       limtype	described  above.)   If open mode is allowed from this subnet,
       then the userclass is determined by the closest subnet match defined by
       the assign net lines in the bwctld.limits file.

EXAMPLES
       An initial limit line might look like:

	      limit root with \
		     bandwidth=900m, \
		     duration=0, \
		     allow_udp=on, \
		     allow_tcp=on, \
		     allow_open_mode=off

       This  would  create a userclass named root. Because no parent is speci-
       fied, this must be the first userclass defined in the file. This	 user-
       class  has  very liberal limits (UDP enabled with 900m limit). However,
       open mode authentication is not enabled for this userclass, so the con-
       nections	 that get these limits must successfully authenticate using an
       AES key.

       If an administrator also wants to create a userclass that  is  used  to
       deny all requests, they might add:

	      limit jail with \
		     parent=root, \
		     allow_udp=off, \
		     allow_tcp=off, \
		     allow_open_mode=off

       This  would  create  a  userclass named jail. Because UDP and TCP tests
       have both been denied, no tests will be allowed. Also,  allow_open_mode
       is  off,	 so  initial  connections  that	 are  not  in authenticated or
       encrypted mode would be dropped immediately anyway.  (It would not make
       much  sense  to	assign a user identity to this userclass. If you don’t
       want connections from a particular user, the best thing	to  do	is  to
       remove that user from the bwctld.keys file.

       If  the	administrator  wanted to allow a limited amount of open tests,
       they could define a userclass like:

	      limit open with \
		     parent=root, \
		     allow_open_mode=on, \
		     allow_udp=off, \
		     allow_tcp=on, \
		     duration=30, \
		     event_horizon=300, \
		     pending=5

       This could be used to allow TCP throughput tests by random connections.
       It  limits  those tests to 30 seconds in duration, and only allows them
       to be scheduled within the next 5  minutes  (event_horizon=300).	 Addi-
       tionally,  it  only  allows  this userclass to have 5 currently pending
       reservations. This ensures that this userclass can only schedule 50% of
       the  next  5  minutes.  The advantage of this kind of setup is that the
       administrator can define other userclasses with a larger	 event_horizon
       allowing then to have priority over this class.	(Suggestions for other
       methods of priority scheduling should  be  sent	to  bwctl-users@inter-
       net2.edu.)

       Now,  these three userclasses might be assigned to specific connections
       in the following ways:

	      # default open
	      assign default open

	      # badguys subnet
	      assign net 192.168.1.0/24 jail

	      # network admins
	      assign user joe root
	      assign user jim root
	      assign user bob root

       This set of assign lines specifically denies access from any open  mode
       connection  from	 the  badguys subnet. It specifically allows access to
       authenticated or encrypted mode transactions that can  authenticate  as
       the identities joe jim or bob (even from the badguys subnet). All other
       connections would match the assign default  rule	 and  get  the	limits
       associated with the open userclass.

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  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.limits(5)