Main Page - Current Development - Developer FAQ - Tools - Related Projects - Project Ideas - Summer Projects
Installation - Troubleshooting - User FAQ - HOWTOs - Samples - Models - Education - Contributed Code - Papers
This is a detailed installation guide for ns-3. Basic installation instructions can be found in the ns-3 tutorial (see Getting Started chapter).
ns-3 is primarily developed on GNU/Linux platforms, and the minimal requirements to run basic simulations are a gcc or clang compiler and Python interpreter (details on versions below).
ns-3 is supported and currently tested on the following primary platforms:
The minimum Python version supported is 2.7 or greater (version 2), or version 3.4 or greater (version 3).
By supported, we mean that the project tries to support most or all of the build options on these platforms unless there is a good reason to exclude the option; and at least the debug build will compile. If you intend to do serious work using ns-3, and are forced by circumstances to use a Windows platform, consider virtualization of a popular Linux platform or using Windows Subsystem for Linux.
The following platforms are lightly supported:
Some aspects of ns-3 depend on Unix (or specifically Linux) support, such as the emulation or TapBridge features, and those components are not enabled on the Windows or MacOS versions cited above.
Additional maintainers are invited to make more platforms, compilers and environments supported.
The Eclipse IDE is not an officially supported platform, but some developers use it and have compiled a HOWTO.
NetBeans is not officially supported either, but there is a HOWTO as well.
Same rule applies to Qt Creator; it's not officially supported, but there are developers that use it and HOWTO is available.
There are a few options that are not enabled by default and are not available on all platforms. At the end of the configuration process (explained below), the status of these options are shown as detected by a waf script:
---- Summary of optional NS-3 features:Python Bindings : not enabled (Python library or headers missing)BRITE Integration : not enabled (BRITE not enabled (see option --with-brite))NS-3 Click Integration : not enabled (nsclick not enabled (see option --with-nsclick))GtkConfigStore : not enabled (library 'gtk+-2.0 >= 2.12' not found)XmlIo : not enabled (library 'libxml-2.0 >= 2.7' not found)Threading Primitives : enabledReal Time Simulator : enabledEmulated Net Device : not enabled (<netpacket/packet.h> include not detected)Network Simulation Cradle : not enabled (architecture None not supported)MPI Support : not enabled (option --enable-mpi not selected)NS-3 OpenFlow Integration : not enabled (Required boost libraries not found)SQlite stats data output : not enabled (library 'sqlite3' not found)Tap Bridge : not enabled (<linux/if_tun.h> include not detected)PyViz visualizer : not enabled (Python Bindings are needed but not enabled)Use sudo to set suid bit : not enabled (option --enable-sudo not selected)Build tests : not enabled (defaults to disabled)Build examples : not enabled (defaults to disabled)GNU Scientific Library (GSL) : not enabled (GSL not found)
Generally if the platform is missing some requirement for an option it is marked as "not enabled." Note that "disabled by user request" will be shown when the user explicitly disables a feature (such as "--disable-python"); and if a feature defaults to disabled this will also be noted (e.g., option --enable-sudo not selected).
The table below is meant to help sort out the different features and on which platforms they are supported. This table reflects the status as of ns-3.15 and may have changed since then:
Option | Linux | FreeBSD | Mac OS X |
---|---|---|---|
Optimized build | Y | Y | Y |
Python bindings | Y | Y | Y |
Threading | Y | Y | Y |
Real-time simulator | Y | Y | N |
Emulated Net Device | Y | N | N |
Tap Bridge | Y | N | N |
Network simulation cradle | Y1 | ? | N |
Static builds | Y | Y | Y |
Key: Y = supported; N = not supported; ? = unknown; dev = support in ns-3-dev (next release)
Notes:
The core of ns-3 requires a gcc/g++ installation of 4.9 or greater (Linux), or a recent version of clang compiler (OS X, Linux, or BSD), and Python 2.7 or greater. As mentioned above, different options require additional support. This is a list of packages (for Debian/Ubuntu systems) that are needed to support different ns-3 options. Note that other distributions (e.g., Fedora, FreeBSD) may have different package names or capitalization (e.g. ImageMagik). Installation should be similar for Red Hat/Fedora based systems, with "yum" replacing "apt-get", but some differences exist, so below is a guide for both Ubuntu (should generally apply to Debian) and Fedora/RedHat-based systems:
Note: CentOS version 6 series (currently 6.8) requires an upgrade of both gcc and Python to meet current ns-3 requirements. See these instructions if you need to upgrade: https://www.nsnam.org/bugzilla/show_bug.cgi?id=2667#c1
The below instructions are based on a CentOS 6.6 install in November 2014; other RedHat/Fedora-based installs are likely similar.
yum install gcc-c++ python
yum install python-devel
The following additional packages add functionality to the build or documentation.
yum install qt5-devel
yum install mercurial
yum install doxygen graphviz ImageMagick
yum install python-sphinx dia texlive texlive-latex
yum install openmpi openmpi-devel
yum install tcpdump wireshark
yum install sqlite sqlite-devel
yum install libxml2 libxml2-devel
yum install uncrustify
yum install boost-devel
This is a bit more involved due to lack of package support in the standard repositories.
yum install graphviz graphviz-devel python-setuptools-devel ipython sudo easy_install pygraphviz
Some additional packages are needed (goocanvas and pygoocanvas). It is suggested to enable the RPMForge repo as described here: http://wiki.centos.org/AdditionalResources/Repositories/RPMForge. Then, try this:
yum install goocanvas pygtk2-devel
Then obtain the RPM for pygoocanvas and pygoocanvas-devel from here: http://li.nux.ro/download/nux/dextop/el6/x86_64/
rpm -ivh pygoocanvas-0.14.1-3.el6.nux.x86_64.rpm rpm -ivh pygoocanvas-devel-0.14.1-3.el6.nux.x86_64.rpm
Or, if you prefer, build pygoocanvas from source code found here: https://wiki.gnome.org/Projects/PyGoocanvas
Note, if you perform this install successfully on a CentOS server that does not have a desktop installed (i.e. a CentOS 'minimal install'), you will still not be able to see pyviz enabled; you will see the configuration report:
PyViz visualizer : not enabled (Missing python modules: gtk)
because the Python gtk module opens the display upon import.
yum install git
yum install gsl gsl-devel
yum install gtk2 gtk2-devel
yum install gdb valgrind
The following list of packages should be accurate for Ubuntu 16.04 release; other releases or other Debian-based systems may slightly vary.
apt-get install gcc g++ python
Note: Ubuntu 14.04 LTS release requires upgrade to gcc-4.9 from default gcc-4.8. More recent Ubuntu versions are OK. The instructions at this link: http://askubuntu.com/questions/466651/how-do-i-use-the-latest-gcc-on-ubuntu?answertab=votes#tab-top have been found to work.
apt-get install gcc g++ python python-dev
apt-get install mercurial python-setuptools git
apt-get install qt5-default
apt-get install python-pygraphviz python-kiwi python-pygoocanvas libgoocanvas-dev ipython
apt-get install gir1.2-goocanvas-2.0 python-gi python-gi-cairo python-pygraphviz python3-gi python3-gi-cairo python3-pygraphviz gir1.2-gtk-3.0 ipython ipython3
apt-get install openmpi-bin openmpi-common openmpi-doc libopenmpi-dev
apt-get install autoconf cvs bzr unrar
apt-get install gdb valgrind
apt-get install uncrustify
apt-get install doxygen graphviz imagemagick apt-get install texlive texlive-extra-utils texlive-latex-extra texlive-font-utils texlive-lang-portuguese dvipng
apt-get install python-sphinx dia
Note: Sphinx version >= 1.12 required for ns-3.15. To check your version, type "sphinx-build". To fetch this package alone, outside of the Ubuntu package system, try "sudo easy_install -U Sphinx".
apt-get install gsl-bin libgsl2 libgsl-dev
apt-get install flex bison libfl-dev
apt-get install tcpdump
apt-get install sqlite sqlite3 libsqlite3-dev
apt-get install libxml2 libxml2-dev
apt-get install cmake libc6-dev libc6-dev-i386 libclang-dev llvm-dev automake pip install cxxfilt
and you will want to install castxml and pygccxml as per the instructions for python bindings (or through the bake build tool as described in the tutorial). The 'castxml' package provided by Ubuntu 18.04 and earlier is not recommended; a source build (coordinated via bake) is recommended.
Note: Ubuntu 16.04 and systems based on it (e.g. Linux Mint 18) default to an old version of llvm (3.8). Users of Ubuntu 16.04 will want to explicitly install a newer version by specifying 'libclang-6.0-dev' and 'llvm-6.0-dev'.
apt-get install libgtk2.0-0 libgtk2.0-dev
apt-get install vtun lxc
apt-get install libboost-signals-dev libboost-filesystem-dev
The following list of packages should be aligned with recent Fedora releases; other releases may slightly vary. Note that these distributions sometimes change the package structure over time.
Release-specific issues
Required and optional packages
dnf install gcc gcc-c++ python
dnf install gcc gcc-c++ python python-devel
dnf install mercurial git
dnf install gsl gsl-devel
dnf install qt5-devel
Prior to ns-3.29, use GTK+ version 2:
dnf install gtk2 gtk2-devel
Starting with ns-3.29, use GTK+ version 3:
dnf install gtk3 gtk3-devel
dnf install gdb valgrind
dnf install doxygen graphviz ImageMagick
dnf install python-sphinx dia texlive texlive-latex texlive-fncychap texlive-capt-of texlive-tabulary texlive-eqparbox
Note: Sphinx version >= 1.12 required for ns-3.15. To check your version, type "sphinx-build". To fetch this package alone, outside of the Fedora package system, try "sudo easy_install -U Sphinx"
dnf install flex bison
dnf install tcpdump
dnf install sqlite sqlite-devel
dnf install libxml2 libxml2-devel
dnf install uncrustify
dnf install openmpi openmpi-devel
dnf install boost-devel
dnf install redhat-rpm-config goocanvas-devel graphviz graphviz-devel python-setuptools python-kiwi pygoocanvas ipython easy_install pygraphviz
pygobject3-devel python3-gobject gobject-introspection-devel goocanvas2-devel graphviz-devel graphviz ipython easy_install pygraphviz
dnf install cmake libclang-devel llvm-devel llvm-static pip install cxxfilt
and you will want to install gccxml and pygccxml as per the instructions for python bindings (or through the bake build tool as described in the tutorial).
dnf install patch autoconf cvs
The following list of packages should be accurate for Gentoo as of 04/22/2010 (please note, this is quite some time ago-- an update would be welcome); due to possible changes in USE-flags or package names the list may slightly vary.First of all, become root as usual.
USE="threads -nocxx nptl" emerge -uavN gcc python
emerge -av --noreplace mercurial
USE="curl" emerge -uavN bzr
emerge -av --noreplace gtk+:2
emerge -av --noreplace gdb valgrind
USE="extra graphics png" emerge -uavN texlive USE="cairo graphviz latex png svg" emerge -uavN doxygen imagemagick dia
emerge -av --noreplace flex bison
emerge -av --noreplace goocanvas
USE="-nocxx nptl" emerge -uavN gcc:3.4
emerge -av --noreplace tcpdump
or you may prefer
emerge -av --noreplace wireshark
USE="threadsafe" emerge -uavN sqlite:3
emerge -av --noreplace libxml2
ACCEPT_KEYWORDS="~x86" emerge -av --noreplace pygraphviz kiwi pygoocanvas ipython
ACCEPT_KEYWORDS="~x86" emerge -av --noreplace uncrustify
USE="cairo curl extra graphics graphviz latex -nocxx nptl png svg threads threadsafe" emerge -uavN bison bzr dia doxygen flex gcc gcc:3.4 goocanvas gtk+:2 imagemagick libxml2 mercurial python ipython sqlite:3 tcpdump texlive valgrind wireshark
Many versions of FreeBSD provide gcc compiler. The latest version of gcc maintained for FreeBSD is 4.2.1. ns-3 (as of ns-3.18.1 release) builds on gcc-4.2.1 and clang-3.3 for FreeBSD.
To use clang, one must set the 'CC=clang' and 'CXX=clang++' environment variables at compile time, such as:
CC=clang CXX=clang++ ./waf configure
or set these in your environment variables.
ns-3.18.1 release and higher are supported by the clang/llvm compiler used in Xcode. To install (last tested for OS X El Capitan), one can follow these instructions:
Note to Anaconda users: If you have installed Anaconda, you may encounter a build problem such as:
"../src/wifi/model/wifi-phy.cc:65:46: error: no matching constructor for initialization of 'WifiPhy::ChannelToFrequencyWidthMap' (aka 'map<pair<unsigned short, ns3::WifiPhyStandard>, pair<unsigned int, unsigned int> >') WifiPhy::ChannelToFrequencyWidthMap WifiPhy::m_channelToFrequencyWidth = ^ /usr/include/c++/4.2.1/bits/stl_map.h:188:9: note: candidate constructor template not viable: requires 2 arguments, but 79 were provided map(_InputIterator __first, _InputIterator __last) ^
This can be worked around by configuring Waf to use the system Python instead of the Python version provided by Anaconda. At the Waf configuration stage, try:
./waf --python=/usr/bin/python configure ...
When using build.py, the argument can be passed as follows:
./build.py --enable-examples --enable-tests -- --python=/usr/bin/python
See: issue 2778 in the ns-3 tracker for more information.
For OS X 10.8 (Mountain Lion) and earlier, using Xcode 4 series, please see HOWTO_get_ns-3_running_on_Mac_OS_X_(10.6.2_Intel) and follow steps 1 and 2 (prerequisites) and continue reading below if you want to work with a released version, and follow all steps if you want to work with a development version of ns-3.
There are two basic options for Windows support:
Bake is a new tool for installing, building and finding out the missing requirements for ns-3 in your own environment.
To use Bake you need to have at least Python (preferably 2.6 and above) and mercurial in your machine (see the section Prerequisites above to see how to install these).
First you need to download Bake using Mercurial, go to where you want Bake to be installed and call
hg clone http://code.nsnam.org/bake
It is advisable to add bake to your path.
export BAKE_HOME=`pwd`/bake export PATH=$PATH:$BAKE_HOME export PYTHONPATH=$PYTHONPATH:$BAKE_HOME
After that you can use Bake to find the missing packages, download build and install ns-3 and its modules.
To find out what is missing in your system and may be needed for installing ns-3 you can call bake check:
bake.py check
You should have seen something like:
> Python - OK
> GNU C++ compiler - OK
> Mercurial - OK
> CVS - OK
> GIT - OK
> Bazaar - OK
> Tar tool - OK
> Unzip tool - OK
> Unrar tool - OK
> 7z data compression utility - OK
> XZ data compression utility - OK
> Make - OK
> cMake - OK
> patch tool - OK
> autoreconf tool - OK
> Path searched for tools: /usr/lib64/qt-3.3/bin
/usr/lib64/ccache /usr/local/bin /usr/bin/bin/usr/local/sbin /usr/sbin
/sbin /user/dcamara/home/scripts/user/dcamara/home/INRIA/Programs/bin
/user/dcamara/home/INRIA/repos/llvm/build/Debug+Asserts/bin
Before downloading and building ns-3 you need to configure bake to inform it which are the modules you want added to ns-3, the standard distribution for example.
bake.py configure -e ns-3.26
Then to see the modules it has added, and the specific system requirements for this configuration, you can call bake show:
bake.py show
To download the modules, build and install you can call bake deploy
bake.py deploy
This will download the selected modules, all their dependencies and build ns-3 with all these independent modules. You can also perform this installation step by step, i.e. by calling download and build in different steps.
bake.py download bake.py build
The ns-3 code is available in Mercurial repositories on the server http://code.nsnam.org (look for the latest release e.g., "ns-3.26"). You can download a tarball of the latest release at http://www.nsnam.org/releases or you can work with our repositories using Mercurial. We recommend using Mercurial unless there's a good reason not to (See the end of this section for instructions on how to get a tarball release).
The simplest way to get started using Mercurial repositories is to use the ns-3-allinone environment. This is a set of scripts that manages the downloading and building of various subystems of ns-3 for you. We recommend that you begin your ns-3 adventures in this environment as it can really simplify your life at this point.
One practice is to create a directory called repos in one's home directory under which one can keep local Mercurial repositories. If you adopt that approach, you can get a copy of ns-3-allinone by typing the following into your Linux shell (assuming you have installed Mercurial):
cd mkdir repos cd repos hg clone http://code.nsnam.org/ns-3-allinone
As the hg (Mercurial) command executes, you should see something like the following displayed,
destination directory: ns-3-allinone requesting all changes adding changesets adding manifests adding file changes added 26 changesets with 40 changes to 7 files 7 files updated, 0 files merged, 0 files removed, 0 files unresolved
After the clone command completes, you should have a directory called ns-3-allinone under your ~/repos directory, the contents of which should look something like the following:
build.py* constants.py dist.py* download.py* README util.py
Notice that you really just downloaded some Python scripts. The next step will be to use those scripts to download and build the ns-3 distribution of your choice.
If you go to the following link: http://code.nsnam.org/ you will see a number of repositories. Many are the private repositories of the ns-3 development team. The repositories of interest to you will be prefixed with ns-3. Official releases of ns-3 will be numbered as ns-3.release.hotfix. For example, a second hotfix to a still hypothetical release nine of ns-3 would be numbered as ns-3.9.2 on this page.
The current development snapshot (unreleased) of ns-3 may be found at http://code.nsnam.org/ns-3-dev/. The developers attempt to keep these repository in consistent, working states but they are in a development area with unreleased code present, so you may want to consider staying with an official release if you do not need newly-introduced features.
Since the release numbers are going to be changing, we will stick with the more constant ns-3-dev here, but you can replace the string ns-3-dev with your choice of release (e.g., ns-3.26) in the text below. You can find the latest version of the code either by inspection of the repository list or by going to the Getting Started web page and looking for the latest release identifier.
To download the most common options type the following into your shell (remember you can substitute the name of your chosen release number instead of ns-3-dev)
./download.py -n ns-3-dev
After download process completes, you should have several new directories under ~/repos/ns-3-allinone:
build.py* constants.pyc download.py* nsc/ README util.pyc constants.py dist.py* ns-3-dev/ pybindgen/ util.py
Go ahead and change into ns-3-dev under your ~/repos/ns-3-allinone directory. You should see something like the following there:
AUTHORS examples/ RELEASE_NOTES utils/ wscript bindings/ LICENSE samples/ VERSION wutils.py CHANGES.html ns3/ scratch/ waf* doc/ README src/ waf.bat*
You are now ready to build the ns-3 distribution.
The process for downloading ns-3 via tarball is simpler than the Mercurial process since all of the pieces are pre-packaged for you. You just have to pick a release, download it and decompress it.
As mentioned above, one practice is to create a directory called repos in one's home directory under which one can keep local Mercurial repositories. One could also keep a tarballs directory. If you adopt the tarballs directory approach, you can get a copy of a release by typing the following into your Linux shell (substitute the appropriate version numbers, of course):
cd mkdir tarballs cd tarballs wget http://www.nsnam.org/release/ns-allinone-3.13.tar.bz2 tar xjf ns-allinone-3.13.tar.bz2
If you change into the directory ns-allinone-3.13 you should see a number of files:
build.py* ns-3.13/ pybindgen-0.15.0.795/ util.py constants.py nsc-0.5.2/ README
You are now ready to build the ns-3 distribution.
The first time you build the ns-3 project you should build using the allinone environment. This will get the project configured for youin the most commonly useful way.
Change into the directory you created in the download section above. If you downloaded using Mercurial you should have a directory called ns-3-allinone under your ~/repos directory. If you downloaded using a tarball you should have a directory called something like ns-allinone-3.13 under your ~/tarballs directory. Type the following:
./build.py
You will see lots of typical compiler output messages displayed as the build script builds the various pieces you downloaded. Eventually you should see the following magic words:
Build finished successfully (00:02:37) Leaving directory `./ns-3-dev'
Once the project has built you typically will not use ns-3-allinone scripts. You will now interact directly with Waf and we do it in the ns-3-dev directory and not in the ns-3-allinone directory.
To see valid configure options, type ./waf --help. The most important option is -d <debug level>. Valid debug levels (which are listed in waf --help) are: "debug" or "optimized". It is also possible to change the flags used for compilation with (e.g.):
CXXFLAGS="-O3" ./waf configure
or, alternately, the gcc compiler
CXX=g++-3.4 ./waf configure
Note: Unlike some other build tools, to change the build target, the option must be supplied during the configure stage rather than the build stage (i.e., "./waf -d optimized" will not work; instead, do
./waf -d optimized configure; ./waf
The resulting binaries are placed in build/<debuglevel>/srcpath. For example, in a debug build you can find the executable for the first.cc example as build/examples/first. You can debug the executable directly by:
./waf --shell cd build/debug/examples gdb ns-<version>-first-debug
Of course, you can run gdb in emacs, or use your favorite debugger such as ddd or insight just as easily. In an optimized build you can find the executable for the first.cc example as build/examples/ns-<version>-first-optimized.
In order to forcibly disable python bindings, you can provide the following option:
./waf --disable-python configure
In order to tell the build system to use the sudo program to set the suid bit if required, you can provide the following option:
./waf --enable-sudo configure
To start over a configuration from scratch, type:
./waf distclean
Or if you get stuck and all else fails:
rm -rf build
followed by changing back into ns-3-allinone and doing:
./build.py
will basically reset your build state.
To see all waf options:
./waf --help
ns-3 has unit tests that can be run to verify the installation:
./test.py
which should produce output like:
PASS: TestSuite histogramPASS: TestSuite ns3-wifi-interferencePASS: TestSuite ns3-tcp-cwndPASS: TestSuite ns3-tcp-interoperabilityPASS: TestSuite sample...
See this page.
See this page.
Older versions of ns-3, prior to 3.15, supported using cygwin to run on Windows platform.
There are three basic options for Windows support:
An alternative Windows platform is MinGW. There are maintainers who attempt to keep a subset of ns-3 running on MinGW, but it is not "officially" suppported. This means that bugs filed against MinGW will be addressed as time permits.
Cygwin can sometimes be problematic due to the way it actually does its emulation, and sometimes interactions with other Windows software can cause problems. If you do use Cygwin or MinGW; and use Logitech products, we will save you quite a bit of heartburn right off the bat and encourage you to take a look at the MinGW FAQ.
Search for "Logitech" and read the FAQ entry, "why does make often crash creating a sh.exe.stackdump file when I try to compile my source code." Believe it or not, the ``Logitech Process Monitor`` insinuates itself into every DLL in the system when it is running. It can cause your Cygwin or MinGW DLLs to die in mysterious ways and often prevents debuggers from running. Beware of Logitech software when using Cygwin.
联系客服