NS#3%basics

Roger%Immich,%PhDPostdoctoral%ResearcherInstituto%de%Computação

Universidade Estadual de%Campinas

Summary

1. Why&simulation?2. Introduction&to&ns63&3. Modules4. Basic&components5. Simple&simulation&example6. More&features

ns#3%– Small%introduction 2ns#3%– basics (2)

Introduction*+ Why*simulation?

o Testbed*x*Simulation• Hard%to%reproduce%results• Harder%to%setup%and%change%environment%(even%with%virtualization%and%containers)

• Harder%to%get%new%results• You%can%not%test%a%non%existent%technology/system• Ease%of%deployment

ns+3*– basics (3)

Discrete(event+simulation

o Simulation*time*moves*in*discrete*jumps*from*event*to*event

o C++*functions*schedule*events*to*occur*at*specific*simulation*times

o A*simulation*scheduler*orders*the*event*executiono Simulation::Run()*gets*it*all*startedo Simulation*stops*at*specific*time*or*when*events*end

Execute*a*function(may*generate*additional*events)

Advance*the*virtual*timeto*the*next*event*(function)

Virtual*time

ns(3+– basics (4)

Introduction*+ Why*ns+3?

o There*are*many*other*simulators*out*there!• Not$that$many$are$free,$scalable$and$extensible

o We*already*do*have*ns2,*and*it*is*free!• Lack$of$support$for$development$and$evolution• Split$object$model$(OTcl and$C++)$and$use$of$Tcl is$confusing$for$students,$and$does$not$scale$well

• Lack$of$support$for$creating$methodologically$sound$simulations

• New$modules$were$created$in$a$disorganized$and$non$validated$way

ns+3*– basics (5)

Web$resources

o Web$site:$$http://www.nsnam.org

o Mailing$lists:$$https://groups.google.com/forum/#!forum/ns;3;usershttp://mailman.isi.edu/mailman/listinfo/ns;developers

o Wiki:http://www.nsnam.org/wiki/

o IRC:$#ns;3$at$http://freenode.net

ns+3$– basics (6)

Documentation

o Available(at(https://www.nsnam.org/documentation/o Written(tutorial(for(beginnerso Reference(manual(on(the(ns<3(coreo Model(library(documentationo Source(code(API(documentation

ns,3.– basics (7)

Simulation*Basics

o ns.3*is*built*as*a*system*of*independent*software*libraries*(modules)*that*can*be*combined*together• Remove&dependences&between&modules• Source&code&heavily&based&on&callbacks

o Each*module*is*internally*organized*into:• Models• Examples• Tests• Documentation

ns.3*– basics (8)

NS#3%details

o NS#3%is%a%new%simulator,%written%from%”scratch”• Not$really$an$evolution$of$ns02• Programming$languages:$C++,$Python

o Well,%not%really%from%scratch• Parts%from:

! GTNetS,$Yans,$ns02

o Despite%huge%success%with%ns#2,%the%ns#3%developers%had%project%goals%that%motivated%the%development%of%a%new%tool• Improve$the$realism$of$the$models• Software$reuse• Improved$debugging• Consider$long0term$software$maintenance

ns#3%– basics (9)

Advantageso Scalable

• Packets0can0have0”virtual0zero0bytes”0(or0dummy0bytes)! For$dummy$application$data$that$we$don't$care$about! No$memory$is$allocated$for$virtual$zero$bytes! Reduces$the$memory$footprint$of$the$simulation

o Real=world0Integration• Packets0can0be0saved0to0PCAP0files,0in0a0real0format

! Many$tools$can$read$PCAP$files,$e.g.$Wireshark• Real=time0scheduler

! Simulation$events$synchronized$to$”wall$clock$time”• ”Network0Simulation0Cradle”

! Run$Linux,$FreeBSD$and$OpenBSD$Kernel$TCP/IP$stack$under$simulation• DCE0– Direct0Code0Execution

! Can$run$applications$over$ns3• Integration0into0testbed0and0virtual0machine0environments

! EmuNetDevice:$Send/Receive$data$from/to$simulation$from/to$real$world! Tap$NetDevice:$allows$a$“real”$host$to$participate$in$an$nsS3$simulation$as$if$it$

were$one$of$the$simulated$nodesns=30– Small0introduction 10ns=30– basics (10)

ns#3%emulation%modes

virtualmachine ns.3

virtualmachine

1)2ns.32interconnects2real2or2virtual2machines

realmachine

ns.3

Testbed

realmachine

ns.3

2)2testbeds2interconnect2ns.32stacks

real2machine

Various2hybrids2of2the2above2are2possible

ns#3%– basics (11)

TapBridge and+ns-3+integration

Container

ns*3

Linux

tapX

/dev/tunX

TapBridge

WiFi

ghost&node Wifi ghost&node

tapY

Tap+device+pushed+into+namespaces;+no+bridging+needed

/dev/tunY

ContainerTapBridgeWiFi

ns-3+– basics (12)

Software)introduction

o Download)the)latest)release• wget http://www.nsnam.org/releases/ns-allinone-3.29.tar.bz2

