Chapter 2 : The ns-3 Network Simulator

George F. RileyThomas R. Henderson

2

ns-3 Introduction

ns-3 (http://www.nsnam.org) is a free, open source software project building and maintaining a discrete-event network simulator for research and education

Technical goals: Build and maintain a simulation core

aligned with the needs of the research community

Help to improve the technical rigor of network simulation practice

3

ns-3 themes Research and education focus

Build and maintain simulation core, integrate models developed by other researchers

Support research-driven workflows Open source development model

Research community maintains the models Leverage available tools and models

Write programs to work together Enforce core coding/testing standards

4

ns-3 software overview

ns-3 is written in C++, with bindings available for Python simulation programs are C++ executables or

Python programs Python is often a glue language, in practice

ns-3 is a GNU GPLv2-licensed project

ns-3 is not backwards-compatible with ns-2

5

ns simulators: a brief history

1988: REAL (Keshav)

1997-2000: DARPA VINT

1990s: ns-11996: ns-2

2001-04: DARPA SAMAN, NSF CONSER2006: ns-3 funded (NSF, INRIA)

June 2008: ns-3.1 releasens-3 core development (2006-08)ns-3 features a

new simulationcore, with modelsdrawn from GTNetS,ns-2, and the "yans" network simulator

1990 2000 2010

quarterlyreleasessince ns-3.1

6

Acknowledgment of support

7

2.1 Introduction

8

Why ns-3? Despite huge success with ns-2, the ns-3

developers had project goals that motivated the development of a new tool

1) Improve the realism of the models2) Software reuse3) Improved debugging4) Consider long-term software maintenance

9

1) attention to realismProblem: Research often involves a mix of

simulations and testbed or live experiments

If the simulator cannot be made to closely model a real system: hard to compare results or validate the model hard to reuse software between the two

domains ns-3 solution:

model nodes more like a real computer support key interfaces such as sockets API and

IP/device driver interface (in Linux) reuse of kernel and application code

10

1) attention to realism (example)

An ns-3 Node is a husk of a computer to which applications, stacks, and NICs are added

ApplicationApplicationApplication

(operatingsystems)

11

2) software integrationProblem: why reimplement models and

tools for which open-source implementations abound?

ns-3 solution: ns-3 conforms to standard input/output

formats so that other tools can be reused. e.g., pcap trace output, ns-2 mobility scripts

ns-3 is adding support for running implementation code Network Simulation Cradle (Jansen) integration

has met with success: Linux TCP code ns-3 “direct code execution” environment

12

2) software reuse (cont.) Example: ns-3 trace viewed with

Wireshark:

13

3) Improved debugging Avoid split-language object implementations

that proved to be hard to debug in ns-2 (OTcl/C++)

ns-3 uses a C++ core with Python API bindings

Layer a "helper" API on top of a powerful but complex low-layer API

Different APIs for different user expertise

Reduce memory errors via use of smart pointers

14

4) Software maintenance Open source projects are challenged to

maintain the software over time Developers contribute models, then graduate Maintainers change over time

ns-3 chose to use a more rigorous coding standard, detailed code reviews, and regression testing infrastructure

ns-3 project decided not to devote scarce maintenance resources to develop and maintain ns-2 backward compatibility

15

2.2 Modeling the Network Elements in ns-3

16

2.2 Modeling the Network Elements in ns-3 Key objects in ns-3: nodes, devices, channels,

protocols, packets, headers

ApplicationApplication

Protocolstack

NodeNetDeviceNetDevice

ApplicationApplication

Protocolstack

Node

NetDevice

Channel

Packet

17

Random Variables

Currently implemented distributions Uniform: values uniformly distributed in an interval Constant: value is always the same (not really random) Sequential: return a sequential list of predefined values Exponential: exponential distribution (poisson process) Normal (gaussian) Log-normal pareto, weibull, triangular, …

18

ns-3 random number generator Uses the MRG32k3a generator from

Pierre L'Ecuyer http://www.iro.umontreal.ca/~lecuyer/

myftp/papers/streams00.pdf Period of PRNG is 3.1x10^57

Partitions a pseudo-random number generator into uncorrelated streams and substreams Each RandomVariable gets its own stream This stream partitioned into substreams

Independent replications are handled by incrementing the run number to obtain uncorrelated substreams

