Centre for Advanced Internet Architectures, Swinburne University of Technology, Melbourne, Australia CRICOS number 00111D 30th July, 2010 ---------------------------------------------- OVERVIEW ---------------------------------------------- CUBIC is a TCP congestion control algorithm proposed by researchers from North Carolina State University, USA (http://ncsu.edu/). It is designed to improve the performance of TCP over high bandwidth-delay paths whilst attempting to maintain fairness with traditional TCP flows. At the time of writing, CUBIC is the default TCP congestion control algorithm in Linux, and has been available in the mainline Linux kernel since 2.6.13. This distribution contains the v0.10 implementation of CUBIC 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. Only the publicly released CUBIC 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 CUBIC 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_cubic.ko To unload the module from the running kernel, run the following as root: kldunload cc_cubic 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 ---------------------------------------------- There are currently no run-time configuration options. ---------------------------------------------- KNOWN LIMITATIONS ---------------------------------------------- Current known limitations of the CUBIC software and any relevant workarounds are outlined below: 1. There is currently no overflow safety checking done in certain key segments of code. Standard networking scenarios should keep all variables within reasonable bounds such that overflow should not be an issue, but extreme situations may cause undeterministic behaviour. 2. The code does not currently handle the kernel tick timer wrapping around back to 0 (which will occur approximately every 49 days with a 1000HZ, 32 bit kernel tick timer). Any active CUBIC flow that straddles a tick timer wrap will obtain a grossly inflated cwnd for the current congestion epoch, and should then return to normal operation. ---------------------------------------------- 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 while studying at Swinburne University's Centre for Advanced Internet Architectures, under the umbrella of the NewTCP research project. 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 (although somewhat outdated) technical overview of the modular congestion control patch to FreeBSD which the CUBIC code is dependent upon. [2] provides the canonical reference for the CUBIC congestion control algorithm, with [3] providing additional background, insights and experimental analysis of the algorithm. [4] contains a technical evaluation and analysis of the SIFTR software which has been extensively used during our experimental FreeBSD work. [5] provides a discussion of useful tuning parameters for the FreeBSD 6 TCP/IP stack. [6] 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] I. Rhee, L. Xu, S. Ha, "CUBIC for Fast Long-Distance Networks", Internet Draft, draft-rhee-tcpm-cubic-02.txt, August 2008. [3] S. Ha, I. Rhee, L. Xu, "CUBIC: A New TCP-Friendly High-Speed TCP Variant", ACM SIGOPS Operating Systems Review 42, 5, pp 64-74, July 2008. [4] L. Stewart, G. Armitage, J. Healy, "Characterising the Behaviour and Performance of SIFTR v1.1.0", CAIA Technical Report 070824A, August 2007. [5] L. Stewart, J. Healy, "Tuning and Testing the FreeBSD 6 TCP Stack", CAIA Technical Report 070717B, July 2007. [6] L. Stewart, J. Healy, "An Introduction to FreeBSD 6 Kernel Hacking", CAIA Technical Report 070622A, June 2007. ---------------------------------------------- AUTHORS ---------------------------------------------- The FreeBSD CUBIC implementation was first released in 2009 by Lawrence Stewart whilst studying 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