\input texinfo  @c -*-texinfo-*-

@c %**start of header

@setfilename ns-3.info

@settitle ns-3 tutorial

@c @setchapternewpage odd

@c %**end of header

@ifinfo

This @command{ns-3} project document is one of a set of project documents:

@itemize @bullet

@item Software Architecture 

@item Manual 

@item Tutorial (this document)

@end itemize

This document is written in GNU Texinfo and is to be maintained in

revision control on the @command{ns-3} code server.  Both PDF and HTML versions

should be available on the server.  Changes to 

the document should be discussed on the ns-developers@@isi.edu mailing list.

@end ifinfo

@copying

This @command{ns-3} project document is one of a set of project documents:

@itemize @bullet

@item Software Architecture 

@item Manual 

@item Tutorial (this document)

@end itemize

This document is written in GNU Texinfo and is to be maintained in

revision control on the @command{ns-3} code server.  Both PDF and HTML 

versions should be available on the server.  Changes to 

the document should be discussed on the ns-developers@@isi.edu mailing list.

This software is free software; you can redistribute it and/or modify

it under the terms of the GNU General Public License as published by

the Free Software Foundation; either version 2 of the License, or

(at your option) any later version.

This software is distributed in the hope that it will be useful,

but WITHOUT ANY WARRANTY; without even the implied warranty of

MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

GNU General Public License for more details.

You should have received a copy of the GNU General Public License

