User FAQ

Main Page - Roadmap - Summer Projects - Project Ideas - Developer FAQ - Tools - Related Projects

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

The Network Simulator ns-3: Frequently Asked Questions (FAQ)

This wiki page is devoted to questions for users of the simulator. There is a similar Developer_FAQ page for ns-3 software developers and maintainers.

What is the difference between ns-2 and ns-3?

ns-2 is a popular discrete-event network simulator developed under several previous research grants and activities. It remains in active use and will continue to be maintained.

ns-3 is a new software development effort focused on improving upon the core architecture, software integration, models, and educational components of ns-2. The project commenced in July 2006 and the first release was made on June 30, 2008.

Will ns-2 scripts run on ns-3?

No. ns-2 uses OTcl as its scripting environment. ns-3 uses C++ programs or python scripts to define simulations.

I found a bug in ns-3. How do I report it?

Please consult this page. Also, please consider fixing the bug, not just reporting it :)

Bug Priorities

Bugs may be assigned a priority from one (P1) to five (P5), with the following meanings:

1. P1 --- The most severe bugs that will block the upcoming release of ns-3 if they are not fixed. Bugs are promoted to P1 by the maintainers based on their severity and impact on the product.
2. P2 --- Very serious bugs that, for some reason, cannot be fixed in the upcoming release. These bugs automatically become P1 when the upcoming release is shipped.
3. P3 --- General priority level for bugs.
4. P4 --- The bug level
5. P5 --- The default priority level chosen by Bugzilla.

In addition, a severity may be assigned to a bug

1. Blocker -- Corresponds to a P1 bug: P1 <=> Blocker;
2. Critical -- Corresponds to a P2 bug P2 <=> Critical;
3. Major
4. Normal
5. Minor
6. Trivial
7. Enhancement

Downloading ns-3

Download a stable release

ns-3 makes unpackaged source releases only at this time. Downloading the latest stable release should be straightforward, from the main project page. Archived older releases are also linked there.

Download the development tree

Some people may want to work with our development branch, which is ns-3-dev. We've introduced a framework to ease working with the development version. It is called ns-3-allinone. As of early January 2009, downloading of optional components to ns-3 has been delegated to a download script in this ns-3-allinone framework.

Using the development tree requires mercurial. Try the following steps:

 hg clone http://code.nsnam.org/ns-3-allinone
 cd ns-3-allinone
 ./download.py

You should then have the following directory structure in ns-3-allinone/

 BRANCH                download.py*          pybindgen/
 build.py*             ns-3-dev/             README 
 constants.py          ns-3-dev-ref-traces/  util.py 
 constants.pyc         nsc/                  util.pyc 

Users will want to then invoke build.py to start a coordinated build.

 ./build.py

If all goes well, one can cd into ns-3-dev and run the unit tests and regression tests:

 cd ns-3-dev
 ./waf --check
 ./waf --regression

Mercurial

merging a separate repository with a main repository

Q. I want to incorporate some code from a mercurial branch (repository) that is off the main repository.

A. (from Mathieu Lacage)

You can create a local clone of the repository and pull into it from the main repository: you can push these yourself by creating a local clone of that repo and then pushing it back to the main repo. It will keep the original history; e.g.:

hg clone http://code.nsnam.org/mathieu/ns-3-ptr
cd ns-3-ptr
# merge from main ns-3 repository into this other repository
hg pull http://code.nsnam.org/ns-3
hg merge

Pushing this new merged repository into another repository will then keep the original change history:

# push back-- must have privileges to push to the repository
hg push ssh://code@code.nsnam.org/repos/ns-3

working with subsets of repositories

Q. Is there a way with mercurial to pull/merge/push subsets of the repositories? For instance, suppose I wanted only to grab the samples directory from a repo and merge that alone.

A. (from Mathieu Lacage) You cannot cherry-pick individual changesets other than by exporting them to patches first. The reason is that each Changeset contains a single hash which is, among others, based on the hash of the 'parent' changeset hash. So, if you 'reparent' a changeset, you change its hash id because the id of the parent changes. If the hash id of a changeset changes, it is a different changeset so, mercurial cannot really manage these individual changesets. There is, however, the transplant extension that lets you do just that.

So, the idea is that merging happens from one repo to another, and cannot be done on a sub-dir basis. The other alternatives are:

