Getting Started

Portability

https://travis-ci.org/named-data-ndnSIM/ndnSIM.svg?branch=test-travis-ci

ndnSIM 2.0 has been successfully compiled and used on following platforms:

  • Ubuntu Linux 12.04 (see the note)
  • Ubuntu Linux 14.04 (32- and 64-bit platform)
  • Ubuntu Linux 16.04 (32- and 64-bit platform)
  • OS X 10.9
  • OS X 10.10
  • OS X 10.11

Note

ndnSIM is currently cannot be compiled on Ubuntu Linux 12.04 with the packaged boost libraries (there is an issue with boost 1.48 and gcc 4.6). It is still possible to compile ndnSIM on this platform, but either compiler or boost libraries (or both) need to get upgraded.

More recent version of boost can be installed from “Boost C++ Libraries” team PPA:

sudo apt-get install python-software-properties
sudo add-apt-repository ppa:boost-latest/ppa
sudo apt-get update
sudo apt-get install libboost1.55-all-dev

# add  --boost-libs=/usr/lib/x86_64-linux-gnu  to ./waf configure
# ./waf configure --boost-libs=/usr/lib/x86_64-linux-gnu

Make sure that all other version of boost libraries (-dev packages) are removed, otherwise compilation will fail.

Prerequisites

1. Core dependencies

  • python >= 2.6
  • libsqlite3
  • libcrypto++
  • pkg-config
  • Boost libraries >= 1.49

Note

If you do not have root permissions to install boost, you can install it in your home folder. However, you need to be make sure that libboost_iostreams library is successfully compiled and is installed. Please refer to the following example for the hints how to successfully compile and install boost libraries on Ubuntu Linux.

Following are the detailed steps for each platform to install the compiler, all necessary development tools and libraries, and ndn-cxx prerequisites.

  • OS X

    • OS X with MacPorts:
    sudo port install pkgconfig boost sqlite3 libcryptopp
    • OS X with HomeBrew:
    brew install boost cryptopp pkg-config libxml2
brew link --force libxml2

  • Linux

    • Ubuntu Linux
    sudo apt-get install build-essential libsqlite3-dev libcrypto++-dev

# For Ubuntu 12.04
sudo apt-get install python-software-properties
sudo add-apt-repository ppa:boost-latest/ppa
sudo apt-get update
sudo apt-get install libboost1.55-all-dev

# For all other Ubuntu versions
sudo apt-get install libboost-all-dev
    • Fedora Linux
    sudo yum install gcc-g++ git sqlite-devel cryptopp-devel boost-devel

    Note

    ndnSIM requires boost version at least 1.49. Many linux distribution (Fedora 16, 17 at the time of this writing) ship an old version of boost, making it impossible to compile ndnSIM out-of-the-box. Please install the latest version, following these simple instructions.

2. Dependencies for NS-3 Python bindings

If you are planning to use NS-3 python bindings, a number of additional dependencies should be installed. For example, in order to run visualizer module, the following should be installed:

  • OS X

    • OS X with MacPorts:

      sudo port install  py27-pygraphviz py27-goocanvas

# If you add NDN macports repository, as described in
# http://named-data.net/doc/NFD/current/INSTALL.html#install-nfd-using-the-ndn-macports-repository-on-os-x
# you will be able to install another useful python module
# sudo port install py27-kiwi

    • OS X with HomeBrew

      Currently, there are many missing dependencies, so it is impossible to use visualizer module with HomeBrew. Use MacPorts instead.

  • Linux

    • Ubuntu Linux

      sudo apt-get install python-dev python-pygraphviz python-kiwi
sudo apt-get install python-pygoocanvas python-gnome2
sudo apt-get install python-rsvg ipython

    • Fedora Linux

      sudo yum install pygoocanvas python-kiwi graphviz-python

# easy_install method, since pygraphviz is not (yet?) packaged into Fedora (https://bugzilla.redhat.com/show_bug.cgi?id=740687)
sudo yum install graphviz-devel
sudo yum install python-pip
sudo easy_install pygraphviz

Downloading ndnSIM source

