Getting Started
***************

Downloading ns-3
================

The ns-3 system as a whole is a fairly complex system and has a number of dependencies on other components.  Along with the systems you will most likely deal with every day (the GNU toolchain, Mercurial, you programmer editor) you will need to ensure that a number of additional libraries are present on your system before proceeding.  ns-3 provides a wiki for your reading pleasure that includes pages with many useful hints and tips. One such page is the ``Installation'' page, http://www.nsnam.org/wiki/index.php/Installation.

The ``Prerequisites'' section of this wiki page explains which packages are required to support common ns-3 options, and also provides the commands used to install them for common Linux variants.  Cygwin users will have to use the Cygwin installer (if you are a Cygwin user, you used it to install Cygwin).

You may want to take this opportunity to explore the ns-3 wiki a bit since there really is a wealth of information there.

From this point forward, we are going to assume that the reader is working in Linux or a Linux emulation environment (Linux, Cygwin, etc.) and has the GNU toolchain installed and verified along with the prerequisites mentioned above.  We are also going to assume that you have Mercurial and Waf installed and running on the target system as described in the ``Getting Started'' section of the  ns-3 web site: http://www.nsnam.org/getting_started.html.

The ns-3 code is available in Mercurial repositories on the server http://code.nsnam.org.  You can also download a tarball release at http://www.nsnam.org/releases/, or you can work with 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 subsystems 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.

Downloading ns-3 Using Mercurial
--------------------------------

One practice is to create a directory called repos in one's home directory under which one can keep local Mercurial repositories. Hint:  we will assume you do this later in the tutorial.  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 31 changesets with 45 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.

We have had a regression testing framework in place since the first release. For each release, a set of output files that define ``good behavior'' are saved. These known good output files are called reference traces and are associated with a given release by name.  For example, in http://code.nsnam.org/ you will find a repository named ns-3.1 which is the first stable release of ns-3.  You will also find a separate repository named ns-3.1-ref-traces that holds the reference traces for the ns-3.1 release.  It is crucial to keep these files consistent if you want to do any regression testing of your repository.  This is a good idea to do at least once to verify everything has built correctly.

The current development snapshot (unreleased) of ns-3 may be found at http://code.nsnam.org/ns-3-dev/ and the associated reference traces may be found at http://code.nsnam.org/ns-3-dev-ref-traces/.  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, I will stick with the more constant ns-3-dev here in the tutorial, but you can replace the string ``ns-3-dev'' with your choice of release (e.g., ns-3.6 and ns-3.6-ref-traces) 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.

Go ahead and change into the ns-3-allinone directory you created when you cloned that repository.  We are now going to use the download.py script to pull down the various pieces of ns-3 you will be using.

Go ahead and type the following into your shell (remember you can substitute the name of your chosen release number instead of ns-3-dev -- like "ns-3.6" and "ns-3.6-ref-traces" if you want to work with a stable release).

  ./download.py -n ns-3-dev -r ns-3-dev-ref-traces

Note that the default for the -n option is ns-3-dev and the default for the -r option is ns-3-dev-ref-traces and so the above is actually redundant.  We provide this example to illustrate how to specify alternate repositories.  In order to download ns-3-dev you can actually use the defaults and simply type,

  ./download.py

As the hg (Mercurial) command executes, you should see something like the following,

      #
      # Get NS-3
      #

  Cloning ns-3 branch
   =>  hg clone http://code.nsnam.org/ns-3-dev ns-3-dev
  requesting all changes
  adding changesets
  adding manifests
  adding file changes
  added 4634 changesets with 16500 changes to 1762 files
  870 files updated, 0 files merged, 0 files removed, 0 files unresolved

This is output by the download script as it fetches the actual ns-3 code from the repository.  Next, you should see something like,

      #
      # Get the regression traces
      #

  Synchronizing reference traces using Mercurial.
   =>  hg clone http://code.nsnam.org/ns-3-dev-ref-traces ns-3-dev-ref-traces
  requesting all changes
  adding changesets
  adding manifests
  adding file changes
  added 86 changesets with 1178 changes to 259 files
  208 files updated, 0 files merged, 0 files removed, 0 files unresolved

