Introduction to ns-2

Michele Weigle
Department of Computer Science

Getting Started Scripts References Unix Tools Examples Source Code

Getting Started

Download and install the latest version of ns-2
Check out the ns-2 wiki for getting started guides and information on the ns-2 framework.

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

References and Tutorials

References

official ns-2 webpage
ns-2 wiki
ns-2 manual - note that it is not always updated and may not be complete - the best reference is the source code (see TCL examples in ~ns/tcl/ex and ~ns/tcl/test)
ns-2 CVS repository - glance at recent code changes
ns-users mailing list
directory structure - (from WPI tutorial)

Tutorials

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

generating PS, EPS, PDF from gnuplot: print-ps, print-eps, print-pdf

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").

Important TCP Source Files and Directories

top-level directory
tcp/
tcp/tcp.h - main TCP header file
tcp/tcp.cc - main TCP source code (contains TcpAgent)
tcp/tcp-full.h - main Full-TCP header file
tcp/tcp-full.cc - main Full-TCP source code (contains FullTcpAgent)
tcl/lib/
tcl/lib/ns-default.tcl - TCL defaults
common/agent.cc - parent of TcpAgent
trace/trace.cc - sets trace file format
look for } else if (!show_tcphdr_) { in format()

Modifying Source Code

Many variables are shared between C++ and OTcl, so when adding new variables, you may also need to add them to the OTcl side. The best source for learning about ns-2 is its own source code. Use things that are already implemented as examples for adding your own code.

Adding variables - Look at how other variables are defined/used. If you want to be able to trace the new variable, look at cwnd_ and ssthresh_ in tcp.cc. You'll also need to add default values in ns-default.tcl to be able to trace.
Adding new TCL commands - look at command() in tcp.cc. Actually, most of the *.cc files have a command() method. It's how commands from TCL scripts get sent to the C++ side.

Using a RED queue and setting parameters

 Queue/RED set mean_pktsize_ 1250
 Queue/RED set setbit_ true;        // use ECN marking
 Queue/RED set gentle_ true;        // use gentle RED

 $ns duplex-link $n1 $n2 $bw $delay RED;   // setup a link with a RED queue
 $ns queue-limit $n1 $n2 1000;             // set max queue size

For other RED parameters, look for Queue/RED in ns-default.tcl.

Adding a new class - Make sure you add the TCL class and give the class a TCL name (see TcpClass in tcp.cc)
Other useful files:
- common/packet.{h,cc} - definitions for packets (includes packet header fields - struct hdr_cmn)
- tools/rng.{h,cc} - random number generator
- tools/ranvar.{h,cc} - random variables

Michele C. Weigle