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

30th July, 2009


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

This is the README for the per-prefix-mrai and path-damping patch for 
Quagga git, contained in the file path-damping-patchset-0.3-git.tar.bz2

The files in the archive are:

	per_prefix_mrai_and_path_damping.patch
	README

This patches provide an implementation of a per-prefix MRAI timer in Quagga, 
replacing the per-peer "burst" behavior, and also an implementation of the 
path-exploration damping algorithm described by Geoff Huston at [1]

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

This patches are released under the GPL Version 2. For more details
please refer to the COPYING and COPYING.LIB files of the Quagga source
distribution.

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

To make use of a per-prefix MRAI timer only in Quagga git,
execute the following steps:

- check out the git source code:
	git clone git://code.quagga.net/quagga.git
- cd into the quagga directory
- apply the patch:
	patch -p1 < per_prefix_mrai_and_path_damping.patch

- execute:
	./bootstrap.sh;
	./configure --enable-per-prefix-mrai;
	make;
	(as su) make install;

---

To make use of a the path-damping algorithm in Quagga git, 
execute the following steps:

- check out the git source code:
	git clone git://code.quagga.net/quagga.git
- cd into the quagga directory
- apply the patch:
        patch -p1 < per_prefix_mrai_and_path_damping.patch

- execute:      
	./bootstrap.sh;
        ./configure --enable-path-damping;
        make;
        (as su) make install;

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

The MRAI timer (which becomes the PDI with path-damping enabled)
is configured in the bgpd config file (or also on the Quagga CLI) with the
command:

	neighbor <address> advertisement-interval <time in sec>

Jitter of (+-) 0-3 seconds will be applied to the interval. 

----------------------------------------------
KNOWN LIMITATIONS
----------------------------------------------

- The implementation has not been tested in a highly loaded production environment.
  This work is HIGHLY EXPERIMENTAL!
  Anyhow it is encouraged to test the implementation under high load and to
  inform the author about issues.

- The jitter applied to the PDI/MRAI timer is not yet configurable.

----------------------------------------------
RELATED READING
----------------------------------------------

This software was developed as part of the BGP Update Heuristics 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/bgp/

The documents directly related to this patches are:

[1] Damping BGP

	http://www.potaroo.net/ispcol/2007-06/dampbgp.html

[2] Implementing path-exploration damping in the
    Quagga Software Routing Suite Version 0.99.13 -
    patch set version 0.3

	http://caia.swin.edu.au/reports/090730A/CAIA-TR-090730A.pdf

----------------------------------------------
ACKNOWLEDGEMENTS
----------------------------------------------

This project has been made possible in part by
a grant from the Cisco University Research Program
Fund at Community Foundation Silicon Valley