1. ns-3 Introduction Tom Henderson (University of Washington) July Modified by Sara Mehar (university of burgundy) April 2015

2. Getting started with ns-3
Agenda (ns-3 PART1)
ns-3 project overview
Why use ns-3?
What is ns-3?
Project organization
Getting started with ns-3
Installation
Examples
Future directions

3. Goal!! Learn about the ns-3 project and its goals
Understand the software architecture, conventions, and basic usage of ns-3
Read and modify an example ns-3 script
Learn how you might extend ns-3 to conduct your own research

4. Why use ns-3?
to study network performance or protocol operation in a controllable or scalable environment
a tool aligned with the experimentation needs of modern networking research
a tool that elevates the technical rigor of network simulation practice
Full Oriented Object programming
Much faster than other simulators
Support group and mailing list
You want to study network performance or protocol operation in a controllable or scalable environment
You are comfortable writing C++ or Python code, and combining ns-3 with other code
You like the idea of working on an active open source project

5. Why use ns-3? Project provides three annual software releases
Users interact on mailing lists and using Bugzilla bug tracker
Code may be proposed for merge
Code reviews occur on a Google site
Maintainers (one for each module) fix or delegate bugs, participate in reviews
Project has been conducting annual workshop and developer meeting around SIMUTools through 2013
ns-3 Annual Meeting in Atlanta, May 2014
Google Summer of Code (March-August) five of the past six summers

6. ns-3: An Open Source Network Simulator
ns-3 is a discrete-event network simulator targeted for research and educational use
ns-3 software
model developers
Research
Education
NS-3 Consortium
ns-3 maintainers

7. What is ns-3: Discrete event network simulator
Model of the evolution of a networked system through discrete events in time
Used for experimentation and education
The system is observed at regular intervals at time t = nD for all constant elementary period D.
An event occurs instantaneously and causes transitions from one discrete state to another .
Time-driven systems
Continuous time systems
Discrete systems (driven by regular clock ticks)
State transitions are synchronized by the clock
Event-driven systems
State changes at various time instants (may not be known in advance) with some event e announcing that it is occurring
State transitions as a result of combining asynchronous and concurrent event processes.
In the field of simulation, a discrete-event simulation (DES), models the operation of a system as a discrete sequence of events in time. Each event occurs at a particular instant in time and marks a change of state in the system.[1] Between consecutive events, no change in the system is assumed to occur; thus the simulation can directly jump in time from one event to the next.

8. ns-3 simulation basics
Simulation time advances in discrete jumps from event to event
C++ functions schedule events to occur at specific simulation times
A simulation scheduler orders the event execution
Simulation::Run() gets it all started
Simulation stops at specific time or when events end

9. Software overview
ns-3 is written in C++, with bindings available for Python
simulation programs are C++ executables or Python programs
~350,000 lines of C++ (estimate based on cloc source code analysis)
ns-3 is a GNU GPLv2-licensed project
ns-3 is mainly supported for Linux, OS X, and FreeBSD
ns-3 is not backwards-compatible with ns-2

10. Software overview The following platforms are lightly supported:
Windows Visual Studio 2012
Windows Cygwin 1.7
Some aspects of ns-3 depend on Unix (or specifically Linux) support, such as the emulation or TapBridge (link) features, and those components are not enabled on the Windows versions cited above.
The Tap Bridge is designed to integrate "real" internet hosts (or more precisely, hosts that support Tun/Tap devices) into ns-3 simulations. The goal is to make it appear to a "real" host node in that it has an ns-3 net device as a local device. The concept of a "real host" is a bit slippery since the "real host" may actually be virtualized using readily available technologies such as VMware, VirtualBox or OpenVZ.

11. Software orientation
Key differences from other network simulators: 1) Command-line, Unix orientation 2) Simulations and models written directly in C++ and Python

12. ns timeline 1990 2000 2010 1988: REAL (Keshav) regular releases
1990s: ns-1
1996: ns-2
: DARPA VINT
: DARPA SAMAN, NSF CONSER
2006: NSF CISE CRI Awards
Inputs: yans,
GTNetS, ns-2
ns-3 core development ( )
June 2008: ns-3.1
June 2014: ns-3.20

