User Manual For NS with TCP/IP Over ATM

Simulation Capability

This manual provides a tutorial introduction about how to use NS for simulating networks. It focuses on the general usage and the input commands available to the user. If you wish to modify NS, you should then also read the NS Programmers Manual. Our description of the usage of NS commands is limited largely because we did not have any communication with the actual authors of this program. For those who have no prior exprience with Tcl, you should read the manpages of Tcl and tclsh. Without this the true power of the Tcl Script may not be realised.

History Of NS (Network Simulator)

Work on the LBL Network Simulator began in May 1990 with modifications to S. Keshav's ( REAL network simulator, which he developed for his Ph.D. work at U.C. Berkeley. In Summer 1991, the simulation description language was revamped, and later, the NEST threads model was replaced with an event driven framework and an efficient scheduler. Among other contributions, Sugih Jamin ( contributed the calendar-queue based scheduling code to this version of the program, which was known as tcpsim. In December 1994, McCanne ported tcpsim to C++ and replaced the yacc-based simulation description language with a Tcl interface, and added preliminary multicast support. Also at this time, the name changed from tcpsim to the more generic ns. Throughout, Floyd has made modifications to the TCP code and added additional source models for her investigations into RED gateways, resource management, class-based queuing, explicit congestion notification, and traffic phase effects. Many of the papers discussing these issues are available through URL .

In this document we will describe the various features available in the simulator and how they can be used to model real networks. We also provide some sample input files for ease of understanding and use of the simulator.

Brief Description

NS is an event-driven network simulator embedded into the Tool Command Language, Tcl. An extensible simulation enginge is implemented in C++ and is configured and controlled via a Tcl interface. The simulator is invoked via the ns interpreter, which is an extension of the vanilla tclsh(1) command shell. All interaction with the interpreter is via a single, new Tcl procedure, ''ns''. (The ns procedure is present in the "ns_default.tcl" file)

A simulation is defined by a Tcl program. Using the ns command, a network topology is defined, traffic sources and sinks are configured, statistics are collected, and the simulation is invoked. By building upon a fully functional language, arbitrary actions can be programmed into the configuration. The simulation is run via the ns run command, and continues until there are no more events to be processed. For example, a traffic source might be started at time 0 and stopped at time 10 (using the ns at command). Once all traffic sources are stopped, all pending packets will be eventually delivered and no more events will remain. At this time, the original invocation of the ns run command returns and the Tcl script can exit or invoke another simulation run after possible reconfiguration. Alternatively, the simulation can be prematurely halted by invoking the ns stop command or by exiting the script with Tcl's standard exit command.

File Organization

The simulator files are arranged in three directories. The docs directory contains the documentation including the online html manual. The src directory contains the source code. The bin directory contains the installed binaries.

Basics: Nodes, Links and Agents

The network topology is specified by using three primitive building blocks: nodes, links, and agents. Nodes are created with the ns node command and arranged in a network topology with the ns link command. Nodes are passive objects which act as containers for agents, the objects that actively drive the simulation. Each node has an automatically-generated, unique address. Traffic sources and sinks and dynamic routing modules are examples of agents. The ns agent command is used to create an agent at a certain node. Thus nodes can be thought of the physical entity representing the computer while the agent can be thought of as the computer process generating and handling the actual packets. The ns agent, ns node, and ns link commands all create new objects and return a procedure that is used to access the object. Once an object is created, it can be manipulated in an object-oriented fashion using the new procedure. More details wiill follow in the User-Commands section.

User Input

The user can enter the input in two forms. One way is to run "ns" and enter the commands line by line or the user can specify a file name on the command line which contains the input data. Any arguments that need to be supplied with the file can be put on the command line. For example, suppose you have defined several procedures in a file. Now all you have to do is to put the procedure name on the command line and at the end of the input file (which only contains procedure definations) you can simply put the line "$argv". In this way after defining the procedures whatever procedure name you pass as the command line option will get called and executed. The sample input file, test-suite.tcl, has many procedures with names starting with "test_". So if you run ns with "ns test-suite.tcl tahoe1", the procedure that will actually get called will be test_tahoe1 because of the following lines at the end of the file.