• tar xjf ns-allinone-3.29.tar.bz2

o Clone)the)latest)development)code• hg clone http://code.nsnam.org/ns-3-allinone

Q.##What#is#"hg)clone"?##A.##Mercurial#is#our#source#code#control#tool.#

ns83)– basics (13)

The$'waf'$build$system

o Waf$is$a$Python6based$framework$for$configuring,$compiling$and$installing$applications• Replacement*for*other*tools*such*as*Autotools,*CMake*or*Ant*

• For*those*familiar*with*Autotools:! ./configure " ./waf configure

! make " ./waf build

o Different$parameters$for$configuration• --build-profile=optimized|debug• --enable-examples and*--enable-tests• Check*other*options*with*./waf --help

ns63$– basics (14)

Testing(ns)3

o You(can(run(the(unit(tests(of(the(ns)3(distribution(by(running(the(following(command:• ./test.py -c core

o This(command(is(typically(run(by(users(to(quickly(verify(that(an(ns)3(distribution(has(built(correctly• Don’t&worry&about&‘passed’&tests

ns)3(– basics (15)

Running&scripts

o We&typically&run&scripts&under&the&control&of&Waf• It#sets#key#environment#variables#for#running#programs

• ./waf --run hello-simulator• ./waf --run scratch/example.cc

Congratulations!&You&are&now&an&ns93&user!

ns93&– basics (16)

Basic&components

o Nodeso Applicationso Protocol&stacko Net&deviceso Channelso Helper&API

ns93&– basics (17)

Node

o A&Node&is&a&shell&of&a&computer&to&which&applications,&protocol&stacks,&and&net&devices&are&added

ApplicationApplication

Application

ns83&– basics (18)

Applications

o Abstraction-for-a-user-program-that-generates-some-network-activity-using-an-(asynchronous)-socket-API

ns<3-– basics (19)

Protocol'stack

o Mainly'TCP/IP'stack• Layer&4&protocols&(TCP,&UDP,&ICMP)• Layer&3&protocols&(IPv4,&IPv6,&ARP)

o Also'provides'the'socket'API,'routing'capabilities'and'traffic'control'module

ns?3'– basics (20)

Net$devices$and$channels

o A$NetDevice$is$like$a$NIC,$which$is$strongly$bound$to$a$channel$of$a$matching$type• Nodes&are&architected&for&multiple&interfaces

WifiNetDevice

WifiChannel

ns?3$– basics (21)

NS#3%Modules

node

simulator

core

common

Smart/pointersDynamic/type/system

AttributesCallbacks,/Tracing

LoggingRandom/Variables

EventsScheduler

Time/arithmetic

PacketsPacket/Tags

Packet/HeadersPcap/ascii/file/writing

mobility

Mobility/Models(static,

random/walk,etc.)

Devices:csma/|/wifi/|/...

InternetLstack(ipv4/impl.)

Routing:olsr,globalLrouting

Node/classNetDevice/ABCAddress/types(IPv4,/MAC,/etc.)

QueuesSocket/ABCIPv4/ABCs

Packet/Sockets

helper

HighLlevel/wrappers/foreverything/else.

No/smart/pointers/used.

Aimed/at/scripting.

ns#3%– basics (22)

Helper&API

o The&ns.3&“helper&API”&provides&a&set&of&classes&and&methods&that&make&common&operations&easier&• Container)of)objects• Helper)classes

ns.3&– basics (23)

Helper&APIo Containers&group&similar&objects&together,&for&

convenience• They%are%often%implemented%using%C++%std%containers

o Helper&classes&provides&simple&“syntactical&sugar” to&make&simulation&scripts&look&nicer&and&easier&to&read• They%are%not%generic• Each%function%applies%a%single%operation%on%a%''set%of%the%same%type%objects”

• A%typical%operation%is%Install()

ns@3&– basics (24)

The$basic$model

Net$Device

Protocol$Stack

Application

Channel

Node

Net$Device

Protocol$Stack

Application

Node

Socket$like$API

The$computer$mother$board:$Ram,$IO,$CPU,$Interfaces…

Network$card$which,$can$be$

plugged$in$an$IOinterface$of$a$Node

Interface$between$an$application$and$

a$networkstack

Packet$generator$and$consumer$running$ona$Node

Physical$connector$between$NetDevices

ns/3$– Small$introduction 25ns/3$– basics (25)

Available(models(– Link(layer

o Point5to5point((PPP(links)o Csma (Ethernet(links)o Bridge:(802.1D(Learning(Bridgeo Wifi (802.11(links)• EDCA%QoS%support%(but%not%HCCA)• Both%infrastructure%(with%beacons),%and%adhoc modes

o Mesh• 802.11s%(but%no%legacy%802.11%stations%supported%yet)• ”Flame”:%Forwarding%LAyer for%MEshing protocol

! ”Easy%Wireless:%broadband%adLhoc networking%for%emergency%services”

o Wimax:(802.16• ”supports%the%four%scheduling%services%defined%by%the%

802.16L2004%standard”o Tap5bridge,(emu:(testbed(integrationo LTE

ns53(– Small(introduction 26ns53(– basics (26)

Available(models(– Routing

o Adhoc:• OLSR%(RFC%3626)

! Since%NS%3.8%with%full%HNA%support%(thanks%Latih Suresh)• AODV%(RFC%3561)

o ”Global(routing”((aka(GOD(routing)• Just%computes%static%routes%on%simulation%start

o Nix@vector(Routing• Limited%but%high%performance%static%routing• For%simulations%with%thousands%of%wired%nodes

o List@routing• Joins%multiple%routing%protocols%in%the%same%node• For%example:%static%routing%tables%+%OLSR%+%AODV

ns@3(– Small(introduction 27ns@3(– basics (27)

Propagation*Models

o Propagation*Loss• ITUR1411,(LogDistance,(ThreeLogDistance,(Range,(

TwoRayGround,(Friis• Nakagami,(Jakes• Obstacle(model((*)

o Propagation*Delay• Constant(Speed• Random

o Be*careful*when*using*YansWifiChannelHelper::Default() the(LogDistance propagation(model(is(added.(Calling(AddPropagationLoss() again(will(add(a(secondpropagation(loss(model.

(*)(Presented(in(WNS3(2015

ns93*– basics (28)

Communication*Range

o Depends*on*many*factors• Propagation*loss*model*and*PHY*configuration• Frame*size*(big*vs small)• Transmission*mode*(12Mbps*vs*54*Mbps)

ns53*– basics (29)

Attribute(systemo Each(ns13(object(has(a(set(of(attributes(that(makes(it(easy(to(

verify(the(parameters(of(a(simulation• Name,&help&text,&type,&and&initial&value

o Dump(and(read(them(all(in(configuration(files(and(visualize(them(in(a(GUI

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

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

Attribute Valuens13(– basics (30)

ns#3%– Small%introduction 31

App:echoClient App:echoServer

App:echoServer

Simple%exampleExample4first.cc

Node%0

nodes:$NodeContainer

Node%1Point4to4point4device10.1.1.1 10.1.1.2

App:echoClient

Node%0(10.1.1.1)

UdpEchoClient

UDP$Packet

UDP$Packet

1

2

3

Node%1(10.1.1.2)

UdpEchoServer

> ./waf --run scratch/myFirstSent 1024 bytes to 10.1.1.2Received 1024 bytes from 10.1.1.1Received 1024 bytes from 10.1.1.2

12

3

ns#3%– basics (31)

MORE%FEATURES…

ns.3%– basics (32)

Command'line+arguments

o Add+CommandLine to+your+program+if+you+want+command'line+argument+parsing

o Passing+''PrintHelp to+programs+will+display+command+line+options,+if+CommandLine is+enabled

./waf --run "sample-simulator --PrintHelp"

ns'3+– basics (33)

Packet'Tags

• Small'chunks'of'information• Any'number'of'tags'can'be'attached'a'packet• Tags'are'keyed'by'the'a'structure'type'itselfE.g.:Ptr<Packet> p;MyTag tag;p->AddTag (tag);p->PeekTag (tag);

! New(tag(types(are(defined(similarly(to(header(types! Tags(can(be(used(to:

– Attach(context(information(to(a(packet– Example:(NetDevice(attaches(destination(MAC(address(when(

queueing,(retrieves(it(when(dequeuing(for(transmission– Convey(additional(information(across(layers

ns:3'– basics (34)

Smart&pointerso Smart&pointers&in&ns-3&use&reference&counting&to&improve&

memory&management

o The$class$ns3::Ptr$is$semantically$similar$to$a$traditional$pointer,$but$the$object$pointed$to$will$be$deleted&when&all&references&to&the&pointer&are&gone

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

o 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.

o No$need$to$use$malloc and$free!

ns-3&– basics (35)

Mobility(and(position

o ALL(nodes(have(to(be(created(before(simulation(startso Position(Allocators(setup(initial(position(of(nodes• List,&Grid,&Random&position…&

o Mobility(models(specify(how(nodes(will(move• Constant&position,&constant&velocity/acceleration,&waypoint…

• Trace:file&based&from&mobility&tools&such&as&SUMO,&etc.• Routes&Mobility&using&Google&API&

ns:3(– basics (36)

Trace&Subsystem&– Introduction

o One&of&the&most&important&mechanisms&to&understand&and&evaluate&ns:3&simulations• The$way$to$collect$data$from$the$experiments$and$compare$the$results$against$previous$implementations$or$different$systems

o Many&other&ways&to&get&data&out&of&the&experiment• E.g.$printfs,$logs$to$files…• But$are$they$standard?$Are$they$scalable?$Would$it$work$for$large$development$modules$and$simulations?$

• The$work$may$become$harder$and$harder

ns:3&– Small&introduction 37ns:3&– basics (37)

Tracing

o Decouple.trace.sources.from.trace.sinkso Users.can.implement.specialized.trace.sinks.and.

connect.to.existing.trace.sources.using.pointer.to.functions

Trace&source

Trace&source

Trace&source

Trace&sink

unchanged configurable/by/user

ns83.– basics (38)

FlowMonitor

o Network-monitoring-framework-• Detect%all%flows%passing%through%the%network• Stores%metrics%for%analysis%such%as%bitrates,%duration,%delays,%packet%sizes,%packet%loss%ratios

ns33-– basics (39)

Logging

o Debug*Logging*(not*to*be*confused*with*tracing!)• Used%to%trace%code%execution%logic,%not%to%extract%results!! NS_LOG_ERROR%(...):%serious%error%messages%only! NS_LOG_WARN%(...):%warning%messages! NS_LOG_DEBUG%(...):%rare%adFhoc%debug%messages! NS_LOG_INFO%(...):%informational%messages%(eg.%banners)! NS_LOG_FUNCTION%(...):%function%tracing! NS_LOG_PARAM%(...):%parameters%to%functions! NS_LOG_LOGIC%(...):%control%flow%tracing%within%functions

ns73*– basics (40)

Debugging

o The*gdb*debugger*can*be*used*directly*on*binaries*in*the*build*directory• ./waf --command-template="gdb %s" --run <program-name>

o The*valgrind*memcheck*can*be*used*directly*on*binaries*in*the*build*directory• ./waf --command-template="valgrind %s" --run <program-name>

ns73*– basics (41)

Visualization

o No,preferred,visualizer,for,ns33o Several,tools,have,been,developed,over,the,years,,

with,some,scope,limitations• Pyviz&• NetAnim&(George&Riley&and&John&Abraham)

ns33,– basics (42)

PyViz

o Live)simulation)visualizer)(no)trace)files)o Useful)for)debugging• mobility(model(behavior• packets(being(dropped

ns;3)– basics (43)

NetAnimo Animate)packets)over)wired3links)and)wireless3links)

based)on)trace)files

pyviz

ns33)– basics (44)

o From%where%we%get%the%material%for%this%presentation• Mathieu(Lacage's Trilogy(summer(school(talks• Gustavo(Carneiro's lab(brief(on(ns;3(• George(Riley's(ACM(SpringSim keynote(on(ns;3(• Mathieu(Lacage's Tunis(tutorial(• INRIA(; NS;3(; Small(introduction• NS;3((Luciano(Jerez(Chaves)• NS;3(Training((Tom(Henderson,(2016)• NS;3(Introduction((Tom(Henderson,(2014)• Network(simulation(using ns;3((Walid(Younes,(2013)(• http://www.nsnam.org/tutorials/

ns23%– Small%introduction 45

Sources%

ns23%– basics (45)

EXTRA&SLIDES...

ns.3&– basics (46)

Tracing

ns)3+– basics (47)

Logging&Subsystem&– Select&log&information

o Each&level&can&be&requested&singly&or&cumulativelyo Can&be&activated

• Logging&system&function&callLogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);

o Shell&environment&variable&(NS_LOG)&export NS_LOG=UdpEchoClientApplication=level_info

o Log&is&hierarchical,&activating&a&level&we&activate&all&the&lower&level&ones• In&this&case&NS_LOG_INFO, NS_LOG_DEBUG, NS_LOG_WARN and&

NS_LOG_ERROR

[dcamara@guacharo ns-3-dev]$ ./waf --run scratch/myFirstWaf: Entering directory `/home/dcamara/INRIA/repos/ns-3-allinone/ns-3-dev/build'Waf: Leaving directory `/home/dcamara/INRIA/repos/ns-3-allinone/ns-3-dev/build''build' finished successfully (2.807s)Sent 1024 bytes to 10.1.1.2Received 1024 bytes from 10.1.1.1Received 1024 bytes from 10.1.1.2

nsC3&– Small&introduction 48nsC3&– basics (48)

Trace&Subsystem&– Using&the&Config&Subsystem&to&Connect&to&Trace&Sources

o The&most&common&way&to&access&the&sources&is&through&the&Config'subsystem'through&the&config'path

o This&function&takes&a&path&that&represents&a&chain&of&Object&pointers&and&follows&them&until&it&gets&to&the&end&of&the&path&and&interprets&the&last&• The$last$segment$has$to$be$an$attribute

ns>3&– Small&introduction 49

Config::ConnectWithoutContext ("/NodeList/0/$ns3::TcpL4Protocol/SocketList/0/CongestionWindow",MakeCallback (&CwndTracer));

/NodeList/0/$ns3::TcpL4Protocol/SocketList/0/CongestionWindow

ns>3&– basics (49)

Callbackso ns)3+Callback class+implements+function(objects

• Type%safe%callbacks,%manipulated%by%value• Used%for%example%in%sockets%and%tracing

o ExampleClass MyClass {public:

double MyFunc (int x, float y) {return double (x + y) / 2;

}[...]

Callback<double, int, float> cb1;MyClass myobj;cb1 = MakeCallback(&MyClass::MyFunc, &myobj);double result = cb1 (2,3); // result receives 2.5

ns)3+– basics (50)

Packetso Packet(uses(an(advanced(data(structure• Supports(real(or(virtual(application(data• Serializable((for(emulation)• Supports(pretty8printing• Efficient((copy8on8write(semantics)

o Packet(tag(objects(allow(packets(to(carry(around(simulator8specific(metadata

ns83(– basics (51)