13. ns is a discrete-event network simulator for Internet systems
Relationship to ns-2
ns is a discrete-event network simulator for Internet systems
protocol design, multiple levels of abstraction
written in multiple languages (C++/OTcl)‏
ns has a companion network animator called nam
hence, has been called the nsnam project
ns-3 is a research-oriented, discrete event simulator

14. Relationship to ns-2
ns-3 is a new simulator, without backward compatibility
Similarities to ns-2:
C++ software core
GNU GPLv2 licensing
ported ns-2 models: random variables, error models, OLSR, Calendar Queue scheduler
Differences:
Python scripting (or C++ programs) replaces OTcl
most of the core rewritten
new animators, configuration tools, etc. are in work
ns-2 is no longer actively maintained/supported

15. Software organization
Two levels of ns-3 software and libraries
1) Several supporting libraries, not system-installed, can be in parallel to ns-3
Netanim
pybindgen
Click routing
ns-3
2) ns-3 modules exist
within the ns-3 directory
module

16. ns-3 Software organization

17. ns-3 Software organization

18. ns-3 Software organization

19. Current models flow-monitor BRITE topology- read utilities stats
config-
store
netanim
visualizer
bridge
csma
emu
point-to-
point
spectrum
tap-bridge
virtual-
net-device
wifi
lte
wimax
devices
uan
mesh
lr-wpan
nix-vector-
routing
aodv
dsdv
olsr
click
protocols
openflow
applications
internet
(IPv4/v6)
propagation
mobility
mpi
energy
network
core 19

20. Current models flow-monitor BRITE topology- read utilities stats
config-
store
netanim
visualizer
bridge
csma
emu
point-to-
point
spectrum
tap-bridge
virtual-
net-device
wifi
lte
wimax
devices
uan
mesh
lr-wpan
nix-vector-
routing
aodv
dsdv
olsr
click
protocols
openflow
Node class
NetDevice ABC
Address types
(Ipv4, MAC, etc.)
Queues
Socket ABC
Ipv4 ABCs
Packet sockets
applications
internet
(IPv4/v6)
propagation
mobility
mpi
energy
Packets
Packet Tags
Packet Headers
Pcap/ascii file writing
Smart pointers
Dynamic types
Attributes
Callbacks
Tracing
Logging
Random Variables
Events
Scheduler
Time arithmetic
network
core 20

21. Example : AODV protocol

22. Example : AODV protocol

23. Python bindings
ns-3 uses a program called PyBindGen to generate Python bindings for all libraries v v v v
Intermediate
Python
program
C++
bindings
code
Python
module
C++
header
(py)gccxml
PyBindGen
C++ compiler

24. NetAnim "NetAnim" by George Riley and John Abraham
see the 'ns-3share' channel on YouTube
pyviz

25. Emulation support
Support moving between simulation and testbeds or live systems
A real-time scheduler, and support for two modes of emulation
Linux is only operating system supported
Must run simulator in real time
GlobalValue::Bind (“SimulatorImplementationType”, StringValue (“ns-3::RealTimeSimulatorImpl”));
Must enable checksum calculations across models
GlobalValue::Bind (“ChecksumEnabled”, BooleanValue (true));
Must sometimes run as root

26. ns-3 emulation modes
ns-3 has been designed for integration into testbed and virtual machine environments.
We have addressed this need by providing two kinds of net devices:
The first kind, which we call an Emu NetDevice allows ns-3 simulations to send data on a “real” network.
The second kind, called a Tap NetDevice allows a “real” host to participate in an ns-3 simulation as if it were one of the simulated nodes.

27. ns-3 emulation modes Various hybrids of the above are possible
real
machine
ns-3
Testbed
2) testbeds interconnect ns-3 stacks
real machine
virtual
machine
virtual
machine
ns-3
1) ns-3 interconnects real or virtual machines
Various hybrids of the above are possible

28. Getting started with ns-3
Agenda
ns-3 project overview
What is ns-3?
Why use ns-3?
Relationship to ns-2
Getting started with ns-3
Installation
Examples
Future directions

29. Getting started with ns-3
Finding what you need
Contributing to the project