if { $argc != 1 } {
        puts stderr {usage: ns test-suite.tcl [ tahoe1 tahoe2 ... reno reno2 ... ]}
        exit 1
if { "[info procs test_$argv]" != "test_$argv" } {
        puts stderr "test-suite.tcl: no such test: $argv"

NS Defaults

The default values for most variables are specified in the ns_default.tcl file. If you have to change any of the defaults you can change them in this file. However if you do this you will have to recompile the program. A collection of such configuration parameters that can be modified as above either before a simulation begins, or dynamically, while the simulation is in progress. If a parameter is not explicitly set, it defaults to a value stored in a global Tcl array. For example, ns_tcp(window-size) contains the default window size for tcp objects. A set of defaults are built into the ns interpreter and can be explicitly overridden by simple assignmet. For example, we can say

to make all future tcp agent creations default to a window size of 30. These defaults include the TCP traffic defaults like window parameters and packet size, parameters for the RED Algorithm , Class-Based Queueing and other algorithms including link defaults. For more details see the ns_default.tcl file.

Besides the default parameter values, the ns_default.tcl file also contains some functions. These functions have been provided so as to make it easier for the user to specify the input. These include the following:

ns_duplex { n1 n2 bw delay type }

ns_create_connection { srcType srcNode sinkType sinkNode class }

Some functions exist for creating certain special connections. These are just slight variations of the ns_create_connection command and include :

ns_create_reno { tcpSrc tcpDst window start class} for creating a reno source connection. It attaches an ftp source with starting time start.

ns_create_cbr { srcNode sinkNode pktSize interval class } for creating a cbr connection at node srcNode and connect it to a loss-monitor sink agent at node sinkNode. Also connect the sink agent to the source agent. The traffic class of the source agent is agent. The cbr source sends packet of size pktSize bytes at intervals of interval seconds. This can be used as follows:

ns_create_class { parent borrow allot maxIdle minIdle priority depth extraDelay} for creating a class-based queueing class. Sets the allotment, maxidle, minidle, priority, depth, and extradelay parameters to the indicated values. There are some other similar functions also available which the user can use. These include ns_create_class1, ns_class_params, ns_class_maxIdle, ns_class_minIdle.

NS Commands

The Procedure ns contains the following commands:

ns connect $tcpnode $atmnetwork $atmnode

ns add-node $atmnetwork $atmnode

ns node

ns link

ns agent $type $node

ns trace

ns at $time "proc"

ns now

ns random

ns random $seed

ns run

Configuration parameters

NS has some simulation parameters that are usually fixed during the entire simulation (like a link bandwidth), but these can be changed dynamically if desired. In this section we will discuss how to do access these configuration parameters and what configuration parameters are available. Each object also has a set of State variables that are specific to a given object and that object's implementation.

Object Methods

In NS all objects including nodes, links and agents are derived from the TclObject class. Thus all such objects have some common methods available which can be executed on an object by invoking that object as a Tcl procedure call. The object class is specified implicitly by the object variable name in the description. For example, $tcp implies the tcp object class and all of its child classes, while $generic implies any object class.

$generic set var value

Link Methods

Link Configuration Parameters

Agent Methods

Agent Configuration Parameters

Node Methods

Drop-tail Object

Red Object

Red Configuration Parameters

CBQ Objects

CBQ Configuration Parameters

WRR-CBQ Objects

Class Object

Class Configuration Parameters


TCP objects are a subclass of agent objects that implement the BSD Tahoe TCP transport protocol. They inherit all of the generic agent functionality.

TCP Configuration Parameters

State Variables


TCP Fack objects are a subclass of TCP objects that implement Forward Acknowledgment congestion control. They inherit all of the TCP object functionality.

FACK TCP Configuration Parameters


Source objects create data for a transport object to send (e.g., TCP).

Source Configuration Parameters

TCP-SINK Objects

Tcp-sink objects are a subclass of agent objects that implement a receiver for TCP packets. The simulator only implements "one-way" TCP connections, where the TCP source sends data packets and the TCP sink sends ACK packets. Tcp-sink objects inherit all of the generic agent functionality. There are no methods or state variables specific to the tcp-sink object.

Sink Configuration Parameters


Tcp-sink-da objects are a subclass of tcp-sink that implement a delayed-ACK receiver for TCP packets. They inherit all of the tcp-sink object functionality. There are no methods or state variables specific to the tcp-sink-da object.

Del Sink Configuration Parameters


Cbr objects generate packets at a constant bit rate. They inherit all of the generic agent functionality. There are no state variables specific to the cbr class.

CBR Configuration Parameters

TRACE Objects

Trace objects are used to generate event level capture logs, either directly to an output file, indirectly through a Tcl procedure, or both. There are no state variables or configuration parameters specific to the trace class.

A Step-by-step walk through Example

Example 1

Example 2