Ubuntu Manpage: bwctld.limits - Bandwidth Control daemon policy configuration file

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

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.

ACKNOWLEDGMENTS