Centre for Advanced Internet Architectures, Swinburne University of Technology, Melbourne, Australia CRICOS number 00111D 19th February, 2010 ---------------------------------------------- OVERVIEW ---------------------------------------------- Hamilton Delay (HD) is a delay-based TCP congestion control algorithm proposed by L. Budzisz et al. [1] at the Hamilton Institute, University of Ireland, Maynooth. It is an experimental first step toward the ability of delay based algorithms to fairly coexist with loss based algorithms. The HD implementation requires that the bundled version of the Modular TCP Congestion control v0.9.4 and Khelp Framework v0.1.0 patch be applied to the kernel before it can be used. If the target system has previously been patched with either the Modular TCP Congestion Control or Khelp Framework patches, these should be removed before applying the bundled patch. The bundled patch is available here: http://caia.swin.edu.au/urp/newtcp/tools/caia_modularcc_v0.9.4_khelp_v0.1.0_bundle_9.x.r203910.patch The code was developed as a "clean-room" implementation. Only the publicly released Hamilton Delay papers were used as the basis for development. ---------------------------------------------- LICENCE ---------------------------------------------- The FreeBSD HD implementation is released under a BSD licence. Refer to licence headers in each source file for further details. ---------------------------------------------- USAGE ---------------------------------------------- Make sure you have the FreeBSD system sources. These can be installed using sysinstall. The running system must have the Modular TCP Congestion control v0.9.4 and Khelp Framework v0.1.0 bundled patch applied. The ERTT Khelp module is also a dependency for the HD implementation and must be loaded into the running kernel before the HD module can be loaded. To build the module, simply run: make HERTT_DIR=/path/to/h_ertt-0.1 setting HERTT_DIR to the directory path containing the "h_ertt.h" file. To load the compiled module into the running kernel, run the following command as root: kldload ./cc_hd.ko To unload the module from the running kernel, run the following as root: kldunload cc_hd To delete all artifacts created by compiling the module, run: make cleandir ---------------------------------------------- COMPILE TIME CONFIGURATION ---------------------------------------------- There are currently no compile-time configuration options. ---------------------------------------------- RUN TIME CONFIGURATION ---------------------------------------------- HD utilises the FreeBSD sysctl interface to export its configuration variables to user-space. HD provides 3 sysctl configuration variables. The names of the 3 variables and their default values on load are: net.inet.tcp.cc.hd.queue_min=5 net.inet.tcp.cc.hd.queue_threshold=20 net.inet.tcp.cc.hd.pmax=5 The minimum queue delay parameter is specified in ticks, and sets the value above which the HD algorithm will begin to operate. The queue threshold parameter is specified in ticks. When there are no loss based flows, the algorithm seeks to keep the queueing delay between queue_min and queue_threshold. The pmax parameter specifies the packet maximum backoff probability as a percentage. The probabilistic backoff mechanism helps aid coexistence with loss based flows. Refer to [1] for more information on the algorithm and these parameters. In order to select HD as the system wide congestion control algorithm, run the following as root: sysctl net.inet.tcp.cc.algorithm=hd ---------------------------------------------- KNOWN LIMITATIONS ---------------------------------------------- Current known limitations of the HD software: 1. The delay thresholds must be manually set. ---------------------------------------------- ACKNOWLEDGEMENTS ---------------------------------------------- This project has been made possible in part by a grant from the Cisco University Research Program Fund at Community Foundation Silicon Valley. Testing and development was further assisted by a grant from the FreeBSD Foundation. ---------------------------------------------- RELATED READING ---------------------------------------------- This software was developed as part of the NewTCP research project at Swinburne University's Centre for Advanced Internet Architectures. More information on the project is available at: http://caia.swin.edu.au/urp/newtcp/ A number of software tools and technical reports related to experimental TCP research in general are available respectively at: http://caia.swin.edu.au/urp/newtcp/tools.html http://caia.swin.edu.au/urp/newtcp/papers.html At the time of writing, the following software tools may be of interest: Modular TCP Congestion Control for FreeBSD Khelp Framework for FreeBSD Vegas congestion control algorithm CUBIC congestion control algorithm H-TCP congestion control algorithm Enhanced Round Trip Time (ERTT) Khelp module Statistical Information For TCP Research (SIFTR) Deterministic Packet Discard (DPD) At the time of writing, the following reports/papers may be of interest: [1] provides the canonical reference for the HD congestion control algorithm. [2] provides a detailed technical discussion of the ERTT module, developed to give improved RTT estimates for use by congestion control algorithms. [3] provides a detailed technical overview of the modular congestion control patch to FreeBSD which the HD code is dependent upon. ---------------------------------------------- REFERENCES ---------------------------------------------- [1] L. Budzisz, R. Stanojevic, R. Shorten, and F. Baker, "A strategy for fair coexistence of loss and delay-based congestion control algorithms", IEEE Commun. Lett., vol. 13, no. 7, pp. 555-557, Jul. 2009. [2] D. Hayes, "Timing enhancements to the FreeBSD kernel to support delay and rate based TCP mechanisms", CAIA Technical Report 100219A, February 2010. [3] L. Stewart, J. Healy, "Light-Weight Modular TCP Congestion Control for FreeBSD 7", CAIA Technical Report 071218A, December 2007. ---------------------------------------------- AUTHORS ---------------------------------------------- The HD implementation was developed by David Hayes whilst working on the NewTCP research project at Swinburne University's Centre for Advanced Internet Architectures, Melbourne, Australia. David Hayes is the current maintainer, and all contact regarding this module should be directed to him via email: dahayes@swin.edu.au