ns-3 Tutorial
Release ns-3.26
ns-3 project
October 04, 2016
CONTENTS
1 Introduction
.
1.1 About ns-3 .
1.2
1.3
1.4
.
.
For ns-2 Users .
.
.
Contributing .
.
Tutorial Organization .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
2 Resources
.
2.1
The Web .
.
2.2 Mercurial .
2.3 Waf .
.
.
2.4 Development Environment .
2.5
.
Socket Programming .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
3 Getting Started
3.1 Overview .
.
3.2 Downloading ns-3 .
3.3
.
.
3.4
3.5
.
Building ns-3 .
.
Testing ns-3 .
.
Running a Script
.
.
.
.
.
4 Conceptual Overview
.
4.1 Key Abstractions .
4.2 A First ns-3 Script
.
4.3 Ns-3 Source Code .
5 Tweaking
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
. . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
. . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
. . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . .
. . .
. . .
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.1 Using the Logging Module .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.2 Using Command Line Arguments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5.3 Using the Tracing System .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
.
.
.
6 Building Topologies
Building a Bus Network Topology .
.
6.1
6.2 Models, Attributes and Reality .
6.3
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Building a Wireless Network Topology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
.
3
3
4
4
5
7
7
7
7
8
8
9
9
9
13
19
20
23
23
25
34
35
35
40
45
51
51
59
60
7 Tracing
Background .
.
7.1
7.2 Overview .
7.3
7.4
7.5
.
.
Real Example .
Trace Helpers .
Summary .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
69
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
69
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
71
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
84
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112
i
113
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
.
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 118
.
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
121
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
8 Data Collection
.
.
.
.
8.1 Motivation .
8.2
Example Code .
8.3 GnuplotHelper .
8.4
8.5
8.6
.
.
.
Supported Trace Types .
.
FileHelper
Summary .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
9 Conclusion
9.1
9.2
Futures .
Closing .
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
ii
ns-3 Tutorial, Release ns-3.26
This is the ns-3 Tutorial. Primary documentation for the ns-3 project is available in five forms:
• ns-3 Doxygen: Documentation of the public APIs of the simulator
• Tutorial (this document), Manual, and Model Library for the latest release and development tree
• ns-3 wiki
This document is written in reStructuredText for Sphinx and is maintained in the doc/tutorial directory of ns-3’s
source code.
CONTENTS
1
ns-3 Tutorial, Release ns-3.26
2
CONTENTS
CHAPTER
ONE
INTRODUCTION
The ns-3 simulator is a discrete-event network simulator targeted primarily for research and educational use. The ns-3
project, started in 2006, is an open-source project developing ns-3.
The purpose of this tutorial is to introduce new 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 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:
• ns-3 is open-source, and the project strives to maintain an open environment for researchers to contribute and
share their software.
• ns-3 is not a backwards-compatible extension of ns-2; it is a new simulator. The two simulators are both written
in C++ but 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 ns-3. The project will continue to maintain ns-2 while ns-3 is being built, and will
study transition and integration mechanisms.
1.1 About ns-3
ns-3 has been developed to provide an open, extensible network simulation platform, for networking research and
education. In brief, ns-3 provides models of how packet data networks work and perform, and provides a simulation
engine for users to conduct simulation experiments. Some of the reasons to use ns-3 include to perform studies that
are more difficult or not possible to perform with real systems, to study system behavior in a highly controllled,
reproducible environment, and to learn about how networks work. Users will note that the available model set in ns-3
focuses on modeling how Internet protocols and networks work, but ns-3 is not limited to Internet systems; several
users are using ns-3 to model non-Internet-based systems.
Many simulation tools exist for network simulation studies. Below are a few distinguishing features of ns-3 in contrast
to other tools.
• ns-3 is designed as a set of libraries that can be combined together and also with other external software libraries.
While some simulation platforms provide users with a single, integrated graphical user interface environment in
which all tasks are carried out, ns-3 is more modular in this regard. Several external animators and data analysis
and visualization tools can be used with ns-3. However, users should expect to work at the command line and
with C++ and/or Python software development tools.
• ns-3 is primarily used on Linux systems, although support exists for FreeBSD, Cygwin (for Windows), and
native Windows Visual Studio support is in the process of being developed.
3
ns-3 Tutorial, Release ns-3.26
• ns-3 is not an officially supported software product of any company. Support for ns-3 is done on a best-effort
basis on the ns-3-users mailing list.
1.2 For ns-2 Users
For those familiar with ns-2 (a popular tool that preceded ns-3), the most visible outward change when moving to ns-3
is the choice of scripting language. Programs in ns-2 are scripted in OTcl and results of simulations can be visualized
using the Network Animator 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 ns-3,
the simulator is written entirely in C++, with optional Python bindings. Simulation scripts can therefore be written in
C++ or in Python. New animators and visualizers are available and under current development. Since 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 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 ns-3). We will try to highlight differences between ns-2 and ns-3 as we proceed in this tutorial.
A question that we often hear is “Should I still use ns-2 or move to ns-3?” In this author’s opinion, unless the user is
somehow vested in ns-2 (either based on existing personal comfort with and knowledge of ns-2, or based on a specific
simulation model that is only available in ns-2), a user will be more productive with ns-3 for the following reasons:
• ns-3 is actively maintained with an active, responsive users mailing list, while ns-2 is only lightly maintained
and has not seen significant development in its main code tree for over a decade.
• ns-3 provides features not available in ns-2, such as a implementation code execution environment (allowing
users to run real implementation code in the simulator)
• ns-3 provides a lower base level of abstraction compared with ns-2, allowing it to align better with how real
systems are put together. Some limitations found in ns-2 (such as supporting multiple types of interfaces on
nodes correctly) have been remedied in ns-3.
ns-2 has a more diverse set of contributed modules than does ns-3, owing to its long history. However, ns-3 has
more detailed models in several popular areas of research (including sophisticated LTE and WiFi models), and its
support of implementation code admits a very wide spectrum of high-fidelity models. Users may be surprised to learn
that the whole Linux networking stack can be encapsulated in an ns-3 node, using the Direct Code Execution (DCE)
framework. ns-2 models can sometimes be ported to ns-3, particularly if they have been implemented in C++.
If in doubt, a good guideline would be to look at both simulators (as well as other simulators), and in particular the
models available for your research, but keep in mind that your experience may be better in using the tool that is being
actively developed and maintained (ns-3).
1.3 Contributing
ns-3 is a research and educational simulator, by and for the research community. It will rely on the ongoing contribu-
tions 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 ns-3 like they have for ns-2:
• Open source licensing based on GNU GPLv2 compatibility
• wiki
• Contributed Code page, similar to ns-2‘s popular Contributed Code page
• Open bug tracker
4
Chapter 1.
Introduction