Lawrence Stewart
Centre for Advanced Internet Architectures
Swinburne University of Technology,
Melbourne, Australia
CRICOS number 00111D

28th December, 2008

-----------------------
OVERVIEW
-----------------------

This work is part of the "Enhancing the FreeBSD TCP Implementation"
project [1,2] funded by the FreeBSD Foundation [3].

TCP appropriate byte counting (ABC) [4] addresses a congestion control related
issue introduced by the early TCP specifications. It suggests increasing the
congestion window by the number of bytes acknowledged by a TCP ACK, as opposed
to the current scheme which relies on an approximation driven by ACK clocking.

ABC will most commonly benefit FreeBSD by improving TCP sender performance when
communicating with a delayed acknowledgement enabled receiver. It also:

- Improves performance when used with next generation congestion control
  algorithms.
- Improves performance when there is ACK loss present on the return path.
- Fixes a minor exploit in the current TCP implementation which allows a
  malicious receiver to elicit preferential treatment from a FreeBSD server.

These benefits are most noticeable over WAN-like paths with non-zero packet loss
and delay in the 10's to 100's of milliseconds.


-----------------------
LICENCE
-----------------------

This code is released under the standard FreeBSD licence.


-----------------------
USAGE
-----------------------

Make sure you have the FreeBSD system source tree available.

The patch against 8-CURRENT is relative to the top of the FreeBSD source tree.
Assuming you are going to patch the src tree at /usr/src, this procedure
should do the trick:

  cd /usr/src
  patch -p0 < /path/to/tcp_abc_8.x.r186471.patch
  make buildkernel installkernel
  reboot

The patch changes the size of the tcpcb structure, thus you will get ABI
breakages with any utilities that rely on the size of the tcpcb
e.g. sockstat will error with "sockstat: struct xtcpcb size mismatch".

A rebuild/install of world will obviously solve the issue. However, copying the
patched tcp_var.h from /usr/src/sys/netinet to /usr/include/netinet and
selectively rebuilding these utilities as they crop up should also solve the
issue faster if you're impatient and familiar with the src tree and make glue.

The patch *will not* apply against the 7-STABLE source tree due to the vimage
chunks. I hope to back-port the patch sometime after it is tested and committed
to 8-CURRENT.


-----------------------
CONFIGURATION
-----------------------

The patch adds two new sysctl variables:

Variable:	net.inet.tcp.rfc3465
Description:	"Enable RFC 3465 (Appropriate Byte Counting)"
Values:		0 to disable, 1 to enable. The default is 1  i.e. enabled.

Variable:	net.inet.tcp.abc_l_var
Description:	"Cap the max cwnd increment during slow-start to this number of
		segments"
Values:		1 or 2. The default is 2, which counteracts the effect of
		delayed ACK during slow start.


-----------------------
REFERENCES
-----------------------

[1] Project announcement,
    http://www.freebsdfoundation.org/project%20announcements.shtml#Lawrence

[2] Project home page, http://caia.swin.edu.au/freebsd/etcp09/

[3] The FreeBSD Foundation, http://www.freebsdfoundation.org/

[4] M. Allman, "TCP Congestion Control with Appropriate Byte Counting (ABC)",
    RFC 3465, February 2003.