NS by Example
Jae Chung
and
Mark Claypool
Purpose
NS (version 2) is an object-oriented, discrete event driven network simulator
developed at UC Berkely written in C++ and OTcl, which is very useful for
simulatry local and wide area networks. Although NS is fairly easy to use
once you get to know the simulator, it is quite difficult for a first time user,
because there are few user-friendly manuals. Even though there is a lot of
documentation written by the developers which has in depth explanation of
the simulator, it is written with the depth of a skilled NS user. The purpose of
this project is to give a new user some basic idea of how the simultor works,
how to setup simulation networks, where to look for further information
about network components in simulator codes, how to create new network
components, etc., mainly by giving simple examples and brief explanations
based on our experiences. Although all the usage of the simulator or possible
network simulation setups may not be covered in this project, the project
should help a new user to get started quickly.
Contents
1. Overview 2
2. Basics
2.1 OTcl: The User Language 5
2.2 Simple Simulation Example 8
2.3 Event Scheduler 14
2.4 Network Components 16
2.5 Packet 21
3. Post Simulation
3.1 Trace Analysis Example 22
3.2 RED Queue Monitor Example 25
4. Extending NS
4.1 Where to Find What? 28
4.2 OTcl Linkage 30
4.3 Add New Application and Agent 35
4.4 Add New Queue 42
5. More Examples
5.1 LAN 45
5.2 Multicasting 45
5.3 Web Server 46
6. Hot Links 47
1. Overview
NS is an event driven network simulator developed at UC Berkeley that simulates variety of IP
networks. It implements network protocols such as TCP and UPD, traffic source behavior such as
FTP, Telnet, Web, CBR and VBR, router queue management mechanism such as Drop Tail, RED
and CBQ, routing algorithms such as Dijkstra, and more. NS also implements multicasting and some
of the MAC layer protocols for LAN simulations. The NS project is now a part of the VINT project
that develops tools for simulation results display, analysis and converters that convert network
topologies generated by well-known generators to NS formats. Currently, NS (version 2) written in
C++ and OTcl (Tcl script language with Object-oriented extensions developed at MIT) is available.
This document talks briefly about the basic structure of NS, and explains in detail how to use NS
mostly by giving examples. Most of the figures that are used in describing the NS basic structure and
network components are from the 5th VINT/NS Simulator Tutorial/Workshop slides and the NS
Notes and Documentation, modified little bit as needed. For more information about NS and the
related tools, visit the VINT project home page.
Figure 1. Simplified User's View of NS
As shown in Figure 1, in a simplified user's view, NS is Object-oriented Tcl (OTcl) script interpreter
that has a simulation event scheduler and network component object libraries, and network setup
(plumbing) module libraries (actually, plumbing modules are implemented as member functions of
the base simulator object). In other
s, to use NS, you program in OTcl script language. To setup
and run a simulation network, a user should write an OTcl script that initiates an event scheduler,
sets up the network topology using the network objects and the plumbing functions in the library,
and tells traffic sources when to start and stop transmitting packets through the event scheduler. The
term "plumbing" is used for a network setup, because setting up a network is plumbing possible data
paths among network objects by setting the "neighbor" pointer of an object to the address of an
appropriate object. When a user wants to make a new network object, he or she can easily make an
object either by writing a new object or by making a compound object from the object library, and
plumb the data path through the object. This may sound like complicated job, but the plumbing OTcl
modules actually make the job very easy. The power of NS comes from this plumbing.
Another major component of NS beside network objects is the event scheduler. An event in NS is a
packet ID that is unique for a packet with scheduled time and the pointer to an object that handles
the event. In NS, an event scheduler keeps track of simulation time and fires all the events in the
event queue scheduled for the current time by invoking appropriate network components, which
usually are the ones who issued the events, and let them do the appropriate action associated with
packet pointed by the event. Network components communicate with one another passing packets,
however this does not consume actual simulation time. All the network components that need to
spend some simulation time handling a packet (i.e. need a delay) use the event scheduler by issuing
an event for the packet and waiting for the event to be fired to itself before doing further action
handling the packet. For example, a network switch component that simulates a switch with 20
microseconds of switching delay issues an event for a packet to be switched to the scheduler as an
event 20 microsecond later. The scheduler after 20 microsecond dequeues the event and fires it to
the switch component, which then passes the packet to an appropriate output link component.
Another use of an event scheduler is timer. For example, TCP needs a timer to keep track of a packet
transmission time out for retransmission (transmission of a packet with the same TCP packet number
but different NS packet ID). Timers use event schedulers in a similar manner that delay does. The
only difference is that timer measures a time value associated with a packet and does an appropriate
action related to that packet after a certain time goes by, and does not simulate a delay.
NS is written not only in OTcl but in C++ also. For efficiency reason, NS separates the data path
implementation from control path implementations. In order to reduce packet and event processing
time (not simulation time), the event scheduler and the basic network component objects in the data
path are written and compiled using C++. These compiled objects are made available to the OTcl
interpreter through an OTcl linkage that creates a matching OTcl object for each of the C++ objects
and makes the control functions and the configurable variables specified by the C++ object act as
member functions and member variables of the corresponding OTcl object. In this way, the controls
of the C++ objects are given to OTcl. It is also possible to add member functions and variables to a
C++ linked OTcl object. The objects in C++ that do not need to be controlled in a simulation or
internally used by another object do not need to be linked to OTcl. Likewise, an object (not in the
data path) can be entirely implemented in OTcl. Figure 2 shows an object hierarchy example in C++
and OTcl. One thing to note in the figure is that for C++ objects that have an OTcl linkage forming a
hierarchy, there is a matching OTcl object hierarchy very similar to that of C++.
Figure 2. C++ and OTcl: The Duality
Figure 3. Architectural View of NS
Figure 3 shows the general architecture of NS. In this figure a general user (not an NS developer)
can be thought of standing at the left bottom corner, designing and running simulations in Tcl using
the simulator objects in the OTcl library. The event schedulers and most of the network components
are implemented in C++ and available to OTcl through an OTcl linkage that is implemented using
tclcl. The whole thing together makes NS, which is an OO extended Tcl interpreter with network
simulator libraries.
This section briefly examined the general structure and architecture of NS. At this point, one might
be wondering about how to obtain NS simulation results. As shown in Figure 1, when a simulation is
finished, NS produces one or more text-based output files that contain detailed simulation data, if
specified to do so in the input Tcl (or more specifically, OTcl) script. The data can be used for
simulation analysis (two simulation result analysis examples are presented in later sections) or as an
input to a graphical simulation display tool called Network Animator (NAM) that is developed as a
part of VINT project. NAM has a nice graphical user interface similar to that of a CD player (play,
fast forward, rewind, pause and so on), and also has a display speed controller. Furthermore, it can
graphically present information such as throughput and number of packet drops at each link,
although the graphical information cannot be used for accurate simulation analysis.
2. Basics
2.1 OTcl: The User Language
As mentioned in the overview section, NS is basically an OTcl interpreter with network simulation
object libraries. It is very useful to know how to program in OTcl to use NS. This section shows an
example Tcl and OTcl script, from which one can get the basic idea of programming in OTcl. These
examples are from the 5th VINT/NS Simulation Tutorial/Workshop. This section and the sections
after assumes that the reader installed NS, and is familiar with C and C++.
Example 1 is a general Tcl script that shows how to create a procedure and call it, how to assign
values to variables, and how to make a loop. Knowing that OTcl is Object-oriented extension of Tcl,
it is obvious that all Tcl commands work on OTcl - the relationship between Tcl and Otcl is just
same as C and C++. To run this script you should download ex-tcl.tcl, and type "ns ex-tcl.tcl" at your
shell prompt - the command "ns" starts the NS (an OTcl interpreter). You will also get the same
results if you type "tcl ex-tcl.tcl", if tcl8.0 is installed in your machine.
Example 1. A Sample Tcl Script
In Tcl, the keyword proc is used to define a procedure, followed by an procedure name and
arguments in curly brackets. The keyword set is used to assign a value to a variable. [expr ...] is to
make the interpreter calculate the value of expression within the bracket after the keyword. One
thing to note is that to get the value assinged to a variable, $ is used with the variable name. The
keyword puts prints out the following string within double quotation marks. The following shows
the result of Example 1.
The next example is an object-oriented programming example in OTcl. This example is very simple,
but shows the way which an object is created and used in OTcl. As an ordinary NS user, the chances
that you will write your own object might be rare. However, since all of the NS objects that you will
use in a NS simulation programming, whether or not they are written in C++ and made available to
OTcl via the linkage or written only in OTcl, are essentially OTcl objects, understanding OTcl object
is helpful.
Example 2. A Sample OTcl Script
Example 2 is an OTcl script that defines two object classes, "mom" and "kid", where "kid" is the
child class of "mom", and a member function called "greet" for each class. After the class
definitions, each object instance is declared, the "age" variable of each instance is set to 45 (for
mom) and 15 (for kid), and the "greet" member function of each object instance is called. The
keyword Class is to create an object class and instproc is to define a member function to an object
class. Class inheritance is specified using the keyword -superclass. In defining member functions,
$self acts same as the "this" pointer in C++, and instvar checks if the following variable name is
already declared in its class or in its superclass. If the variable name given is already declared, the
variable is referenced, if not a new one is declared. Finally, to create an object instance, the keyword
new is used as shown in the example. Downloading ex-otcl.tcl and executing "ns ex-otcl.tcl" will
give you the following result:
2.2 Simple Simulation Example
This section shows a simple NS simulation script and explains what each line does. Example 3 is an
OTcl script that creates the simple network configuration and runs the simulation scenario in Figure
4. To run this simulation, download "ns-simple.tcl" and type "ns ns-simple.tcl" at your shell prompt.
Figure 4. A Simple Network Topology and Simulation Scenario
This network consists of 4 nodes (n0, n1, n2, n3) as shown in above figure. The duplex links
between n0 and n2, and n1 and n2 have 2 Mbps of bandwidth and 10 ms of delay. The duplex link
between n2 and n3 has 1.7 Mbps of bandwidth and 20 ms of delay. Each node uses a DropTail
queue, of which the maximum size is 10. A "tcp" agent is attached to n0, and a connection is
established to a tcp "sink" agent attached to n3. As default, the maximum size of a packet that a "tcp"
agent can generate is 1KByte. A tcp "sink" agent generates and sends ACK packets to the sender
(tcp agent) and frees the received packets. A "udp" agent that is attached to n1 is connected to a
"null" agent attached to n3. A "null" agent just frees the packets received. A "ftp" and a "cbr" traffic
generator are attached to "tcp" and "udp" agents respectively, and the "cbr" is configured to generate
1 KByte packets at the rate of 1 Mbps. The "cbr" is set to start at 0.1 sec and stop at 4.5 sec, and
"ftp" is set to start at 1.0 sec and stop at 4.0 sec.
Example 3. A Simple NS Simulation Script
The following is the explanation of the script above. In general, an NS script starts with making a
Simulator object instance.
• set ns [new Simulator]: generates an NS simulator object instance, and assigns it to variable
ns (italics is used for variables and values in this section). What this line does is the
following:
• Initialize the packet format (ignore this for now)
• Create a scheduler (default is calendar scheduler)
• Select the default address format (ignore this for now)
The "Simulator" object has member functions that do the following:
• Create compound objects such as nodes and links (described later)
• Connect network component objects created (ex. attach-agent)
• Set network component parameters (mostly for compound objects)
• Create connections between agents (ex. make connection between a "tcp" and "sink")
• Specify NAM display options
• Etc.
Most of member functions are for simulation setup (referred to as plumbing functions in the
Overview section) and scheduling, however some of them are for the NAM display. The
"Simulator" object member function implementations are located in the "ns-2/tcl/lib/ns-
lib.tcl" file.
• $ns color fid color: is to set color of the packets for a flow specified by the flow id (fid). This
member function of "Simulator" object is for the NAM display, and has no effect on the
actual simulation.
• $ns namtrace-all file-descriptor: This member function tells the simulator to record
simulation traces in NAM input format. It also gives the file name that the trace will be
written to later by the command $ns flush-trace. Similarly, the member function trace-all is
for recording the simulation trace in a general format.
• proc finish {}: is called after this simulation is over by the command $ns at 5.0 "finish". In
this function, post-simulation processes are specified.
• set n0 [$ns node]: The member function node creates a node. A node in NS is compound
object made of address and port classifiers (described in a later section). Users can create a
node by separately creating an address and a port classifier objects and connecting them
together. However, this member function of Simulator object makes the job easier. To see
how a node is created, look at the files: "ns-2/tcl/libs/ns-lib.tcl" and "ns-2/tcl/libs/ns-
node.tcl".
• $ns duplex-link node1 node2 bandwidth delay queue-type: creates two simplex links of
specified bandwidth and delay, and connects the two specified nodes. In NS, the output
queue of a node is implemented as a part of a link, therefore users should specify the queue-
type when creating links. In the above simulation script, DropTail queue is used. If the reader
wants to use a RED queue, simply replace the word DropTail with RED. The NS
implementation of a link is shown in a later section. Like a node, a link is a compound object,
and users can create its sub-objects and connect them and the nodes. Link source codes can
be found in "ns-2/tcl/libs/ns-lib.tcl" and "ns-2/tcl/libs/ns-link.tcl" files. One thing to note is
that you can insert error modules in a link component to simulate a lossy link (actually users
can make and insert any network objects). Refer to the NS documentation to find out how to
do this.
• $ns queue-limit node1 node2 number: This line sets the queue limit of the two simplex links
that connect node1 and node2 to the number specified. At this point, the authors do not know
how many of these kinds of member functions of Simulator objects are available and what
they are. Please take a look at "ns-2/tcl/libs/ns-lib.tcl" and "ns-2/tcl/libs/ns-link.tcl", or NS
documentation for more information.
• $ns duplex-link-op node1 node2 ...: The next couple of lines are used for the NAM display.
To see the effects of these lines, users can comment these lines out and try the simulation.
Now that the basic network setup is done, the next thing to do is to setup traffic agents such as TCP
and UDP, traffic sources such as FTP and CBR, and attach them to nodes and agents respectively.
• set tcp [new Agent/TCP]: This line shows how to create a TCP agent. But in general, users
can create any agent or traffic sources in this way. Agents and traffic sources are in fact basic
objects (not compound objects), mostly implemented in C++ and linked to OTcl. Therefore,
there are no specific Simulator object member functions that create these object instances. To
create agents or traffic sources, a user should know the class names these objects
(Agent/TCP, Agnet/TCPSink, Application/FTP and so on). This information can be found in
the NS documentation or partly in this documentation. But one shortcut is to look at the "ns-
2/tcl/libs/ns-default.tcl" file. This file contains the default configurable parameter value
settings for available network objects. Therefore, it works as a good indicator of what kind of
network objects are available i