This is the download script fetching the reference trace files for you. The download script is smart enough to know that on some platforms various pieces of ns-3 are not supported.  On your platform you may not see some of these pieces come down.  However, on most platforms, the process should continue with something like,

      #
      # Get PyBindGen
      #

  Required pybindgen version:  0.10.0.640
  Trying to fetch pybindgen; this will fail if no network connection is available.  Hit Ctrl-C to skip.
   =>  bzr checkout -rrevno:640 https://launchpad.net/pybindgen pybindgen
  Fetch was successful.

This was the download script getting the Python bindings generator for you. Note that you will need bazaar (bzr), a version control system, to download PyBindGen. Next you should see (modulo platform variations) something along the lines of,

      #
      # Get NSC
      #

  Required NSC version:  nsc-0.5.0
  Retrieving nsc from https://secure.wand.net.nz/mercurial/nsc
   =>  hg clone https://secure.wand.net.nz/mercurial/nsc nsc
  requesting all changes
  adding changesets
  adding manifests
  adding file changes
  added 273 changesets with 17565 changes to 15175 files
  10622 files updated, 0 files merged, 0 files removed, 0 files unresolved

This part of the process is the script downloading the Network Simulation Cradle for you. Note that NSC is not supported on OSX or Cygwin and works best with gcc-3.4 or gcc-4.2 or greater series.

After the clone command completes, you should have several new directories under ~/repos/ns-3-allinone:

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

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/  regression/    scratch/  waf*
  bindings/     LICENSE    regression.py  src/      waf.bat*
  CHANGES.html  ns3/       RELEASE_NOTES  utils/    wscript
  doc/          README     samples/       VERSION   wutils.py

You are now ready to build the ns-3 distribution.

Downloading ns-3 Using a Tarball
--------------------------------

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.  Hint:  the tutorial will assume you downloaded into a repos directory, so remember the placekeeper.  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/releases/ns-allinone-3.6.tar.bz2
  tar xjf ns-allinone-3.6.tar.bz2

If you change into the directory ns-allinone-3.6 you should see a number of files:

build.py*     ns-3.6/             nsc-0.5.1/             README
constants.py  ns-3.6-ref-traces/  pybindgen-0.12.0.700/  util.py

You are now ready to build the ns-3 distribution.

Building ns-3
=============

Building with build.py
----------------------

The first time you build the ns-3 project you should build using the allinone environment.  This will get the project configured for you in 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.6 under your ~/tarballs directory.  Take a deep breath and 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:

  Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
  'build' finished successfully (2m30.586s)