19

Tracing and statistics

Tracing is a structured form of simulation output Example (from ns-2):+ 1.84375 0 2 cbr 210 ------- 0 0.0 3.1 225 610- 1.84375 0 2 cbr 210 ------- 0 0.0 3.1 225 610r 1.84471 2 1 cbr 210 ------- 1 3.0 1.0 195 600r 1.84566 2 0 ack 40 ------- 2 3.2 0.1 82 602+ 1.84566 0 2 tcp 1000 ------- 2 0.1 3.2 102 611

Problem: Tracing needs vary widely would like to change tracing output without editing the core would like to support multiple outputs

20

ns-3 has a new tracing model

ns-3 solution: decouple trace sources from trace sinks

Benefit: Customizable trace sinks

Trace source

Trace source

Trace source

Trace sink

unchangingconfigurable byuser

21

ns-3 tracing various trace sources (e.g., packet receptions,

state machine transitions) are plumbed through the system

Documented in a central place

22

Basic tracing Helper classes hide the tracing details from the

user, for simple trace types ascii or pcap traces of devices

std::ofstream ascii; ascii.open ("wns3-helper.tr"); CsmaHelper::EnableAsciiAll (ascii); CsmaHelper::EnablePcapAll ("wns3-helper"); YansWifiPhyHelper::EnablePcapAll ("wsn3-helper");

23

Multiple levels of tracing

Highest-level: Use built-in trace sources and sinks and hook a trace file to them

Mid-level: Customize trace source/sink behavior using the tracing namespace

Low-level: Add trace sources to the tracing namespace

Or expose trace source explicitly

24

Highest-level of tracing Use built-in trace sources/sinks, and hook a trace file

to them // Also configure some tcpdump traces; each interface will be traced // The output files will be named // simple-point-to-point.pcap-<nodeId>-<interfaceId> // and can be read by the "tcpdump -r" command (use "-tt" option to // display timestamps correctly) PcapTrace pcaptrace ("simple-point-to-point.pcap"); pcaptrace.TraceAllIp ();

25

Mid-level of tracing

Mid-level:Customize trace source/sink behaviour with tracing

namespacevoidPcapTrace::TraceAllIp (void){ NodeList::Connect ("/nodes/*/ipv4/(tx|rx)", MakeCallback (&PcapTrace::LogIp, this));}

Regular expression editing

Hook in a different trace sink

26

ns-3 attribute system

Problem: Researchers want to identify all of the values affecting the results of their simulations and configure them easily

ns-3 solution: Each ns-3 object has a set of attributes: A name, help text A type An initial value

Control all simulation parameters for static objects

Dump and read them all in configuration files Visualize them in a GUI Makes it easy to verify the parameters of a

simulation

27

Use cases for attributes

An Attribute represents a value in our system An Attribute can be connected to an underlying

variable or function e.g. TcpSocket::m_cwnd; or a trace source

28

Use cases for attributes (cont.)

What would users like to do? Know what are all the attributes that affect the simulation at

run time Set a default initial value for a variable Set or get the current value of a variable Initialize the value of a variable when a constructor is called

The attribute system is a unified way of handling these functions

29

How to handle attributes

The traditional C++ way: export attributes as part of a class's public API walk pointer chains (and iterators, when needed) to find what

you need use static variables for defaults

The attribute system provides a more convenient API to the user to do these things

30

Navigating the attributes

Attributes are exported into a string-based namespace, with filesystem-like paths

namespace supports regular expressions This allows individual instances of attributes to be manipulated

Attributes also can be referenced by name without specifying a path through the object namespace

e.g. “ns3::WifiPhy::TxGain” This allows users to manipulate a global (default) value of the

attribute A Config class allows users to manipulate the

attributes

31

Attribute namespace

strings are used to describe paths through the namespace

Config::Set ("/NodeList/1/$ns3::Ns3NscStack<linux2.6.26>/net.ipv4.tcp_sack", StringValue ("0"));

32

Navigating the attributes using paths

Examples: Nodes with NodeIds 1, 3, 4, 5, 8, 9, 10, 11:

“/NodeList/[3-5]|[8-11]|1” UdpL4Protocol object instance aggregated to matching nodes:

“/$ns3::UdpL4Protocol”

33