30. Resources Web site: Mailing lists: Wiki: Tutorial:
Mailing lists:
Wiki:
Tutorial:
IRC: #ns-3 at freenode.net

31. Work through the ns-3 tutorial
Suggested steps
Work through the ns-3 tutorial
Browse the source code and other project documentation
manual, model library, Doxygen, wiki
ns-3 Consortium tutorials (March 2013)
-meeting-march-2013/
Ask on ns-3-users mailing list if you still have questions
We try to answer most questions

32. Most of the ns-3 API is documented with Doxygen
APIs
Most of the ns-3 API is documented with Doxygen

33. Reading existing code
Much insight can be gained from reading ns-3 examples and tests, and running them yourselves
Many core features of ns-3 are only demonstrated in the core test suite (src/core/test)
Stepping through code with a debugger is informative
callbacks and templates make it more challenging than usual

34. Does ns-3 have a Windows version?
FAQs
Does ns-3 have a Windows version?
Yes, for Visual Studio 2012
Does ns-3 support Eclipse or other IDEs?
Instructions have been contributed by users
Is ns-3 provided in Linux or OS X package systems (e.g. Debian packages)? No

35. Any amount of help is appreciated!
Contributing
Any amount of help is appreciated!
Reporting stale documentation to
Contributing small patches
Writing new documentation
Reporting bugs
Fixing bugs
Reviewing code of others
Contributing new code
Becoming a maintainer

36. Visit the wiki under "Project Ideas" tab
New project ideas
Visit the wiki under "Project Ideas" tab
Students, consider to apply for Google Summer of Code 2015
A 10-week summer job that mentors a student project on ns-3
Students apply in March 2015 timeframe

37. Skills requirement
To write a new protocols or modules
C++
Python (plus)
To do analysis and tests
Shell, awk, or Python, ….
Networking basic skills:
IPv4 address utilization, Lan, wifi, …

38. Getting started
This section is aimed at getting a user to a working state starting with a machine that may never have had ns-3 installed. It covers Ubuntu platform, prerequisites, ways to obtain ns-3, ways to build ns-3, and ways to verify your build and run simple programs.

39. Installation (Prerequisites)
Link:
Example for Ubuntu release; other releases or other Debian-based systems may slightly vary.
C++ (release):
apt-get install gcc g++

40. Installation: (Prerequisites)
Python (release):
Note: qt4 development tools (Note: qt4, not qt5) needed for NetAnim animator
…..Other libraries may be required (depends on the project)
apt-get install python python-dev
apt-get install qt4-dev-tools

41. Installation: ns-3 tarball
$ cd
$ mkdir workspace
$ cd workspace
$ wget
$ tar xjf ns-allinone-3.22.tar.bz2
$ ls
bake constants.py ns README
build.py netanim pybindgen util.py

