table of contents
bwctld.limits(5) | File Formats Manual | bwctld.limits(5) |
NAME¶
bwctld.limits - Bandwidth Control daemon policy configuration fileDESCRIPTION¶
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?
- •
- 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.
- 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
limit jail with \
parent=root, \
allow_udp=off, \
allow_tcp=off, \
allow_open_mode=off
limit open with \
parent=root, \
allow_open_mode=on, \
allow_udp=off, \
allow_tcp=on, \
duration=30, \
event_horizon=300, \
pending=5
# 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.$Date: 2009-02-23 08:08:04 -0500 (Mon, 23 Feb 2009) $ |