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

April, 2012

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

The MRT slice tool takes a large MRT BGP4MP type dump containing
BGP update sequences, and cuts out slices for certain time intervals, 
which do not only contain the update messages of this time interval,
but also the updates of an initial RIB propagation.
The tool can also be used to convert RIB dumps into BGP updates 
in MRT format, or to join multiple MRT update dumps, and cut slices 
of those, producing one single MRT file with the updates of the desired 
time frame. The tool takes care of 4 byte AS to 2 byte AS conversions 
as well.
This MRT slices can be used to reproduce a complete BGP session
between two BGP speakers as it would have been happened at the
exact time the updates were collected.

This tool is part of the MDFMT and can be found in folder mrt_slice.
The following files are part of the tool:

        README-mrtslice
        mrt_slice-0.2.py

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

This tool is released under a new BSD License. For more details
please refer to the included source files.

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

Execute the script as follows:

	python mrt_slice-0.2.py [options]

Options:

  -i DUMPFILE, --infile=DUMPFILE (required if -r is not specified)
                        MRT input dump file - add multiple files by specifying
                        them as list separated by "," e.g.: -i
                        file1,file2,file3. Filenames can include wildcards
  -o DUMPFILE, --outfile=DUMPFILE (required)
                        MRT output dump file
  -r RIBDUMP, --ribdump=RIBDUMP (required if -i is not specified)
                        MRT RIB dump file (TableDump_v2). The new MRT dump
                        file will start from the time of the first RIB dump
                        entry. If not set, the slice will start from the
                        beginning of the input dump file, or from the time
                        specified with the -s option
  -a ASIP, --asipfile=ASIP (required if both, -i and -r are specified)
                        ASIP file to determine whether the (TableDump_v2)
                        entries in the RIB should be converted to 4-byte or
                        2-byte ASes to match the input files. Required if both, 
			-r and -i are used.
  -t TIMESPAN, --timespan=TIMESPAN (optional)
                        Timespan of the slice in seconds. Add "m" for minutes,
                        "h" for hours, "d" for days and "w" for weeks. If
                        there is only a single input file and no RIB file or
                        start time, the default is 1h. Otherwise the default
                        is to join the RIB file and all input files and
                        process them to the end.
  -s STARTTIMESTRING, --starttime=STARTTIMESTRING (optional if -r is not specified)
                        Start time of the slice if no RIB dump is given. The
                        time needs to be in the format: "dd/mm/YYYY HH:MM:SS"
                        for the GMT Timezone. If a RIB dump is given, it will
                        override this setting.

The resulting file will be an MRT BGP4MP type dump.

----------------------
ADDITIONAL INFORMATION
----------------------

The mrt_slice tool works only with a patched dpkt library 
which allows the use of 4 byte AS numbers. 
The patchset is part of the MDFMT project and
should be located in folder dpkt-patchset.
The complete MDFMT can be obtained at:

        http://caia.swin.edu.au/urp/bgp/tools.html

Refer to the dpkt-patchset README for more information
on how to install dpkt and the patchset.

A slightly outdated documentation of the mrt_slice tool version 0.1 
can be found at [2].

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

There have been issues with large MRT dump files obtained from 
the rrc0 collector at RIPE. It seemd that python is not able to handle 
very long TableDumpV2 entries, which are read as a single string, 
and causes the mrt-slicer to crash.

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

[1] MRT dump format RFC (RFC 6396):

	http://tools.ietf.org/html/rfc6396

[2] MRT dump file manipulation toolkit (MDFMT) - version 0.2
    (CAIA technical report) PDF format

	http://caia.swin.edu.au/reports/090730B/CAIA-TR-090730B.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