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

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 individual  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 connection 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 userclass 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  '\'  character  followed
                     immediately  by  a  newline.  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 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 identities 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 userclass.

              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 userclass.

       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 network.

                     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 specified, this must be the
       first  userclass  defined in the file. This userclass has very liberal limits (UDP enabled
       with 900m limit). However, open mode authentication is not enabled for this userclass,  so
       the connections 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). Additionally,  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@internet2.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 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$                             bwctld.limits(5)