Table of Contents

NAME

ns - network simulator

SYNOPSIS

ns [ file [ arg arg ... ] ]

DESCRIPTION

ns is an event-driven network simulator embedded into the Tool Command Language, Tcl(1). An extensible simulation engine 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''.

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 ns at command allows Tcl procedures to be invoked at arbitrary points in simulation time. These Tcl callbacks provide a flexible simulation mechanism --- they can be used to start or stop sources, dump statistics, instantiate link failures, reconfigure the network topology, etc.

A network topology is realized 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.

The ns agent, ns node, and ns link commands all create new objects and return a procedure that is used to access the object, in the spirit of Tk(1) widgets. Once an object is created, it can be manipulated in an object-oriented fashion using the new procedure. For example, we might create a tcp agent using this command:

   set tcpSource [ns agent tcp ...]

Then, object attributes can be set by invoking the agent in this manner:

   $tcpSource set window-size 25

Each agent has 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 assignment. For example, we can say

   set ns_tcp(window-size) 30

to make all future tcp agent creations default to a window size of 30.

Once a topology is defined, agents are attached to nodes. Agents are the objects that actually produce and consume packets. Each agent is automatically assigned a port number unique across all agents on a given node (analogous to a tcp or udp port). Links can be thought of as the physical transmission links, nodes as end hosts and routers, and agents as transport entities and/or processes that run on end hosts. Some types of agents may have sources attached to them while others may generate their own data. For example, you can attach ``ftp'' and ``telnet'' sources to ``tcp'' agents but ``constant bit-rate'' agents generate their own data.

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.

Packets are forwarded along the shortest path route from a source to a destination, where the distance metric is simply the hop count. If the network topology changes during the simulation, routes are recomputed instantaneously -- i.e., the routing protocol is not simulated. Reverse-path forwarding trees are similarly computed for multicast routing.

NS COMMANDS

There are two classes of Tcl procedures used to manipulate the simulation: the core ns commands and the object commands. All of the core commands are invoked by the ns Tcl procedure while the object commands are invoked indirectly on objects that are created with the core commands, ns node, ns link, ns agent, and ns trace. This section describes the core commands.
ns agent type node
Create an agent of type type and attach to node node. node must already have been created with a link command. type identifies the type of agent to create:

tcp - BSD Tahoe TCP
tcp-reno - BSD Reno TCP
tcp-newreno - a modified version of BSD Reno TCP
tcp-sack1 - BSD Reno TCP with selective ACKs
tcp-fack - BSD Reno TCP with forward ACKs
tcp-fackrh - Forward ACKs with Rate-Halving
tcp-sink - a standard TCP sink
tcp-sink-da - a TCP sink that generates delayed ACKs
sack1-tcp-sink - a TCP sink that generates selective ACKs
sack1-tcp-sink-da - a delayed-ack TCP sink with selective ACKs
cbr - a constant bit rate traffic source
loss-monitor - a CBR sink that reports losses