What users will do

e.g.: Set a default initial value for a variableConfig::Set (“ns3::WifiPhy::TxGain”, DoubleValue (1.0));

Syntax also supports string values:Config::Set (“WifiPhy::TxGain”, StringValue (“1.0”));

Attribute Value

34

Fine-grained attribute handling

Set or get the current value of a variable Here, one needs the path in the namespace to the right

instance of the objectConfig::SetAttribute(“/NodeList/5/DeviceList/3/Phy/TxGain”, DoubleValue(1.0));

DoubleValue d; nodePtr->GetAttribute ( “/NodeList/5/NetDevice/3/Phy/TxGain”, v);

Users can get pointers to instances also, and pointers to trace sources, in the same way

35

ns-3 attribute system

Object attributes are organized and documented in the Doxygen

Enables the construction of graphical configuration tools:

36

Attribute documentation

37

Options to manipulate attributes

Individual object attributes often derive from default values Setting the default value will affect all subsequently created

objects Ability to configure attributes on a per-object basis

Set the default value of an attribute from the command-line:CommandLine cmd;cmd.Parse (argc, argv);

Set the default value of an attribute with NS_ATTRIBUTE_DEFAULT

Set the default value of an attribute in C++:Config::SetDefault ("ns3::Ipv4L3Protocol::CalcChecksum",BooleanValue (true));

Set an attribute directly on a specic object:Ptr<CsmaChannel> csmaChannel = ...;csmaChannel->SetAttribute ("DataRate",StringValue ("5Mbps"));

38

2.3 Simulating a Computer Network in ns-3

39

Four basic steps to perform

1. Create the network topology

2. Create the data demand on the network

3. Execute the simulation

4. Analyze the results

Program listing 2-1 annotates the file "first.cc", whichis the first tutorial program discussed in the ns-3 tutorial

40

2.4: Smart Pointers in ns-3

41

Smart Pointers Memory management in a C++ program is a

complex process, and is often done incorrectly or inconsistently.

We have settled on a reference counting design using so-called "smart-pointers"

All objects maintain an internal reference count that allows the object to safely delete itself when the count goes to zero

We provide a class called "Ptr" that is similar to the intrusive_ptr of the Boost C++ library

This implementation allows you to manipulate the smart pointer as if it was a normal pointer: you can compare it with zero, compare it against other pointers, assign zero to it, etc.

42

2.5: Representing Packets in ns-3

43

2.5: Representing Packets in ns-3 The design of the Packet framework of ns-3 was

heavily guided by a few important use-cases: avoid changing the core of the simulator to introduce new

types of packet headers or trailers maximize the ease of integration with real-world code and

systems make it easy to support fragmentation, defragmentation,

and, concatenation which are important, especially in wireless systems.

make memory management of this object efficient allow actual application data or dummy application bytes

for emulated applications Each network packet contains a byte buffer, a set of

byte tags, a set of packet tags, and metadata.

44

Packet class organization

class Packet providesthe user API

each Packet has a reference to a Bufferholding packed packetdata

optional PacketMetadataprovides metadataabout the contents ofthe buffer to enable(e.g.) pretty-printing

Packet Tags containsimulation-specificinformation such ascross-layer messages, or simulation flow IDs

45

Copy-on-write semantics Packets implement copy-on-write semantics to

reduce the number of deep data buffer copies during a simulation

Packets are reference-counted objects; multiple clients can hold references to the same packet, and the packet is automatically freed when all references are deleted

When more than one reference to a packet buffer exists, the packet buffer can be shared unless a so-called "dirty"operation (such as editing a protocol header) is performed by one of the packet users

46

2.6: Object Aggregation in ns-3

47

ns-3 object aggregationProblem: coupling between models hinders

software reuse in different configurations must intrusively edit the base class for this or, leads to C++ downcasting, e.g.:

// Channels use Node pointers, but here I really want a // MobileNode pointer, to access the MobileNode API