1) the latest mercurial has support for in-repo branches: you can maintain multiple branches within a single repository but each branch represents a branch for the whole repository.

2) the latest mercurial contains the forest extension which is a way to make mercurial manage a 'forest' of repos: each repo is independent but they also behave as a single big repo through the forest extension.

WAF (build process)

See also the WAF developers FAQ

How to build NS-3

First choose the debug level that you want. To select the debug level, you have to configure NS-3 first with the command:

./waf configure -d debuglevel

Where debuglevel is one of:

• debug (the default): builds NS-3 with the most suited options for debugging. This includes disabling of all optimization, since it confuses the debugger and makes debugging very difficult. It also activates NS-3 internal assertions to catch all programming errors, as well as enabling support for debugging messages (NS_DEBUG and NS_DEBUG_UNCONDITIONAL). This mode should be used initially for development, until you are happy that the code runs correctly and does not contain any serious programming mistake.
• optimized: this compiles NS-3 with optimization, but disabled assertions and debugging messages. Use this when the program is correct and you just want to extrat results.

It is also possible to customize the C compilation flags through the CXXFLAGS environment variable. Example:

CXXFLAGS='-O3' ./waf configure -d optimized

See here for a list of additional environment variables that can be used to control waf configure. After configuration, NS-3 can be built with the command:

./waf build

[ The waf command build can be omitted, since it is the default command. ]

WARNING: even though the -d option is accepted outside "waf configure", it is completely ignored unless applied together with the configure command.

Note:: If you have a multicore machine, you can accelerate the building and linking process by using the -j option. For instance, for a machine with four cores:

./waf -j4

How to run NS-3 programs

First, the builtin NS-3 unit tests can be executed with the command:

./waf --check

To run the remaining programs, there are three different ways to do it.

1. The hard way: because NS-3 is built as a set of shared library (dll) files, it requires you to manually configure LD_LIBRARY_PATH, PATH, or DYLD_LIBRARY_PATH, depending on your platform, to make them point to each ns-3 module directory. Only then can you run the programs that were built as build/<debuglevel>/path/to/program.
2. Easy way #2: run ./waf shell. You will then have a new nested shell from which programs can be run, e.g. gdb ./build/debug/examples/simple-p2p.
3. Easy way #1: ./waf --run programname, or ./waf --run "programname args". To find out available program names, run ./waf --run non-existent-program-name.

How to run NS-3 programs under another tool

For running ns-3 programs with gdb or valgrind, try the following:

• Use the "command-template" argument; e.g.
  • waf --run csma-cd-one-subnet --command-template="gdb %s"
  • waf --run csma-cd-one-subnet --command-template="valgrind %s"
• To run the unit tests (waf --check) under gdb:
  • ./waf --command-template="gdb %s" --run run-tests

How to configure cygwin

cygwin works reasonably-well by default: just make sure you grab the cygwin installer from http://www.cygwin.com/setup.exe cygwin includes support for mercurial, gcc, and, python so, nothing else should be needed.

How to configure mingw

mingw requires more work than cygwin to setup. You need to grab:

• the core mingw system: http://downloads.sourceforge.net/mingw/MinGW-5.1.4.exe
• python: http://www.python.org/ftp/python/2.5.2/python-2.5.2.msi

Since msvc cannot build ns-3, you need to tell WAF to use your mingw g++ compiler instead: waf configure --check-cxx-compiler=g++ will do this

You might need additional packages, depending on your needs:

• the msys shell. Warning: you should not use the msys terminal, as it does not play well with native windows binaries, such as Python. For running regression tests, you only need access to the diff command, so just put the path to the msys binaries in the system PATH environment variable (My Computer -> Properties -> Advanced), but _do NOT_ run the msys terminal. Instead, run a plain old Windows terminal;
• mercurial. You will need this if you plan to use mercurial or if you need to pull regression traces for development ns-3 versions.

Note: under mingw, all regression tests are known to fail. The developers have not had the time yet to investigate the reasons for those failures.

How to run programs with gdb

It's not very hard:

• First, setup your environment variables: ./waf --shell
• Then, run your program with gdb: gdb ./buidl/debug/examples/csma-broadcast

Python bindings

Questions about how to use Python with ns-3? See ns-3 python wiki page