As part of a broader organisational restructure, data networking research at Swinburne University of Technology has moved from the Centre for Advanced Internet Architecture (CAIA) to the Internet For Things (I4T) Research Lab.

Although CAIA no longer exists, this website reflects CAIA's activities and outputs between March 2002 and February 2017, and is being maintained as a service to the broader data networking research community.

TCP Experiment Automation Controlled Using Python (TEACUP)

A Tool for Automated TCP Testbed Experiments


The Transmission Control Protocol (TCP) underpins much of today's Internet. Mechanisms for negotiating TCP connections, retransmitting lost packets and rearranging out of order arrivals have remained relatively stable for years. On-the-wire packet formats are likewise well defined. The challenge that continues to vex academia and industry is ensuring individual TCP connections can transfer data as fast as possible without overloading either the destination host (flow control) or the underlying network path (congestion control).

We built TEACUP (TCP Experiment Automation Controlled Using Python) to automate many aspects of running TCP performance experiments in our specially-constructed physical testbed. TEACUP enables repeatable testing of different TCP algorithms over a range of emulated network path conditions, bottleneck rate limits and bottleneck queuing disciplines.We hope TEACUP proves useful to other researchers who already have (or are interested in setting up) similar network testbeds.

Testbed environment

Using a dedicated testbed sits somewhere between simulation-based evaluations (e.g. ns-2 or ns-3) and wide-area experiments over real networks (e.g. the Internet). Our typical use-case involves TEACUP controlling a testbed containing multiple hosts either side of a Linux- or FreeBSD-based bottleneck router in the classic dumbbell topology. Figure 1 illustrates the testbed we used in-house while developing TEACUP, built according to the details in CAIA-TR-150210C.

Figure 1  Example TEACUP testbed topology

TEACUP runs on the 'data and control' server, orchestrating the configuration of end hosts and bottleneck router as required for particular experiments or ranges of experiments. It automates the process of configuring the bottleneck router for emulating different path delays, intrinsic packet loss rates, bottleneck rate limits, Active Queue Management (AQM) selection, ECN support, and so forth. Automated end-host OS selection is supported when the end hosts have Windows, Linux and/or FreeBSD on different local hard drive partitions, or are dedicated to running Mac OSX. If the testbed includes suitable remote power control units (IP-PDUs), TEACUP can automatically power cycle machines that get stuck during reboot.

In addition to launching full experiments, the user can query, configure or reboot testbed hosts (individually or in groups) using TEACUP from the command line of the control server.


TEACUP utilises a text-based configuration file to define experiments as combinations of parameters specifying desired network path and end host conditions. When multiple values are provided (e.g. for the bottleneck rate limit, or TCP congestion control algorithm), an experiment is made up of multiple tests -- consecutively run instances of the experiment run for each parameter combination.  For each experiment and test, TEACUP collects a range of data, such as tcpdump files of traffic seen at all network interfaces, FreeBSD SIFTR logs and Linux Web10G logs. TEACUP also collects a variety of metadata from the end hosts and bottleneck router (such as the actual OS/kernel version(s) in use, network interface configuration, NTP state and so forth).


TEACUP also provides some simple tools for analysing the results of experiments. These include plotting against time TCP's round trip time (RTT) estimate, congestion window size (CWND), SPP's RTT estimate (from tcpdump files), and estimated throughput. TEACUP can also plot any other TCP statistic gathered by SIFTR or Web10g over time.

Rudimentary animation of captured TCP traffic is provided by TEAPLOT.

Further reading

The rest of this website contains an introduction to TEACUP and its functionality, some examples on how to use TEACUP (including the configuration files), and the source code of TEACUP itself and some TCP statistics logging tools we developed for Linux, Windows and Mac OS X.


Up to v1.0, while developed at CAIA: From v1.0 onwards, see our Sourceforge site.

Projects using TEACUP

The following projects are (or have been) using TEACUP:

  • 2016 -- "Implementing Active Queue Management at the home to reduce NBN speed demands" (final year engineering student project)
  • 2015-present -- PhD research into content streaming and AQM
  • 2015-present -- PhD research into delay-sensitive congestion control algorithms
  • 2015-2016 -- "Implementing AQM in FreeBSD" (funded R&D)
  • 2015-2016 -- "An integrated social and technical evaluation of household broadband service requirements for educational innovation and the Internet of Things" (funded R&D)
  • 2015 -- "Queue management in Home Gateways: Potential impact on IoT traffic flows" (summer internship student project)
  • 2015 -- TEAPLOT (animated visualisation of selected TEACUP results)
  • 2015 -- "High-availability Internet Gateway for Uptime-Sensitive Medical Telemetry Applications" (final year engineering student project)
  • 2014 -- "Alternative Backoff: Achieving Low Latency and High Throughput with ECN and AQM" (collaborative research)
  • 2014 -- "Study in TCP Congestion Control Performance In A Data Centre" (funded R&D)


TEACUP versions prior to 1.0 were developed as part of a project funded by Cisco Systems and titled "Study in TCP Congestion Control Performance In A Data Centre". This was a collaborative effort between Swinburne University of Technology's Center for Advanced Internet Archectures and Fred Baker of Cisco Systems.

Starting with TEACUP v1.0, development will be community supported and publicly hosted at our Sourceforge site.

Last Updated: Friday 9-Dec-2016 11:06:39 AEDT | No longer maintained. Pre-2018 was maintained and authorised by Grenville Armitage,