Motivation or the lack thereof…
Every time I get an invite to conduct a workshop on Network Simulation, the first thing people ask me is How to install ns3? I am almost always tempted to say RTFM politely, but I understand that it can be overwhelming for people using either ns3 or Linux for the first time. So this is a newbie guide to getting started with ns3 configuration and installation.
Part I: Install Prerequisites
First, I assume that you are running an Ubuntu 15.04 operating system (should work on other Ubuntu distributions as well), either Natively or using a Virtual Machine (VM) (A VM is strongly recommended if you don’t know what you are doing). You need to make sure that you have a working Internet connection at the time of install.
We start by installing the required packages and libraries before downloading and installing ns3. Go to the Ubuntu Launcher and search for Software & Updates. Check everything under Ubuntu Software, Other Software and Updates. You may be asked enter your password in order to effect a change. Click on Reload when you are asked to confirm reloading the repository cache.
Now open a Terminal by searching for it in the Ubuntu Launcher. Run the following commands in the Terminal:
First re-run the update just to be sure.
sudo apt-get update
Optionally, you can upgrade your currently installed Ubuntu packages by running the command:
sudo apt-get -y upgrade
Now install the following development libraries and dependencies by using the command:
sudo apt-get -y install gcc g++ python python-dev qt4-dev-tools mercurial bzr cmake libc6-dev libc6-dev-i386 g++-multilib gdb valgrind gsl-bin libgsl0-dev libgsl0ldbl flex bison libfl-dev tcpdump sqlite sqlite3 libsqlite3-dev libxml2 libxml2-dev libgtk2.0-0 libgtk2.0-dev uncrustify python-pygraphviz python-kiwi python-pygoocanvas libgoocanvas-dev
If you plan on using the Emulation features of ns3 install the Bridge & User Mode Linux Utilities: (Recommended)
sudo apt-get -y install vtun lxc bridge-utils uml-utilities
Finally, if you plan on building the ns3 Module and API documentation locally on your machine, install the following packages: (Optional, make take a while)
sudo apt-get -y install doxygen graphviz imagemagick texlive texlive-extra-utils texlive-latex-extra python-sphinx dia
Install Wireshark if you prefer a Graphical Protocol Analyzer to work with the .pcap files instead of the tcpdump (CLI tool).
sudo apt-get -y install wireshark
You can also install the Gnuplot plotting engine as ns3 has in-built support for generating graphs using Gnuplot. Gnuplot also has a graphical front-end interface called PlotDrop that may be useful for beginners for creating plots/graphs using a simple drag-and-drop interface. To install both the packages use:
sudo apt-get -y install gnuplot plotdrop
Part II: Install ns3 Stable Branch
In this section, we’ll install the ns3 stable release available at ns3 Releases. At the time of this writing, the latest available release of ns3 is ns-3.23. The stable release should serve the needs of most users and is the recommended install option. If you want to develop your own modules and contribute to ns3 development branch, then you’ll need the development branch. For development branch install instructions, skip this section and go to Part III.
Open a Terminal and run the following commands:
cd wget http://www.nsnam.org/release/ns-allinone-3.23.tar.bz2 tar xvjf ns-allinone-3.23.tar.bz2 cd ns-allinone-3.23
You should now see the following directory structure:
ls bake constants.py netanim-3.106 pybindgen-0.17.0.886 util.py build.py constants.pyc ns-3.23 README util.pyc
Now all that needs to be done is to build ns3 using the command:
./build.py --enable-examples --enable-tests
The build script outputs lot of information on the console and eventually you should see the build completed successfully message as shown below.
Part III: Install ns-3-dev branch
This section outline the installation of the ns3 development branch. Unlike the previous method (which used the ns3 tarball), to install the development branch, we make use of the bake tool. Bake can not only be used to fetch and build the development branch, but also to download/build ns3 extensions like NSC and DCE. First, we clone the bake mercurial repository using the hg command.
cd mkdir ns3 cd ns3 hg clone http://code.nsnam.org/bake cd bake
The bake tool has some additional package requirements which we’ll install next. To install the required packages, enter:
sudo apt-get -y install unrar-free autoconf cvs git unzip p7zip-full
Now export the bake environment variables using the following commands and then check bake to ensure that all dependencies are met
export BAKE_HOME=`pwd` export PATH=$PATH:$BAKE_HOME:$BAKE_HOME/build/bin export PYTHONPATH=$PYTHONPATH:$BAKE_HOME:$BAKE_HOME/build/lib ./bake.py check
Once the dependencies are satisfied, we proceed to configure the ns3 target branch. According to the ns3 website, there are four configuration targets available as follows:
- ns-3.23: Module corresponding to the release tarball in Part II.
- ns-3-dev: Module using the development code tree
- ns-allinone-3.23: Module with additional features such as click routing, openflow for ns-3, and the Network Simulation Cradle.
- ns-3-allinone: Development code for the released version of the allinone module.
We will work with ns-3-dev, and configure bake to use the development branch by using the configure command as below:
./bake.py configure -e ns-3-dev
Now proceed to download the ns-3-dev branch by issuing the command
./bake.py download -vvv
And finally build the ns-3-dev branch by using
./bake.py build -vvv
You can now use the waf tool to build your simulation scripts. If you installed the release version,
cd ns-3.23 ./waf --run scratch/scratch-simulator
If you installed the development branch,
cd source/ns-3-dev ./waf --run scratch/scratch-simulator
And that’s it, you now have a working ns3 installation.
Disclaimer: This tutorial is designed for an Ubuntu 15.04 distribution.
Getting Started — Tutorial. Retrieved May 23, 2015, from https://www.nsnam.org/docs/release/3.23/tutorial/html/getting-started.html
Installation – Nsnam. Retrieved May 4, 2015, from https://www.nsnam.org/wiki/Installation#Ubuntu.2FDebian