Getting Started with VODSim

VODSim is shipped as a supplement to an existing ns-3.18+ installation (tested until ns-3.20 and likely both up- and backwards compatible with proper build script modification). Getting started is relatively easy:

  1. If you don't have ns-3 yet, download it from the project's homepage http://www.nsnam.org/ and extract it.
  2. Download the latest version from the "Files" / "Dateien" section from above.
  3. Extract the contents of the archive to your ns-3 installation. Just move VODSim into your ns-3 folder (usually ns-allinone-3.*/ns-3.*) and extract it. (Extraction will replace one wscript file in src/topology-read and otherwise only add files.)
  4. (Re)configure your ns3 installation: cd into the main ns3 folder and execute: ./waf -d debug configure or ./waf -d release configure. To enable MPI support, add the switch --enable-mpi. Then build using ./waf build.

To get an idea of the interconnections in the model, you may want to have a look at our paper (see the index page for a link). You may then want to read the documentation found in src/bittorrent/examples/Quickstart Guide.txt and src/bittorrent/helper/Story-Reference.txt to get an idea of how to get the whole thing running.

VODSim ships with a small collection of example scenarios, to which we refer as "stories". To start these examples, which are located in the input/bittorrent/stories folder, you need to untar the provided "torrent data" files in input/bittorrent/torrent-data; they are 110MB in size combined when extracted. To set up an (e.g., WiFi-based) simulation without a story, have a look at the example file src/bittorrent/examples/vodsim-no-story.cc.

Have fun :=)

New functionality since the wns3 / SIMUTOOLS paper

VODSim meanwhile offers a few bits of functionality in addition to those mentioned in our main wns3'12 (SIMUTOOLS'12) publication. These are:

  • MPI support (manually per client and automatic via the Story functionality)
  • Multiple clients on one node (you can use the client's message exchange mechanisms to couple them)
  • Setup of (simple) background traffic via the Story funtionality
  • A simple global metrics gatherer for easier output generation

Current version: VODSim 0.3.4.2 (2015-01-27) (Version History)

Bug fix

VODSim 0.3.4.0 and 0.3.4.1 were successfully built on some compiler/platform configurations, whilst compilation failed on other systems. This was due to a class duplication bug (BriteTopologyHelper was recently introduced in a different version by mainline ns-3). This release fixes the issue by renaming the file and class names of the VODSim version of the helper. You need not upgrade to this version if you are not experiencing compliation errors.

Known issue: Broken sample scenarios in ns-3.21 (NOT in ns-3.20)

Whilst VODSim works great with ns-3 up to version ns-3.20, there seems to be a problem with the NIX Vector implementation in ns-3.21 which causes at least the sample VODSim scenarios to fail. While we have an investigation of the causes on our TODO list, it is currently not our priority. We suggest that you continue using ns-3.20 or try setting up simulations without NIX Vector routing (see the BRITETopologyHelper on how to change routing in the Story file-driven scenarios).

If anyone has a fix for the problem, we would greatly appreciate if you could share it with us (just mail René at ). Thanks!

Doxygen Documentation

VODSim is extensively documented, both via in-source comments and Doxygen documentation. As generating a doxygen documentation for ns-3 is quite a lengthy process, we pre-built an (introspected) version of the documentation and uploaded it to the "Dateien" / "Files" section. The file just contains the documentation for VODSim. Don't worry about possibly differing version numbers - the documentation does not change that often so it's safe to have a look at older versions ;-) - Just open the file named namespacens3_1_1bittorrent.html for a list of all classes.

The name

VODSim stands for "Video-On-Demand Simulation", as it was originally intended to be used for the simulation of BitTorrent-based VoD protocols. Although it never came to that specific project, the functionality is still integrated. Just have a look at the documentation of the BitTorrentVideoClient class. VoD protocols are by default not activated.

License

VODSim is provided under the terms of the GNU General Public License v2.

Get in touch!

We appreciate any researchers using VODSim for their own projects getting in contact with us. We like to see how and for which purposes VODSim is used and are always open for bug hunting and project collaborations!

For any (potential) bug reports, please always submit the used Story file, the torrent and the exact size (in bytes) of the payload files (if you didn't use our shipped example files). Additionally, it'd be great if you could include the output of the simulation debug build (./waf -d debug configure) started with both stdout and stderr redirected to one file, e.g., using './waf --run "vodsim [...]" 2>&1 | tee [output file]'. Please note that we will not respond to bug reports not containing at least the used Story file. Thank you!

Your contact for the simulation model in general: René Glebke ()
Your contact for emulation and SliceTime bindings: Alexander Hocks ()