Network Simulator NS2

1
Network Simulator (NS2)

• Slides taken from ISI
• http//www.isi.edu/nsnam/ns/

2
Agenda

• Overview of NS2
• What is NS2
• How to build an NS2 simulation
• NS2 internals
• Language organization
• Network architecture
• How to extend NS2
• Write your code in Otcl
• Write your code in C

3
What is NS

• Discrete event simulator
• Packet-level
• Link layer and up
• Wired and wireless

4
Background

• VINT Virtual InterNet Testbed
• Intended audience
• Researchers, Developers, Educators
• Users from approximately
• 600 institutes
• 50 countries
• Releases
• Periodic releases (currently 2.29, Oct. 2000)
• Nightly snapshots (probably compiles and works,
  but unstable)

5
Research Using NS

• intserv/diffserv (QoS)
• Multicast
• Routing
• Reliable multicast
• Transport
• TCP
• Congestion control
• Application
• Web caching
• Multimedia
• Mobile Computing

6
Current Status

• ns-2 (2.29) Simulator Core
• gt100K lines of C
• gt70K lines of OTcl
• gt30K lines of test suite
• gt20K lines of documentation
• Other Components
• Tcl/TK 8.x, OTcl, TclCL, nam-1
• Tcl-debug, GT-ITM, xgraph,

7
ns Directory Structure
ns-allinone
TK8.0
OTcl
tclcl
Tcl8.0
ns-2
nam-1
C code
...
tcl
ex
test
mcast
lib
...
examples
validation tests
OTcl code
8
Platforms

• Most UNIX and UNIX-like systems
• FreeBSD or BSD
• Linux
• Sun Solaris
• HP, SGI
• Window 95/98/NT
• Work with Cygwin

9
Running simulations with ns

• Compile the simulator core (ns)
• Write a simulation script in Otcl
• e.g. my-test.tcl
• Running the simulator
• e.g. ns my-test.tcl

10
Hello World

• simple.tcl
• set sim new Simulator
• sim at 1 puts \Hello World!\
• sim at 1.5 exit
• sim run
• arches 74 ns simple.tcl
• Hello World!
• arches 75

11
How NS2 is implemented?

• Object-oriented (C, OTcl)
• Extension to Tcl
• C for data
• Per packet action
• OTcl for control
• Periodic or triggered action

12
Elements of ns-2

• Create the event scheduler
• Turn on tracing
• Create network
• Setup routing
• Insert errors
• Create transport connection
• Create traffic
• Transmit application-level data

13
Creating Event Scheduler

• Create event scheduler
• set ns new Simulator
• Schedule events
• ns at lttimegt lteventgt
• lteventgt any legitimate ns/tcl commands
• Start scheduler
• ns run

14
Tracing

• Trace packets on all links
• ns trace-all open test.out w
• lteventgt lttimegt ltfromgt lttogt ltpktgt ltsizegt -- ltfidgt
  ltsrcgt ltdstgt ltseqgt ltattrgt
• 1 0 2 cbr 210 ------- 0 0.0 3.1 0 0
• - 1 0 2 cbr 210 ------- 0 0.0 3.1 0 0
• r 1.00234 0 2 cbr 210 ------- 0 0.0 3.1 0 0
• Trace packets on all links in nam-1 format
• ns namtrace-all open test.nam w

15
Tracing

• Turn on tracing on specific links
• ns trace-queue n0 n1
• ns namtrace-queue n0 n1

16
Creating Network

• Nodes
• set n0 ns node
• set n1 ns node
• Links and queuing
• ns duplex-link n0 n1 ltbandwidthgt ltdelaygt
  ltqueue_typegt
• ltqueue_typegt DropTail, RED, CBQ, FQ, SFQ, DRR

17
Inserting Errors

• Creating Error Module
• set loss_module new ErrorModel
• loss_module set rate_ 0.01
• loss_module unit pkt
• loss_module ranvar new RandomVariable/Uniform
• loss_module drop-target new Agent/Null
• Inserting Error Module
• ns lossmodel loss_module n0 n1

18
Network Dynamics

• Link failures
• Hooks in routing module to reflect routing
  changes
• Four models
• ns rtmodel Trace ltconfig_filegt n0 n1
• ns rtmodel Exponential ltparamsgt n0 n1
• ns rtmodel Deterministic ltparamsgt n0 n1
• ns rtmodel-at lttimegt updown n0 n1
• Parameter list
• ltstartgt ltup_intervalgt ltdown_intervalgt
  ltfinishgt

19
Setup Routing

• Unicast
• ns rtproto lttypegt
• lttypegt Static, Session, DV, cost, multi-path
• Multicast
• ns multicast (right after new Simulator)
• ns mrtproto lttypegt
• lttypegt CtrMcast, DM, ST, BST

