This site has been archived. For information on the GN Project’s eduPERT initiative please visit https://archive.geant.org/projects/gn3/geant/services/edupert/Pages/Home.html

BWCTL and BWCTLD

For full information on these tools, see the 'Man' pages, either in the applications or on-line at http://e2epi.internet2.edu/bwctl/manpages.html

BWCTL and BWCLTD Basics

BWCTL/BWCTLD is a wrapper for iperf, and allows controlled, authenticated use of iperf i.e. rather than running an iperf server on a given port and using local or remote firewall to limit access to it, access can all be controlled by an easily editable file bwctld.limits .

Note, in order for BWCTL control to function properly TCP port 4823 needs to be open. There is a second control connection established, which is chosen by the receiving (iperf) server. By default this uses a high numbered port , but it can be limited in scope using the peer_ports parameter. Finally, any and all ports that will be used by iperf need to be open (by default the iperf server is spawned on port TCP/UDP 5001, but this can be changed in the bwctld.conf file, using the parameter iperfport). When two bwctl servers negotiate a test session, it is the receiver who chooses which port should be used to send/receive iperf traffic (in other words, if the two servers have different port ranges configured in their '.conf files, it is the receiver's config that will be used).

The bwctld.limits file

The application is installed with a default bwctld.limits file, which can easily be edited in place to ensure the correct syntax and format is kept (note the use of commas and back slashes). In short, the .limits file defines user classes (and assigns user names and/or network prefixes to these classes).

# setup the root node with max bandwidth as open as possible.
limit root with \
        bandwidth=900m, \
        duration=0, \
        allow_udp=on, \
        allow_tcp=on, \
        allow_open_mode=off

# wide open everything - default integer limits to parent to get max
limit ami with parent=root, \
        bandwidth=0, \   <== '0' means unlimited
        duration=0, \
        allow_open_mode=on

# Allow GN2 servers full access
assign net 62.40.122.0/24 ami

The meaning of the above terms is given in this list of user-class parameters and their explanations, courtesy of Main.ChrisWelti.

Note bwctld needs to be restarted for changes to take effect, which can be done with a simple script such as this

User Authorization and bwctd.keys file

By creating a user-class with 'allow_open_mode=off' you can force users to supply a user name and password in order to use bwctl. The usernames are as per listed in bwctld.limits and they must match the username and password stored in the bwctld.keys file (which for simplicity should be co-located with the bwctld.conf and bwctld.limits files). The passwords stored in the keys file are hashed for security, and the way to create a new keys file (with one new user) is as follows:

[user@localhost]$aespasswd -f <path_filename_of_keys_file> -n <username>
Enter passphrase for identity '<username>':
[user@localhost]$

After this, new users can be added by simply leaving out the '-n'

[user@localhost]$aespasswd -f <path_filename_of_keys_file> <username>

User names (identities) can be deleted either by editing the keys file directly, or using

[user@localhost]$aespasswd -f <path_filename_of_keys_file> -d <username>

Having set up usernames and passwords (keys) it is possible to run a bwctl tets between two remote machines

[user@localhost]$bwctl -s <send host> -c <receive host> [-t <time> etc] -A A AESKEY <username>
Enter passphrase for identity '<username>':
...

"Gotchas" and Recommendations

  • Always specify the path of the bwctld.conf file when starting bwctld e.g. bwctld -c /etc/bwctld/
  • Always keep the .conf , .limits and .keys in the same directory

  • If you get the following message without seeing results:

    BWCTL_WARNING: iperf killed: timslot irregularity

    .. it's not 100% clear what that means. This most often occurs with 'bwctl -c' and means that iperf didn't receive the expected data within the time scheduled for the measurement. Adding -i 1 or similar option may help in getting the data nonetheless. Often also increasing the buffer size (e.g., =-w 4M=) may help if the defaults are very low. There is also some speculation on this on bwctl-users list (longer explanation).

  • If you get a message like ...

          bwctl: _BWLWriteStartSession: called in wrong state.
      bwctl: BWLStartSessions: Failed

    ... it almost certainly means the 'limits' have been violated. Check in particular that the UDP bandwidth setting includes 'm' or 'k' as required (for Mbps and kbps)

  • If you get a result without data, such as ...

       [admin@pm1.ams.nl.geant2.net ~]$bwctl -c
   server2-saopaulo.lan.redclara.net -t 10 -A A AESKEY bwctl
   Enter passphrase for identity 'bwctl':
   bwctl: 17 seconds until test results available
   RECEIVER START
   RECEIVER END

    And associated syslog message ...

       Oct  6 10:47:07 pm1 bwctld[9831]: FILE=endpoint.c, LINE=941, Endpoint:Signal = 14
   Oct  6 10:47:07 pm1 bwctld[9831]: FILE=endpoint.c, LINE=938, Endpoint:Unable to connect to Peer!: Interrupted system call
   Oct  6 10:47:02 pm1 bwctl: 16 seconds until test results available
   Oct  6 10:47:01 pm1 bwctld[9830]: FILE=sa no resultsi.c, LINE=442,ControlSession([62.40.122.115]:4823) accepted from userid(bwctl):([62.40
.122.115]:55619)
   Oct  6 10:47:01 pm1 bwctld[9830]: FILE=sapi.c, LINE=286, Connection to(62.40.122.115:4823) from (62.40.122.115:55619)

    ... then the problem is probably that a port is being blocked somewhere. Use tcpdump host <ip-address> to check what ports BWCTL is using for its second (non-4823) control session, and for iperf itself (usually ports 5001-5005). This problem may also be seen when using an old version of iperf (typically 1.7.0), which should be upgraded.

– Main.TobyRodwell - 19 Sep 2006
-- Main.PekkaSavola - 25 Oct 2006
-- Main.PekkaSavola - 07 Dec 2006

  • No labels