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

6th October, 2008


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

DPD (deterministic packet discard) v2.0 is a patch against the FreeBSD
ipfw/dummynet source code to add configurable, deterministic packet loss
capabilities to dummynet pipes. Using ipfw filtering rules, packets can be
placed into a dummynet DPD pipe, which will then drop the specified packet set.

DPD's primary use is to provide repeatable experimental conditions for
observing and debugging protocol behaviour.

DPD v2.0 is a complete reimplementation of the basic idea described above,
and is related to DPD v1.0 in spirit only.


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

The DPD code is released under a BSD licence. Refer to the licence header in the
patch file for further details.


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

The patch is relative to the top of the FreeBSD source tree.
Place the patch in the top level source tree directory (referred to as
<srctree> from here on in, and typically located at /usr/src).

Patch the source code by running:

  cd <srctree> ; patch -p0 < dpdv2_*.patch

Install the patched kernel:

  make buildkernel installkernel ; reboot

Install the patched header files:

  cp <srctree>/sys/netinet/ip_dummynet.h /usr/include/netinet/
  cp <srctree>/sys/netinet/in.h /usr/include/netinet/

Install patched ipfw:

  cd <srctree>/sbin/ipfw> ; make depend all install


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

With that done, you should be able to do this sort of thing:

  kldload dummynet
  ipfw add 65534 allow ip from any to any
  ipfw pipe 1 config pls 5,10-12
  ipfw add 1 pipe 1 ip from any to any
  ipfw pipe list (observe the tot_pkt and drp fields)

NB:

- kldloading dummynet autoloads ipfw so be careful not to do it on a box you
  don't have console access to! Alternatively, put the above in a shell script
  and run the shell script.

- pls stands for "packet loss set". The above example would cause the 5th,
  10th, 11th and 12th packet through the pipe/queue to be dropped.

We also added some simple new functionality to ipfw. You can now do this:

  ipfw pipe 1 zero

  Which zeros the counters for the pipe/queue and starts the numbering
  (tot_pkt) at 0 again so pls will start dropping packets again from the start
  of the range.

and

  ipfw pipe zero

  Which does the same as above but for all pipes/queues.


----------------------------------------------
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)

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 we developed using DPD for verification purposes.

[2] contains a technical evaluation and analysis of the SIFTR software which
has been extensively used during our experimental FreeBSD work.

[3] provides a discussion of useful tuning parameters for the FreeBSD 6
TCP/IP stack.

[4] 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] L. Stewart, G. Armitage, J. Healy, "Characterising the Behaviour and
    Performance of SIFTR v1.1.0", CAIA Technical Report 070824A, August 2007.

[3] L. Stewart, J. Healy,  "Tuning and Testing the FreeBSD 6 TCP Stack", CAIA
    Technical Report 070717B, July 2007.

[4] L. Stewart, J. Healy, "An Introduction to FreeBSD 6 Kernel Hacking", CAIA
    Technical Report 070622A, June 2007.