20
Creating Connection UDP

• UDP
• set udp new Agent/UDP
• set null new Agent/Null
• ns attach-agent n0 udp
• ns attach-agent n1 null
• ns connect udp null

21
Creating Traffic On Top of UDP

• CBR
• set src new Application/Traffic/CBR
• Exponential or Pareto on-off
• set src new Application/Traffic/Exponential
• set src new Application/Traffic/Pareto

22
Creating Connection TCP

• TCP
• set tcp new Agent/TCP
• set tcpsink new Agent/TCPSink
• ns attach-agent n0 tcp
• ns attach-agent n1 tcpsink
• ns connect tcp tcpsink

23
Creating Traffic On Top of TCP

• FTP
• set ftp new Application/FTP
• ftp attach-agent tcp
• Telnet
• set telnet new Application/Telnet
• telnet attach-agent tcp

24
Creating Traffic Trace Driven

• Trace driven
• set tfile new Tracefile
• tfile filename ltfilegt
• set src new Application/Traffic/Trace
• src attach-tracefile tfile
• ltfilegt
• Binary format (native!)
• inter-packet time (msec) and packet size (byte)

25
Summary Generic Script Structure

• set ns new Simulator
• Turn on tracing
• Create topology
• Setup packet loss, link dynamics
• Create routing agents
• Create
• - multicast groups
• - protocol agents
• - application and/or setup traffic sources
• Post-processing procs
• Start simulation

26
Part II ns Internals
27
OTcl and C The Duality
Pure OTcl objects
Pure C objects
C/OTcl split objects
C
OTcl
ns
28
C/OTcl Linkage
29
TclObject

• Basic hierarchy in ns for split objects
• Mirrored in both C and OTcl
• Example
• set tcp new Agent/TCP
• tcp set packetSize_ 1024
• tcp advance 5000

30
TclObject Hierarchy and Shadowing
TclObject
TclObject
OTcl class hierarchy
C class hierarchy
Agent
Agent
TcpAgent
Agent/TCP
tcp
_o123
Agent/TCP OTcl shadow object
Agent/TCP C object
31
TclObjectbind()

• Link C member variables to OTcl object
  variables
• C
• TcpAgentTcpAgent()
• bind(window_, wnd_)
• bind_time(), bind_bool(), bind_bw()
• OTcl
• set tcp new Agent/TCP
• tcp set window_ 200

32
Initialization of Bound Variables

• Initialization through OTcl class variables
• Agent/TCP set window_ 50
• Do all initialization of bound variables in
  ns/lib/ns-default.tcl
• Otherwise a warning will be issued when the
  shadow object is created

33
TclObjectcommand()

• Implement OTcl methods in C
• Trap point OTcl method cmd
• Send all arguments after cmd call to
  TclObjectcommand()

34
TclObjectcommand()