Once the project has built you can say goodbye to your old friends, the ns-3-allinone scripts.  You got what you needed from them and will now interact directly with Waf and we do it in the ns-3-dev directory, not in the ns-3-allinone directory.  Go ahead and change into the ns-3-dev directory (or the directory for the appropriate release you downloaded.

  cd ns-3-dev

Building with Waf
-----------------

We use Waf to configure and build the ns-3 project.  It's not strictly required at this point, but it will be valuable to take a slight detour and look at how to make changes to the configuration of the project. Probably the most useful configuration change you can make will be to build the optimized version of the code.  By default you have configured your project to build the debug version.  Let's tell the project to do make an optimized build.  To explain to Waf that it should do optimized builds you will need to execute the following command,

  ./waf -d optimized configure

This runs Waf out of the local directory (which is provided as a convenience for you).  As the build system checks for various dependencies you should see output that looks similar to the following,

  Checking for program g++                 : ok /usr/bin/g++
  Checking for program cpp                 : ok /usr/bin/cpp
  Checking for program ar                  : ok /usr/bin/ar
  Checking for program ranlib              : ok /usr/bin/ranlib
  Checking for g++                         : ok
  Checking for program pkg-config          : ok /usr/bin/pkg-config
  Checking for regression reference traces  : ok ../ns-3-dev-ref-traces (guessed)
  Checking for -Wno-error=deprecated-declarations support : yes
  Checking for -Wl,--soname=foo support                   : yes
  Checking for header stdlib.h                            : ok
  Checking for header signal.h                            : ok
  Checking for header pthread.h                           : ok
  Checking for high precision time implementation         : 128-bit integer
  Checking for header stdint.h                            : ok
  Checking for header inttypes.h                          : ok
  Checking for header sys/inttypes.h                      : not found
  Checking for library rt                                 : ok
  Checking for header netpacket/packet.h                  : ok
  Checking for pkg-config flags for GSL                   : ok
  Checking for header linux/if_tun.h                      : ok
  Checking for pkg-config flags for GTK_CONFIG_STORE      : ok
  Checking for pkg-config flags for LIBXML2               : ok
  Checking for library sqlite3                            : ok
  Checking for NSC location                               : ok ../nsc (guessed)
  Checking for library dl                                 : ok
  Checking for NSC supported architecture x86_64          : ok
  Checking for program python                             : ok /usr/bin/python
  Checking for Python version >= 2.3                      : ok 2.5.2
  Checking for library python2.5                          : ok
  Checking for program python2.5-config                   : ok /usr/bin/python2.5-config
  Checking for header Python.h                            : ok
  Checking for -fvisibility=hidden support                : yes
  Checking for pybindgen location                         : ok ../pybindgen (guessed)
  Checking for Python module pybindgen                    : ok
  Checking for pybindgen version                          : ok 0.10.0.640
  Checking for Python module pygccxml                     : ok
  Checking for pygccxml version                           : ok 0.9.5
  Checking for program gccxml                             : ok /usr/local/bin/gccxml
  Checking for gccxml version                             : ok 0.9.0
  Checking for program sudo                               : ok /usr/bin/sudo
  Checking for program hg                                 : ok /usr/bin/hg
  Checking for program valgrind                           : ok /usr/bin/valgrind
  ---- Summary of optional NS-3 features:
  Threading Primitives          : enabled
  Real Time Simulator           : enabled
  Emulated Net Device           : enabled
  GNU Scientific Library (GSL)  : enabled
  Tap Bridge                    : enabled
  GtkConfigStore                : enabled
  XmlIo                         : enabled
  SQlite stats data output      : enabled
  Network Simulation Cradle     : enabled
  Python Bindings               : enabled
  Python API Scanning Support   : enabled
  Use sudo to set suid bit      : not enabled (option --enable-sudo not selected)
  Build examples and samples    : enabled
  Static build                  : not enabled (option --enable-static not selected)
  'configure' finished successfully (2.870s)

Note the last part of the above output.  Some ns-3 options are not enabled by default or require support from the underlying system to work properly. For instance, to enable XmlTo, the library libxml-2.0 must be found on the system.  If this library were not found, the corresponding ns-3 feature would not be enabled and a message would be displayed.  Note further that there is a feature to use the program sudo to set the suid bit of certain programs. This is not enabled by default and so this feature is reported as ``not enabled.''

Now go ahead and switch back to the debug build.

  ./waf -d debug configure

The build system is now configured and you can build the debug versions of the ns-3 programs by simply typing,

  ./waf

Some waf commands are meaningful during the build phase and some commands are valid in the configuration phase.  For example, if you wanted to use the emulation features of ns-3 you might want to enable setting the suid bit using sudo as described above.  This turns out to be a configuration-time command, and so you could reconfigure using the following command

  ./waf -d debug --enable-sudo configure

If you do this, waf will have run sudo to change the socket creator programs of the emulation code to run as root.  There are many other configure- and build-time options available in waf.  To explore these options, type:

  ./waf --help

We'll use some of the testing-related commands in the next section.

Okay, sorry, I made you build the ns-3 part of the system twice, but now you know how to change the configuration and build optimized code.

Testing ns-3
============

You can run the unit tests of the ns-3 distribution by running the ``./test.py -c core'' script,

  ./test.py -c core

These tests are run in parallel by waf. You should eventually see a report saying that,

  47 of 47 tests passed (47 passed, 0 failed, 0 crashed, 0 valgrind errors)

This is the important message.

You will also see output from the test runner and the output will actually look something like,

  Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
  Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
  'build' finished successfully (1.799s)
  PASS: TestSuite ns3-wifi-interference
  PASS: TestSuite histogram
  PASS: TestSuite sample
  PASS: TestSuite ipv4-address-helper
  PASS: TestSuite devices-wifi
  PASS: TestSuite propagation-loss-model

  ...

  PASS: TestSuite attributes
  PASS: TestSuite config
  PASS: TestSuite global-value
  PASS: TestSuite command-line
  PASS: TestSuite basic-random-number
  PASS: TestSuite object
  PASS: TestSuite random-number-generators
  47 of 47 tests passed (47 passed, 0 failed, 0 crashed, 0 valgrind errors)

This command is typically run by users to quickly verify that an ns-3 distribution has built correctly.

You can also run our regression test suite to ensure that your distribution and toolchain have produced binaries that generate output that is identical to known-good reference output files.  You downloaded these reference traces to your machine during the ./download.py process above.  (Warning:  The ns-3.2 and ns-3.3 releases do not use the ns-3-allinone environment and require you to be online when you run regression tests because they dynamically synchronize the reference traces directory with an online repository immediately prior to the run).

During regression testing Waf will run a number of tests that generate what we call trace files.  The content of these trace files are compared with the reference traces.  If they are identical, the regression tests report a PASS status.  If a regression test fails you will see a FAIL indication along with a pointer to the offending trace file and its associated reference trace file along with a suggestion on diff parameters and options in order to see what has gone awry.  If the error was discovered in a pcap file, it will be useful to convert the pcap files to text using tcpdump prior to comparison.

Some regression tests may be SKIPped if the required support is not present.

Note that the regression tests are also run in parallel and so the messages may be interleaved.

To run the regression tests, you provide Waf with the regression flag.

  ./waf --regression

You should see messages indicating that many tests are being run and are passing.

  Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
  [647/669] regression-test (test-csma-bridge)
  [648/669] regression-test (test-csma-broadcast)
  [649/669] regression-test (test-csma-multicast)
  [650/669] regression-test (test-csma-one-subnet)
  PASS test-csma-multicast
  [651/669] regression-test (test-csma-packet-socket)
  PASS test-csma-bridge
  ...
  Regression testing summary:
  PASS: 22 of 22 tests passed
  Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
  'build' finished successfully (25.826s)

If you want to take a look at an example of what might be checked during a regression test, you can do the following:

  cd build/debug/regression/traces/second.ref
  tcpdump -nn -tt -r second-2-0.pcap

The output should be clear to anyone who is familiar with tcpdump or net sniffers.  We'll have much more to say on pcap files later in this tutorial.

Remember to cd back into the top-level ns-3 directory after you are done:

  cd ../../../../..

Running a Script
================

We typically run scripts under the control of Waf.  This allows the build system to ensure that the shared library paths are set correctly and that the libraries are available at run time.  To run a program, simply use the --run option in Waf.  Let's run the ns-3 equivalent of the ubiquitous hello world program by typing the following:

  ./waf --run hello-simulator

Waf first checks to make sure that the program is built correctly and executes a build if required.  Waf then executes the program, which produces the following output.

  Hello Simulator

Congratulations.  You are now an ns-3 user.

What do I do if I don't see the output?

If you don't see waf messages indicating that the build was completed successfully, but do not see the ``Hello Simulator'' output, chances are that you have switched your build mode to ``optimized'' in the ``Building with Waf'' section, but have missed the change back to ``debug'' mode.  All of the console output used in this tutorial uses a special ns-3 logging component that is useful for printing user messages to the console.  Output from this component is automatically disabled when you compile optimized code -- it is ``optimized out.''  If you don't see the ``Hello Simulator'' output, type the following,

  ./waf -d debug configure

to tell waf to build the debug versions of the ns-3 programs.  You must still build the actual debug version of the code by typing,

  ./waf

Now, if you run the hello-simulator program, you should see the expected output.

If you want to run programs under another tool such as gdb or valgrind, see this wiki entry.