ns node
Create a new node and return the Tcl procedure name of the corresponding object.
ns link node1 node2 type
Create a new link between node1 and node2 and return the Tcl procedure name of the corresponding object. node1 and node2 must have already been created with the ns node command. A link is unidirectional -- bidirectional links are composed from two unidirectional links. The queuing discipline of the link is specified by type, which may be drop-tail, red, cbq, lossy-uniform, lossy-det, or lossy-patt. A drop-tail link is a simple FIFO queue which drops the last packet in the queue when the queue overflows. A red link is a random-early drop queue (for details see [2]). A cbq link is for class-based queueing (for details see [3]). A lossy link drops packets, either according to a fixed probability which is independently applied to each arriving packet (lossy-uniform), by pre-specifying exactly which packets will be discarded (lossy-det), or in probabilistic or periodic bursts of a specified length (lossy-patt). The bandwidth and delay attributes of the link (among others) are set using the returned object (see OBJECT COMMANDS section). A helper procedure, ns_duplex, is defined to facilitate building point-to-point links (see BUILTINS section).
ns link
Return a list of the names of all the link objects that have been created.
ns link node1 node2
Return the name of the link object that connects node1 and node2 (there may be only one such object -- multiply connected nodes are handled by a single aggregate link object (not yet implemented).
ns at time proc
Evaluate the Tcl code proc at simulation time time. This command can be used to dynamically reconfigure the simulator, dump statistics at specified intervals, start and stop sources, etc.
ns now
Return the current simulation time.
ns trace
Create a new trace object and return it. Trace objects are used to generate event level capture logs. A trace can be bound either to a file, using a file identifier created with the standard Tcl open command, or to a Tcl procedure so that arbitrary event logging can be carried out by the user script.
ns random [ seed ]
If seed is not present, return a pseudo-random integer between 0 and 2^31-1. Otherwise, seed the pseudo-random number generator with seed and return the seed used. If seed is 0, choose an initial seed heuristically (which varies on successive invocations).
ns version
Return a string identifying the version of ns currently running.
ns run [route-model [args]]
With no arguments, the command will initialize the routing, and start the simulation. If a route-model is specified, then invoke procedures to initialize that route-model (called ns_rt_<route-model>) with any specified args before starting the simulation.
ns route-object node
Create a route object, and attach it to node.
ns route-proto node protocol [protocol ...]
Associate an instance of each of the protocols specified at the particular node.

OBJECT HIERARCHY

All ns simulation objects are derived from a single, generic object class. Nested subclasses form a hierarchy where child objects implement a superset of their parent's functionality. Objects can be invoked as a Tcl procedure call, their configuration parameters can be dynamically set and queried, and their state variables can be queried (but not modified).

Configuration parameters represent simulation parameters that are usually fixed during the entire simulation (like a link bandwidth), but can be changed dynamically if desired. State variables represent values that are specific to a given object and that object's implementation.

The following diagram depicts the ns-1 object hierarchy:

generic
agent
tcp
tcp-reno
tcp-newreno
tcp-sack1
tcp-fack
tcp-fackrh
tcp-sink
tcp-sink-da
sack1-tcp-sink
sack1-tcp-sink-da
cbr
loss-monitor
rtObject
rtProto
tcp-source
ftp
telnet
bursty
link
drop-tail
red
cbq
wrr-cbq
lossy
trace
node
class
flowmgr

For example, any method that is supported by a tcp agent is also supported by a tcp-reno or a tcp-sack1 agent. Default configuration parameters are also inherited. For example, ns_tcp(window) defines the default TCP window size for both tcp and tcp-reno objects.

OBJECT METHODS

This section documents each command that may 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
Sets the member variable var of the generic object to value. This command behaves analogously to the Tcl set command, but the variables are private to each object and only the predefined configuration parameters can be set (i.e., new variables cannot be created).
$generic get var
Return the current value of the parameter var that is private to the generic object. var is either a configuration parameter or a state variable of the generic object.
$generic trace trace
Attach the trace identified by trace to the generic object. trace must be an identifier return by the ns trace command.

LINK METHODS

$link reset
Reset all internal statistics variables associated with this link.
$link integral util|qsize|qlen
Return the integral over time of the utilization, queue size in bytes, or queue length in packets, according to the third argument. For example, the average queue delay at a give link can be computed by dividing the elapsed simulation time into

   expr "8 * [$link integral qsize] / [$link get bandwidth]"

$link stat class type
Return a per-class statistic associated with this link. class identifies the traffic class of interest (all packets are assigned an integer class identifier which is determined by the class object variable that sourced the packet). type identifies the statistic of interest and may be one of: packets, bytes, drops, mean-qlen, or mean-qsize. packets, bytes, and drops give counts of the number of occurrences of each event for the given traffic class. mean-qlen gives the average number of packets in the queue on this link as seen by class class. Similarly, mean-qsize gives the average number of bytes in the queue.
$link flow-mgr flowmgr
Attachs a flow-manager object to this link.

$link up
$link down
Toggle the state of this link up or down. Note that this command requires some form of dynamic routing in order to ensure end-to-end connectivity.

Lossy Links

Lossy links do not perform queueing, but may drop packets. The following methods are available to lossy-uniform links:
$lossylink set loss_prob prob
This sets the independent packet drop probability to prob; any packet passing through the link will be dropped with the specified probability.

The following methods are available to lossy-det links:

$lossylink filter s1.sp1 d1.dp1 n
The filter instruction causes the nth packet originating at node s1 with source port sp1 destined for node d1, destination port dp1 to be dropped. More than one filter instruction can be applied to a single lossy-det link.

The following methods are available to lossy-patt links:

$lossylink set loss_interval int
This sets the (periodic) packet loss interval to int. If int is non-zero, this command instructs the link to drop a specified number of packets (see loss_burst) for every int packet arrivals. If int is zero (or this command is not used), a loss burst will be probabilistically invoked.
$lossylink set loss_prob prob
This sets the probability of a burst loss to prob. Burst losses occur independently. This command only has an effect if loss_interval is zero or not set.
$lossylink set loss_burst blen
This command sets the length (in packets) of a burst loss to blen. Burst losses occur either periodically or probabilistically depending on the setting of loss_interval.

Configuration Parameters (ns_link)

bandwidth
The bandwidth of the link, in bits per second.
delay
The latency of the link, in seconds.
queue-limit
The maximum number of packets that can be queued at the link.
state
The current state of the link, i.e. up or down.

Default values for these parameters are stored in the ns_link Tcl array, e.g., ns_link(bandwidth), ns_link(delay), etc.

State Variables

queue-length
The current number of packets queued at this link.
queue-size
The current number of bytes in all packets queued at this link.

AGENT METHODS

$agent addr
Return the address of the node to which this agent is attached.
$agent port
Return the transport-level port of the agent. Ports are used to identify agents within a node.
$agent dst-addr
Return the address of the node this agent is connected to.
$agent dst-port
Return the port that this agent is connected to.
$agent join group
Add this agent to the multicast host group identified by the address group. This causes the group membership protocol to arrange for the appropriate multicast traffic to reach this agent.
$agent connect addr port
Connect this agent to the agent identified by the address addr and port port. This causes packets transmitted from this agent to contain the address and port indicated, so that such packets are routed to the intended agent. The two agents must be compatible (e.g., a tcp-source/tcp-sink pair as opposed a cbr/tcp-sink pair). Otherwise, the results of the simulation are unpredictable.

Configuration Parameters (ns_agent)

class
The traffic class of packets generated from this agent. Traffic classes can be used for aggregating (or separating) flows for statistical data reduction and are also used by the CBQ (class-based queuing) module. For example, in a TCP simulation, you might assign a different traffic class to each connection.

State Variables

There are no state variables specific to the generic agent class.

NODE METHODS

$node addr
Return this node's address.
$node agent port
Return the Tcl object name of the agent attached to port port on this node. Returns an empty string if the port is not in use.
$node notify-ifchanged
Some interfaces on this node have changed state. Invalidate the routes that use links that are now down, add routes to neighbors for those links that have just come up.

There are no state variables or configuration parameters specific to the node class.

DYNAMIC ROUTING METHODS

There are two types of dynamic routing objects, rtObject, and rtProto. Every node that participates in some form of dynamic routing will have one rtobject associated with it. Each node that runs an instance of a particular routing protocol will have one rtProto associated with that protocol at that node.

RtObject Methods

$rtObject init
Initialize the routing tables at this node. It will create routes for immediate neighbors, and set the rest of the routes to infinity.
$rtObject notify-ifchanged
This method is used to notify the route object at a node that the state of some of the interfaces at that node have changed state. This then causes each protocol to recompute its routes, and if they have changed, to (possibly) install new routes. If new routes have been installed, then this also causes updates to be sent to respective neighbors.
$rtObject dump-routes traceObject
Dump the forwarding table entries at this node.

RtProto Methods

Currently, only a simple distance vector routing protocol (that implements a split horizon with poisoned-reverse updates) is implemented. Its methods are

$rtProto proto protocol
Create a route protocol instance for the specified protocol.
$rtProto rtagent rtObject
Associate this particular rtProto with the specified rtobject.
$rtProto peer-init link peer
This method connects a particular protocol instance at a given node to a peer protocol instance running at a neighboring node. link is the link connecting the given node to the neighbor node.

For additional details, please see the section on route models below.

DROP-TAIL OBJECTS

Drop-tail objects are a subclass of link objects that implement simple FIFO queue. There are no methods, configuration parameter, or state variables that are specific to drop-tail objects.

RED OBJECTS

RED objects are a subclass of link objects that implement random early-drop queuing. There are no object methods that are specific to RED objects.

Configuration Parameters (ns_red)

bytes
Set to "1" to measure the queue in bytes rather than in packets.
thresh
The minimum threshold for the average queue size.
maxthresh
The maximum threshold for the average queue size.
mean_pktsize
A rough estimate of the average packet size in bytes. Used in updating the calculated average queue size after an idle period.
q_weight
The queue weight, used in the exponential-weighted moving average for calculating the average queue size.
wait
Set to true to maintain an interval between dropped packets.
linterm
As the average queue size varies between "thresh" and "maxthresh", the packet dropping probability varies between 0 and "1/linterm".
setbit
Set to true to set the congestion indication bit in packet headers rather than drop packets.
drop-tail
Set to true to use drop-tail rather than random-drop when the queue overflows.
doubleq
Set to true to give priority to small packets. The default is false.
dqthresh
The largest size in bytes of a "small" packet. This is only used if "doubleq" is set to true.

For a further explanation of these variables, see [2].

State Variables

None of the state variables of the RED implementation are accessible.

CBQ OBJECTS

CBQ objects are a subclass of link objects that implement class-based queueing.
$cbq insert $class
Insert traffic class class into the link-sharing structure associated with link object cbq.
$cbq bind $class $classID
Bind class ID classID to the traffic class class associated with link object cbq.

Configuration Parameters (ns_cbq)

algorithm
Set to "0" for Ancestor-Only link-sharing, to "1" for Top-Level link-sharing, to "2" for Formal link-sharing.
max-pktsize
Used in implementing weighted round-robin.

WRR-CBQ OBJECTS

WRR-CBQ objects are a subclass of CBQ objects that implement weighted round-robin scheduling among classes of the same priority level. In contrast, CBQ objects implement packet-by-packet round-robin scheduling among classes of the same priority level.

CLASS OBJECTS

CLASS objects implement the traffic classes associated with CBQ objects.
$class1 parent $class2
Assign traffic class class2 as the parent class of the traffic class class1. The root class should have parent class "none".
$class1 borrow $class2
Assign traffic class class2 as the class to borrow bandwidth from for the traffic class class1. A class that is not allowed to borrow bandwidth should have borrow class "none".

Configuration Parameters (ns_class)

priority
The class's priority level for packet scheduling. Priority-0 classes have the highest priority.
depth
Used for the Top-Level link-sharing algorithm. Leaf classes have "depth=0".
allotment
The link-sharing bandwidth allocated to the class, given as a fraction of the link bandwidth.
maxidle
Used in calculating the bandwidth used by the class.
minidle
Used in calculating the bandwidth used by the class.
extradelay
Used in delaying an overlimit class.

For a further explanation of the CBQ variables, see [5] and [6].

TCP OBJECTS

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 source ftp|telnet|bursty
Install a data source of the type indicated in the tcp agent. Returns the name of the Tcl object that corresponds to the new source.

Configuration Parameters (ns_tcp)

window
The upper bound on the advertised window for the TCP connection.
window-init
The initial size of the congestion window on slow-start.
window-option
The algorithm to use for managing the congestion window.
window-thresh
Gain constant to exponential averaging filter used to compute awnd (see below). For investigations of different window-increase algorithms.
overhead
The range of a uniform random variable used to delay each output packet. The idea is to insert random delays at the source in order to avoid phase effects, when desired [4]. This has only been implemented for the Tahoe ("tcp") version of tcp, not for tcp-reno. This is not intended to be a realistic model of CPU processing overhead.
ecn
Set to true to use explicit congestion notification in addition to packet drops to signal congestion.
packet-size
The size in bytes to use for all packets from this source.
tcp-tick
The TCP clock granularity for measuring roundtrip times.
bug-fix
Set to true to remove a bug when multiple fast retransmits are allowed for packets dropped in a single window of data.
maxburst
Set to zero to ignore. Otherwise, the maximum number of packets that the source can send in response to a single incoming ACK.
MWS
The Maximum Window Size in packets for a TCP connection. MWS determines the size of an array in tcp-sink.cc. The default for MWS is 1024 packets. For Tahoe TCP, the "window" parameter, representing the receiver's advertised window, should be less than MWS-1. For Reno TCP, the "window" parameter should be less than (MWS-1)/2. (MWS is currently a defined constant, but we plan to change MWS to a configuration parameter in a future release.)

State Variables

dupacks
Number of duplicate acks seen since any new data was acknowledged.
seqno
Current position in the sequence space (can move backwards).
ack
Highest acknowledgment seen from receiver.
cwnd
Current value of the congestion window.
awnd
Current value of a low-pass filtered version of the congestion window. For investigations of different window-increase algorithms.
ssthresh
Current value of the slow-start threshold.
rtt
Round-trip time estimate.
srtt
Smoothed round-trip time estimate.
rttvar
Round-trip time mean deviation estimate.
backoff
Round-trip time exponential backoff constant.

TCP FACK OBJECTS

TCP Fack objects are a subclass of TCP objects that implement Forward Acknowledgment congestion control. They inherit all of the TCP object functionality. For further information on FACK, see [8].

Configuration Parameters (ns_facktcp)

ss-div4
Overdamping algorithm. Divides ssthresh by 4 (instead of 2) if congestion is detected within 1/2 RTT of slow-start. (1=Enable, 0=Disable)
rampdown
Rampdown data smoothing algorithm. Slowly reduces congestion window rather than instantly halving it. (1=Enable, 0=Disable)

TCP FACKRH OBJECTS

TCP Fack with Rate-Halving objects are a subclass of TCP objects that implement Forward Acknowledgment with Rate-Halving congestion control. They inherit all of the TCP object functionality. For further information on FACK with Rate-Halving, see [9].

SOURCE OBJECTS

Source objects create data for a transport object to send (e.g., TCP).
$source start
Causes the source to start producing an unbounded amount of data.
$source produce n
Causes the source to produce exactly n packets instantaneously.

Configuration Parameters (ns_source)

maxpkts
The maximum number of packets generated by the source.

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.

Configuration Parameters (ns_sink)

packet-size
The size in bytes to use for all acknowledgment packets.

TCP-SINK-DA OBJECTS

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.

Configuration Parameters (ns_delsink)

interval
The amount of time to delay before generating an acknowledgment for a single packet. If another packet arrives before this time expires, generate an acknowledgment immediately.

CONSTANT BIT-RATE OBJECTS

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 start
Causes the source to start generating packets.
$cbr stop
Causes the source to stop generating packets.

Configuration Parameters (ns_cbr)

interval
The amount of time to delay between packet transmission times.
packet-size
The size in bytes to use for all packets from this source.

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.
$trace attach fileID
Attach a file to a trace object so that events are written to the indicated file. fileID must be a file handle returned by the Tcl open command and it must have been open for writing.
$trace detach
Detach any attached file indicated from the trace object. Events will no longer be logged to this file.
$trace callback proc
Arrange for the Tcl procedure proc to be called for every event logged by the trace object. Both the Tcl callback and an attached file may be simultaneously active. proc is called with a single argument, which consists of a Tcl list representing the captured event. Be warned that invoking the Tcl interpreter on each event like this will substantially slow down the simulation. If proc is an empty string, cancel the callback.

Trace records for link objects have the following form:

<code> <time> <hsrc> <hdst> <packet>

where

<code> := [hd+-] h=hop d=drop +=enque -=deque
<time> := simulation time in seconds
<hsrc> := first node address of hop/queuing link
<hdst> := second node address of hop/queuing link
<packet> := <type> <size> <flags> <class> <src.sport> <dst.dport>
<type> := tcp|telnet|cbr|ack etc.
<size> := packet size in bytes
<flags> := [CP] C=congestion, P=priority
<class> := class ID number
<src.sport> := transport address (src=node,sport=agent)
<dst.sport> := transport address (dst=node,dport=agent)

For links that use RED gateways, there are additional trace records as follows:

<code> <time> <value>

where

<code> := [Qap] Q=queue size, a=average queue size,
   p=packet dropping probability
<time> := simulation time in seconds
<value> := value

FLOW MANAGER OBJECTS

Flow-manager (flowmgr) objects are used to maintain per-flow counts of packet arrivals and drops at links and queues. When the flow-manager object is created with the new command, it is told which of the source, destination, and class packet fields to use to distinguish a flow. We summarize some of the more important commands for the flow-manager below.
$flowmgr attach file
Attachs a report file to a flow-manager object.
$flowmgr ndropcats n
Tells the flow-manager to keep separate statistics for n categories of packet drops.
$flowmgr total-drops-pthresh n
Tells the flow-manager to only report after at least n packet drops.
$flowmgr minimum-time n
Tells the flow-manager to wait at least n seconds between reports.
$flowmgr total-drops-pcallback procedure
Tells the flow-manager the Tcl procedure to call when reporting flow information.
$flowmgr resetcounters
Causes the flow-manager to reset counters.
$flowmgr dump
Causes the flow-manager to append a report to the report file.
$flowmgr dump n
Causes the flow-manager to append a report for drops from category n to the report file.
$flowmgr flush
Causes the flow-manager to append the remaining report data to the report file.

BUILTINS

Because Tcl is a full-fledged programming language, it is easy to build high-level simulation constructs from the ns primitives. Several library routines have been built in this way, and are embedded into the ns interpreter (see the ns_default.tcl file in the distribution for the source code).

ns_connect src sink
Establish a two-way connection between the agent src and the agent sink.
ns_duplex node1 node2 bandwidth delay type
Create a duplex link (i.e., two simplex links) between nodes node1 and node2. The bandwidth and delay of each link is set to bandwidth and delay, respectively. Both links are of type type (e.g., drop-tail, red, etc.). Returns a two-element list containing the Tcl names of the two link objects.
ns_create_connection srcType srcNode sinkType sinkNode class
Create a source agent of type srcType at node srcNode and connect it to a sink agent of type sinkType at node sinkNode. Also, connect the sink agent to the source agent. The traffic class of both agents is set to class.
ns_create_cbr srcNode sinkNode pktSize interval class
Create a cbr source agent 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 set to class. The cbr source sends packets of size pktSize bytes at intervals of interval seconds.
ns_create_class class parent borrow allot maxIdle minIdle
priority depth extraDelay Set the parent class of the traffic class class to parent and set the class for borrowing bandwidth to borrow. Set the allotment, maxidle, minidle, priority, depth, and extradelay parameters to the indicated values.

ROUTE MODELS

There are two parts to the route models in ns: a routing protocol implementation and network dynamics. We have already discussed the current implementation of the routing protocol in ns. Network dynamics is the ability to make links and nodes in the topology change go up and down periodically. The following constructs are useful for network dynamics.
ns_rtq_enq time model node0 node1 model-args
ns_rtq_deq time
These constructs implement a simple event queue in Tcl. This guarantees that multiple simultaneous link failures and recoveries are handled in a simultaneous fashion.
ns_init_routing model model-args
This construct simply invokes the specific procedure, ns_rt_<model> <model-args>, to initialize the appropriate route model.
ns_init_routeobjects
This construct is used to initialize the rtObject and rtProto objects at all of the relevant nodes in the topology. It should be the first step when initializing the route model.

Currently, two types of models of network dynamics are implemented in ns.

Static Topology Models

This is the default model, in which the links of the topology do not change their state during the course of a simulation. The model simply pre-computes routes over the entire topology once prior to starting the simulation.

Exponentially Distributed Link Up/Down Times

This model requires the parameters node0 node1 [up-interval [down-interval]], and causes the link between node0 and node1 to periodically toggle state between being up and down. The link is assumed to be initially up.

The link up-time is an exponential distribution around the mean up-interval. Similarly, the link down-time is an exponential distribution around the man down-interval. Default values for up-interval and down-interval are 10s and 1s respectively. The dynamics are initiated 0.5s after the start of the simulation in order to let the routing protocol computation quiesce.

The work on route models is still experimental, and the interface is likely to change in the future.

EXAMPLE

#
# Create two nodes and connect them with a 1.5Mb link with a
# transmission delay of 10ms using FIFO drop-tail queuing
#
set n0 [ns node]
set n1 [ns node]
ns_duplex $n0 $n1 1.5Mb 10ms drop-tail

#
# Set up BSD Tahoe TCP connections in opposite directions.
#
set src1 [ns agent tcp $n0]
set snk1 [ns agent tcp-sink $n1]
set src2 [ns agent tcp $n1]
set snk2 [ns agent tcp-sink $n0]
ns_connect $src1 $snk1
ns_connect $src2 $snk2
$src1 set class 1
$src2 set class 2

#
# Create ftp sources at the each node
#
set ftp1 [$src1 source ftp]
set ftp2 [$src2 source ftp]

#
# Start up the first ftp at the time 0 and
# the second ftp staggered 1 second later
#
ns at 0.0 "$ftp1 start"
ns at 1.0 "$ftp2 start"

#
# Create a trace and arrange for all link
# events to be dumped to "out.tr"
#
set trace [ns trace]
$trace attach [open out.tr w]
foreach link [ns link] {
$link trace $trace
}

#
# Dump the queuing delay on the n0/n1 link
# to stdout every second of simulation time.
#
proc dump { link interval } {
ns at [expr [ns now] + $interval] "dump $link $interval"
set delay [expr 8 * [$link integral qsize] / [$link get bandwidth]]
puts "[ns now] delay=$delay"
}
ns at 0.0 "dump [ns link $n0 $n1] 1"

#
# run the simulation for 10 simulated seconds
#
ns at 10.0 "exit 0"
ns run
#
# Or, alternately, we can specify that the link should be dynamic,
#
#    ns run exponential $n0 $n1 10 1
#
# This invokes the ``exponential'' route model, i.e. one where the
# link between $n0 and $n1 goes up and down, and the period that the
# link is up or down is exponentially distributed around the mean
# value of 10s and 1s respectively.
#

DEBUGGING

To enable debugging when building ns from source, simply run ``./configure --enable-debug'' before running ``make''.

HISTORY

Work on the LBL Network Simulator began in May 1990 with modifications to S. Keshav's (keshav@research.att.com) 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 (jamin@usc.edu) 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 http://www-nrg.ee.lbl.gov/.

SEE ALSO

Tcl(1), tclsh(1), nam(1)
  1. S. Keshav, ``REAL: A Network Simulator''. UCB CS Tech Report 88/472, December 1988. See http://minnie.cs.adfa.oz.au/REAL/index.html for more information.
  2. Floyd, S. and Jacobson, V. Random Early Detection gateways for Congestion Avoidance. IEEE/ACM Transactions on Networking, Vol. 1, No. 4. August 1993. pp. 197-413. Available from http://www-nrg.ee.lbl.gov/floyd/red.html.
  3. Floyd, S. Simulator Tests. July 1995. URL ftp://ftp.ee.lbl.gov/papers/simtests.ps.Z.
  4. Floyd, S., and Jacobson, V. On Traffic Phase Effects in Packet-Switched Gateways. Internetworking: Research and Experience, V.3 N.3, September 1992. pp. 115-156.
  5. Floyd, S., and Jacobson, V. Link-sharing and Resource Management Models for Packet Networks. IEEE/ACM Transactions on Networking, Vol. 3 No. 4, August 1995. pp. 365-386.
  6. Floyd, S., Notes of Class-Based Queueing: Setting Parameters. URL ftp://ftp.ee.lbl.gov/papers/ params.ps.Z. September 1995.
  7. Fall, K., and Floyd, S. Comparisons of Tahoe, Reno, and Sack TCP. December 1995. URL ftp:// ftp.ee.lbl.gov/papers/sacks.ps.Z.
  8. Mathis, M., and Mahdavi, J. Forward Acknowledgement: Refining TCP Congestion Control. ACM Computer Communications Review, Vol. 26 No. 4, October 1996. pp. 281-291. Available from ftp://ftp.psc.edu/pub/networking/papers/Fack.9608.ps
  9. Mathis, M., and Mahdavi, J. TCP Rate-Halving with Bounding Parameters. Available from http://www.psc.edu/networking/papers/FACKnotes/current/

AUTHORS

Steven McCanne (mccanne@ee.lbl.gov), University of California, Berkeley and Lawrence Berkeley National Laboratory, Berkeley, CA, and Sally Floyd (floyd@ee.lbl.gov) Lawrence Berkeley National Laboratory, Berkeley, CA. Major contributors to ns include Kevin Fall, Jamshid Mahdavi, Matt Mathis, and Kannan Varadhan.

BUGS

Only a single trace can be attached to any given object.

Several modules from tcpsim have not been ported over yet to ns-1.

This manual page is incomplete.


Table of Contents