The simulator is invoked via the ns interpreter, an extension of the vanilla otclsh command shell. A simulation is defined by a OTcl script. The scripts use the Simulator Class as the principal interface to the simulation engine. Using the methods defined in this class, a network topology is defined, traffic sources and sinks are configured, the simulation is invoked, and the statistics are collected. By building upon a fully functional language, arbitrary actions can be programmed into the configuration.
The first step in the simulation is to acquire an instance of the Simulator class. Instances of objects in classes are created and destroyed in ns using the new and delete methods. For example, an instance of the Simulator object is created by the following command:
e.g. set ns [new Simulator]
A network topology is realized using three primitive building blocks: nodes, links, and agents. The Simulator class has methods to create/ configure each of these building blocks. Nodes are created with the node Simulator method that automatically assigns an unique address to each node. Links are created between nodes to form a network topology with the simplex-link and duplex-link methods that set up unidirectional and bidirectional links respectively. Agents are the objects that actively drive the simulation. Agents can be thought of as the processes and/or transport entities that run on nodes that may be end hosts or routers. Traffic sources and sinks, dynamic routing modules and the various protocol modules are all examples of agents. Agents are created by instantiating objects in the subclass of class Agent i.e., Agent/type where type specifies the nature of the agent. For example, a TCP agent is created using the command:
set tcp [new Agent/TCP]
Once the agents are created, they are attached to nodes with the attach-agent Simulator method. Each agent is automatically assigned a port number unique across all agents on a given node (analogous to a tcp or udp port). 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. Sources are attached to agents using the attach-source and attachtraffic agent methods.
Each object has some configuration parameters associated with it that can be modified. Configuration parameters are instance variables of the object. These parameters are initialized during startup to default values that can simply be read from the instance variables of the object. For example, $tcp set window_ returns the default window size for the tcp object. The default values for that object can be explicitly overridden by simple assignment either before a simulation begins, or dynamically, while the simulation is in progress. For example the window-size for a particular TCP session can be changed in the following manner.
$tcp set window_ 25
The default values for the configuration parameters of all the class objects subsequently created can also be changed by simple assignment. For example, we can say
Agent/TCP set window_ 30
to make all future tcp agent creations default to a window size of 30.
Events are scheduled in ns using the at Simulator method that allows OTcl procedures to be invoked at arbitrary points in simulation time. These OTcl 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. The simulation is started via the run method and continues until there are no more events to be processed. At this time, the original invocation of the 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 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 the sum of costs of the links traversed from the source to the destination. The cost of a link is 1 by default; the distance metric is simply the hop count in this case. The cost of a link can be changed with the cost Simulator method. A static topology model is used as the default in ns in which the states of nodes/links do not change during the course of a simulation. Network Dynamics could be specified using methods described in NETWORK DYNAMICS METHODS section. Also static unicast routing is the default in which the routes are pre-computed over the entire topology once prior to starting the simulation. Methods to enable and configure dynamic unicast and multicast routing are described in the UNICAST ROUTING METHODS and MULTICAST ROUTING METHODS sections respectively.
The first step in running a simulation as stated before is to acquire an instance of the Simulator class that has methods to configure and run the simulation. Throughout this section the object variable name $ns is used to imply a Simulator object.
$ns node
Create a new node object and return a handle to it.
$ns all-nodes-list
Returns a list of all the node objects defined in the
simulation.
$ns simplex-link node1 node2 bw delay type Create a new unidirectional link between node1 and node2 with bandwidth bw in bits per second and link propagation delay delay in seconds. node1 and node2 must have already been created with the node method. bw and delay default to 1.5 Mbits/sec and 100 ms respectively. The defaults can be changed by modifying the relevant configuration parameters of the DelayLink Object (see DELAYLINK OBJECTS section). node1 and node2 must have already been created with the node method. The queuing discipline of the link is specified by type, which may be DropTail, FQ, SFQ, DRR, RED, CBQ, or CBQ/WRR. A DropTail link is a simple FIFO queue which drops the last packet in the queue when the queue overflows. A FQ link is for Fair Queuing (for details see [?]). A SFQ link is for Stochastic Fair Queuing (for details see [?]). A DRR link is for deficit round robin scheduling (for details see [9]). A RED link is a random-early drop queue (for details see [2]). A CBQ link is for class-based queuing using a packet-bypacket round-robin scheduler (for details see [3]). A CBQ/WRR link is for class-based queuing with a weighted round robin scheduler. If multicast routing is used links with interface labels are required. Such links are created by setting Simulator NumberInterfaces_ variable to 1. All the subsequently created links will have interface labels. To disable creation of interfaces simply reset NumberInterfaces_ to 0 (this is the default).
$ns duplex-link node1 node2 bw delay type Create a new bidirectional link between node1 and node2 with bandwidth bw in bits per second and link propagation delay delay in seconds. node1 and node2 must have already been created with the node method. bw and delay default to 1.5 Mbits/sec and 100 ms respectively. The defaults can be changed by modifying the relevant configuration parameters of the DelayLink Object (see DELAYLINK OBJECTS section). The queuing discipline of the link is specified by type, which may be DropTail, FQ SFQ, DRR, RED, CBQ, or CBQ/WRR. A DropTail link is a simple FIFO queue which drops the last packet in the queue when the queue overflows. A FQ link is for Fair Queuing (for details see [?]). A SFQ link is for Stochastic Fair Queuing (for details see [?]). A DRR link is for deficit round robin scheduling (for details see [9]). A RED link is a random-early drop queue (for details see [2]). A CBQ link is for class-based queuing using a packet-by-packet round-robin scheduler (for details see [3]). A CBQ/WRR link is for class-based queuing with a weighted round robin scheduler. If multicast routing is used links with interface labels are required. Such links are created by setting Simulator NumberInterfaces_ variable to 1. All the subsequently created links will have interface labels. To disable creation of interfaces simply reset NumberInterfaces_ to 0 (this is the default).
$ns link node1 node2
Returns a reference to the link connecting nodes node1
and node2. This is useful for setting link configuration
parameters and to invoke tracing methods (see LINK
OBJECTS section).
$ns queue-limit node1 node2 queue-limit
Set the maximum number of packets that can be queued on
the link in the direction from node1 to node2 to
queue-limit. The link between node1 and node2 should
have already been created.
$ns delay node1 node2 time-interval
Set the latency of the link in the direction from node1
to node2 to time-interval seconds. The link between
node1 and node2 should have already been created.
$ns cost node1 node2 cost-val
Assign the cost cost-val to the link between nodes
node1 and node2. The costs assigned to links are used
in unicast route computations. All the links default
to a cost of 1.
new Agent/type
Create an Agent of type type which may be:
$ns detach-agent node agent
Detach the agent object agent from node.
$ns connect src dst
Establish a two-way connection between the agent src
and the agent dst. Returns the handle to src agent. A
helper method has been defined to facilitate creating
and attaching an agent to each of two nodes and establishing
a two-way connection between them. (see BUILTINS
section).
$ns use-scheduler type
Use an event scheduler of type type in the simulations.
type is one of List, Heap, Calendar, RealTime. The
List scheduler is the default. A Heap scheduler uses a
heap for event queueing. A Calendar scheduler uses a
calendar queue to keep track of events. RealTime
scheduler is used in emulation mode when the simulator
interacts with an external agent.
$ns at time procedure
Evaluate procedure at simulation time time. The procedure
could be a globally accessible function (proc)
or an object method (instproc). This command can be
used to start and stop sources, dynamically reconfigure
the simulator, dump statistics at specified intervals,
etc. Returns an event id.
$ns cancel eid
Remove the event specified by the event id eid from the
event queue.
$ns now
Return the current simulation time.
$ns gen-map
Walks through the simulation topology and lists all the
objects that have been created and the way they are
hooked up to each other. This is useful to debug simulation
scripts.
ns-version
Return a string identifying the version of ns currently
running. This method is executed in the global context
by the interpreter.
ns-random [ seed ]
If seed is not present, return a pseudo-random integer
between 0 and 2^31-1. Otherwise, seed the pseudorandom
number generator with seed and return the seed
used. If seed is 0, choose an initial seed heuristically
(which varies on successive invocations). This
method is executed in the global context by the interpreter.
Objects are associated with configuration parameters that can be dynamically set and queried, and state variables that can be queried (usually modified only when the state variables need to be reset for another simulation run).
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 object hierarchy:
Simulator
MultiSim
Node
Link
SimpleLink
CBQLink
DummyLink
DelayLink
Queue
DropTail
FQ
SFQ
DRR
RED
CBQ
CBQ/WRR
QueueMonitor
ED
Flowmon
Flow
rtObject
RouteLogic
Agent
rtProto
Static
Session
DV
Direct
Null
LossMonitor
TCPSimple
TCP
FullTcp
Reno
Newreno
Sack1
Fack
TCPSink
DelAck
Sack1
DelAck
CBR
UDP
RTP
RTCP
IVS
Source
Receiver
SRM
Session
RTP
Source
FTP
Telnet
Traffic
Expoo
Pareto
Trace
Integrator
Samples
For example, any method that is supported by a TCP agent is
also supported by a Reno or a Sack1 agent. Default configuration
parameters are also inherited. For example, $tcp
set window_ 20 where $tcp is a TCP agent defines the default
TCP window size for both TCP and Reno objects.
$node id
Returns the node id.
$node neighbors
Returns a list of the neighbour node objects.
$node attach agent
Attach an agent of type agent to this node.
$node detach agent
Detach an agent of type agent from this node.
$node agent port
Return a handle to the agent attached to port port on
this node. Returns an empty string if the port is not
in use.
$node reset port
Reset all agents attached to this node. This would
re-initialize the state variables associated with the
various agents at this node.
$node rtObject?
Returns a handle to rtObject if there exists an
instance of the object at that node. Only nodes that
take part in a dynamic unicast routing protocol will
have this object (see UNICAST ROUTING METHODS and RTOBJECT
OBJECTS section).
$node join-group agent group
Add the agent specified by the object handle 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. Multicast group address should be in the
range 0x8000 - 0xFFFF.
$node allocaddr
Returns multicast group address in ascending order on
each invocation starting from 0x8000 and ending at
0xFFFF.
There are no state variables or configuration parameters specific to the node class.
$link trace-dynamics ns fileID
Trace the dynamics of this link and write the output to
fileID filehandle. ns is an instance of the Simulator
or MultiSim object that was created to invoke the simulation
(see TRACE AND MONITORING METHODS section for
the output trace format).
$link cost cost-val
Make cost-val the cost of this link.
$link cost?
Return the cost of this link.
Any configuration parameters or state variables?
The DelayLink Objects determine the amount of time required for a packet to traverse a link. This is defined to be size/bw + delay where size is the packet size, bw is the link bandwidth and delay is the link propagation delay. There are no methods or state variables associated with this object.
Configuration Parameters
bandwidth_
Link bandwidth in bits per second.
delay_
Link propagation delay in seconds.
There are no state variables associated with this object.
$ns rtmodel model model-params node1 [node2] Make the link between node1 and node2 change between up and down states according to the model model. In case only node1 is specified all the links incident on the node would be brought up and down according to the specified model. model-params contains the parameters required for the relevant model and is to be specified as a list i.e. the parameters are to be enclosed in curly brackets. model can be one of Deterministic, Exponential, Manual, Trace. Returns a handle to a model object corresponding to the specified model.
In the Deterministic model model-params is [start-time] up-interval down-interval [finish-time]. Starting from start-time the link is made up for up-interval and down for down-interval till finish-time is reached. The default values for start-time, up-interval, downinterval are 0.5s, 2.0s, 1.0s respectively. finishtime defaults to the end of the simulation. The start-time defaults to 0.5s in order to let the routing protocol computation quiesce.
If the Exponential model is used model-params is of the form up-interval down-interval where the link up-time is an exponential distribution around the mean upinterval and the link down-time is an exponential distribution around the mean down-interval. Default values for up-interval and down-interval are 10s and 1s respectively.
If the Manual distribution is used model-params is at op where at specifies the time at which the operation op should occur. op is one of up, down. The Manual distribution could be specified alternately using the rtmodel-at method described later in the section.
If Trace is specified as the model the link/node dynamics is read from a Tracefile. The model-params argument would in this case be the file-handle of the Tracefile that has the dynamics information. The tracefile format is identical to the trace output generated by the trace-dynamics link method (see TRACE AND MONITORING METHODS SECTION).
$ns rtmodel-delete model-handle
Delete the instance of the route model specified by
model-handle.
$ns rtmodel-at at op node1 [node2]
Used to specify the up and down times of the link
between nodes node1 and node2. If only node1 is given
all the links incident on node1 will be brought up and
down. at is the time at which the operation op that
can be either up or down is to be performed on the
specified link(s).
Configuration Parameters
limit_
The queue size in packets.
blocked_
Set to false by default, this is true if the queue
is blocked (unable to send a packet to its downstream
neighbor).
unblock_on_resume_
Set to true by default, indicates a queue should
unblock itself at the time the last packet packet
sent has been transmitted (but not necessarily
received).
Configuration Parameters
secsPerByte_
There are no state variables associated with this object.
Configuration Parameters
maxqueue_
buckets_
There are no state variables associated with this object.
Configuration Parameters
buckets_
Indicates the total number of buckets to be used
for hashing each of the flows.
blimit_
Indicates the shared buffer size in bytes.
quantum_
Indicates (in bytes) how much each flow can send
during its turn.
mask_
mask_, when set to 1, means that a particular flow
consists of packets having the same node id (and
possibly different port ids), otherwise a flow
consists of packets having the same node and port
ids.
Configuration Parameters
bytes_
Set to "true" to enable ``byte-mode'' RED, where
the size of arriving packets affect the likelihood
of marking (dropping) packets.
queue-in-bytes_
Set to "true" to measure the average queue size in
bytes rather than packets. Enabling this option
also causes thresh_ and maxthresh_ to be automatically
scaled by mean_pktsize_ (see below).
thresh_
The minimum threshold for the average queue size
in packets.
maxthresh_
The maximum threshold for the average queue size
in packets.
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 mark packets by setting the
congestion indication bit in packet headers rather
than drop packets.
drop-tail_
Set to true to use drop-tail rather than randomdrop
when the queue overflows or the average queue
size exceeds "maxthresh_". For a further explanation
of these variables, see [2].
State Variables
None of the state variables of the RED implementation
are accessible.
$cbq insert $class
Insert traffic class class into the link-sharing
structure associated with link object cbq.
$cbq bind $cbqclass $id1 [$id2]
Cause packets containing flow id $id1 (or those in the
range $id1 to $id2 inclusive) to be associated with the
traffic class $cbqclass.
$cbq algorithm $alg
Select the CBQ internal algorithm. $alg may be set to
one of: "ancestor-only", "top-level", or "formal".
Configuration Parameters
maxpkt_
The maximum size of a packet in bytes. This is
used only by CBQ/WRR objects in computing maximum
bandwidth allocations for the weighted round-robin
scheduler.
extradelay
$cbqclass setparams parent okborrow allot maxidle prio level
Sets several of the configuration parameters for the
CBQ traffic class (see below).
$cbqclass parent [$cbqcl|none]
specify the parent of this class in the link-sharing
tree. The parent may be specified as ``none'' to indicate
this class is a root.
$cbqclass newallot $a
Change the link allocation of this class to the specified
amount (in range 0.0 to 1.0). Note that only the
specified class is affected.
$cbqclass install-queue $q
Install a Queue object into the compound CBQ or CBQ/WRR
link structure. When a CBQ object is initially
created, it includes no internal queue (only a packet
classifier and scheduler).
Configuration Parameters
okborrow_
is a boolean indicating the class is permitted to
borrow bandwidth from its parent.
allot_
is the maximum fraction of link bandwidth allocated
to the class expressed as a real number
between 0.0 and 1.0.
maxidle_
is the maximum amount of time a class may be
required to have its packets queued before they
are permitted to be forwarded
priority_
is the class' priority level with respect to other
classes. This value may range from 0 to 10, and
more than one class may exist at the same priority.
Priority 0 is the highest priority.
level_
is the level of this class in the link-sharing
tree. Leaf nodes in the tree are considered to be
at level 1; their parents are at level 2, etc.
extradelay_
increase the delay experienced by a delayed class
by the specified time
$queuemonitor
reset all the cumulative counters described below
(arrivals, departures, and drops) to zero. Also, reset
the integrators and delay sampler, if defined.
$queuemonitor set-delay-samples delaySamp_
Set up the Samples object delaySamp_ to record statistics
about queue delays. delaySamp_ is a handle to a
Samples object i.e the Samples object should have
already been created.
$queuemonitor get-bytes-integrator
Returns an Integrator object that can be used to find
the integral of the queue size in bytes. (see
Integrator Objects section).
$queuemonitor get-pkts-integrator
Returns an Integrator object that can be used to find
the integral of the queue size in packets. (see
Integrator Objects section).
$queuemonitor get-delay-samples
Returns a Samples object delaySamp_ to record statistics
about queue delays (see Samples Objects section).
There are no configuration parameters specific to this object.
State Variables
size_
Instantaneous queue size in bytes.
pkts_
Instantaneous queue size in packets.
parrivals_
Running total of packets that have arrived.
barrivals_
Running total of bytes contained in packets that
have arrived.
pdepartures_
Running total of packets that have departed (not
dropped).
bdepartures_
Running total of bytes contained in packets that
have departed (not dropped).
pdrops_
Total number of packets dropped.
bdrops_
Total number of bytes dropped.
bytesInt_
Integrator object that computes the integral of
the queue size in bytes. The sum_ variable of this
object has the running sum (integral) of the queue
size in bytes.
pktsInt_
Integrator object that computes the integral of
the queue size in packets. The sum_ variable of
this object has the running sum (integral) of the
queue size in packets.
State Variables
epdrops_
The number of packets that have been dropped
``early''.
ebdrops_
The number of bytes comprising packets that have
been dropped ``early''
Note: because this class is a subclass of QueueMonitor, objects of this type also have fields such as pdrops_ and bdrops_. These fields describe the total number of dropped packets and bytes, including both early and non-early drops.
$fmon classifier [$cl]
insert (read) the specified classifier into (from) the
flow monitor object. This is used to map incoming
packets to which flows they are associated with.
$fmon dump
Dump the current per-flow counters and statistics to
the I/O channel specified in a previous attach operation.
$fmon flows
Return a character string containing the names of all
flow objects known by this flow monitor. Each of these
objects are of type QueueMonitor/ED/Flow.
$fmon attach $chan
Attach a tcl I/O channel to the flow monitor. Flow
statistics are written to the channel when the dump
operation is executed.
Configuration Parameters
enable_in_
Set to true by default, indicates that per-flow
arrival state should be kept by the flow monitor.
If set to false, only the aggregate arrival information
is kept.
enable_out_
Set to true by default, indicates that per-flow
departure state should be kept by the flow monitor.
If set to false, only the aggregate departure
information is kept.
enable_drop_
Set to true by default, indicates that per-flow
drop state should be kept by the flow monitor. If
set to false, only the aggregate drop information
is kept.
enable_edrop_
Set to true by default, indicates that per-flow
early drop state should be kept by the flow monitor.
If set to false, only the aggregate early
drop information is kept.
State Variables
src_ The source address of packets belonging to this flow.
dst_ The destination address of packets belonging to this flow.
flowid_
The flow id of packets belonging to this flow.
$ns rtproto proto node-list
Specifies the dynamic unicast routing protocol proto to
be run on the nodes specified by node-list. Currently
proto can be one of Static, Session, DV. Static routing
is the default. Session implies that the unicast
routes over the entire topology are instantaneously
recomputed whenever a link goes up or down. DV implies
that a simple distance vector routing protocol is to be
simulated. node-list defaults to all the nodes in the
topology.
$ns compute-routes
Compute routes between all the nodes in the topology.
This can be used if static routing is done and the
routes have to be recomputed as the state of a link has
changed. Note that Session routing (see rtproto method
above) will recompute routes automatically whenever the
state of any link in the topology changes.
$ns get-routelogic
Returns an handle to a RouteLogic object that has
methods for route table lookup etc.
$routelogic dump nodeid
Dump the routing tables of all nodes whose id is less
than nodeid. Node ids are typically assigned to nodes
in ascending fashion starting from 0 by their order of
creation.
$rtobject dump-routes fileID
Dump the routing table to the output channel specified
by fileID. fileID must be a file handle returned by the
Tcl open command and it must have been opened for writing.
$rtobject rtProto? proto
Returns a handle to the routing protocol agent specified
by proto if it exists at that node. Returns an
empty string otherwise.
$rtobject nextHop? destID
Returns the id of the node that is the next hop to the
destination specified by the node id, destID.
$rtobject rtpref? destID
$rtobject metric? destID
$ns mrtproto proto node-list
Specifies the multicast routing protocol proto to be
run on the nodes specified by node-list. Currently
proto can be one of CtrMcast, DM, dynamicDM, pimDM.
node-list defaults to all the nodes in the topology.
Returns an handle to a protocol-specific object that
has methods, configuration parameters specific to that
protocol. Note that currently CtrMcastComp object is
returned if CtrMcast is used but a null string is
returned if DM, dynamicDM or pimDM are used.
If proto is `CtrMcast' a Rendezvous Point (RP) rooted shared tree is built for a multicast group. The actual sending of prune, join messages etc. to set up state at the nodes is not simulated. A centralized computation agent is used to compute the fowarding trees and set up multicast forwarding state, (*,G) at the relevant nodes as new receivers join a group. Data packets from the senders to a group are unicast to the RP. Methods are provided in the CtrMcastComp object (see CTRMCASTCOMP OBJECTS section) that is returned by mrtproto to switch to source-specific trees, choose some nodes as candidate RPs etc. When a node/link on a multicast distribution tree goes down, the tree is instanteously recomputed.
If proto is `DM' DVMRP-like dense mode is simulated. Parent-child lists are used to reduce the number of links over which the data packets are broadcast. Prune messages are sent by nodes to remove branches from the multicast forwarding tree that do not lead to any group members. The prune timeout value is 0.5s by default (see DM OBJECTS section to change the default). This does not adapt to network changes.
If proto is `dynamicDM' DVMRP-like dense mode protocol that adapts to network changes is simulated. (i.e. the information that a particular neighbouring node uses me to reach a particular network) is read from the routing tables of neighbouring nodes in order to adapt to network dynamics (DVMRP runs its own unicast routing protocol that exchanges this information). The prune timeout value is 0.5s by default (see DM OBJECTS section to change the default).
If proto is `pimDM' Protocol Independent Multicast Dense mode is simulated. In this case the data packets are broadcast over all the outgoing links except the incoming link. Prune messages are sent by nodes to remove the branches of the multicast forwarding tree that do not lead to any group members. The prune timeout value is 0.5s by default (see DM OBJECTS section to change the default).
$ctrmcastcomp switch-treetype group-addr
Switch from the Rendezvous Point rooted shared tree to
source-specific trees for the group specified by
group-addr. Note that this method cannot be used to
switch from source-specific trees back to a shared tree
for a multicast group.
$ctrmcastcomp set_c_rp node-list
Make all the nodes specified in node-list as candidate
RPs. All nodes are candidate RPs by default and
currently the node with the highest node id serves as
the RP for all multicast groups. This is likely to
change soon.
$ctrmcastcomp get_rp node group
Returns the RP for the group as seen by the node node
for the multicast group with address group-addr. Note
that different nodes may see different RPs for the
group if the network is partitioned as the nodes might
be in different partitions.
Configuration parameters
PruneTimeout
Timeout value for the prune state at nodes.
$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 destination node this agent
is connected to.
$agent dst-port
Return the port at the destination node that this agent
is connected to.
$agent attach-source type
Install a data source of type type in this agent. type
is one of FTP or bursty[???]. See the corresponding
object methods for information on configuration parameters.
Returns a handle to the source object.
$agent attach-traffic traffic-object
Attach traffic-object to this agent traffic-object is
an instance of Traffic/Expoo, Traffic/Pareto or
Traffic/Trace. Traffic/Expoo generates traffic based
on an Exponential On/Off distribution. Traffic/Pareto
generates traffic based on a Pareto On/Off distribution.
Traffic/Trace generates traffic from a trace
file. The relevant configuration parameters for each
of the above objects can be found in the TRAFFIC
METHODS section.
$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
dst_ Address of destination that the agent is connected to. Currently 32 bits with the higher 24 bits the destination node ID and the lower 8 bits being the port number.
There are no state variables specific to the generic agent class.
Null objects are a subclass of agent objects that implement a traffic sink. They inherit all of the generic agent object functionality. There are no methods, configuration parameters or state variables specific to this object.
LossMonitor objects are a subclass of agent objects that implement a traffic sink which also maintains some statistics about the received data e.g., number of bytes received, number of packets lost etc. They inherit all of the generic agent object functionality.
$lossmonitor clear
Resets the expected sequence number to -1.
Configuration Parameters
There are no configuration parameters specific to this object.
State Variables
nlost_
Number of packets lost.
npkts_
Number of packets received.
bytes_
Number of bytes received.
lastPktTime_
Time at which the last packet was received.
expected_
The expected sequence number of the next packet.
Configuration Parameters
window_
The upper bound on the advertised window for the
TCP connection.
maxcwnd_
The upper bound on the congestion window for the
TCP connection. Set to zero to ignore. (This is
the default.)
windowInit_
The initial size of the congestion window on
slow-start.
windowOption_
The algorithm to use for managing the congestion
window.
windowThresh_
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. This allows a Fast Retransmit after a quench() due to an ECN (explicit congestion notification) bit.
packetSize_
The size in bytes to use for all packets from this
source.
tcpTick_
The TCP clock granularity for measuring roundtrip
times. Note that it is set by default to the
non-standard value of 100ms.
bugFix_
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.
slow_start_restart_
Set to 1 to slow-start after the connection goes
idle. On by default.
Defined Constants
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.
State Variables
dupacks_
Number of duplicate acks seen since any new data
was acknowledged.
seqno_
Highest sequence number for data from data source
to TCP.
t_seqno_
Current transmit sequence number.
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.
There are no methods or state variables specific to this object.
Configuration Parameters
newreno_changes_
Set to zero for the default NewReno described in
[7]. Set to 1 for additional NewReno algorithms
as suggested in [10]; this includes the estimation
of the ssthresh parameter during slow-start.
They inherit all of the TCP object functionality. There are no methods, configuration parameters or state variables specific to this object.
They inherit all of the TCP object functionality. There are no methods or state variables specific to this object.
Configuration Parameters
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)
Configuration Parameters
packetSize_
The size in bytes to use for all acknowledgment
packets.
maxSackBlocks_
The maximum number of blocks of data that can be
acknowledged in a SACK option. For a receiver
that is also using the time stamp option [RFC
1323], the SACK option specified in RFC 2018 has
room to include three SACK blocks. This is only
used by the TCPSink/Sack1 subclass. This value
may not be increased within any particular TCPSink
object after that object has been allocated.
(Once a TCPSink object has been allocated, the
value of this parameter may be decreased but not
increased).
Configuration Parameters
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.
Configuration Parameters
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.
$srm traffic-source source
Attach a traffic source, e.g., Agent/CBR, to the SRM
agent. This is likely to change as the API for Traffic
Generators is improved.
$srm start
Join the multicast group, start the SRM agent and its
attached traffic source.
$srm delete
Stop the SRM agent, delete all its status and detach
the traffic source.
$srm trace trace-file
Write the traces generated by the SRM agent to tracefile.
The traces includes timer settings, request and
repair sending and receipts, etc. Two related files
that are not built into ns are tcl/mcast/srm-debug.tcl
that permits more detailed tracing of the delay computation
functions, and tcl/mcast/srm-nam.tcl that
separately marks srm control messages from data. The
latter is useful to enhance nam visualisation.
$srm log log-file
Write the recovery statistics during each request or
repair to log-file. The statistics include start time,
duration, message id, total number of duplicate
requests and repairs.
$srm distance? node
Return the distance estimate to node in this SRM agent.
$srm distances? node
Returns a list of <group member, distance> tuples of
the distances to all group members that this node is
aware of. The group member is identified as the
address of the remote agent. The first tuple is this
agent's token. The list can be directly loaded into a
Tcl array.
Configuration Parameters
packetSize_
The data packet size that will be used for repair
messages. The default value is 1024.
requestFunction_
The algorithm used to produce a retransmission request, e.g., setting request timers. The default value is SRM/request. Other possible request functions are SRM/request/Adaptive, used by the Adaptive SRM code.
repairFunction_
The algorithm used to produce a repair, e.g., compute
repair timers. The default value is
SRM/repair. Other possible request functions are
SRM/repair/Adaptive, used by the Adaptive SRM
code.
sessionFunction_
The algorithm used to generate session messages.
Default is SRM/session
sessionDelay_
The basic interval of session messages. Slight
random variation is added to this interval to
avoid global synchronization of session messages.
User may want to adjust this variable according to
their specific simulation. Default value is 1.0.
C1_, C2_
The parameters which control the request timer.
Refer to [8] for detail. The default value is C1_
= C2_ = 2.0.
D1_, D2_
The parameters which control the repair timer.
Refer to [8] for detail. The default value is D1_
= D2_ = 1.0.
requestBackoffLimit_
The maximum number of exponential backoffs.
Default value is 5.
State Variables
stats_
An array containing multiple statistics needed by
adaptive SRM agent. Including: duplicate requests
and repairs in current request/repair period,
average number of duplicate requests and repairs,
request and repair delay in current request/repair
period, average request and repair delay.
State Variables Refer to the SRM paper by Sally et al ([11]) for more detail.
pdistance_
This variable is used to pass the distance estimate
provided by the remote agent in a request or
repair message.
D1_, D2_
The same as that in SRM agents, except that they
are initialized to log10(group size) when generating
the first repair.
MinC1_, MaxC1_, MinC2_, MaxC2_
The minimum/maximum values of C1_ and C2_. Default
initial values are defined in [8]. These values
define the dynamic range of C1_ and C2_.
MinD1_, MaxD1_, MinD2_, MaxD2_
The minimum/maximum values of D1_ and D2_. Default
initial values are defined in [8]. These values
define the dynamic range of D1_ and D2_.
AveDups
Higher bound for average duplicates.
AveDelay
Higher bound for average delay.
eps AveDups - dups determines the lower bound of the number of duplicates, when we should adjust parameters to decrease delay.
$cbr start
Causes the source to start generating packets.
$cbr stop
Causes the source to stop generating packets.
Configuration Parameters
interval_
The amount of time to delay between packet
transmission times.
packetSize_
The size in bytes to use for all packets from this
source.
random_
This parameter determines whether random noise is introduced into the
packet generation process.
If random_ is zero, the inter-packet
time is interval_. If random_ is
non-zero, inter-packet times are chosen uniformly from
[.5 * interval_, 1.5 * interval_].
$ftp start
Causes the source to produce maxpkts_ packets.
$ftp produce n
Causes the FTP object to produce n packets instantaneously.
$ftp stop
Causes the attached TCP object to stop sending data.
$ftp attach agent
Attaches a Source/FTP object to agent.
$ftp producemore count
Causes the Source/FTP object to produce count more
packets.
Configuration Parameters
maxpkts
The maximum number of packets generated by the
source.
$telnet stop
Causes the SOURCE/Telnet object to stop producing packets.
$telnet attach agent
Attaches a Source/Telnet object to agent.
Configuration Parameters
interval_
The average inter-arrival time in seconds for
packets generated by the SOURCE/Telnet object.
Configuration Parameters
packet-size
The packet size in bytes.
burst-time
Burst duration in seconds.
idle-time
Idle time in seconds.
rate Peak rate in bits per second.
Configuration Parameters
packet-size
The packet size in bytes.
burst-time
Average on time in seconds.
idle-time
Average off time in seconds.
rate Peak rate in bits per second.
shape
Pareto shape parameter.
$trace attach-tracefile tfile
Attach the Tracefile object tfile to this trace. The
Tracefile object specifies the trace file from which
the traffic data is to be read (see TRACEFILE OBJECTS
section). Multiple Traffic/Trace objects can be
attached to the same Tracefile object. A random starting
place within the Tracefile is chosen for each
Traffic/Trace object.
There are no configuration parameters for this object.
$tracefile filename trace-input
Set the filename from which the traffic trace data is
to be read to trace-input.
There are no configuration parameters for this object. A trace file consists of any number of fixed length records. Each record consists of 2 32 bit fields. The first indicates the interval until the next packet is generated in microseconds. The second indicates the length of the next packet in bytes.
Trace objects are used to generate event level capture logs typically to an output file. Throughout this section $ns refers to a Simulator object.
$ns create-trace type fileID node1 node2 Create a Trace object of type type and attach the filehandle fileID to it to monitor the queues between nodes node1 and node2. type can be one of Enque, Deque, Drop. Enque monitors packet arrival at a queue. Deque monitors packet departure at a queue. Drop monitors packet drops at a queue. fileID must be a file handle returned by the Tcl open command and it must have been opened for writing. Returns a handle to the trace object.
$ns drop-trace node1 node2 trace
Remove trace object attached to the link between nodes
node1 and node2 with trace as the object handle.
$ns trace-queue node1 node2 fileID
Enable Enque, Deque and Drop tracing on the link
between node1 and node2.
$ns trace-all fileID
Enable Enque, Deque, Drop Tracing on all the links in
the topology created after this method is invoked.
Also enables the tracing of network dynamics. fileID
must be a file handle returned by the Tcl open command
and it must have been opened for writing.
$ns monitor-queue node1 node2
Arrange for queue length of link between nodes node1
and node2 to be tracked. Returns QueueMonitor object
that can be queried to learn average queue size etc.
[see QueueMonitor Objects section]
$ns flush-trace
Flush the output channels attached to all the trace
objects.
$link trace-dynamics ns fileID
Trace the dynamics of this link and write the output to fileID filehandle. ns is an instance of the Simulator or MultiSim object that was created to invoke the simulation.
The tracefile format is backward compatible with the output files in the ns version 1 simulator so that ns-1 postprocessing scripts can still be used. Trace records of traffic for link objects with Enque, Deque, receive or Drop Tracing have the following form:
<code> <time> <hsrc> <hdst> <packet>
where
<code> := [hd+-] h=hop d=drop +=enque -=deque r=receive
<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> <flowID> <src.sport> <dst.dport> <seq> <pktID>
<type> := tcp|telnet|cbr|ack etc.
<size> := packet size in bytes
<flags> := [CP] C=congestion, P=priority
<flowID> := flow identifier field as defined for IPv6
<src.sport> := transport address (src=node,sport=agent)
<dst.sport> := transport address (dst=node,dport=agent)
<seq> := packet sequence number
<pktID> := unique identifer for every new packet
Only those agents interested in providing sequencing will generate sequence numbers and hence this field may not be useful for packets generated by some agents.
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
Trace records for link dynamics are of the form:
<code> <time> <state> <src> <dst>
where
<code> := [v]
<time> := simulation time in seconds
<state> := [link-up | link-down]
<src> := first node address of link
<dst> := second node address of link
$integrator newpoint x y
Add the point (x,y) to the sum. Note that it does not
make sense for x to be less than lastx_.
There are no configuration parameters specific to this object.
State Variables
lastx_
x-coordinate of the last sample point.
lasty_
y-coordinate of the last sample point.
sum_ Running sum (i.e. the integral) of the sample points.
$samples mean
Returns mean of the sample.
$samples variance
Returns variance of the sample.
$samples cnt
Returns a count of the sample points considered.
$samples reset
Reset the Samples object to monitor a fresh set of samples.
There are no configuration parameters or state variables specific to this object.
Because OTcl 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 as methods of the Simulator class. Throughout this section $ns represents a Simulator object.
$ns create-connection srcType srcNode dstType dstNode class Create a source agent of type srcType at node srcNode and connect it to a destination agent of type dstType at node dstNode. Also, connect the destination agent to the source agent. The traffic class of both agents is set to class. This method returns the source agent.
#
# Create two nodes
#
set n0 [$ns node]
set n1 [$ns node]
#
# Create a trace and arrange for all the trace events of the
# links subsequently created to be dumped to "out.tr"
#
set f [open out.tr w]
$ns trace-all $f
#
# Connect the two nodes with a 1.5Mb link with a transmission
# delay of 10ms using FIFO drop-tail queuing
#
$ns duplex-link $n0 $n1 1.5Mb 10ms DropTail
#
# Set up BSD Tahoe TCP connections in opposite directions.
#
set tcp_src1 [new Agent/TCP]
set tcp_snk1 [new Agent/TCPSink]
set tcp_src2 [new Agent/TCP]
set tcp_snk2 [new Agent/TCPSink]
$ns attach-agent $n0 $tcp_src1
$ns attach-agent $n1 $tcp_snk1
$ns attach-agent $n1 $tcp_src2
$ns attach-agent $n0 $tcp_snk2
$ns connect $tcp_src1 $tcp_snk1
$ns connect $tcp_src2 $tcp_snk2
#
# Create ftp sources at the each node
#
set ftp1 [$tcp_src1 attach-source FTP]
set ftp2 [$tcp_src2 attach-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"
#
# run the simulation for 10 simulated seconds
#
$ns at 10.0 "exit 0"
$ns run
For more details about ns debugging please see <http://www.isi.edu/nsnam/ns/ns-debugging.html>.
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 ([email protected]) 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://wwwnrg.ee.lbl.gov/.
[1] S. Keshav, ``REAL: A Network Simulator''. UCB CS Tech Report 88/472, December 1988. See http://www.cs.cornell.edu/home/skeshav/real/overview.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. 397-413. Available from http://wwwnrg.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] David Wetherall and Christopher J. Linblad. Extending Tcl for Dynamic Object-Oriented Programming. In Proceedings of the USENIX Tcl/Tk Workshop, Toronto, Ontario, USENIX. July, 1995. At <http://www.tns.lcs.mit.edu/publications/tcltk95.djw.html>.
[9] M. Shreedhar and G. Varghese. Efficient Fair Queueing Using Deficit Round Robin. In Proc. of SIGCOMM, pp. 231-242, 1995.
[10] Hoe, J., Improving the Start-up Behavior of a Congestion Control Scheme for TCP. in SIGCOMM 96, August 1996, pp. 270-280. URL http://www.acm.org/sigcomm/sigcomm96/papers/hoe.html.
[11] Fall, K., Floyd, S., and Henderson, T., Ns Simulator Tests for Reno FullTCP. URL ftp://ftp.ee.lbl.gov/papers/fulltcp.ps. July 1997.
[12] Floyd, S., Jacobson, V., Liu, C.-G., McCanne, S. and Zhang, L., A Reliable Multicast Framework for Lightweight Sessions and Application Level Framing. To appear in IEEE/ACK Transaction on Networking, November 1996. ftp://ftp.ee.lbl.gov/papers/srm1.ps.gz
Work on ns is on-going. Information about the most recent version is available at <http://www.isi.edu/nsnam/ns/ns.html>.
A mailing list for ns users is also available, visit the list's information page to join.
This manual page is incomplete.