Introduction to ns-2

Michele Weigle
Department of Computer Science

CS 555 | ODU Setup Scripts References Unix Tools Examples Source Code Validation

Setup at ODU

I have installed the latest release of ns-2 (2.30) in my home directory in the CS dept Unix space:
/home/mweigle/555/ns-allinone-2.30/ns-2.30/ns

If you cannot run this executable, please let me know.

Creating Simulation Scripts

Scripts to drive your simulations are written in OTcl.

Building Blocks

node - represents a host
Agent - TCP, Full-TCP (attached to a node)
Application - FTP, Telnet (attached to an Agent)
link - links two nodes together, properties: bandwidth, propagation delay, queuing mechanism
queue - DropTail, RED (associated with every link by default)

Simulation Script Outline

create the simulator object
create the nodes
link the nodes together
setup the application or traffic generator
schedule the start of the simulation
schedule the end of the simulation
run

Notes

Refer to the NS Manual for more details, but be careful, since it is not complete and it does not keep up with the changes in the code. The ultimate reference is always the source code, so it is critical to understand the general architecture of the simulator.
Learning by example is the most common technique. NS includes tons of them in ~ns/tcl/ex and ~ns/tcl/test (Hint: use grep -R to find examples of whatever you're interested in.)
Search the ns-users mailing list.
Be patient: NS can be frustrating (and you may find bugs). It is a large project with many contributors, and it has plenty of arbitrary/temporary implementation decisions. However, it is a really powerful research tool, the general design is very good, and you can learn a lot about networking using it.
(Thanks to Felix Hernandez-Campos (UNC-CH) for these notes.)

References and Tutorials

ns-2 - main ns-2 webpage
ns-2 CVS repository - glance at recent code changes
directory structure - (from WPI tutorial)
Marc Greis's tutorial
WPI's tutorial
OTcl tutorial (from WPI)
INRIA's NS Course for Beginners

Helpful Unix Tools

(use man for more information on these tools)

compression: gzip, gunzip, gzcat
parsing output files: awk Example: awk '{print $2, $4}' file - prints the 2nd and 4th columns of the file

Examples

one-flow.tcl - simple TCL script that sets up a dumbbell network and a single TCP flow
TCP-q01.trq - sample trace-queue file produced by one-flow.tcl (trace-queue monitors every packet on the link)
- + enqueue
- - dequeue
- d drop
- r received at endpoint
tracevar.out - sample tracevar file produced by one-flow.tcl
cwnd.gp - sample gnuplot file to plot congestion window of flow in one-flow.tcl

fulltcp.tcl - simple TCL script that sets up a dumbbell network and a single FullTCP flow

full-TCP-q01.trq - sample trace-queue file produced by fulltcp.tcl TCP Flags (from tcp-full.h)

#define TH_FIN  0x01        /* FIN: closing a connection */
#define TH_SYN  0x02        /* SYN: starting a connection */
#define TH_PUSH 0x08        /* PUSH: used here to "deliver" data */
#define TH_ACK  0x10        /* ACK: ack number is valid */
#define TH_ECE  0x40        /* ECE: CE echo flag */
#define TH_CWR  0x80        /* CWR: congestion window reduced */

full-tracevar.out - sample tracevar file produced by fulltcp.tcl

full-cwnd.gp - sample gnuplot file to plot congestion window of flow in fulltcp.tcl

Source Code Basics

In order to be effective at writing good simulation experiments with ns-2, you need to be familar with how ns-2 is written. The source code is a mix of C++ and OTcl (Object-oriented TCL - "oh tickle").

At the beginning, you may not need to modify any source code, but feel free to download the ns-2 source yourself to take a look at it. Note that ns-2 comes with lots of other packages in the form of ns-allinone. You can download the ns-2.30 source itself from the ns-2.30 source itself from the ns-2 project at Sourceforge.

Important TCP Source Files and Directories

Validation Scripts

Validation scripts are located in tcl/test/. There are a couple types of filenames in this directory:

test-output-testname - directory that holds the results for a particular validation suite
test-all-testname - script that runs all of the tests for a particular validation suite
test-suite-testname.tcl - TCL file that contains the code for all of the tests in a particular validation suite

tcl/test/FullTCP.notes - notes about the current state of the Full-TCP tests

I've put a couple of helpful shell scripts in /home/mweigle/555/ns/ for looking at what tests are needed. (Both of these are modifications of tools written by Sally Floyd.)

compare-suites - given the names of two test suites (minus "test-suite" and ".tcl"), indicate which are in one suite and not in the other
list-tests - given the name of a test suite (again minus "test-suite" and ".tcl"), print all of the tests in that suite

CS 555 Projects

Michele C. Weigle