Comprehensive NS-2 Simulation Tutorial: Getting Started with TCL/OTCL and Protocols

1. CprE 543x – ns-2 Tutorial Zak Abichar, abicharz@iastate.edu Dept of Electrical and Computer Engineering Iowa State University Ames, IA 50011 Based on a presentation by Polly Huang (2nd European ns-2 Workshop, April 2001)

2. Tutorial Goals • overview/intro/essentials/getting started • tcl/otcl/ns-2 fundamentals • designing a simulation • examples

3. Outline • Introduction • The project, the software, the philosophy • Software architecture • Installation and getting started • About extending ns-2 • tcl/otcl/ns-2 fundamentals • Programming tcl/otcl • Running a ns-2 simulation • Simulation design • Example scripts

4. Multi-state collaboration • AT&T Research • Lawrence Berkeley National Laboratory • UC Berkeley • USC/ISI • Xerox PARC • ETH TIK (Swiss Federal Institute of Technology)

5. Project Goal • To support collaborative simulation effort • promote sharing • incorporate recent simulation models • increase confidence in results • establish regression test suite • establish common reference • current and periodic availability of source code • Base software is ns-2

6. ns-2 • Discrete event simulator • Packet level • Link layer and up • Wired and wireless

7. Development Status • Columbia NEST • UCB REAL • ns-1 • ns-2 • 100K lines of C++ code • 70K lines of otcl support code • 30K lines of test suites • 20K lines of documentation

8. Usage and Releases • Users from approximately • 600 institutes • 50 countries • Releases • periodic official releases • nightly snapshots (probably compiles and works, but buyers beware) • available from USC/ISI or UK mirror

9. Words of Caution • While we have considerable confidence in ns, ns is not a polished and finished product, but the result of an ongoing effort of research and development. In particular, bugs in the software are still being discovered and corrected. • Users of ns are responsible for verifying for themselves that their simulations are not invalidated by bugs.

10. Preliminary for NS-2 • Ability to write correct programs • Familiarity with object-oriented programming • Patience to debug NS source code when needed • Simple usage will not need NS source code debugging • More complex simulations may need modification to NS source code • Debugging skills • NS uses C++ and Otcl • User scripts are in Otcl

11. What you can do using NS-2 • Simulate different scenarios with existing protocols (TCP/UDP) • Wired Routing protocols - Distance Vector and Link State (with the link state patch) • Ad-Hoc Routing protocols - DSR, AODV, TORA • MAC protocols - 802.3, 802.11 (Wireless MAC) • Scheduling disciplines - DropTail, RED, WFQ, DRR, LQD etc. • Different traffic characterizations - Poisson, Exponential, Pareto etc.

12. What you can do using NS-2 • Modify NS-2 to implement your own versions of the above protocols or even code totally new protocols • Measurement of Statistics: • Throughput, Delay, Jitter etc. • Queue Monitoring, Drops at Queues. • Literally all that you will need to know with your simulations. • Graphic visualization - using “nam” (Network Animator)

13. The downside • Cannot capture all the nuances of the real world networks. • Very large scale simulations take a lot of time – they may not be feasible • Still in the research phase, and there may be many more bugs lurking out there • Documentation not adequate • No fancy user interface – often perceived as “unfriendly” (at least by people who are new to ns-2)

14. Outline • Introduction • The project, the software, the philosophy • Software architecture • Installation and getting started • About extending ns-2 • tcl/otcl/ns-2 fundamentals • Programming tcl/otcl • Running a ns-2 simulation • Simulation design • Example scripts

15. Object-Oriented • Reusability • Maintainability • Careful planning ahead • Performance

16. C++ and otcl Separation • C++ for data • per packet action • otcl for control • periodic or triggered action • Compromize between composibility and speed • Learning & debugging

17. otcl and C++: The Duality C++ otcl

18. tcl Interpreter With Extents Event Scheduler • otcl: Object-oriented support • tclcl: C++ and otcl linkage • Discrete event scheduler • Data network components ns-2 tclcl Network Component otcl tcl8.0

19. Installation • Getting the code: • http://www.isi.edu/nsnam/ns/ • Installing ns-2 • http://csl.ee.iastate.edu/~cpre543/ns2_howToInstall.htm

20. About extending ns-2 • Implement new functionalities not covered in ns-2 • Essential for researchers • Implementing and evaluating new protocols and schemes • Requires the understanding of the internal architecture • Not that hard • Need more information?

21. Outline • Introduction • The project, the software, the philosophy • Software architecture • Installation and getting started • About extending ns-2 • tcl/otcl/ns-2 fundamentals • Programming tcl/otcl • Running a ns-2 simulation • Simulation design • Example scripts

22. Hello World simple.tcl set ns [new Simulator] $ns at 1 “puts \“Hello World!\”” $ns at 1.5 “exit” $ns run % ns simple.tcl Hello World! %

23. Fundamentals • tcl • otcl • ftp://ftp.tns.lcs.mit.edu/pub/otcl/doc/tutorial.html • ns-2 • http://www.isi.edu/nsnam/ns/ns_doc.ps.gz • http://www.isi.edu/nsnam/ns/ns_doc.pdf • http://www.isi.edu/nsnam/ns/doc/index.html

24. Basic tcl k < 5, pow = 1.0 k < 5, pow = 1120.0 k < 5, pow = 1254400.0 k < 5, pow = 1404928000.0 k < 5, pow = 1573519360000.0 k > 5, mod = 0 k > 5, mod = 4 k > 5, mod = 0 k > 5, mod = 0 k > 5, mod = 4 proc test {} { set a 43 set b 27 set c [expr $a + $b] set d [expr [expr $a - $b] * $c] for {set k 0} {$k < 10} {incr k} { if {$k < 5} { puts “k < 5, pow= [expr pow($d, $k)]” } else { puts “k >= 5, mod= [expr $d % $k]” } } } test