42. Installation: Building ns-3
$ ./build.py --enable-examples --enable-tests
Waf: Leaving directory `/path/to/workspace/ns-allinone-3.22/ns-3.22/build'
'build' finished successfully (6m25.032s)
Modules built:
antenna aodv applications
bridge buildings config-store
core csma csma-layout ….
Modules not built (see ns-3 tutorial for explanation):
brite click openflow
Visualizer

43. Installation: Building ns-3 with WAF
Configure the optimized code build
$ ./waf clean
$ ./waf --build-profile=optimized --enable-examples --enable-tests configure Or
Configure the Debug build
$ ./waf clean
$ ./waf --build-profile=debug --enable-examples --enable-tests configure

44. Installation: Build
The build system is now configured and you can build the debug versions of the ns-3 programs by simply typing
./waf
Testing ns-3
$ ./test.py -c core
92 of 92 tests passed (92 passed, 0 failed, 0 crashed, 0 valgrind errors)

45. NS-3 installation video

46. Example ./waf --run hello-simulator Run: #include "ns3/core-module.h"
using namespace ns3;
NS_LOG_COMPONENT_DEFINE ("HelloSimulator");
int
main (int argc, char *argv[]) {
NS_LOG_UNCOND ("Hello Simulator"); }

47. Example
Run:
./waf --run hello-simulator

48. Path to examples
/workspaceNS/ns-allinone-3.22/ns-3.22/examples/tutorial

49. Example2: First.cc 1
Server
Client

50. Example2: First.cc

51. Example2: First.cc ///include #include "ns3/core-module.h"
#include "ns3/network-module.h"
#include "ns3/internet-module.h"
#include "ns3/point-to-point-module.h"
#include "ns3/applications-module.h"
///ns3 namespace groups all ns-3-related declarations
using namespace ns3;
//declares a logging component called FirstScriptExample, allows you to enable and disable console message logging
NS_LOG_COMPONENT_DEFINE ("FirstScriptExample");
Namespace :This groups all ns-3-related declarations in a scope outside the global namespace

52. Example2: First.cc int main (int argc, char *argv[])
{//time resolution to one nanosecond
Time::SetResolution (Time::NS);
LogComponentEnable ("UdpEchoClientApplication", LOG_LEVEL_INFO);
LogComponentEnable ("UdpEchoServerApplication", LOG_LEVEL_INFO);
///Node creation
NodeContainer nodes;
nodes.Create (2);
The next step is to create two nodes that we will connect via the point-to-point link.

53. Example2: First.cc ///PointToPoint link
PointToPointHelper pointToPoint;
pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
//NetDevice
NetDeviceContainer devices;
devices = pointToPoint.Install (nodes);

54. Example2: First.cc //Internet Stack InternetStackHelper stack;
stack.Install (nodes);
//Ipv4 network
Ipv4AddressHelper address;
address.SetBase (" ", " ");
Ipv4InterfaceContainer interfaces = address.Assign (devices);

55. Example2: First.cc //Server UDP application configuration
UdpEchoServerHelper echoServer (9);
ApplicationContainer serverApps = echoServer.Install (nodes.Get (1));
serverApps.Start (Seconds (1.0));
serverApps.Stop (Seconds (10.0));

56. Example2: First.cc //Client UDP application configuration
UdpEchoClientHelper echoClient (interfaces.GetAddress (1), 9);
echoClient.SetAttribute ("MaxPackets", UintegerValue (1));
echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.0)));
echoClient.SetAttribute ("PacketSize", UintegerValue (1024));
ApplicationContainer clientApps = echoClient.Install (nodes.Get (0));
clientApps.Start (Seconds (2.0));
clientApps.Stop (Seconds (10.0));

57. Example2: First.cc //Start and stop the simulation Simulator::Run ();
Simulator::Destroy ();
return 0;

58. Example3: create new module
Path where ns-3 is installed
cd /home/master/1er/1erPhd/tools/tarballs/ns-allinone-3.17/ns-3.17/src/
782 ./create-module.py dhvn
Create a new module automatically, for example AAA
./create-module.py AAA

59. Getting started with ns-3
Agenda
ns-3 project overview
What is ns-3?
Why use ns-3?
Project organization
Getting started with ns-3
Installation
Example
Future directions

60. Development Priorities
Software modularity and long-term maintenance
Improved integration of direct code execution
Improved integration with container-based and testbed-based experiment infrastructures
Simulation-based experiment management
Usability

61. Modularity Open source project maintains a (more stable) core
Models migrate to a more federated development process
"bake" tool (Lacage and Camara)
Components:
build client
"module store" server
module metadata
Bake is an integration tool which can be used to automate the reproducible build of a number of projects which depend on each other and which might be developed, and hosted by unrelated parties
Figure source: Daniel Camara

62. SAFE: Simulation Automation Framework
Data collection, transient analysis, management of independent replications, graphical configuration and visualization
In ns-2 realm, similar to projects like ANSWER, ns2measure, and Akaroa2
ns-3
Simulation client
Server host
ns-3
Simulation client
ns-3
Simulation client
Experiment execution
manager
Results database
Client hosts
Figure source: Felipe Perrone

63. Usability Animation and visualization
Linkage to external tools (topology, mobility, statistics)
Improved helper APIs
PyVis (Carneiro)
NetAnim (Riley and Abraham)
pyviz
NetAnim

64. Questions?

65. Bibliography
Tom Henderson (University of Washington), “ ns-3 overview,”