ndnSIM package consists of three pieces:

  • a custom branch of NS-3 that contains a few useful patches
  • a customized python binding generation library (necessary if you want to use NS-3’s python bindings and/or visualizer module)
  • the source code of ndnSIM module
  • modified source code of ndn-cxx library and NDN Forwarding Daemon (NFD), attached to ndnSIM git repository as git submodules

The following commands download all pieces from GitHub repositories:

mkdir ndnSIM
cd ndnSIM
git clone https://github.com/named-data-ndnSIM/ns-3-dev.git ns-3
git clone https://github.com/named-data-ndnSIM/pybindgen.git pybindgen
git clone --recursive https://github.com/named-data-ndnSIM/ndnSIM.git ns-3/src/ndnSIM

The last command downloads ndnSIM source code and source code of all submodules (i.e., ndn-cxx and NFD). If you previously cloned without --recursive flag, the correct versions of submodules can be retrieved using:

git submodule update --init

The same command should be run to update submodules when there are new changes available.

Note

A few modification to the base NS-3 and pybindgen are necessary to run successfully compile and run ndnSIM. Some of the changes are specific to ndnSIM and some are bugfixes that we are submitting to NS-3 upstream. We also periodically update repository with the new NS-3 releases, usually in form of rebasing (and if necessary updating or eliminating) our custom patches on top of the released commits.

Compiling and running ndnSIM

ndnSIM uses a standard NS-3 compilation procedure. Normally the following commands should be sufficient to configure and build ndnSIM with python bindings enabled:

cd <ns-3-folder>
./waf configure --enable-examples
./waf

On OS X (with MacPorts), you may need to modify the configure command to use MacPorts version of python:

cd <ns-3-folder>
./waf configure --with-python=/opt/local/bin/python2.7 --enable-examples
# or run ``sudo port select python python27``
./waf

Note

On OS X configuration stage may get stuck at detecting gtk module. Make sure you have XQuartz installed or disable python as described in the following instructions.

Python bindings is an optional and not very stable feature of NS-3 simulator. It is possible to disable python bindings compilation either to speed up compilation or to avoid certain compilation errors (e.g., “Could not find a task generator for the name ‘ns3-visualizer’”):

cd <ns-3-folder>
./waf configure --disable-python --enable-examples
./waf

For more configuration options, please refer to ./waf --help.

Simulating using ndnSIM

  • Example simulation scenarios

    When NS-3 is configured with --with-examples flag, you can directly run all examples described in examples section of this tutorial. For example, to run ndn-simple.cpp scenario, you can run the following command:

    ./waf --run=ndn-simple

    To run ndn-grid.cpp scenario:

    ./waf --run=ndn-grid

    To run the sample simulation scenarios with the logging module of NS-3 enabled (note that this will work only when NS-3 is compiled in debug mode):

    NS_LOG=ndn.Producer:ndn.Consumer ./waf --run=<scenario name>

    If you have compiled with python bindings, then you can try to run these simulations with visualizer:

    ./waf --run=ndn-simple --vis

    or:

    ./waf --run=ndn-grid --vis

    Note

    Do not forget to configure and compile NS-3 in optimized mode (./waf configure -d optimized) in order to run actual simulations.

  • Real experimentation

    Simulation scenarios can be written directly inside NS-3 in scratch/ or src/ndnSIM/examples folder.

    Alternative and a recommended way is to write simulation scenarios in a separate repository, not related to either NS-3 or ndnSIM. For example, you can use the following template to write your extensions, simulation scenarios, and metric processing scripts: http://github.com/cawka/ndnSIM-scenario-template:

    mkdir ndnSIM
cd ndnSIM
git clone https://github.com/named-data-ndnSIM/ns-3-dev.git ns-3
git clone https://github.com/named-data-ndnSIM/pybindgen.git pybindgen
git clone --recursive https://github.com/named-data-ndnSIM/ndnSIM.git ns-3/src/ndnSIM

# Build and install NS-3 and ndnSIM
cd ns-3
./waf configure -d optimized
./waf

sudo ./waf install
cd ..

git clone https://github.com/named-data-ndnSIM/scenario-template.git scenario
cd scenario
export PKG_CONFIG_PATH=/usr/local/lib/pkgconfig
export LD_LIBRARY_PATH=/usr/local/lib:$LD_LIBRARY_PATH

./waf configure

./waf --run <scenario>

    For more detailed information, refer to README file.