25. Class mom mom instproc init {age} { $selfinstvar age_ set age_ $age } mom instproc greet {} { $selfinstvar age_ puts “$age_ years old mom: How are you doing?” } Class kid -superclass mom kid instproc greet {} { $selfinstvar age_ puts “$age_ years old kid: What’s up, dude?” } set a [new mom 34] set b [new kid 6] $a greet $b greet Basic otcl 34 years old mom: How are you doing? 6 years old kid: What's up?

26. Outline • Introduction • The project, the software, the philosophy • Software architecture • Installation and getting started • About extending ns-2 • tcl/otcl/ns-2 fundamentals • Programming tcl/otcl • Running a ns-2 simulation • Simulation design • Example scripts

27. NS input & output

28. Running a Simulation • Design your simulation • Build NS-2 scripts • Run simulation program • Analyze trace files • Visualize your simulation (Animation)

29. Design your simulation • Goal and expected results • Network topology • Node • Link • Specify Agents • Protocol • Traffic • Simulation Scenario

30. A simulation example

31. n0 n1 A TCL script example set ns [new Simulator] set n0 [$ns node] set n1 [$ns node] Network Topology Traffic Generation set ftp [new Application/FTP] $ftp attach-agent $tcp $ns at 0.2 "$ftp start" $ns at 1.2 ”exit" $ns run $ns duplex-link $n0 $n1 1.5Mb 10ms DropTail Transport Protocol set tcp [$ns create-connection TCP $n0 TCPSink $n1 0]

32. Run simulation program • Usage: ns file.tcl • If the C++ source codes are modified, re-compilation is required • What ns-2 does: • Read the tcl file • Run the simulation program • Create trace files • NAM (network animator) input files • Statistics (you may need to write post processing scripts)

33. Analyze trace file • Use some scripts like awk or Perl, to filter the trace file • Use Excel, xplot or xgraph to plot the results

34. Raw trace file + 0.001 2 0 tcp 1000 ------- 0 2.0 1.0 0 0 - 0.001 2 0 tcp 1000 ------- 0 2.0 1.0 0 0 r 0.0028 2 0 tcp 1000 ------- 0 2.0 1.0 0 0 + 0.0028 0 1 tcp 1000 ------- 0 2.0 1.0 0 0 - 0.0028 0 1 tcp 1000 ------- 0 2.0 1.0 0 0 r 0.009884 0 1 tcp 1000 ------- 0 2.0 1.0 0 0 + 0.009884 1 0 ack 40 ------- 0 1.0 2.0 0 1 - 0.009884 1 2 ack 40 ------- 0 1.0 2.0 0 1 r 0.013128 1 0 ack 40 ------- 0 1.0 2.0 0 1 + 0.013128 0 2 ack 40 ------- 0 1.0 2.0 0 1 - 0.013128 0 2 ack 40 ------- 0 1.0 2.0 0 1 r 0.01416 0 2 ack 40 ------- 0 1.0 2.0 0 1 + 0.01416 2 0 tcp 1000 ------- 0 2.0 1.0 1 2 - 0.01416 2 0 tcp 1000 ------- 0 2.0 1.0 1 2

35. Open trace.out in Excel

36. Plot results in Excel

37. Outline • Introduction • The project, the software, the philosophy • Software architecture • Installation and getting started • About extending ns-2 • tcl/otcl/ns-2 fundamentals • Programming tcl/otcl • Running a ns-2 simulation • Simulation design • Example scripts

38. A Simulation Example

39. TCL Script Step 1 # has denotes a one line commentns holds the name of the new simulation #Create a simulator object set ns [new Simulator] #Open the NAM trace file set nf [open out.nam w] $ns namtrace-all $nf #Open the general trace file Set f [open out.tr w] $ns trace-all $f

40. TCL Script Step 2 #Create four nodes set n0 [$ns node] set n1 [$ns node] set n2 [$ns node] set n3 [$ns node] #Create links between the nodes $ns duplex-link $n0 $n2 2Mb 10ms DropTail $ns duplex-link $n1 $n2 2Mb 10ms DropTail $ns duplex-link $n2 $n3 1.7Mb 20ms DropTail

41. TCL Script Step 3 #Set Queue Size of link (n2-n3) to 10 $ns queue-limit $n2 $n3 10 #Setup a TCP connection set tcp [new Agent/TCP] $ns attach-agent $n0 $tcp set sink [new Agent/TCPSink] $ns attach-agent $n3 $sink $ns connect $tcp $sink #Setup a FTP over TCP connection set ftp [new Application/FTP] $ftp attach-agent $tcp

42. TCL Script Step 4 #Setup a UDP connection set udp [new Agent/UDP] $ns attach-agent $n1 $udp set null [new Agent/Null] $ns attach-agent $n3 $null $ns connect $udp $null #Setup a CBR over UDP connection set cbr [new Application/Traffic/CBR] $cbr attach-agent $udp $cbr set packet_size_ 1000 $cbr set rate_ 1mb

43. TCL Script Step 5 #Schedule events for the CBR and FTP agents $ns at 0.1 "$cbr start" $ns at 1.0 "$ftp start" $ns at 4.0 "$ftp stop" $ns at 4.5 "$cbr stop" #Call the finish procedure after 5 seconds of simulation time $ns at 5.0 "finish"

44. TCL Script Step 6 #Define a 'finish' procedure proc finish {} { global ns nf $ns flush-trace #Close the NAM trace file close $nf #Execute NAM on the trace file exec nam out.nam & exit 0 } #Run the simulation $ns run