Difference between revisions of "BRITE integration with ns-3"

From Nsnam
Jump to: navigation, search
m (Project Goals)
m (Vedranm moved page Ns3 BRITE Integration to BRITE integration with ns-3: Wiki page name cleanup)
 
(3 intermediate revisions by one other user not shown)
Line 1: Line 1:
 
{{TOC}}
 
{{TOC}}
  
= Overview =
 
 
The Boston university Representative Internet Topology gEnerator ([http://www.cs.bu.edu/brite/ BRITE]) is a topology generation framework built with flexibility and extensibility in mind. By integrating this topology framework with ns-3, users will have the power to quickly and efficiently create large Internet topologies, while taking advantage of ns-3's simulation capabilities.
 
The Boston university Representative Internet Topology gEnerator ([http://www.cs.bu.edu/brite/ BRITE]) is a topology generation framework built with flexibility and extensibility in mind. By integrating this topology framework with ns-3, users will have the power to quickly and efficiently create large Internet topologies, while taking advantage of ns-3's simulation capabilities.
 +
 +
[[Image:Brite.png|thumb|Brite Topology in ns-3]]
 +
 +
  
 
= Project Goals =
 
= Project Goals =
 
# The user will be able to easily leverage the power of BRITE within ns-3, in order to create and simulate large-scale Internet topologies.  
 
# The user will be able to easily leverage the power of BRITE within ns-3, in order to create and simulate large-scale Internet topologies.  
 
# Example ns-3 scripts will be provided to show use.
 
# Example ns-3 scripts will be provided to show use.
# Several BRITE configuration examples will be run through ns-3's test-runner to ensure continued operation
+
# Several BRITE configuration examples will be run through ns-3's test-runner to ensure continued operation.
 
# Code documentation, including doxygen will be provided.
 
# Code documentation, including doxygen will be provided.
 
# Manual section will be created to provide information on use and operation.
 
# Manual section will be created to provide information on use and operation.
Line 22: Line 25:
 
# http://code.nsnam.org/jpelkey3/ns-3-brite-modular/summary
 
# http://code.nsnam.org/jpelkey3/ns-3-brite-modular/summary
  
The integration is nearly complete. Users can use the ns-3 BRITE interface to generate ns-3 topologies using BRITE configuration files. An ns-3 example has been provided in src/brite/examples to show its usage. Test cases and complete modularization to align with the new ns-3 modularization model remain.
+
The integration is nearly complete. Users can use the ns-3 BRITE interface to generate ns-3 topologies using BRITE configuration files. An ns-3 example has been provided in src/brite/examples to show its usage. Complete modularization to align with the new ns-3 modularization model remains, including integration with ./download.py to automatically download and build BRITE if enabled.
 +
 
 +
= Build Instructions =
 +
The first step is to download and build the ns-3 specific BRITE repository:
 +
 
 +
  $: hg clone http://code.nsnam.org/jpelkey3/BRITE
 +
  $: cd BRITE
 +
  $: make
 +
 +
This will build BRITE and create a library, libbrite.so, within the BRITE
 +
directory.
 +
 
 +
Once BRITE has been built successfully, we proceed to configure ns-3 with BRITE support. Currently, ns-3-brite is not merged with the main ns-3 branch; therefore you must first download a custom ns-3 branch and build that:
 +
 
 +
  $: hg clone http://code.nsnam.org/jpelkey3/ns-3-brite-modular
 +
  $: cd ns-3-brite-modular
 +
  $: ./waf configure --with-brite=/path/to/brite/source
 +
 
 +
Make sure it says 'enabled' beside 'BRITE Integration'. If it does not, then something has gone wrong. Either you have forgotten to build BRITE first following the steps above, or ns-3 could not find your BRITE directory.
 +
 
 +
Next, build ns-3-brite-modular.
 +
 
 +
  $: ./waf
 +
 
 +
Finally, try running the brite-generic-example
 +
 
 +
  $: ./waf --run 'brite-generic-example --verbose=1'
 +
 
 +
By enabling the verbose parameter, the example will print out the node and edge information in a similar format to standard BRITE output. There are many other command-line parameters including confFile, seedFile, newseedFile, tracing, and nix, described below:
 +
 
 +
  confFile:    A BRITE configuration file. Many different BRITE configuration
 +
                file examples exist in the BRITE/conf_files directory, for
 +
                example, RTBarabasi20.conf and RTWaxman.conf. Please refer to
 +
                the conf_files directory for more examples.
 +
  seedFile:    BRITE specific seed file to seed a psuedo-random number genrator
 +
                from BRITE.
 +
  newseedFile: BRITE automatically generates a new seed file for you, if you
 +
                would like to randomize subsequent runs. If you would like
 +
                this to happen automatically, simply use the same file for
 +
                seedFile and newseedFile. This way, BRITE will run with the
 +
                current seeds and then overwrite them for the next run.
 +
  verbose:    Prints out the node and edge information in a similar format
 +
                to standard BRITE output.
 +
  tracing:    Enables ascii tracing.
 +
  nix:        Enables nix-vector routing. Global routing is used by default.
 +
 
 +
= Usage =
 +
The brite-generic-example can be referenced to see basic usage of the BRITE interface. In summary, the BriteTopologyHelper is used as the interface point by passing in a BRITE  configuration and seed file. The BRITE generated nodes and edges can then be accessed through this helper to create ns-3 nodes and edges.
 +
 
 +
Within the brite-generic-example, assigning IPs and creating applications are done fairly simply, as topology generation is the main topic of the BRITE interface. It is very likely  that the user will need to change the way in which IP addresses are assigned or applications are installed.
 +
 
 +
== A note on BRITE seed files ==
 +
BRITE accepts a seed file to seed its psuedo-random number generator. It also spits out a new seed file after every run -- overwriting your old seed file -- in case you wish to randomize subsequent runs. Finally, it saves the most recently used seed file in a file called "last_seed_file." I didn't like the way this was done, specifically the overwriting bit, so I changed it in the ns-3 interface. You still pass in a seed file, but you also pass in another file for BRITE to write the new seed file. This keeps BRITE from overwriting your seed file. I believe this makes it easier to run the exact same simulation over and over. I think this is important. Finally, if you wish to overwrite the seed file each run, randomizing each subsequent run as before, you can simply pass in the same file name for the seed file and new seed file in ns-3.

Latest revision as of 16:01, 10 February 2013

Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects

Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers

The Boston university Representative Internet Topology gEnerator (BRITE) is a topology generation framework built with flexibility and extensibility in mind. By integrating this topology framework with ns-3, users will have the power to quickly and efficiently create large Internet topologies, while taking advantage of ns-3's simulation capabilities.

Brite Topology in ns-3


Project Goals

  1. The user will be able to easily leverage the power of BRITE within ns-3, in order to create and simulate large-scale Internet topologies.
  2. Example ns-3 scripts will be provided to show use.
  3. Several BRITE configuration examples will be run through ns-3's test-runner to ensure continued operation.
  4. Code documentation, including doxygen will be provided.
  5. Manual section will be created to provide information on use and operation.

Development Plan

For modularity, the BRITE source code will be separate from the ns-3 code. Within the ns-3-allinone directory, the download.py script will take care of downloading and building the BRITE source code should the user choose to use BRITE. During the ns-3 build process, if BRITE is enabled, the BRITE code will be linked with the ns-3 code. Within the src/brite directory, the helper code, examples, test cases, and documentation will be provided.

The heart of the ns-3/BRITE integration is contained within the topology helper. By passing in a BRITE configuration file to this helper, the topology is created with BRITE. This topology is initially incompatible with ns-3; however, the helper will use this initial topology generation to create the ns-3 topology. Once topology generation is completed, the user can install applications on the nodes within this topology and run the simulation.

Current Status

Two repositories exist for BRITE integration with ns-3. First is the BRITE code itself, slightly modified to work with ns-3. Second is the ns-3-brite repository where the BRITE toplogy helper, examples, and test cases will exist.

  1. http://code.nsnam.org/jpelkey3/BRITE/summary
  2. http://code.nsnam.org/jpelkey3/ns-3-brite-modular/summary

The integration is nearly complete. Users can use the ns-3 BRITE interface to generate ns-3 topologies using BRITE configuration files. An ns-3 example has been provided in src/brite/examples to show its usage. Complete modularization to align with the new ns-3 modularization model remains, including integration with ./download.py to automatically download and build BRITE if enabled.

Build Instructions

The first step is to download and build the ns-3 specific BRITE repository:

 $: hg clone http://code.nsnam.org/jpelkey3/BRITE
 $: cd BRITE
 $: make

This will build BRITE and create a library, libbrite.so, within the BRITE directory.

Once BRITE has been built successfully, we proceed to configure ns-3 with BRITE support. Currently, ns-3-brite is not merged with the main ns-3 branch; therefore you must first download a custom ns-3 branch and build that:

 $: hg clone http://code.nsnam.org/jpelkey3/ns-3-brite-modular
 $: cd ns-3-brite-modular
 $: ./waf configure --with-brite=/path/to/brite/source

Make sure it says 'enabled' beside 'BRITE Integration'. If it does not, then something has gone wrong. Either you have forgotten to build BRITE first following the steps above, or ns-3 could not find your BRITE directory.

Next, build ns-3-brite-modular.

 $: ./waf

Finally, try running the brite-generic-example

 $: ./waf --run 'brite-generic-example --verbose=1'

By enabling the verbose parameter, the example will print out the node and edge information in a similar format to standard BRITE output. There are many other command-line parameters including confFile, seedFile, newseedFile, tracing, and nix, described below:

  confFile:    A BRITE configuration file. Many different BRITE configuration 
               file examples exist in the BRITE/conf_files directory, for 
               example, RTBarabasi20.conf and RTWaxman.conf. Please refer to 
               the conf_files directory for more examples.
  seedFile:    BRITE specific seed file to seed a psuedo-random number genrator 
               from BRITE.
  newseedFile: BRITE automatically generates a new seed file for you, if you 
               would like to randomize subsequent runs. If you would like
               this to happen automatically, simply use the same file for 
               seedFile and newseedFile. This way, BRITE will run with the 
               current seeds and then overwrite them for the next run.
  verbose:     Prints out the node and edge information in a similar format 
               to standard BRITE output.
  tracing:     Enables ascii tracing.
  nix:         Enables nix-vector routing. Global routing is used by default.

Usage

The brite-generic-example can be referenced to see basic usage of the BRITE interface. In summary, the BriteTopologyHelper is used as the interface point by passing in a BRITE configuration and seed file. The BRITE generated nodes and edges can then be accessed through this helper to create ns-3 nodes and edges.

Within the brite-generic-example, assigning IPs and creating applications are done fairly simply, as topology generation is the main topic of the BRITE interface. It is very likely that the user will need to change the way in which IP addresses are assigned or applications are installed.

A note on BRITE seed files

BRITE accepts a seed file to seed its psuedo-random number generator. It also spits out a new seed file after every run -- overwriting your old seed file -- in case you wish to randomize subsequent runs. Finally, it saves the most recently used seed file in a file called "last_seed_file." I didn't like the way this was done, specifically the overwriting bit, so I changed it in the ns-3 interface. You still pass in a seed file, but you also pass in another file for BRITE to write the new seed file. This keeps BRITE from overwriting your seed file. I believe this makes it easier to run the exact same simulation over and over. I think this is important. Finally, if you wish to overwrite the seed file each run, randomizing each subsequent run as before, you can simply pass in the same file name for the seed file and new seed file in ns-3.