Extensions for BRITE 2.x
-----------------------

==============================================================================
Copyright (c) 2007 HAW Hamburg.  All rights reserved.  Permission to use,
copy, modify, and distribute this software and its documentation for any
purpose and without fee is hereby granted, provided that the above
copyright notice appears in all copies and that both the copyright notice
and this permission notice appear in supporting documentation.  The HAW
Hamburg makes no representations about the suitability of this software for
any purpose.  It is provided "as is" without express or implied warranty.

Please, refer to: http://www.realmv6.org/brite-extension.html
==============================================================================

Up to date information can be found at
http://www.realmv6.org/brite-extension.html

The contents of this README are:
  0.  Whats new in this version
  1.  Requirements
  2.  Installing
  3.  Documentation
  4.  Bugs, mailing lists and other contact information


0. Whats new in this extension version:
---------------------------------------

This is an extension of BRITE, Boston University Representative Internet
Topology Generator, which includes the import support of current real-world
topologies and filter schemas. We have extended only the Java version of
BRITE. The new key features are:

 (1) Major rewrite of Skitter import
 (2) Import of DIMES data
 (3) OMNeT++ support included from Andras Varga
 (4) Different filter schemas

1. Requirements:
-----------------

The extensions requires BRITE 2.1

  * http://www.cs.bu.edu/brite/ or
  * http://www.realmv6.org/brite-extension.html

For the Skitter import you need CAIDA's sk_analysis_dump-2.0.5:

  * http://www.caida.org/tools/measurement/skitter/sample_code/code/

2. Installing:
--------------

First of all download BRITE 2.1, uncompress and untar it:

  $ gunzip BRITE.tar.gz
  $ tar -xvf BRITE.tar.gz

Download the extension patch from
http://www.realmv6.org/brite-extension.html and copy the file into the
BRITE directory.

Change your directory to BRITE, patch and compile the software:

  $ patch -p 1 < brite21-extension10.patch
  $ make all

3. Use:
---------

Change to the BRITE directory.

To run BRITE with the GUI type:
  $ ./brite &

To run BRITE with the command line type:
  $ java Main.FileConverter <output-filename>  RT {|AS} skitter2brite {|skitter2omnet} {|brite2omnet} {|dimes2brite} {|dimes2omnet} <filterSettings-filename> <input-filename(s)>*

    RT {|AS}: Choose IP-level or AS-level graph as input.

    filterSettings-filename: Name of file, which turns on or off the filter.

    input-filename(s):
      For Skitter: <sk_analysis_dumps>
      For Dimes: <Node File> <Edge File>


3.1 More Documentation:
----------------------

Import and Conversion of Dimes and Skitter Data:

    The BRITE Extension supports the import of an IP- or AS-level graph
    created by Skitter or Dimes. According to your Skitter/Dimes data, you
    have to select at CMD and GUI RT for an IP-level graph or AS for an
    autonomous system view.

    Note, that the BRITE Extension supposes symmetric routing, such that
    every edge between node A and B automatically generates an edge between
    B and A.

    DIMES: Dimes splits nodes and edges information into two files. The
    order for input files regarding the BRITE Extension is the following:
    <Node File> <Edge File>.

    SKITTER: The raw IP-level Skitter measurements will be provided in a
    specific DB format by CAIDA. To import the files to BRITE, first you
    need to convert the data into readable ASCII using the
    sk_analysis_dump-2.0.5 tool.

    The BRITE Extension decomposes the traceroute path in separate edges.
    The import routine creates a complete graph over all passed Skitter
    files, i.e., all edges will be extracted from all input files to shape
    the graph. Consequently, more monitor point data provides probably more
    visible connections. If there are two or more edges connecting the same
    vertices, e.g., resulting from different monitor files, the mean value
    of the delay will be assigned as link weight. In case that the delay
    between nodes cannot be calculated based on the RTT (that can happen
    for Skitter data) a preconfigured default value of 10ms will be used.

    The AS adjacency matrix is computed daily from observed skitter
    measurements. In contrast to the IP-level graph the data are available
    in plain ASCII summarized over all monitor points. As noted at 

      * http://www.caida.org/tools/measurement/skitter/as_adjacencies.xml 

    the graph can contain AS-sets, multi-origin ASs and no ASs. Edges
    affected by one of these effects will be *discarded* by the import
    routine to avoid ambiguities. Skitter's AS-level data set does not
    imply any link weights, such that a homogeneous link weight of 10ms
    will be assumed.

Filter Schemas:

    The BRITE Extension provides two filter schemas:

    MAP SAMPLING: This algorithm by Magoni and Pansiot ("Internet Topology
    Modeler Based on Map Sampling", 2002) allows you to create a subgraph
    with a predefined number of nodes and mean degree based on your input
    topology.

    RADIUS VIEW: Using the radius view, you can create a subgraph, which
    includes all nodes with a predefined maximum hop distance starting from
    a particular node. Let G=(V,E) the origin topology and v \in V the
    choosen node, than is G'=(V',E') the subgraph with V'={v' \in V |
    dist(v,v') <= maxHop}.

    The filters will be configured for the CMD by a configuration file. A
    sample file can be found in the patched BRITE root directory called
    filterSettings.conf.

Java Error:

    If you get the error  message: "Error: Java heap space", you need to
    increase the memory allocation with "java -Xmx<value> ..."

4. Contact Us:
----------------

If you find bugs or if you have further questions as well as suggestions
for improvements, please contact us: waehlisch@ieee.org.

5. History:
-----------

September 2th, 2007 - Initial Version
Novemeber 5th, 2008 - Update to support commata delimiter in DIMES files