doubleWirelessChannel::get_pdelay(Node* tnode, Node* rnode){ // Scheduler &s = Scheduler::instance(); MobileNode* tmnode = (MobileNode*)tnode; MobileNode* rmnode = (MobileNode*)rnode;

known as the C++ “weak base class” problem

48

ns-3 object aggregation (cont.)ns-3 solution: an object aggregation model objects can be aggregated to other objects

at run-time a “query interface” is provided to ask

whether an particular object is aggregated similar in spirit to COM or Bonobo objects

// aggregate an optional mobility object to a node:node->AggregateObject (mobility);...

// later, other users of node can query for the optional object: senderMobility = i->first->GetNode ()->GetObject<MobilityModel> ();

// we did not have to edit class Node (base class), or downcast!

49

2.7: Events in ns-3

50

Events in discrete-event simulation

Simulation time moves discretely 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

51

Events in ns-3 An event in ns-3 is simply a function pointer with

some state (the technical term is a "functor")

Any object method or static function can be used as an event handler in ns-3

e.g. Simulator::Schedule (function name, object pointer, arguments);

This is different from several other discrete-event simulators, where special Handler() methods provide a centralized place for processing events on an object

52

2.7: Events in ns-3static voidExampleFunction (MyModel *model){ std::cout << "ExampleFunction received event at " << Simulator::Now ().GetSeconds () << "s" << std::endl; model->Start ();}

int main (int argc, char *argv[]){ MyModel model; Simulator::Schedule (Seconds (10.0), &ExampleFunction, &model); Simulator::Run ();

Simulator::Destroy ();} An event: At time 10 seconds,

call ExampleFunction() with the argument &model.

53

2.8 Compiling and Running the Simulation

54

ns-3 uses the waf build system

Waf is a Python-based framework for configuring, compiling and installing applications.

It is a replacement for other tools such as Autotools, Scons, CMake or Ant

http://code.google.com/p/waf/ For those familiar with autotools:

Autotools -> Waf equivalentconfigure -> ./waf -d [optimized|debug] configuremake -> ./waf

55

Running programs Programs are built as build/<variant>/path/program-name

programs link shared library libns3.so Using ./waf --shell

./waf --shell

./build/debug/samples/main-simulator Using ./waf --run

./waf --run examples/csma-bridge

./waf --pyrun examples/csma-bridge.py

56

2.9: Animating the Simulation

57

Animation Overview

ns-3 not directly funding visualizers and configurators no “official” tool; expect multiple to be developed Not integrated (directly) with ns-3

Ns-3 creates “animation” file, visualizers use this as input and create the animation.

netanim, pyviz, and nam for ns-3

58

Pyviz: A Python-based animator

59

NetVis

60

NetVis / XML Interface<anim lp = "0”><topology minX = "1000" minY = "2382.3" maxX = "10900" maxY = "8617.7"><node lp = "0" id = "0" locX = "4000" locY = "5500” image = "Satellite.png" imageScale = "10.0"/><node lp = "0" id = "1" locX = "7000" locY = "5500” image ="Satellite.png" imageScale = "5.0"/><link fromLp = "0" fromId = "0" toLp = "0" toId = "1"/></topology>

<packet fromLp = "0" fromId = "11" fbTx = "0.66483" lbTx = "0.665264"><rx toLp = "0" toId = "1" fbRx = "0.66583" lbRx = "0.666264"/></packet>

<wpacket fromLp = "0" fromId = "49" fbTx = "0.549245" lbTx = "0.549497” range = "250"><rx toLp = "0" toId = "16" fbRx = "0.549497" lbRx = "0.549749"/><rx toLp = "0" toId = "18" fbRx = "0.549497" lbRx = "0.549749"/><rx toLp = "0" toId = "29" fbRx = "0.549497" lbRx = "0.549749"/><rx toLp = "0" toId = "32" fbRx = "0.549498" lbRx = "0.549749"/><rx toLp = "0" toId = "36" fbRx = "0.549498" lbRx = "0.549749"/><rx toLp = "0" toId = "37" fbRx = "0.549497" lbRx = "0.549749"/></wpacket></anim>

61

2.10: Scalability with Distributed Simulation

62

Overview Parallel and distributed discrete event simulation

Allows single simulation program to run on multiple interconnected processors

Reduced execution time! Larger topologies! Terminology

Logical process (LP) Rank or system id

63

Quick and Easy Example

Figure 1. Simple point-to-point topology

64

Quick and Easy Example

Figure 2. Simple point-to-point topology, distributed

65

Implementation Details LP communication

Message Passing Interface (MPI) standard Send/Receive time-stamped messages MpiInterface in ns-3

Synchronization Conservative algorithm using lookahead DistributedSimulator in ns-3

66

Implementation Details (cont.) Assigning rank

Currently handled manually in simulation script Next step, MpiHelper for easier node/rank mapping

Remote point-to-point links Created automatically between nodes with different ranks through point-

to-point helper Packet sent across using MpiInterface

67

Distributing the topology All nodes created on all LPs, regardless of rank Applications are only installed on LPs with target node

Implementation Details (cont.)

Figure 3. Mixed topology, distributed

68

Performance Test DARPA NMS campus network simulation

Allows creation of very large topologies Any number of campus networks are created and connected together Different campus networks can be placed on different LPs Tested with 2 CNs, 4 CNs, and 6 CNs

69

Campus Network Topology

Figure 4. Single campus network

70

2 Campus Networks

Figure 5. Execution time with 2 campus networks Figure 6. Speedup with 2 LPs

0

500

1000

1500

2000

2500

3000

3500

4000

4500

116 164 260 452 836

Tim

e (s

)

Number of nodes

1 LP

2 LPs

1.5

1.75

2

2.25

2.5

116 164 260 452 836

Spee

dup

Number of nodes

71

Summary Distributed simulation in ns-3 allows a user to run a single

simulation in parallel on multiple processors By assigning a different rank to nodes and connecting these

nodes with point-to-point links, simulator boundaries are created

Simulator boundaries divide LPs, and each LP can be executed by a different processor

Distributed simulation in ns-3 offers solid performance gains in time of execution for large topologies

72

2.11: Emulation Capabilities

73

Emulation support

Support moving between simulation and testbeds or live systems

A real-time scheduler, and support for two modes of emulationGlobalValue::Bind (“SimulatorImplementationType”, StringValue (“ns3::RealTimeSimulatorImpl”));

74

ns-3 emulation modes

virtualmachin

e ns-3virtualmachin

e

1) ns-3 interconnects real or virtual machines