• OTcl
• set tcp new Agent/TCP
• tcp advance 10
• C
• int TcpAgentcommand(int argc,
• const charconst argv)
• if (argc 3)
• if (strcmp(argv1, advance) 0)
• int newseq atoi(argv2)
• return(TCL_OK)
• return (Agentcommand(argc, argv)

35
TclObjectcommand()
OTcl space
tcp send
TclObjectunknown
tcp cmd send
no such procedure
C space
TcpAgentcommand()
match send?
Yes
No
Invoke parent return Agentcommand()
process and return
36
TclObject Creation and Deletion

• Global procedures new, delete
• Example
• set tcp new Agent/TCP
• delete tcp

37
TclObject Creation and Deletion
invoke parent constructor
OTcl
C
38
Summary

• TclObject
• Unified interpreted (OTcl) and compiled (C)
  class hierarchies
• Seamless access (procedure call and variable
  access) between OTcl and C
• TclClass
• The mechanism that makes TclObject work
• Tcl primitives to access Tcl interpreter

39
ns Internals

• Discrete event scheduler
• Network topology
• Routing
• Transport
• Packet flow
• Packet format
• Application

40
Discrete Event Scheduler
time_, uid_, next_, handler_
head_ -gt

• Three types of schedulers
• List simple linked list, order-preserving, O(N)
• Heap O(logN)
• Calendar hash-based, fastest, O(1)

41
Network Topology Node
Unicast Node
42
Network Topology Link
43
Routing
44
Routing (cont)
Link n0-n1
45
Transport
n0
n1
Port Classifier
Port Classifier
Addr Classifier
Addr Classifier
0
0
dmux_
dmux_
Link n0-n1
entry_
entry_
classifier_
classifier_
Link n1-n0
46
Application Traffic Generator
n0
n1
Port Classifier
Port Classifier
Agent/TCPSink
Addr Classifier
Agent/TCP
Addr Classifier
0
0
agents_
agents_
dmux_
dmux_
Link n0-n1
entry_
entry_
classifier_
classifier_
Link n1-n0
47
Plumbing Packet Flow
n0
n1
Application/FTP
Port Classifier
Port Classifier
Agent/TCPSink
Addr Classifier
Agent/TCP
Addr Classifier
0
0
Link n0-n1
entry_
entry_
Link n1-n0
48
Packet Format
header
data
49
Part III Extending ns
50
ns Directory Structure
ns-allinone
TK8.0
OTcl
tclcl
Tcl8.0
ns-2
nam-1
C code
...
tcl
ex
test
mcast
lib
...
examples
validation tests
OTcl code
51
Extending ns in OTcl

• If you dont want to compile
• source your changes in your sim scripts
• Otherwise
• Modifying code recompile
• Adding new files
• Change Makefile (NS_TCL_LIB), tcl/lib/ns-lib.tcl
• Recompile

52
Example Agent/Message
n4
n2
128Kb, 50ms
n0
n1
10Mb, 1ms
10Mb, 1ms
n3
n5
53
Agent/Message
S
R
pkt 64 bytes of arbitrary string
Receiver-side processing

• A UDP agent (without UDP header)
• Up to 64 bytes user message
• Good for fast prototyping a simple idea
• Usage requires extending ns functionality

54
Agent/Message Step 1

• Define sender
• class Sender superclass Agent/Message
• Message format Addr Op SeqNo
• Sender instproc send-next
• self instvar seq_ agent_addr_
• self send agent_addr_ send seq_
• incr seq_
• global ns
• ns at expr ns now0.1 "self send-next"

55
Agent/Message Step 2

• Define sender packet processing
• Sender instproc recv msg
• self instvar agent_addr_
• set sdr lindex msg 0
• set seq lindex msg 2
• puts "Sender gets ack seq from sdr"

56
Agent/Message Step 3

• Define receiver packet processing
• Class Receiver superclass Agent/Message
• Receiver instproc recv msg
• self instvar agent_addr_
• set sdr lindex msg 0
• set seq lindex msg 2
• puts Receiver gets seq seq from sdr
• self send addr_ ack seq

57
Agent/Message Step 4

• Scheduler and tracing
• Create scheduler
• set ns new Simulator
• Turn on Tracing
• set fd new message.nam w
• ns namtrace-all fd

58
Agent/Message Step 5

• Topology
• for set i 0 i lt 6 incr i
• set n(i) ns node
• ns duplex-link n(0) n(1) 128kb 50ms DropTail
• ns duplex-link n(1) n(4) 10Mb 1ms DropTail
• ns duplex-link n(1) n(5) 10Mb 1ms DropTail
• ns duplex-link n(0) n(2) 10Mb 1ms DropTail
• ns duplex-link n(0) n(3) 10Mb 1ms DropTail
• ns queue-limit n(0) n(1) 5
• ns queue-limit n(1) n(0) 5

59
Agent/Message Step 6

• Routing
• Packet loss produced by queueing
• Routing protocol lets run distance vector
• ns rtproto DV

60
Agent/Message Step 7

• Cross traffic
• set udp0 new Agent/UDP
• ns attach-agent n(2) udp0
• set null0 new Agent/NULL
• ns attach-agent n(4) null0
• ns connect udp0 null0
• set exp0 new Application/Traffic/Exponential
• exp0 set rate_ 128k
• exp0 attach-agent udp0
• ns at 1.0 exp0 start

61
Agent/Message Step 8

• Message agents
• set sdr new Sender
• sdr set packetSize_ 1000
• set rcvr new Receiver
• rcvr set packetSize_ 40
• ns attach n(3) sdr
• ns attach n(5) rcvr
• ns connect sdr rcvr
• ns connect rcvr sdr
• ns at 1.1 sdr send-next

62
Agent/Message Step 9

• End-of-simulation wrapper (as usual)
• ns at 2.0 finish
• proc finish
• global ns fd
• ns flush-trace
• close fd
• exit 0

63
Agent/Message Result

• Example output
• gt ./ns msg.tcl
• Receiver gets seq 0 from 0
• Sender gets ack 0 from 1
• Receiver gets seq 1 from 0
• Sender gets ack 1 from 1
• Receiver gets seq 2 from 0
• Sender gets ack 2 from 1
• Receiver gets seq 3 from 0
• Sender gets ack 3 from 1
• Receiver gets seq 4 from 0
• Sender gets ack 4 from 1
• Receiver gets seq 5 from 0

64
Add Your Changes into ns
ns-allinone
TK8.0
OTcl
tclcl
Tcl8.0
ns-2
nam-1
C code
...
tcl
mcast
lib
ex
test
...
mysrc
examples
validation tests
msg.tcl
OTcl code
65
Add Your Change into ns

• tcl/lib/ns-lib.tcl
• Class Simulator
• source ../mysrc/msg.tcl
• Makefile
• NS_TCL_LIB \
• tcl/mysrc/msg.tcl \
• Or change Makefile.in, make distclean, then
  ./configure --enable-debug

66
Extending ns in C

• Modifying code
• make depend
• Recompile
• Adding code in new files
• Change Makefile
• make depend
• recompile

67
Guidelines

• Decide position in class hierarchy
• I.e., which class to derive from?
• Create new packet header (if necessary)
• Create C class, fill in methods
• Define OTcl linkage (if any)
• Write OTcl code (if any)
• Build (and debug)

68
Example Agent/Message

• New packet header for 64-byte message
• New transport agent to process this new header

69
New Packet Header Step 1

• Create header structure
• struct hdr_msg
• char msg_64
• static int offset_
• inline static int offset() return offset_
• inline static hdr_msg access(Packet p)
• return (hdr_msg) p-gtaccess(offset_)
• / per-field member functions /
• char msg() return (msg_)
• int maxmsg() return (sizeof(msg_))

70
New Packet Header Step 2

• PacketHeader/Message
• static class MessageHeaderClass
• public PacketHeaderClass
• public
• MessageHeaderClass() PacketHeaderClass("PacketH
  eader/Message",
• sizeof(hdr_msg))
• bind_offset(hdr_msgoffset_)
• class_msghdr

71
New Packet Header Step 3

• Enable tracing (packet.h)
• enum packet_t
• PT_TCP,
• ,
• PT_MESSAGE,
• PT_NTYPE // This MUST be the LAST one
• class p_info
• name_PT_MESSAGE message
• name_PT_NTYPE "undefined"

72
New Packet Header Step 4

• Register new header (tcl/lib/ns-packet.tcl)
• foreach pair
• Common off_cmn_
• Message off_msg_

73
Agent/Message Step 1
TclObject
NsObject
Connector
Classifier
Delay
AddrClassifier
Agent
McastClasifier
Queue
Trace
Enq
Deq
Drop
DropTail
RED
TCP
Message
Reno
SACK
74
Agent/Message Step 2

• C class definition
• // Standard split object declaration
• static class MessageClass public TclClass
• public
• MessageClass() TclClass("Agent/Message")
• TclObject create(int, const charconst)
• return (new MessageAgent())
• class_message
• class MessageAgent public Agent
• public
• MessageAgent() Agent(PT_MESSAGE)
• virtual int command(int argc, const charconst
  argv)
• virtual void recv(Packet, Handler)

75
Agent/Message Step 3

• Packet processing send
• int MessageAgentcommand(int, const charconst
  argv)
• Tcl tcl Tclinstance()
• if (strcmp(argv1, "send") 0)
• Packet pkt allocpkt()
• hdr_msg mh hdr_msgaccess(pkt)
• // We ignore message size check...
• strcpy(mh-gtmsg(), argv2)
• send(pkt, 0)
• return (TCL_OK)
• return (Agentcommand(argc, argv))

76
Agent/Message Step 4

• Packet processing receive
• void MessageAgentrecv(Packet pkt, Handler)
• hdr_msg mh hdr_msgaccess(pkt)
• // OTcl callback
• char wrk128
• sprintf(wrk, "s recv s", name(), mh-gtmsg())
• Tcl tcl Tclinstance()
• tcl.eval(wrk)
• Packetfree(pkt)

77
Scalability vs Flexibility

• Its tempting to write all-OTcl simulation
• Benefit quick prototyping
• Cost memory runtime
• Solution
• Control the granularity of your split object by
  migrating methods from OTcl to C

78
THE Merit of OTcl
Program size, complexity
low
high
OTcl
C/C
split objects

• Smoothly adjust the granularity of scripting to
  balance extensibility and performance
• With complete compatibility with existing
  simulation scripts

79
Object Granularity Tips

• Functionality
• Per-packet processing ? C
• Hooks, frequently changing code ? OTcl
• Data management
• Complex/large data structure ? C
• One-time configuration variables ? OTcl

80
Final Word

• My extended ns dumps OTcl scripts!
• Find the last 10-20 lines of the dump
• Is the error related to _o cmd ?
• Check your command()
• Otherwise, check the otcl script pointed by the
  error message

81
Math Support in NS

• Random Numbers
• Tools/rng.cc
• Tool/random.h,cc
• Integrals
• Integrator.h,cc

82
Some examples

• Multicasting
• RTP
• TCP
• Network Dynamics
• /tcl/ex/simple.tcl