bwctld.limits
Section: File Formats (5)
Updated: $Date: 2009-02-23 08:08:04 -0500 (Mon, 23 Feb 2009) $
Index
Return to Main Contents
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:
| |
|
|
|
|
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://e2epi.internet2.edu/bwctl/ 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 Thrulay, see the http://e2epi.internet2.edu/thrulay/
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.
Index
- NAME
-
- DESCRIPTION
-
- CONFIGURATION OPTIONS
-
- AUTHENTICATION PROCESS
-
- EXAMPLES
-
- SEE ALSO
-
- ACKNOWLEDGMENTS
-
This document was created by
man2html,
using the manual pages.
Time: 22:37:06 GMT, May 19, 2010