BWCTL Version 1.4

(Bandwidth Control)
http://e2epi.internet2.edu/bwctl/
$Date: 2012-04-18 10:23:11 -0400 (Wed, 18 Apr 2012) $
BWCTL is a command line client application and a scheduling and policy daemon that wraps the throughput testing tools Iperf, Thrulay, and Nuttcp. These tests can measure maximum TCP bandwidth, with various tuning options available, or, by doing a UDP test, the delay, jitter, and datagram loss of a network.

The bwctl client application works by contacting a bwctld process on the two test endpoint systems. BWCTL will work as a 3-party application. The client can arrange a test between two servers on two different systems. If the local system is intended to be one of the endpoints of the test, bwctl will detect whether a local bwctld is running and will handle the required server functionality if needed. bwctld manages and schedules the resources of the host on which it runs. A more detailed description of the architecture is available in the architecture documentation.

The bwctl client is used to request the type of throughput test wanted. Furthermore, it requests when the test should be executed. bwctld either responds with a tentative reservation or a test denied message. Once bwctl is able to get a matching reservation from both bwctld processes (one for each host involved in the test), it confirms the reservation. Then, the bwctld processes run the test and return the results. The results are returned to the client from both sides of the test. Additionally, the bwctld processes share the results from their respective sides of the test with each other.

BWCTL is used to enable non-specific throughput tests to a host without having to give full user accounts on the given system. Users want the ability to run throughput tests to determine the achievable or available bandwidth between a pair of hosts. It is often useful to test to multiple points along a network path to determine the network characteristics along that path. Typically, users who want to do this path decomposition have to contact the network/system administrators that control the hosts along the path directly. The administrator needs to either run half of the test for the user or provide a user account on the host. Also, network paths of interest usually are controlled by multiple administrators. These hurdles have made this kind of testing difficult in practice.

BWCTL was designed to help with this problem. It allows an administrator to configure a given host as an Iperf, Thrulay or Nuttcp endpoint that can be shared by multiple users without concern that those users will interfere with each other. Specific policy limits can be applied to specific users, and individual tests are scheduled so they will not interfere with each other. BWCTL allows the administrator to classify incoming connections based upon a user name and AES key (generated by a pass phrase) combination or, alternatively, based upon an IP/netmask. Once the connection is classified, the bwctld can determine the exact type and intensities of throughput tests that will be allowed. (More details on the policy controls can be found in the bwctld.limits(8) manual page.)


What's Changed Since Version 1.2a


What's Changed Since Version 1.1b


Features


Requirements


Supported Systems

BWCTL has been tested most extensively on Red Hat Linux 4 and 5 systems, but most recent versions of UNIX should work. The code cleanly compiles on FreeBSD, Linux, and OS X.

BWCTL compiles on Solaris. However, Thrulay does not work on that platform so is not compiled in. If anyone has any interest in updating thrulay to work on Solaris, let us know.


Recommended Hardware

BWCTL does not have any strict hardware requirements. The limits imposed by the specific throughput tests are more taxing to hardware than the scheduling and policy functions added by BWCTL. The hardware requirements are therefore a function of the specific throughput tests that are desired. Internet2 had good luck using the following hardware to perform 1Gbps tests on the Abilene network:
Intel SCB2 motherboard
2 x 1.266 GHz PIII, 512 KB L2 cache, 133 MHz FSB
2 x 512 MB ECC registered RAM (one/slot to enable interleaving)
2 x Seagate 18 GB SCSI (ST318406LC)
SysConnect Gigabit Ethernet SK-9843 SX


Building the Application

The BWCTL software uses the gnu autoconf tools to configure the build process. BWCTL is distributed with a pre-built configure script so the actual autoconf tools should not be needed on the target system. (Although, gnumake may be required.) The configure script can be run with the --help option to determine the full set of configurable options.

A basic build procedure would be:

% gzip -cd bwctl-$VERS.tar.gz | tar xf -
% cd bwctl-$VERS
  # --prefix is only needed if you don't like the default
  #   (/usr/local on most systems)
% ./configure --prefix=/install/root
% make
% make install
Please report any build problems to bwctl-users@internet2.edu.


Configuring bwctld

The basic procedure to configure bwctld is to create a bwctld.conf and, optionally, a bwctld.limits file and a bwctld.keys file. These files need to be installed in the same directory that is specified with the -c option to bwctld. The recommended directory is /install/root/etc. (The etc directory below your install root.) There are examples of these files in the bwctl-$VERS/conf  sub directory of the distribution.

bwctld.conf:
Used to configure basic operation of the daemon, such as server listening port, the path for Iperf, and error logging. For a detailed description of the options available, see the bwctld.conf(8) manual page.

bwctld.limits:
Used to configure the policy limits for the daemon. There are two parts to this policy: 1) authentication and 2) authorization. The authentication is done by assigning a class to each new connection. Each class has a set of limits associated with it. The classes are hierarchical, so a connection must pass the limit restrictions of the assigned class as well as all parent classes. For a detailed description of the options available, see the bwctld.limits(8) manual page.

bwctl.keys:
Used to associate identities with AES keys. These identities are then mapped to a class by the bwctld.limits file. For a more detailed description, see the bwctld.keys(8) manual page.


Configuring firewalls

If a firewall is enabled on the machine running bwctld, it will need to be configured to allow incoming clients and tests. Use this set of directions to configure the firewall.

Configuring NTP

To ensure that tests can be run, the machine running bwctld should have its clock synchronized using NTP. Use this set of directions to configure NTP.

Running bwctld

The normal command line to start the daemon is:
 % bwctld -c /install/root/etc
It is possible to run the daemon without a config file directory if enough command line options are specified, but it is easier to use a config file.

To see all the available options:

 % bwctld -h
More details on running the daemon, as well as a complete description of the command line options, is available from the bwctld manual page.


Running bwctl

The basic command line for the client is:
% bwctl [options] [-c catchhost] [-s sendhost]
The -c option indicates that the catchhost should be an Iperf server (think packet catcher). The -s option indicates the sendhost should be an Iperf client (think packet sender). At least one of the -c/-s options must be specified. If only one of these options is specified, the local host is assumed to be the other test endpoint.

To see a list of available options:

% bwctl -h
More details on running the client application, with a complete description of all command line options, is available from the bwctl manual page.


Caveats

Thrulay support is deprecated. If there is enough desire, or if someone is willing to maintain thrulay, the functionality could be undeprecated.
Mailing Lists There are two email lists to support this software:
bwctl-users
This is a general discussion list for users to discuss problems. This list is monitored as bug reports should be sent here.
bwctl-announce
This list is used to announce new versions or significant developments with regard to the software.
Information about these lists, including links to subscribe, is at https://mail.internet2.edu/wws/lists/engineering.


Author

Jeff Boote
boote@internet2.edu
Internet2

Aaron Brown
aaron@internet2.edu
Internet2


Acknowledgments

The following individuals have greatly aided in the development, testing, or debugging of BWCTL:

$Id: index.html 565 2012-04-18 14:23:11Z alake $