bwctld.limits(5) | File Formats Manual | bwctld.limits(5) |
bwctld.limits - Bandwidth Control daemon policy configuration file
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:
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:
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) |
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:
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.
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.
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.
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.
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$ |