Centre for Advanced Internet Architectures, Swinburne University of Technology, Melbourne, Australia CRICOS number 00111D 30th July, 2010 ---------------------------------------------- OVERVIEW ---------------------------------------------- H-TCP is a TCP congestion control algorithm proposed by the Hamilton Institute, Ireland (http://www.hamilton.ie/). It is designed to improve the performance of TCP over high bandwidth-delay paths whilst attempting to maintain fairness with traditional TCP flows. Hamilton themselves authored an implementation of H-TCP for Linux which has been available in the mainline Linux kernel since 2.6.13. This distribution contains the v0.12 implementation of H-TCP for FreeBSD. It requires the CAIA modular congestion control v0.10.0 patch to be applied to the kernel before it can be used, which is available from: http://caia.swin.edu.au/urp/newtcp/tools.html The code was developed as a "clean-room" implementation, which was a requirement of the NewTCP project. Only the publicly released H-TCP specification documents were used as the basis for development. The Linux implementation has not been referred to at all during the development process. ---------------------------------------------- LICENCE ---------------------------------------------- The FreeBSD H-TCP 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 installed under /usr/src These can be installed using sysinstall if they are not currently installed. The running system must have the CAIA modular congestion control v0.10.0 patch applied. Refer to [1] for further information on the the CAIA modular congestion control patch. To build the module, simply run: make To load the compiled module into the running kernel, run the following command as root: kldload ./cc_htcp.ko To unload the module from the running kernel, run the following as root: kldunload cc_htcp To delete all artifacts created by compiling the module, run: make cleandir ---------------------------------------------- COMPILE TIME CONFIGURATION ---------------------------------------------- The H-TCP module can be configured to provide detailed debugging information via dmesg by uncommenting CFLAGS+=-DHTCP_DEBUG in Makefile and recompiling. ---------------------------------------------- RUN TIME CONFIGURATION ---------------------------------------------- H-TCP utilises the FreeBSD sysctl interface to export its configuration variables to user-space. HTCP provides 2 sysctl configuration variables. The names of the 2 variables and their default values on load are: net.inet.tcp.cc.htcp.rtt_scaling=0 net.inet.tcp.cc.htcp.adaptive_backoff=0 RTT scaling in H-TCP may optionally be used to increase the fairness between competing TCP flows traversing different RTT paths through a common bottleneck. It attempts to make the cwnd rate of increase invariant with path RTT. Adaptive backoff in H-TCP may optionally be used to increase the efficiency of bandwidth utilisation in the network by adjusting the AIMD backoff parameter, beta, according to the amount of buffers available on the path. This attempts to ensure no queue along the path will remain completely empty after a packet loss event. Refer to [2,3,4,5] for more information on the algorithm and these parameters. In order to select H-TCP as the system wide congestion control algorithm, run the following as root: sysctl net.inet.tcp.cc.algorithm=htcp If the module was compiled with debugging support, an additional sysctl variable will be available: net.inet.tcp.cc.htcp.debug_ticks=1000 This sets the approximate number of ticks between debug log messages being written to dmesg. It defaults to the value of hz on the system, which is equivalent to 1 second. ---------------------------------------------- KNOWN LIMITATIONS ---------------------------------------------- Current known limitations of the H-TCP software and any relevant workarounds are outlined below: 1. The calculation of alpha is based on the number ticks since the last congestion event. Due to the use of fixed point math in the calculation, if more than 26843545 ticks elapses (7.4 hours with a 1000HZ kernel tick timer) between congestion events, alpha will be capped to prevent an integer overflow. This does NOT stop cwnd from increasing. It simply caps the rate of increase. 2. If the kernel tick timer wraps around back to 0 (which will occur approximately every 49 days with a 1000HZ, 32 bit kernel tick timer), we forget the value of ticks since last congestion event (delta), and reset delta to delta_l for every H-TCP flow. This has the effect of resetting alpha to 1 again, but does NOT reset the current cwnd. ---------------------------------------------- ACKNOWLEDGEMENTS ---------------------------------------------- This project has been made possible in part by a grant from the Cisco University Research Program Fund at Community Foundation Silicon Valley. ---------------------------------------------- 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: 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 a detailed technical overview of the modular congestion control patch to FreeBSD which the H-TCP code is dependent upon. [2] provides the canonical reference for the H-TCP congestion control algorithm, with [3,4,5] providing additional insights, specifications and experimental analysis of the algorithm. [6] examines our FreeBSD H-TCP implementation in detail. [7] contains a technical evaluation and analysis of the SIFTR software which has been extensively used during our experimental FreeBSD work. [8] provides a discussion of useful tuning parameters for the FreeBSD 6 TCP/IP stack. [9] is an introduction to FreeBSD kernel programming. ---------------------------------------------- REFERENCES ---------------------------------------------- [1] L. Stewart, J. Healy, "Light-Weight Modular TCP Congestion Control for FreeBSD 7", CAIA Technical Report 071218A, December 2007. [2] D. Leith, R. Shorten, "H-TCP: TCP for high-speed and long-distance networks", in Second International Workshop on Protocols for Fast Long-Distance Networks, Argonne, Illinois USA, February 2004. [3] D. Leith, R. Shorten, "On RTT Scaling in H-TCP", Discussion Note, 2005. [4] Y. Li, D. Leith, R.Shorten, "Experimental Evaluation of TCP Protocols for High-Speed Networks", HI Technical Report, June 2005. [5] D. Leith, R. Shorten, "H-TCP: TCP Congestion Control for High Bandwidth-Delay Product Paths", Internet Draft, draft-leith-tcp-htcp-04.txt, July 2007. [6] G. Armitage, L. Stewart, M. Welzl, J. Healy, "An independent H-TCP implementation under FreeBSD 7.0 - description and observed behaviour", ACM SIGCOMM Computer Communication Review, Volume 38 Issue 3, July 2008. [7] L. Stewart, G. Armitage, J. Healy, "Characterising the Behaviour and Performance of SIFTR v1.1.0", CAIA Technical Report 070824A, August 2007. [8] L. Stewart, J. Healy, "Tuning and Testing the FreeBSD 6 TCP Stack", CAIA Technical Report 070717B, July 2007. [9] L. Stewart, J. Healy, "An Introduction to FreeBSD 6 Kernel Hacking", CAIA Technical Report 070622A, June 2007. ---------------------------------------------- AUTHORS ---------------------------------------------- The FreeBSD H-TCP implementation was first released in 2007 by James Healy and Lawrence Stewart whilst working on the NewTCP research project at Swinburne University's Centre for Advanced Internet Architectures, Melbourne, Australia. Lawrence Stewart is currently the sole maintainer, and all contact regarding this module should be directed to him via email: lastewart@swin.edu.au