|
Bandwidth Test Controller (BWCTL)
|
|
bwctld.limits(5) Manual Page
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)
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.
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://e2epi.internet2.edu/bwctl/ web site.
For details on Iperf, see the http://dast.nlanr.net/Projects/Iperf/ 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: 2004/03/10 13:55:37 $ bwctld.limits(5)
Man(1) output converted with
man2html
|
|
| Bandwidth Test Controller (BWCTL) |
16 February, 2004 |
|
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.
|
|
