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

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

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

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

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

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

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.

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

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

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. https://www.nsnam.org/docs/release/3.9/doxygen/group___tap_bridge_model.html 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.

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

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

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

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

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

ns-3 Software organization

ns-3 Software organization

ns-3 Software organization

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

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

Example : AODV protocol

Example : AODV protocol

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

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

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

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.

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

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

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

Resources Web site: Mailing lists: Wiki: Tutorial: http://www.nsnam.org Mailing lists: https://groups.google.com/forum/#!forum/ns-3-users http://mailman.isi.edu/mailman/listinfo/ns-developers Wiki: http://www.nsnam.org/wiki/ Tutorial: http://www.nsnam.org/docs/tutorial/tutorial.html IRC: #ns-3 at freenode.net

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) http://www.nsnam.org/consortium/activities/annual -meeting-march-2013/ Ask on ns-3-users mailing list if you still have questions We try to answer most questions

Most of the ns-3 API is documented with Doxygen APIs Most of the ns-3 API is documented with Doxygen http://www.stack.nl/~dimitri/doxygen/

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

Does ns-3 have a Windows version? FAQs Does ns-3 have a Windows version? Yes, for Visual Studio 2012 http://www.nsnam.org/wiki/Ns-3_on_Visual_Studio_2012 Does ns-3 support Eclipse or other IDEs? Instructions have been contributed by users http://www.nsnam.org/wiki/HOWTO_configure_Eclipse_with_ns-3 Is ns-3 provided in Linux or OS X package systems (e.g. Debian packages)? No

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

Visit the wiki under "Project Ideas" tab New project ideas Visit the wiki under "Project Ideas" tab http://www.nsnam.org/wiki/Project_Ideas 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 http://www.nsnam.org/wiki/GSOC2014Projects

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, …

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.

Installation (Prerequisites) Link: https://www.nsnam.org/docs/tutorial/html/getting-started.html#overview https://www.nsnam.org/wiki/Installation Example for Ubuntu 14.10 release; other releases or other Debian-based systems may slightly vary. C++ (release): apt-get install gcc g++

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

Installation: ns-3 tarball $ cd $ mkdir workspace $ cd workspace $ wget http://www.nsnam.org/release/ns-allinone-3.22.tar.bz2 $ tar xjf ns-allinone-3.22.tar.bz2 $ ls bake constants.py ns-3.22 README build.py netanim-3.105 pybindgen-0.16.0.886 util.py

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

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

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)

NS-3 installation video https://www.youtube.com/watch?v=Fbk89Nb-7M0&feature=youtu.be

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"); }

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

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

Example2: First.cc 1 Server Client

Example2: First.cc

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

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.

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

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

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));

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));

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

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

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

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

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

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

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

Questions?

Bibliography Tom Henderson (University of Washington), “ ns-3 overview,” https://www.nsnam.org/docs/tutorial/html/getting-started.html https://www.nsnam.org/wiki/Installation