realmachin

e

ns-3

Testbed

realmachin

e

ns-3

2) testbeds interconnect ns-3 stacks

real machine

Various hybrids of the above are possible

75

Example: ns-3 with Linux Network Namespaces

Container

ns-3

Linux (FC 12 or Ubuntu 9.10) machine

tapX/dev/tunX

TapBridgeWiFi

ghost node Wifi

ghost node

tapY/dev/tunY

Container

Makes use of a "ghost node" that bridges packets to aLinux namespace container running the protocol stackand applications

76

Example: ORBIT and ns-3

• Support for use of Rutgers WINLAB ORBIT radio grid

Image from ORBIT - Wireless Network Testbed website

77

Issues in Performing "Co-Simulation" Ease of use

Configuration management and coherence Information coordination (two sets of state)

e.g. IP/MAC address coordination Output data exists in two domains Debugging

Error-free operation (avoidance of misuse) Synchronization, information sharing, exception

handling Checkpoints for execution bring-up Inoperative commands within an execution domain Deal with run-time errors

Soft performance degradation (CPU) and time discontinuities

78

2.12: Analyzing the Results

79

Frameworks for ns-3 NSF CISE Community Research

Infrastructure University of Washington (Tom Henderson),

Georgia Tech (George Riley), Bucknell Univ. (Felipe Perrone)

Project timeline: 2010-14

Figure courtesy of Dr. Felipe Perrone, Bucknell University

80

Automation Inspired by SWAN-Tools and ANSWER

frameworks. User interfaces, description languages,

and tools for automation of experiments. Model composition, structural validation,

control of experiments, data processing and storage, and archiving experimental setup.

81

Topology generation

Integrate BRITE topology generator (Boston Univ.) into framework.

BRITE is downloaded into distribution and compiled by the ns-3 build system.

The ns-3 simulation script uses a topology helper which reads a BRITE configuration file, receives results from BRITE, and builds the ns-3 topology.

82

Higher-level modeling and experiment description

Provide a model and a description of experiment.

Framework generates design of experiment space, distribute simulation runs to machines, collect results and archive in persistent storage.

User mines storage to find, extract, and visualize results.Figure courtesy of Dr. Felipe Perrone, Bucknell University

83

General architecture

Figure courtesy of Dr. Felipe Perrone, Bucknell University