@c ========================================================================
@c Begin document body here
@c ========================================================================
@c ========================================================================
@c PART: Introduction
@c ========================================================================
@c The below chapters are under the major heading "Introduction"
@c This is similar to the Latex \part command
@c
@c ========================================================================
@c Introduction
@c ========================================================================
@node Introduction
@chapter Introduction
@menu
* For ns-2 Users::
* Contributing::
* Tutorial Organization::
@end menu
The @command{ns-3} simulator is a discrete-event network simulator targeted
primarily for research and educational use. The
@uref{http://www.nsnam.org,,ns-3 project},
started in 2006, is an open-source project developing @command{ns-3}.
Primary documentation for the @command{ns-3} project is available in four
forms:
@itemize @bullet
@item @uref{http://www.nsnam.org/doxygen/index.html,,ns-3 Doxygen/Manual}:
Documentation of the public APIs of the simulator
@item Tutorial (this document)
@item @uref{http://www.nsnam.org/docs/manual.html,,Reference Manual}: Reference Manual
@item @uref{http://www.nsnam.org/wiki/index.php,, ns-3 wiki}
@end itemize
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.
A few key points are worth noting at the onset:
@itemize @bullet
@item Ns-3 is not an extension of @uref{http://www.isi.edu/nsnam/ns,,ns-2};
it is a new simulator. The two simulators are both written in C++ but
@command{ns-3} is a new simulator that does not support the ns-2 APIs. Some
models from ns-2 have already been ported from ns-2 to @command{ns-3}. The
project will continue to maintain ns-2 while @command{ns-3} is being built,
and will study transition and integration mechanisms.
@item @command{Ns-3} is open-source, and the project strives to maintain an
open environment for researchers to contribute and share their software.
@end itemize
@node For ns-2 Users
@section For ns-2 Users
For those familiar with ns-2, the most visible outward change when moving to
@command{ns-3} is the choice of scripting language. Ns-2 is
scripted in OTcl and results of simulations can be visualized using the
Network Animator @command{nam}. It is not possible to run a simulation
in ns-2 purely from C++ (i.e., as a main() program without any OTcl).
Moreover, some components of ns-2 are written in C++ and others in OTcl.
In @command{ns-3}, the simulator is written entirely in C++, with optional
Python bindings. Simulation scripts can therefore be written in C++
or in Python. The results of some simulations can be visualized by
@command{nam}, but new animators are under development. Since @command{ns-3}
generates pcap packet trace files, other utilities can be used to
analyze traces as well.
In this tutorial, we will first concentrate on scripting
directly in C++ and interpreting results via ascii trace files.
But there are similarities as well (both, for example, are based on C++
objects, and some code from ns-2 has already been ported to @command{ns-3}).
We will try to highlight differences between ns-2 and @command{ns-3}
as we proceed in this tutorial.
A question that we often hear is "Should I still use ns-2 or move to
@command{ns-3}?" The answer is that it depends. @command{ns-3} does not have
all of the models that ns-2 currently has, but on the other hand, @command{ns-3}
does have new capabilities (such as handling multiple interfaces on nodes
correctly, use of IP addressing and more alignment with Internet
protocols and designs, more detailed 802.11 models, etc.). ns-2
models can usually be ported to @command{ns-3} (a porting guide is under
development). There is active development on multiple fronts for
@command{ns-3}. The @command{ns-3} developers believe (and certain early users
have proven) that @command{ns-3} is ready for active use, and should be an
attractive alternative for users looking to start new simulation projects.
@node Contributing
@section Contributing
@cindex contributing
@command{Ns-3} is a research and educational simulator, by and for the
research community. It will rely on the ongoing contributions of the
community to develop new models, debug or maintain existing ones, and share
results. There are a few policies that we hope will encourage people to
contribute to @command{ns-3} like they have for ns-2:
@itemize @bullet
@item Open source licensing based on GNU GPLv2 compatibility;
@item @uref{http://www.nsnam.org/wiki/index.php,,wiki};
@item @uref{http://www.nsnam.org/wiki/index.php/Contributed_Code,,Contributed Code} page, similar to ns-2's popular
@uref{http://nsnam.isi.edu/nsnam/index.php/Contributed_Code,,Contributed Code}
page;
@item @code{src/contrib} directory (we will host your contributed code);
@item Open @uref{http://www.nsnam.org/bugzilla,,bug tracker};
@item @command{Ns-3} developers will gladly help potential contributors to get
started with the simulator (please contact @uref{http://www.nsnam.org/people.html,,one of us}).
@end itemize
We realize that if you are reading this document, contributing back to
the project is probably not your foremost concern at this point, but
we want you to be aware that contributing is in the spirit of the project and
that even the act of dropping us a note about your early experience
with @command{ns-3} (e.g. "this tutorial section was not clear..."),
reports of stale documentation, etc. are much appreciated.
@node Tutorial Organization
@section Tutorial Organization
The tutorial assumes that new users might initially follow a path such as the
following:
@itemize @bullet
@item Try to download and build a copy;
@item Try to run a few sample programs;
@item Look at simulation output, and try to adjust it.
@end itemize
As a result, we have tried to organize the tutorial along the above
broad sequences of events.
@c ========================================================================
@c Resources
@c ========================================================================
@node Resources
@chapter Resources
@menu
* The Web::
* Mercurial::
* Waf::
* Development Environment::
* Socket Programming::
@end menu
@node The Web
@section The Web
@cindex www.nsnam.org
@cindex documentation
@cindex architecture
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}. You can also find documents
relating to the system architecture from this page.
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.
@cindex mercurial repository
@cindex ns-3-dev repository
@cindex release repository
The source code may be found and browsed at @uref{http://code.nsnam.org/}.
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 well known of these tools is @code{make}. Along
with being the most well known, @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 Development Environment
@section Development Environment
@cindex C++
@cindex Python
As mentioned above, scripting in @command{ns-3} is done in C++ or Python.
As of ns-3.2, most of the @command{ns-3} API is available in Python, but the
models are written in C++ in either case. 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. For instance,
@uref{http://www.cplusplus.com/doc/tutorial/,,this tutorial}.
@cindex toolchain
@cindex GNU
The @command{ns-3} system uses several components of 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}. @command{ns-3} uses gcc,
GNU binutils, and gdb. However, we do not use the GNU build system,
either make or autotools, using Waf instead.
@cindex Linux
Typically an @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 environment for
these users. See @uref{http://www.cygwin.com/}
for details on downloading (MinGW is presently not supported).
Cygwin provides many of the popular Linux system commands.
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, we 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 software when using Cygwin.
Another alternative to Cygwin is to install a virtual machine environment
such as VMware server and install a Linux virtual machine.
@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 if you look at the multicast
examples in the distribution.