along with this program.  If not, see @uref{http://www.gnu.org/licenses/}.

@end copying

@titlepage

@title ns-3 Tutorial

@author ns-3 project

@author feedback:  ns-developers@@isi.edu

@today{}

@c @page

@vskip 0pt plus 1filll

@insertcopying

@end titlepage

@c So the toc is printed at the start.

@anchor{Full Table of Contents}

@contents

@ifnottex

@node Top, Preface, Full Table of Contents 

@top ns-3 Tutorial (html version)

For a pdf version of this manual, 

see @uref{http://www.nsnam.org/docs/tutorial.pdf}.

@insertcopying

@end ifnottex

@menu

* Preface::

* Introduction::

* Resources::

* The-Basics::

* Some-Prerequisites::

* A-First-ns-3-Script::

* Tracing-at-a-Glance::

* Other-network-topologies::

* Nonlinear-Thinking::

* Summary::

* The-Doxygen-Documentation-System::

* How-To-Change-Things::

* How-To-Set-Default-Values::

* How-To-Write-A-New-Application::

@end menu

@node Preface

@chapter Preface

The purpose of this tutorial is to introduce new @command{ns-3} users to the 

system in a structured way.  It is sometimes difficult for new users to

glean essential information from detailed manuals and to convert this

information into working simulations.  In this tutorial, we will build 

several example simulations, introducing and explaining key concepts and

features as we go.

As the tutorial unfolds, we will introduce the full @command{ns-3} 

documentation 

and provide pointers to source code for those interested in delving deeper

into the workings of the system.

This document is one of a set of @command{ns-3} project documents:

@itemize @bullet

@item Software Architecture 

@item Manual 

@item Tutorial (this document)

@end itemize

This document is written in Texinfo and is to be maintained in

revision control on the @command{ns-3} code server.  Both PDF and HTML versions

should be available on the server.  Changes to 

the document should be discussed on the ns-developers@@isi.edu mailing list.

@c ========================================================================

@c Begin document body here

@c ========================================================================

@c ========================================================================

@c Introduction

@c ========================================================================

@node Introduction

@chapter Introduction

The @command{ns-3} project is a discrete-event network simulator targeted

primarily for research and educational use.  It is aimed at 

comprehensively redesigning and enhancing the popular Network Simulator 

@command{ns-2}.

For those familiar with @command{ns-2}, the most visible outward change 

when moving to @command{ns-3} is the choice of scripting language.  

@command{ns-2} is typically scripted in Tcl and results of simulations are

often visualized using the Network Animator @command{nam}.  In 

@command{ns-3} there is currently no visualization module, and multiple 

language bindings are allowed.  In this tutorial, we will concentrate on 

scripting directly in C++ and interpreting results via trace files.  Scripting

in other languages will typically be done via straightforward bindings of the 

target language into the underlying C++.

The goal of this tutorial is to introduce new users of @command{ns-3} to enough

of the system to enable them to author simple simulation scripts and extract

useful information from the simulations.  We begin by introducing some of the

other important resources that are available to those interested in using or

writing scripts, models and even those interested in making contributions to

the core @command{ns-3} system.  We provide an overview of some of the 

important abstractions, design patterns and idioms used when writing 

@command{ns-3} scripts, and then dig right in by begining to write simulation 

scripts, run them and interpret results.

After completing this tutorial, one should be able to:

@itemize @bullet

@item Find documentation resources in the distribution and on the web;

@item Download and compile the @command{ns-3} system;

@item Use the provided devices to author network simulations of fairly  

significant complexity;

@item Use the default value system to configure simulations;

@item Write new @command{ns-3} applications;

@item Use the tracing subsystem.

@end itemize

@c ========================================================================

@c Resources

@c ========================================================================

@node Resources

@chapter Resources

@menu

* The-Web::

* Mercurial::

* Waf::

* Environment-Idioms-Design-Patterns::

* Socket-Programming::

@end menu

@node The-Web

@section The Web

@cindex www.nsnam.org

There are several important resources of which any @command{ns-3} user must be

aware.  The main web site is located at @uref{http://www.nsnam.org}

and provides access to basic information about the @command{ns-3} system.  

Detailed documentation is available through the main web site at

@uref{http://www.nsnam.org/documents.html}.

@cindex documentation

@cindex architecture

You can find documents relating to the system architecture from this page,

and also gain access to the detailed software documentation.  The software

system is documented in great detail using 

@uref{http://www.stack.nl/~dimitri/doxygen/,,Doxygen}.  There is a Wiki that

complements the main @command{ns-3} web site which you will find at 

@uref{http://www.nsnam.org/wiki/}.

You will find user and developer FAQs there as well as troubleshooting guides, 

third-party contributed code, papers, etc. The source code may be found 

and browsed at @uref{http://code.nsnam.org/}. 

@cindex repository!ns-3-dev

@cindex repository!releases

There you will find the current development tree in the repository named

@code{ns-3-dev}. Past releases and experimental repositories of the core

developers may also be found there.

@node Mercurial

@section Mercurial

Complex software systems need some way to manage the organization and 

changes to the underlying code and documentation.  There are many ways to

perform this feat, and you may have heard of some of the systems that are

currently used to do this.  The Concurrent Version System (CVS) is probably

the most well known.

@cindex software configuration management

@cindex Mercurial

The @command{ns-3} project uses Mercurial as its source code management system.

Although you do not need to know much about Mercurial in order to complete

this tutorial, we recommend becoming familiar with Mercurial and using it 

to access the source code.  Mercurial has a web site at 

@uref{http://www.selenic.com/mercurial/},

from which you can get binary or source releases of this Software

Configuration Management (SCM) system.  Selenic (the developer of Mercurial)

also provides a tutorial at 

@uref{http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial/},

and a QuickStart guide at

@uref{http://www.selenic.com/mercurial/wiki/index.cgi/QuickStart/}.

You can also find vital information about using Mercurial and @command{ns-3}

on the main @command{ns-3} web site.

@node Waf

@section Waf

@cindex Waf

@cindex make

@cindex build

Once you have source code downloaded to your local system, you will need 

to compile that source to produce usable programs.  Just as in the case of

source code management, there are many tools available to perform this 

function.  Probably the most famous of these tools is @code{make}.  Along

with being the most famous, @code{make} is probably the most difficult to

use in a very large and highly configurable system.  Because of this, many

alternatives have been developed.  Recently these systems have been developed

using the Python language.

The build system @code{Waf} is used on the @command{ns-3} project.  It is one 

of the new generation of Python-based build systems.  You will not need to 

understand any Python to build the existing @command{ns-3} system, and will 

only have to understand a tiny and intuitively obvious subset of Python in 

order to extend the system in most cases.

For those interested in the gory details of Waf, the main web site can be 

found at @uref{http://freehackers.org/\~tnagy/waf.html}.

@node Environment-Idioms-Design-Patterns

@section Environment, Idioms, and Design Patterns

@cindex C++

As mentioned above, scripting in @command{ns-3} is done in C++.  A working 

knowledge of C++ and object-oriented concepts is assumed in this document.

We will take some time to review some of the more advanced concepts or 

possibly unfamiliar language features, idioms and design patterns as they 

appear.  We don't want this tutorial to devolve into a C++ tutorial, though,

so we do expect a basic command of the language.  There are an almost 

unimaginable number of sources of information on C++ available on the web or

in print.

If you are new to C++, you may want to find a tutorial- or cookbook-based

book or web site and work through at least the basic features of the language

before proceeding.

@subsection Environment

@cindex toolchain

@cindex GNU

The @command{ns-3} system uses the GNU ``toolchain'' for development.  

A software toolchain is the set of programming tools available in the given 

environment. For a quick review of what is included in the GNU toolchain see,

@uref{http://en.wikipedia.org/wiki/GNU_toolchain}.

@cindex Linux

Typically a @command{ns-3} author will work in Linux or a Linux-like

environment.  For those running under Windows, there do exist environments 

which simulate the Linux environment to various degrees.  The @command{ns-3} 

project supports development in the Cygwin and the MinGW environments for 

these users.  See @uref{http://www.cygwin.com/} and 

@uref{http://www.mingw.org/} for details on downloading and using these

systems.  I use Cygwin in these cases since it provides all of the Linux tools

I know and love.  It can, however, sometimes be problematic due to the way it 

actually does its emulation, and sometimes interactions with other Windows

software can cause problems.

@cindex Cygwin

@cindex MinGW

If you do use Cygwin or MinGW; and use Logitech products, I will save you

quite a bit of heartburn right off the bat and encourage you to take a look

at the @uref{http://www.mingw.org/MinGWiki/index.php/FAQ,,MinGW FAQ}.

@cindex Logitech

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 @code{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.

@subsection Idioms and Design Patterns

@cindex idiom

In any system, there are a number of problems to be solved that happen 

repeatedly.  Often the solutions to these problems can be generalized and

applied in a similar way across the system.  These solutions are called

Design Patterns.  The @command{ns-3} system relies on several classic design

patterns.

@cindex design pattern

Also, in any language, there are constructs that, while they aren't part of the

language per se, are commonly found and useful.  For example, at the lowest 

level a C programmer should be able to immediately recognize the purpose and 

intent  of the following code without having to reflect on the details:

@verbatim

  for (;;)

@end verbatim

These low-level constructs, or idioms, extend upward in complexity, eventually

becoming implementations of design patterns.  As you are exposed to more 

and more of the @command{ns-3} system, you will begin to recognize and be 

comfortable with the C++ implementations (idioms) of several important design

patterns.

@cindex functor

@cindex callback

@cindex smart pointer

The @command{ns-3} code relies heavily on 

@emph{Generalized Functors, Callbacks, 

Smart Pointers, Singletons, and Object Factories}.  Although we will 

not assume any detailed knowledge of the idioms and design patterns used 

in the @command{ns-3}

system, it will be useful for readers who intend to delve deeply into the

system to understand some important related concepts.  We recommend two 

resources: @uref{http://www.amazon.com/Design-Patterns-Object-Oriented-Addison-Wesley-Professional/dp/0201633612/,,Design Patterns: Elements of Reusable Object-Oriented Software, Gamma et. al.} and

@uref{http://www.amazon.com/exec/obidos/ASIN/0201704315,,Modern C++ Design: Generic Programming and Design Patterns Applied, Alexandrescu}.

Gamma addresses the abstract design patterns, and Alexandrescu addresses the

C++ idioms you will often see throughout the @command{ns-3} code.

@cindex template

Almost any use of @command{ns-3} will require some basic knowledge of C++ 

templates.

We will discuss the high-level uses in this tutorial.  However, if you venture

deeply into the source code, you will see fairly heavy use of relatively

sophisticated C++ templates in some of low-level modules of the system.  The

You don't have to be a template guru to complete this tutorial but if you

expect to work in @command{ns-3} at a low level you will have to be 

somewhat fluent

with templates.  If you  want to truly grok C++ templates we recommend,

@uref{http://www.amazon.com/Templates-Complete-Guide-David-Vandevoorde/dp/0201734842/,,C++ Templates: The Complete Guide, Vandevoorde and Josuttis}.

@node Socket-Programming

@section Socket Programming

@cindex sockets

We will assume a basic facility with the Berkeley Sockets API in the examples

used in this tutorial.  If you are new to sockets, we recommend reviewing the

API and some common usage cases.  For a good overview of programming TCP/IP

sockets we recommend @uref{http://www.elsevier.com/wps/product/cws_home/680765,,Practical TCP/IP Sockets in C, Donahoo and Calvert}.

There is an associated web site that includes source for the examples in the

book, which you can find at:

@uref{http://cs.baylor.edu/~donahoo/practical/CSockets/}.

If you understand the first four chapters of the book (or for those who do

not have access to a copy of the book, the echo clients and servers shown in 

the website above) you will be in good shape to understand the tutorial.

There is a similar book on Multicast Sockets,

@uref{http://www.elsevier.com/wps/product/cws_home/700736,,Multicast Sockets, Makofske and Almeroth}.

that covers material you may need to understand for the multicast examples.

@c ========================================================================

@c The Basics

@c ========================================================================

@node The-Basics

@chapter The Basics

@cindex Linux

@cindex Cygwin

@cindex GNU

@cindex toolchain

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.  

@cindex Mercurial

@cindex Waf

We are 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 

@command{ns-3} web site: @uref{http://www.nsnam.org/getting_started.html}.

@section Downloading

@cindex tarball

The @command{ns-3} code is available in Mercurial repositories on the server

code.nsnam.org.  You can download a tarball, but we recommend working with

Mercurial --- it will make your life easier in the long run.

@cindex repository

If you go to the following link: @uref{http://code.nsnam.org/},

you will see a number of repositories.  Many are the private repositories of

the @command{ns-3} development team.  The repositories of interest to you 

will be

prefixed with ``ns-3''.  The current development snapshot (unreleased) of

@command{ns-3} may be found at: @uref{http://code.nsnam.org/ns-3-dev/}.

The developers attempt to keep this repository in a consistent, working state

but it is a development area with unreleased code present, so you may want to

consider downloading an official release.

There will be a number of released repositories present at code.nsnam.org.

These repos will have names like ns-3.0.1 --- which referes to release 3.0.1 

of the network simulator (or if you like, release 0.1 of @command{ns-3}).  

Since the releases are changing at a rate of one per month, I 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.0.5) 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.

I typically create a directory called @code{repos} in my home directory under

which I keep all of my local Mercurial repositories.  @emph{Hint:  I will

assume you do this later in the tutorial.} If you adopt that approach, you 

can get a copy of the development version of @command{ns-3} by typing 

the following into your Linux shell (I use bash).

@verbatim

  cd

  mkdir repos

  cd !$

  hg clone http://code.nanam.org/ns-3-dev

@end verbatim

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

@verbatim

  destination directory: ns-3-dev

  requesting all changes

  adding changesets

  adding manifests

  adding file changes

  added 1513 changesets with 5687 changes to 733 files

  358 files updated, 0 files merged, 0 files removed, 0 files unresolved

@end verbatim

After the clone command completes, you should have a directory called 

ns-3-dev under your @code{~/repos} directory, the contents of which should 

look something like the following:

@verbatim

  AUTHORS  RELEASE_NOTES  examples/  src/       waf*

  LICENSE  VERSION        ns3/       tutorial/  waf.bat*

  README   doc/           samples/   utils/     wscript

@end verbatim

You are now ready to build the @command{ns-3} distribution.

@section Building

@cindex Waf!build

@cindex Waf!configure

@cindex Waf!debug

@cindex Waf!compile

We use Waf to build the @command{ns-3} project.  The first thing you 

will need to do is to configure the build.  For reasons that will become clear

later, we are going to work with debug builds in the tutorial.  To explain to 

Waf that it should do debug builds you will need to execute the following 

command,

@verbatim

  ./waf -d debug configure

@end verbatim

This runs the copy of Waf in 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,

@verbatim

  ~/repos/ns-3-dev >./waf -d debug configure

  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 compiler could create programs : ok

  Checking for compiler could create shared libs : ok

  Checking for compiler could create static libs : ok

  Checking for flags -Wall                       : ok

  Checking for flags -O2                         : ok

  Checking for flags -g -DDEBUG                  : ok

  Checking for flags -g3 -O0 -DDEBUG             : ok

  Checking for g++                               : ok

  Checking for header stdlib.h                   : ok

  Checking for header stdlib.h                   : ok

  Checking for header signal.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

  Configuration finished successfully; project is now ready to build.

  ~/repos/ns-3-dev >

@end verbatim

The build system is now configured and you can build the debug versions of 

the @command{ns-3} programs by simply typing,

@verbatim

  ./waf

@end verbatim

You will see many Waf status messages displayed as the system compiles.  The

most important is the last one,

@verbatim

  Compilation finished successfully

@end verbatim

@section Running a Script