NS(1)

📦 version 2.35, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NS(1) — the manual, but make it make sense 💖

General Commands Manual · ns(1)

✨ NAME ✨

ns — network simulator (version 2). That's the whole vibe. 🦋

🌸 SYNOPSIS 🌸

ns [ file [ arg arg ...  ] ]

🎀 DESCRIPTION 🎀

okay so bestie, ns is an event-driven network simulator. Under the hood there's an extensible simulation engine written in C++, and it talks to you through MIT's Object Tool Command Language, aka OTcl — which is just an object-oriented version of Tcl — as the command and configuration interface. 🫶

The previous version of the simulator, ns version 1, used the Tool Command Language, Tcl, as its configuration language. And the current version still supports simulation scripts written in Tcl that were meant for the ns version 1 simulator. (Backwards compatible, we love to see it. 💅)

This manual page documents some of the interfaces for ns. For much more complete documentation, please see "ns Notes and Documentation" [13] — it's available in the distribution and on the web.

The simulator is invoked via the ns interpreter, which is an extension of the vanilla otclsh command shell. A simulation is defined by a OTcl script. Those scripts use the Simulator Class as the principal interface to the simulation engine. Using the methods defined in this class, you define a network topology, configure traffic sources and sinks, invoke the simulation, and collect the statistics. And because you're building on top of a fully functional language, arbitrary actions can be programmed right into the configuration. iconic, honestly. 👑

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, which automatically assigns a unique address to each node.
Links are created between nodes to form a network topology with the simplex-link and duplex-link methods, which 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. Applications are attached to agents using the attach-app method.

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, which lets OTcl procedures 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 the 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. 🧚

💅 NS COMMANDS 💅

This section describes the basic commands to create the building blocks of the simulation (i.e. the node, link and agent objects) and to run the simulation.

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 the 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-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 the 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 the 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.

$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 the 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. 💰
$ns multi-link node-list bw delay type — bestie, this one hooks up every node in node-list into a whole mesh of duplex links, which is the move when you wanna fake a broadcast LAN 🫶. node-list is a list of node object handles you already made with the node method, obviously. Bandwidth is bw in bits per second, link propagation delay is delay in seconds. bw and delay default to 1.5 Mbits/sec and 100 ms respectively (and yeah, you can change those defaults by editing the relevant configuration parameters of the DelayLink Object — go peek at the DELAYLINK OBJECTS section 👀). The queuing discipline comes from type, which can be DropTail, FQ SFQ, DRR, RED, CBQ, or CBQ/WRR. Run-down, no skips:
- A DropTail link is a simple FIFO queue that drops the last packet in the queue when the queue overflows. bye 👋
- A FQ link is for Fair Queuing (deets in [?]).
- A SFQ link is for Stochastic Fair Queuing (deets in [?]).
- A DRR link is for deficit round robin scheduling (deets in [9]).
- A RED link is a random-early drop queue (deets in [2]).
- A CBQ link is for class-based queuing using a packet-by-packet round-robin scheduler (deets in [3]).
- A CBQ/WRR link is for class-based queuing with a weighted round robin scheduler. slay 💅
$ns multi-link-of-interfaces node-list bw delay type — literally the same energy as above but the mesh of duplex links has interfaces on it (again, simulating a broadcast LAN ✨). Same deal: bw in bits per second, delay in seconds, node-list is node handles you already built with the node method, bw and delay default to 1.5 Mbits/sec and 100 ms, and you can tweak those defaults via the relevant configuration parameters of the DelayLink Object (hi again, DELAYLINK OBJECTS section 💖). type gives you the queuing discipline: DropTail, FQ SFQ, DRR, RED, CBQ, or CBQ/WRR.
- DropTail = simple FIFO queue, drops the last packet in the queue when the queue overflows.
- FQ = Fair Queuing (see [?]).
- SFQ = Stochastic Fair Queuing (see [?]).
- DRR = deficit round robin scheduling (see [9]).
- RED = random-early drop queue (see [2]).
- CBQ = class-based queuing with a packet-by-packet round-robin scheduler (see [3]).
- CBQ/WRR = class-based queuing with a weighted round robin scheduler.
new Agent/type — spin up an Agent of type type, and type can be any of these lil guys:
- Null — Traffic Sink
- LossMonitor — Traffic Sink that monitors loss parameters
- TCP — BSD Tahoe TCP
- TCP/FullTcp — Full Reno TCP with two-way connections [11]
- TCP/Reno — BSD Reno TCP
- TCP/Newreno — a modified version of BSD Reno TCP
- TCP/Vegas — Vegas TCP (from U. Arizonia via USC)
- TCP/Sack1 — BSD Reno TCP with selective ACKs
- TCP/Fack — BSD Reno TCP with forward ACKs
- TCPSink — standard TCP sink
- TCPSink/DelAck — TCP sink that generates delayed ACKs
- TCPSink/Sack1 — TCP sink that generates selective ACKs
- TCPSink/Sack1/DelAck — delayed-ack TCP sink with selective ACKs
- UDP — UDP Transport
- RTP — RTP agent
- Session/RTP —
- RTCP — RTCP agent
- IVS/Source —
- IVS/Receiver —
- SRM —

The methods, configuration parameters and the relevant state variables attached to these objects get discussed in detail in later sections, so hold that thought. Also note: some agents, like TCP or SRM, do not generate their own data 😭. Those ones need sources attached to them to make data (go look at the attach-source and attach-traffic methods in the AGENT OBJECTS section).

$ns attach-agent node agent — attaches the agent object agent to node. Both of them should already exist, no cap. 💫
$ns detach-agent node agent — detaches the agent object agent from node. goodbye bestie 🦋
$ns connect src dst — sets up a two-way connection between the agent src and the agent dst, and returns the handle to the src agent. There's a helper method defined to make it easy to create and attach an agent to each of two nodes and then connect them both ways (peep the BUILTINS section 👑).
$ns use-scheduler type — tells your simulation to use an event scheduler of type type. type is one of List, Heap, Calendar, RealTime. List is the default, periodt. A Heap scheduler uses a heap for event queueing. A Calendar scheduler uses a calendar queue to keep track of events. The RealTime scheduler is used in emulation mode, when the simulator is interacting with an external agent. 🔥
$ns at time procedure — evaluates procedure at simulation time time. That procedure can be a globally accessible function (proc) or an object method (instproc). Use this to start and stop sources, dynamically reconfigure the simulator, dump statistics at specified intervals, whatever your heart desires 💖. Returns an event id.
$ns cancel eid — removes the event specified by the event id eid from the event queue. poof, gone 💀
$ns now — returns the current simulation time. that's it, that's the whole vibe ✨
$ns gen-map — walks through the simulation topology and lists every object that's been created plus how they're all hooked up to each other. genuinely so useful for debugging your simulation scripts, ngl 🧚
ns-version — returns 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 isn't there, it returns a pseudo-random integer between 0 and 2^31-1. Otherwise it seeds the pseudo-random number generator with seed and returns the seed used. And if seed is 0, it picks an initial seed heuristically (which varies on successive invocations 👀). This method is executed in the global context by the interpreter.

Ns has other facilities for random number generation too; please see documentation for details [13].

🌸 OBJECT HIERARCHY 🌸

Okay so here's a lil description of the object hierarchy in ns. Heads up: this is not meant to be complete, it's just here so you can see how the methods and configuration parameters of the various objects get inherited. For the full picture, check "ns notes & documentation" and the automatically generated class library info on the ns web page. 📚

Objects are associated with configuration parameters that can be dynamically set and queried, and state variables that can be queried (usually only modified when the state variables need to be reset for another simulation run).

Configuration parameters = simulation parameters that are usually fixed for the whole simulation (like a link bandwidth), but can be changed dynamically if you want. State variables = values specific to a given object and that object's implementation. 💅

The following diagram depicts a portion 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
          TCP
               FullTcp
               Reno
               Newreno
               Sack1
               Fack
          TCPSink
               DelAck
               Sack1
                   DelAck
          UDP
          RTP
          RTCP
          IVS
               Source
               Receiver
          SRM
          Session
               RTP [how is this diff from Agent/CBR/RTP]
    Appplication
          FTP
          Telnet
          Traffic
               Expoo
               Pareto
               CBR
               Trace
    Integrator
    Samples

For a complete, automatically generated, object hierarchy, see the link "class hierarchy" (which points to http://www-sop.inria.fr/rodeo/personnel/Antoine.Clerget/ns/) on the ns web pages. (Thanks to Antoine Clerget for maintaining this! 🫶)

Example time: any method that's supported by a TCP agent is also supported by a Reno or a Sack1 agent. Default configuration parameters get inherited too ✨. So like, $tcp set window_ 20 — where $tcp is a TCP agent — defines the default TCP window size for both TCP and Reno objects.

💜 OBJECT METHODS 💜

The following sections document the methods, configuration parameters and state variables associated with the various objects, plus the ones that enable Network dynamics, Unicast routing, Multicast routing, and Trace and Monitoring support. 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.

🦋 NODE OBJECTS 🦋

⚠️ NOTE: This section has not been verified to be up-to-date with the release. ⚠️

Okay bestie, node methods time. These are the little knobs you can turn on a node object:

$node id — hands you the node's id. That's it, that's the whole thing. ✨
$node neighbors — gives you back a list of the neighbour node objects. Your node's little friendship circle 🫶
$node attach agent — attaches an agent of type agent onto this node. Welcome to the node, girlie 💅
$node detach agent — detaches an agent of type agent from this node. We're breaking up actually 💀
$node agent port — returns a handle to the agent attached to port port on this node. If that port isn't in use, you get an empty string back. Nothing there, babe. 🙈
$node reset — resets all agents attached to this node. Basically it re-initializes the state variables tied to the various agents sitting at this node. A lil factory reset for your agents 🔄
$node rtObject? — returns a handle to rtObject if an instance of that object actually exists at that node. Heads up: only nodes that take part in a dynamic unicast routing protocol will have this object (peep the UNICAST ROUTING METHODS and RTOBJECT OBJECTS sections for the tea). If you don't have it, don't come looking 🧐
$node join-group agent group — adds the agent specified by the object handle agent to the multicast host group identified by the address group. This makes the group membership protocol do its thing so the right multicast traffic actually reaches this agent. The multicast group address should be in the range 0x8000 - 0xFFFF. 📬
$node allocaddr — returns a multicast group address, going up in ascending order every time you call it, starting at 0x8000 and ending at 0xFFFF. It's just handing out numbers like candy 🍓
$node shape shape — sets the shape of the node to shape. If you call it before the simulator starts running, it changes the node's default shape in the nam trace file. The default shape of a node is "circle". ⭕
$node color color — sets the color of the node to color. You can call this anytime to change the node's current color in the nam trace file, if there is one. Serve looks, always 🎀
$node get-attribute name — gets the specified attribute name of the node. Right now a Node object has exactly two attributes: COLOR and SHAPE. Note: those letters must be capital, no exceptions bestie. 👑
$node add-mark name color shape — adds a mark (in the nam trace file) with the given color and shape around the node. The shape can be "circle", "hexagon" or "square" (yes, case sensitive, be careful). The added mark gets identified by name. 🖍️
$node delete-mark name — deletes the mark called name on the given node. Gone, poof, bye ✨

And that's the whole menu: there are no state variables or configuration parameters specific to the node class. Clean, minimal, iconic.

🔗 LINK OBJECTS 🔗

⚠️ NOTE: This section has not been verified to be up-to-date with the release. ⚠️

$link trace-dynamics ns fileID — traces the dynamics of this link and writes the output to the fileID filehandle. Here ns is an instance of the Simulator or MultiSim object that was created to invoke the simulation (go check the TRACE AND MONITORING METHODS section for what the output trace format looks like). 📝
$link trace-callback ns cmd — traces all packets on the link using the callback cmd. The cmd gets invoked for each trace event — that's enqueue, dequeue, and drop — with the text that would be logged as parameters. (Again, see the description of the log file for that info.) There's a whole demo of trace callbacks sitting in the program tcl/ex/callback_demo.tcl in the distribution. Go run it, it's cute 🔥
$link color color — sets the color of the Link object. Call it anytime to change the link's current color in the nam trace file, if there is one. Same energy as the node color, slay 🎨
$link get-attribute name — gets the specified attribute name of the Link. Currently a Link object has three attributes: COLOR, ORIENTATION, and QUEUE_POS. Three, not two, don't mix them up 💜

Now, lowkey important:

Currently the following two functions should not be directly called. Use $ns duplex-link-op instead. Go refer to the corresponding section in this man page. Don't be a rebel about this one 🙈

$link orient ori — sets the orientation of the link to ori. When called before the simulator starts to run, it changes the default orientation of the link in the nam trace file, if there is one. If orientation is unspecified for any link(s), nam will use automatic layout. The default orientation of a Link object is unspecified. 🧭
$link queuePos pos — sets the queue position of the link to pos. When called before the simulator starts to run, it changes the default queue placement of the simplex link in the nam trace file, if there is one. Here pos specifies the angle between the horizontal line and the line along which queued packets will be displayed. 📐

🌈 SIMPLELINK OBJECTS 🌈

⚠️ NOTE: This section has not been verified to be up-to-date with the release. ⚠️

$link cost cost-val — makes cost-val the cost of this link. Price tag acquired 🏷️
$link cost? — returns the cost of this link. Yes, with the question mark, it's asking not telling 💅

And the man page literally just asks back: Any configuration parameters or state variables? Bestie, the docs said "you tell me" 😭

⏳ DELAYLINK OBJECTS ⏳

⚠️ NOTE: This section has not been verified to be up-to-date with the release. ⚠️

So the DelayLink Objects are the ones that decide how long it takes a packet to traverse a link. The formula is:

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. Just vibes and math 🧮

Configuration Parameters

bandwidth_ — Link bandwidth in bits per second.
delay_ — Link propagation delay in seconds.

There are no state variables associated with this object. (Said it twice for emphasis, periodt.)

🎢 NETWORK DYNAMICS METHODS 🎢

This section is all about the methods that make the links and nodes in your topology go up and down according to various distributions. Plot twist central over here 🎭

A dynamic routing protocol should generally be used whenever a simulation is to be done with network dynamics. Also note that a static topology model is the default in ns. So if you didn't ask for chaos, you're getting stillness 💀

$ns rtmodel model model-params node1 [node2] — makes the link between node1 and node2 flip between up and down states according to the model model. If you only specify node1, then all the links incident on that node get brought up and down according to the specified model. The model-params holds the parameters needed for the relevant model and must be given as a list — meaning the parameters go inside curly brackets. The 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, all the way until finish-time is reached. The default values for start-time, up-interval, and down-interval are 0.5s, 2.0s, and 1.0s respectively. finish-time defaults to the end of the simulation. And why does start-time default to 0.5s? To let the routing protocol computation quiesce. Give it a sec to breathe, bestie 🫶

If the Exponential model is used, model-params looks like up-interval down-interval, where the link up-time is an exponential distribution around the mean up-interval 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, and op is one of up, down. The Manual distribution could also be specified using the rtmodel-at method described later in this section. ✋

If Trace is specified as the model, the link/node dynamics get read from a Tracefile. In that case the model-params argument would be the file-handle of the Tracefile holding the dynamics information. The tracefile format is identical to the trace output generated by the trace-dynamics link method (see the TRACE AND MONITORING METHODS SECTION). 📂

$ns rtmodel-delete model-handle — deletes the instance of the route model specified by model-handle. Say bye bye 👋
$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 — which can be either up or down — is to be performed on the specified link(s). ⏰

📦 QUEUE OBJECTS 📦

A queue object is a general class of object that can hold — and possibly mark or discard — packets as they travel through the simulated topology. Very "bouncer at the club door" energy 🚪

Configuration Parameters

limit_ — The queue size in packets.
blocked_ — Set to false by default. This is true if the queue is blocked, i.e. it's unable to send a packet to its downstream neighbor. Stuck in traffic bestie 🚧
unblock_on_resume_ — Set to true by default. This indicates a queue should unblock itself at the time the last packet packet sent has been transmitted (but not necessarily received). Important distinction, don't skip it 👀

🍃 DROP-TAIL OBJECTS 🍃

Drop-tail objects are a subclass of Queue objects that implement a simple FIFO queue. There are no methods that are specific to drop-tail objects.

The only configuration parameter is drop-front_, which — when set to true — causes the queue to behave as a drop-from-front queueing discipline. This variable is set to false by default. 🎯

⚖️ FQ OBJECTS ⚖️

FQ objects are a subclass of Queue objects that implement Fair queuing. There are no methods that are specific to FQ objects.

Configuration Parameters

secsPerByte_

There are no state variables associated with this object.

🎲 SFQ OBJECTS 🎲

SFQ objects are a subclass of Queue objects that implement Stochastic Fair queuing. There are no methods that are specific to SFQ objects.

Configuration Parameters

maxqueue_
buckets_

There are no state variables associated with this object.

🎀 DRR OBJECTS 🎀

okay so DRR objects are a subclass of Queue objects, and what they do is implement deficit round robin scheduling. The way it works: it does deficit round robin scheduling amongst different flows — and bestie, a flow is specifically packets that have the same node and port id, OR packets that have the same node id alone. iykyk

Also, and this is the iconic part — unlike other multi-queue objects, this queue object implements a single shared buffer space for its different flows. One buffer, many flows. She's generous like that. 💅

✨ Configuration Parameters ✨

buckets_ — the total number of buckets to be used for hashing each of the flows. 🍓
blimit_ — the shared buffer size, in bytes.
quantum_ — in bytes, how much each flow can send during its turn. Everybody gets their lil moment. ⭐
mask_ — when mask_ is set to 1, 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. That's the whole vibe check right there.

🔥 RED OBJECTS 🔥

RED objects are a subclass of Queue objects that implement random early-detection gateways. The object can be configured to either drop or ``mark'' packets. And ngl? There are no methods that are specific to RED objects. That's it, that's the whole method list. 💀

✨ 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. Heads up though: 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 random-drop or drop-from-front when the queue overflows or the average queue size exceeds "maxthresh_". This is the default behavior. For a further explanation of these variables, see [2].
drop-rand_ — set to true to use random-drop rather than drop-tail or drop-from-front when the queue overflows or the average queue size exceeds "maxthresh_".
drop-front_ — set to true to use drop-from-front rather than drop-tail or random drop when the queue overflows or the average queue size exceeds "maxthresh_".
ns1-compat_ — set to true to avoid resetting the count since the last packet drop, after a forced packet is dropped. This gives compatibility with previous behavior of RED. The default is set to false.
entle_ — set to true to increase the packet drop rate slowly from max_p to 1 as the average queue size ranges from maxthresh to twice maxthresh. The default is set to false, and max_p increases abruptly from max_p to 1 when the average queue size exceeds maxthresh.

👀 State Variables 👀

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

bestie. none. zero. not one. don't even try. 😭

💜 CBQ OBJECTS 💜

CBQ objects are a subclass of Queue objects that implement class-based queueing. Very classy of them, honestly. 🎀

$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. Inclusive range, no cap. 🫶
$cbq algorithm $alg — select the CBQ internal algorithm. $alg may be set to one of: "ancestor-only", "top-level", or "formal".

🌈 CBQ/WRR OBJECTS 🌈

CBQ/WRR 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. Different scheduling energy entirely. ⭐

✨ 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.

🦋 CBQCLASS OBJECTS 🦋

CBQClass objects implement the traffic classes associated with CBQ objects. So yes, they're the actual classes doing the work while CBQ runs the show. main character energy, honestly. 👑

$cbqclass setparams parent okborrow allot maxidle prio level extradelay — 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 — no cascading drama.
$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). So yeah, you gotta install one. 💅

✨ 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. Don't forget that. 🚨
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 number of seconds.

🧚 QUEUEMONITOR Objects 🧚

QueueMonitor Objects are used to monitor a set of packet and byte arrival, departure and drop counters. It also includes support for aggregate statistics such as average queue size, etc. [see TRACE AND MONITORING METHODS]. She's watching. Always watching. 👀✨

$queuemonitor reset — reset all the cumulative counters described below (arrivals, departures, and drops) to zero. Also, reset the integrators and delay sampler, if defined. Fresh start, clean slate, slay. 🎀
$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. So like… create it first bestie. 😭
$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). bye bestie 👋
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.

🌸 QUEUEMONITOR/ED Objects 🌸

This derived object is capable of differentiating regular packet drops from early drops. Some queues distinguish regular drops (e.g. drops due to buffer exhaustion) from other drops (e.g. random drops in RED queues). Under some circumstances, it is useful to distinguish these two types of drops. So this object said "I got you." 🫶

👀 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. So don't get confused — epdrops_ is just the early girls, pdrops_ is everybody. 💅

🫧 QUEUEMONITOR/ED/FLOWMON Objects 🫧

okay bestie, these are the glow-up version of a plain QueueMonitor — you slot one of these in wherever a conventional QueueMonitor would go when you want per-flow counts and statistics on top of the aggregate counts and statistics that the basic QueueMonitor already hands you. two layers of receipts, no cap 💅

$fmon classifier [$cl] — inserts (or reads) the classifier you name into (or from) the flow monitor object. this is the whole mapping situation: it's how incoming packets get sorted into the flows they belong to.
$fmon dump — dumps all the current per-flow counters and statistics out to the I/O channel you set up earlier with an attach operation. the receipts go public 📤
$fmon flows — hands you back a character string listing the names of every flow object this flow monitor knows about. every single one of those objects is of type QueueMonitor/ED/Flow.
$fmon attach $chan — attaches a tcl I/O channel to the flow monitor. flow statistics get written to that channel whenever you run the dump operation.

✨ Configuration Parameters ✨

enable_in_ — true by default, and it means per-flow arrival state gets kept by the flow monitor. set it to false and only the aggregate arrival information sticks around.
enable_out_ — true by default, and it means per-flow departure state gets kept by the flow monitor. set it to false and only the aggregate departure information sticks around.
enable_drop_ — true by default, and it means per-flow drop state gets kept by the flow monitor. set it to false and only the aggregate drop information sticks around.
enable_edrop_ — true by default, and it means per-flow early drop state gets kept by the flow monitor. set it to false and only the aggregate early drop information sticks around.

🌸 QUEUEMONITOR/ED/FLOW Objects 🌸

these little guys hold the per-flow counts and statistics, and they're managed by a QUEUEMONITOR/ED/FLOWMON object. they typically get created inside an OTcl callback procedure — specifically when a flow monitor is handed a packet it cannot map onto a known flow, so it's like "new flow, who dis" and spawns one 🦋

heads up though: the flow monitor's classifier is the one responsible for mapping packets to flows, and it does that in some arbitrary way. so depending on which type of classifier you're running, not every state variable is gonna be relevant. (like, if you classify packets based purely on flow id, then the source and destination addresses might not be significant at all. just sayin'.)

💜 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.

🌈 UNICAST ROUTING METHODS 🌈

so you can tell a dynamic unicast routing protocol to run on just a subset of the nodes in your topology. and ngl, the rule of thumb here is: if your simulation is doing network dynamics, you should generally be running a dynamic routing protocol. periodt.

$ns rtproto proto node-list — specifies the dynamic unicast routing protocol proto to run on the nodes named in node-list. right now proto can be one of Static, Session, DV. Static routing is the default. Session means the unicast routes across the entire topology get instantaneously recomputed every time a link goes up or down. DV means a simple distance vector routing protocol is what's being simulated. and node-list defaults to all the nodes in the topology.
$ns compute-routes — computes routes between all the nodes in the topology. use this when you're doing static routing and the routes have to be recomputed because a link's state changed. 👀 note that Session routing (that's the rtproto method up there) will recompute routes automatically whenever the state of any link in the topology changes — so you don't need to come knocking.
$ns get-routelogic — returns a handle to a RouteLogic object, which has methods for route table lookup and all that good stuff.

🎀 ROUTELOGIC OBJECTS 🎀

$routelogic lookup srcid destid — returns the id of the node that is the next hop from the node with id srcid to the node with id destid.
$routelogic dump nodeid — dumps 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, in their order of creation — so this is basically "everyone before this one" 💅)

⭐ RTOBJECT OBJECTS ⭐

every node that takes part in a dynamic unicast routing protocol gets an instance of rtObject — check the NODE OBJECTS section for the method that gets you a handle to this object at a particular node. but bestie, listen: nodes will not have an instance of this object if Session routing is what's happening, because a detailed routing protocol isn't being simulated in that case. no protocol, no object, simple as 🫶

$rtobject dump-routes fileID — dumps 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. otherwise you get an empty string back. 💀
$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

ngl the source page just… lists those last two with zero explanation. iconic of it honestly. all we know is they take a destID. 🙈

🦋 MULTICAST ROUTING METHODS 🦋

multicast routing gets switched on by setting the Simulator EnableMcast_ variable to 1 at the beginning of the simulation. and this is a hard requirement, okay — that variable has to be set before any node, link or agent objects are created in the simulation. also, the links must have been created with interface labels (go see the simplex-link and duplex-link methods over in the NS COMMANDS section). no shortcuts here 🚫

$ns mrtproto proto node-list — specifies the multicast routing protocol proto to run on the nodes in node-list. right now proto can be one of CtrMcast, DM, detailedDM, dynamicDM, pimDM. node-list defaults to all the nodes in the topology. it returns a handle to a protocol-specific object that has methods and configuration parameters specific to that protocol. ⚠️ heads up: currently a CtrMcastComp object is returned if CtrMcast is used, but a null string is returned if DM, detailedDM, dynamicDM or pimDM are used.

now let's break down the tea on each one, because they are not the same vibe:

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. instead, a centralized computation agent is used to compute the forwarding 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 the CTRMCASTCOMP OBJECTS section) that mrtproto returns, letting you switch to source-specific trees, choose some nodes as candidate RPs, etc. and when a node/link on a multicast distribution tree goes down, the tree is instantaneously recomputed. slay, adaptive queen ✨
if proto is DM — DVMRP-like dense mode is simulated. parent-child lists are used to cut down 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 don't lead to any group members. the prune timeout value is 0.5s by default (see the DM OBJECTS section to change the default). ⚠️ this does not adapt to network changes. there is also currently no support for proper functioning in topologies with LANs.
if proto is detailedDM — a dense mode protocol based on Protocol Independent Multicast - Dense Mode (PIM-DM) is simulated. this is currently the most complete version of the dense mode protocol in the simulator and is recommended for use over the other dense mode protocols 👑 it adapts to network dynamics and functions correctly in topologies with LANs (where LANs are created using the multi-link-of-interfaces method — see NS COMMANDS). in case there are multiple potential forwarders for a LAN, the node with the highest id is chosen as the forwarder (this happens through the Assert mechanism). the default values for the prune timeout, interface deletion timeout (used for LANs) and graft retransmission timeout are 0.5s, 0.1s and 0.05s respectively. (see the Prune/Iface/Timer, Deletion/Iface/Timer and GraftRtx/Timer objects respectively to change the default values and for more info about the timers.)
if proto is dynamicDM — a DVMRP-like dense mode protocol that adapts to network changes is simulated. 'Poison-reverse' information (that's the info that a particular neighbouring node uses this node 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 current implementation does not support proper functioning in topologies with LANs. the prune timeout value is 0.5s by default (see the 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 don't lead to any group members. ⚠️ the current implementation does not adapt to network dynamics and does not support proper functioning in topologies with LANs. the prune timeout value is 0.5s by default (see the DM OBJECTS section to change the default).

CTRMCASTCOMP OBJECTS 🎀

Okay so you get a handle to this CtrMcastComp object when you pass 'CtrMcast' as the protocol in mrtproto. That's it, that's the entry fee. 💅

$ctrmcastcomp switch-treetype group-addr — flips the whole vibe from the Rendezvous Point-rooted shared tree over to source-specific trees for the group you name in group-addr. Heads up though: this one's a one-way door, bestie — you literally cannot use this method to go back from source-specific trees to a shared tree for a multicast group. No undo button. 😭
$ctrmcastcomp set_c_rp node-list — takes every node in node-list and makes them candidate RPs, and demotes literally everyone else to not-candidate-RP status. Fun fact: all nodes are candidate RPs by default ✨. As of right now, the node with the highest node id is the one serving as the RP for all multicast groups. And you need to invoke this before any source starts sending packets to the group or any receiver joins the group. Timing is everything, fr fr.
$ctrmcastcomp get_rp node group — hands you the RP for the group as seen by node for the multicast group with address group-addr. Lowkey important detail: different nodes may see different RPs for the group if the network is partitioned, because the nodes might be sitting in different partitions. It's giving "it depends who you ask" 🦋.

DM OBJECTS 🌈

DM Objects do DVMRP-style densemode multicast, where parent-child lists are used to cut down the number of links over which initial data packets get broadcast. Think of it like trimming your group chat down to just the people who actually need the tea. 🫶

There are no methods or state variables specific to this object. Periodt.

Configuration parameters 🍓

PruneTimeout — the timeout value for the prune state at nodes.

PRUNE/IFACE/TIMER OBJECTS ⏰

These little cuties implement the prune timer for detailedDM.

There are no methods or state variables specific to this object.

Configuration parameters 🍓

timeout — the timeout value for the prune state at nodes.

DELETION/IFACE/TIMER OBJECTS 💀

The Deletion/Iface/Timer objects implement the interface deletion timer, and these are required for correct functioning at nodes that are part of LANs. Okay lemme explain the whole drama, because it's actually iconic:

If a node has a LAN as its incoming interface for packets from a certain source, and it does not have any downstream members, it sends out a prune message onto the LAN. Any node that has that same LAN as its incoming interface for the same source and has downstream members — upon hearing that prune message sent on the LAN — will send a join message onto the LAN.

Now here's the main character moment: when the node acting as the forwarder for the LAN hears the prune message from the LAN, it does not immediately prune off the LAN as its outgoing interface. Nope. Instead it starts an interface deletion timer for the outgoing interface. The forwarder will only remove the LAN as its outgoing interface if it does not receive any join messages from the LAN before its deletion timer expires. It's called ✨patience✨.

There are no methods or state variables specific to this object.

Configuration parameters 🍓

timeout — the timeout value for the interface deletion timer.

GRAFTRTX/TIMER OBJECTS 🔁

GraftRtx/Timer objects implement the graft retransmission timer at nodes. The whole point is making sure the grafts a node sends upstream actually get there — reliability girlies rise up 🙈.

Configuration parameters 🍓

timeout — the timeout value for the graft retransmission timer.

AGENT OBJECTS 👑

[NOTE: This section has not been verified to be up-to-date with the release.] — so take it with a grain of salt, bestie 🧂

$agent port — returns the transport-level port of the agent. Ports are how you tell agents apart within a node.
$agent dst-addr — returns the address of the destination node this agent is connected to.
$agent dst-port — returns the port at the destination node that this agent is connected to.
$agent attach-source type — installs a data source of type type in this agent. type is one of FTP or bursty[???]. Peep the corresponding object methods for the deets on configuration parameters. Returns a handle to the source object. 🫶
$agent attach-traffic traffic-object — attaches 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. Go look, it's all there 💅
$agent connect addr port — connects this agent to the agent identified by the address addr and port port. This makes packets transmitted from this agent contain the address and port indicated, so those packets get routed to the intended agent. The two agents must be compatible (think a tcp-source/tcp-sink pair, as opposed to a cbr/tcp-sink pair). Otherwise, the results of the simulation are unpredictable. Do not test fate, babe. 😭

Configuration Parameters 🍓

dst_ — address of the destination that the agent is connected to. Currently 32 bits, with the higher 24 bits being 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 🌸

[NOTE: This section has not been verified to be up-to-date with the release.] 🧂

Null objects are a subclass of agent objects that implement a traffic sink. They inherit all of the generic agent object functionality — the whole inheritance glow-up ✨.

There are no methods, configuration parameters or state variables specific to this object. Truly the low-maintenance bestie of the object world.

LOSSMONITOR OBJECTS 🦋

[NOTE: This section has not been verified to be up-to-date with the release.] 🧂

LossMonitor objects are a subclass of agent objects that implement a traffic sink — except this one is nosy and also keeps some statistics about the data it received, like the number of bytes received, the number of packets lost, etc. They inherit all of the generic agent object functionality. She's observant, okay? 👀

$lossmonitor clear — resets the expected sequence number to -1. Clean slate energy. 🎀

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.

💖 TCP OBJECTS 💖

TCP objects are a subclass of agent objects, and they implement the BSD Tahoe TCP transport protocol — yes, that one, the one described in [7]. They inherit literally all of the generic agent functionality, so everything the agent can do, they can do too. Bestie behavior. 🫶

Okay so if you want to trace TCP parameters, you mark each parameter with $tcp trace window_ and then you send that output off to a trace file with $tcp attach [open trace.tr w]. Cute, right?

Tcp segments can be sent with the advance and advanceby commands. When all data is sent, the done method gets invoked — and you can override that in OTcl if you're feeling spicy. ✨

$tcp advance n — Sends up to the *n*th packets.
$tcp advanceby n — Sends n more packets.
$tcp done — The function that gets called when all packets (the ones specified by advance/advanceby/maxpkts_) have been sent. You can override it on a per-object basis. 💅

🌸 Configuration Parameters 🌸

window_ — The upper bound on the advertised window for the TCP connection, measured in packets.
maxcwnd_ — The upper bound on the congestion window for the TCP connection. Set it to zero to ignore it — and fun fact, zero is the default. Measured in packets.
windowInit_ — The initial size of the congestion window on slow-start, in packets.
wnd_init_option_ — The algorithm used for figuring out the initial size of the congestion window. Set it to 1 for a static algorithm that uses the value in windowInit_. Set it to 2 for a dynamic algorithm that uses a function of packetSize_.
syn_ — Set to true to model the initial SYN/ACK exchange in one-way TCP. Set to false as default.
delay_growth_ — Set to true to delay the initial congestion window until after one packet has been sent and acked. Set to false as default.
windowOption_ — The algorithm to use for managing the congestion window in linear phase. The standard algorithm is 1, which is the default. Other experimental algorithms are documented in the source code, iykyk.
windowThresh_ — Gain constant for the exponential averaging filter used to compute awnd (see below). This one's for investigations of different window-increase algorithms.
overhead_ — The range, in seconds, of a uniform random variable used to delay each output packet. The idea is to insert random delays at the source so you can avoid phase effects when you want to [4]. Heads up though: this has only been implemented for the Tahoe (tcp) version of tcp, not for tcp-reno. And it 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.
tcpip_base_hdr_size_ — The size in bytes of the base TCP/IP header.
tcpTick_ — The TCP clock granularity for measuring roundtrip times. Note that it's set by default to the non-standard value of 100ms. Measured in seconds.
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 it. Otherwise, it's the maximum number of packets that the source can send in response to a single incoming ACK.
slow_start_restart_ — Boolean; set to 1 to slow-start after the connection goes idle. On by default.
srtt_init_ — Initial value for the smoothed roundtrip time estimate. Default is 0 seconds.
t_rttvar_ — Initial value for the variance in roundtrip time. Default is 3 seconds.
rtxcur_init_ — Initial value for the retransmit value. Default is 6 seconds.
T_SRTT_BITS — Exponent of the weight for updating the smoothed round-trip time t_srtt_. Default is 3, for a weight of 1/2^T_SRTT_BITS or 1/8.
T_RTTVAR_BITS — Exponent of the weight for updating variance in round-trip time, t_rttvar_. Default is 2, for a weight of 1/2^T_RTTVAR_BITS or 1/4.
rttvar_exp_ — Exponent of the multiple of the mean deviation in calculating the current retransmit value t_rtxcur_. Default is 2, for a multiple of 2^rttvar_exp_ or 4.

👑 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 — which represents the receiver's advertised window — should be less than MWS-1. For Reno TCP, the window parameter should be less than (MWS-1)/2.

Do not play with these boundaries, bestie. Respect the MWS math. 🙈

🦋 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 (in packets).
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 (in packets).
rtt_ — Round-trip time estimate. In seconds (expressed in multiples of tcpTick_).
srtt_ — Smoothed round-trip time estimate. In seconds (in multiples of tcpTick_/8).
rttvar_ — Round-trip time mean deviation estimate.
t_rtxcur_ — Current retransmit value. In seconds.
backoff_ — Round-trip time exponential backoff constant.

✨ TCP/RENO OBJECTS ✨

TCP/Reno objects are a subclass of TCP objects that implement the Reno TCP transport protocol as described in [7]. And get this — there are no methods, configuration parameters or state variables specific to this object. It's the low-maintenance bestie of the TCP family. 💜

💅 TCP/NEWRENO OBJECTS 💅

TCP/Newreno objects are a subclass of TCP objects that implement a modified version of the BSD Reno TCP transport protocol.

There are no methods or state variables specific to this object. Nope, none. 🙈

🌈 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.

🎀 TCP/VEGAS OBJECTS 🎀

This section of the man page has not yet been written. (Not me leaving a whole section blank 💀 — the original really does say that.)

🧚 TCP/SACK1 OBJECTS 🧚

TCP/Sack1 objects are a subclass of TCP objects that implement the BSD Reno TCP transport protocol with Selective Acknowledgement Extensions as described in [7].

They inherit all of the TCP object functionality. And there are no methods, configuration parameters or state variables specific to this object. Zero notes. Immaculate. ⭐

🔥 TCP/FACK OBJECTS 🔥

TCP/Fack objects are a subclass of TCP objects that implement the BSD Reno TCP transport protocol with Forward Acknowledgement congestion control.

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 the congestion window rather than instantly halving it. (1=Enable, 0=Disable)

🌸 TCP/FULLTCP OBJECTS 🌸

This section has not yet been added to the man page. The implementation and the configuration parameters are described in [11]. So like, go read [11], bestie. 📚

💖 TCPSINK OBJECTS 💖

TCPSink 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. TCPSink objects inherit all of the generic agent functionality. There are no methods or state variables specific to the TCPSink object — it just sits there, receiving and acking, main character energy honestly. 👑

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

That last part is a hard no. Allocate first, regret later. You can only go down, never up. 😭

🦋 TCPSINK/DELACK OBJECTS 🦋

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

⭐ 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. Impatient king behavior. 💅

🌈 TCPSINK/SACK1 OBJECTS 🌈

TCPSink/Sack1 objects are a subclass of TCPSink that implement a SACK receiver for TCP packets. They inherit all of the TCPSink object functionality. There are no methods, configuration parameters or state variables specific to this object.

Literally nothing extra. It's giving "I just work here" and honestly? Iconic. ✨

🌸 TCPSINK/SACK1/DELACK OBJECTS 🌸

TCPSink/Sack1/DelAck objects are a subclass of TCPSink/Sack1 that implement a delayed-SACK receiver for TCP packets, bestie. They inherit all of the TCPSink/Sack1 object functionality. And here's the thing — there are no methods or state variables specific to this object. She's just vibing off her parent class. 💅

⚙️ Configuration Parameters ⚙️

interval_ — the amount of time to delay before generating an acknowledgment for a single packet. But plot twist 🫢 — if another packet arrives before this time expires, generate an acknowledgment immediately. No waiting around, she's ready.

💖 SRM OBJECTS 💖

SRM objects are a subclass of agent objects that implement the SRM reliable multicast transport protocol. They inherit all of the generic agent functionalities, no cap.

$srm traffic-source source — attach a traffic source, e.g., Application/Traffic/CBR, to the SRM agent. 🚗
$srm start — join the multicast group, start the SRM agent <em>and</em> its attached traffic source. it's giving main character energy 👑
$srm delete — stop the SRM agent, delete all its status and detach the traffic source. bye bestie 👋
$srm trace trace-file — write the traces generated by the SRM agent to trace-file. 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. lowkey so handy 🧚

⚙️ Configuration Parameters ⚙️

packetSize_ — the data packet size in bytes 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. Measured in seconds; default value is 1.0 seconds.
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.

🦋 SRM/Adaptive OBJECTS 🦋

SRM/Adaptive objects are a subclass of the SRM objects that implement the adaptive SRM reliable multicast transport protocol. They inherit all of the SRM object functionalities, periodt.

🔮 State Variables 🔮

Refer to the SRM paper by Sally et al ([11]) for more detail, bestie.

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.

🎀 APPLICATION OBJECTS 🎀

Application objects generate data for transport agents to send. they're the content creators fr fr ✨

🍓 FTP APPLICATION OBJECTS 🍓

Application/FTP objects produce bulk data for a TCP object to send.

$ftp start — causes FTP to produce packets indefinitely. 💀
$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 an Application/FTP object to agent.
$ftp producemore count — causes the Application/FTP object to produce count more packets.

⚙️ Configuration Parameters ⚙️

maxpkts — the maximum number of packets generated.

🧚 TELNET APPLICATION OBJECTS 🧚

Application/Telnet objects produce individual packets with inter-arrival times as follows. If interval_ is non-zero, then inter-arrival times are chosen from an exponential distribution with average interval_. If interval_ is zero, then inter-arrival times are chosen using the "tcplib" telnet distribution. slay 🌈

$telnet start — causes the Application/Telnet object to start producing packets.
$telnet stop — causes the Application/Telnet object to stop producing packets.
$telnet attach agent — attaches a Application/Telnet object to agent.

⚙️ Configuration Parameters ⚙️

interval_ — the average inter-arrival time in seconds for packets generated by the Application/Telnet object.

🌈 TRAFFIC OBJECTS 🌈

Traffic objects create data for a transport protocol to send. A Traffic object is created by instantiating an object of class Application/Traffic/type where type is one of Exponential, Pareto, CBR, Trace. pick your fighter 💅

💜 EXPONENTIAL TRAFFIC OBJECTS 💜

Application/Traffic/Exponential objects generate On/Off traffic. During "on" periods, packets are generated at a constant burst rate. During "off" periods, no traffic is generated. Burst times and idle times are taken from exponential distributions.

⚙️ 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.

🌸 PARETO TRAFFIC OBJECTS 🌸

Application/Traffic/Pareto objects generate On/Off traffic with burst times and idle times taken from pareto distributions.

⚙️ 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.

⭐ CBR (CONSTANT BIT RATE) TRAFFIC OBJECTS ⭐

Application/Traffic/CBR objects generate packets at a constant rate. Dither can be added to the interarrival times by enabling the "random" flag.

⚙️ Configuration Parameters ⚙️

rate_ — peak rate in bits per second.
packet_size_ — the packet size in bytes.
random_ — flag that turns dithering on and off (default is off).
maxpkts_ — maximum number of packets to send.

🔥 TRACE TRAFFIC OBJECTS 🔥

Application/Traffic/Trace objects are used to generate traffic from a trace file.

$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 Application/Traffic/Trace objects can be attached to the same Tracefile object. A random starting place within the Tracefile is chosen for each Application/Traffic/Trace object. 🎲

There are no configuration parameters for this object.

🫶 TRACEFILE OBJECTS 🫶

Tracefile objects are used to specify the trace file that is to be used for generating traffic (see TRAFFIC/TRACE OBJECTS section). $tracefile is an instance of the Tracefile 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. iconic format tbh 📼

🌈 TRACE AND MONITORING METHODS 🌈

💀 NOTE: this section has not been verified to be up-to-date with the release. bestie, take it with a lil grain of salt ok?

So. Trace objects are the ones that make event level capture logs, usually dumped into an output file. Throughout this whole section, $ns means a Simulator object and $agent means an Agent object. 🫶

$ns create-trace type fileID node1 node2 [option] — makes a Trace object of type type and attaches the filehandle fileID to it so it can watch the queues between nodes node1 and node2. type can be one of Enque, Deque, Drop. Enque watches packets arriving at a queue. Deque watches packets leaving a queue. Drop watches packets getting dropped at a queue. 💀 fileID has to be a file handle that the Tcl open command gave you, and it must have been opened for writing. If option isn't given, the command tells the new trace object to generate ns traces. If option is "nam", the new object produces nam traces instead. Returns a handle to the trace object. ✨
$ns drop-trace node1 node2 trace — removes the trace object attached to the link between nodes node1 and node2, using trace as the object handle.
$ns trace-queue node1 node2 fileID — turns on Enque, Deque and Drop tracing on the link between node1 and node2.
$ns namtrace-queue node1 node2 fileID — literally the same job as $ns trace-queue, except it makes nam traces instead.
$ns trace-all fileID — turns on Enque, Deque, Drop tracing on all the links in the topology created after this method gets invoked. Also turns on tracing of network dynamics. fileID has to be a file handle from the Tcl open command and must have been opened for writing. 💅
$ns namtrace-all fileID — same function as $ns trace-all, except it produces all the equivalent traces in nam format. Bonus: calling this before the simulator starts running generates the color configurations (if there are any) and the topology info nam needs (nodes, links, queues). An example lives at ns-2/tcl/ex/nam-example.tcl. 👑
$ns namtrace-config fileID — assigns a file to store nam configuration info, like node/link/agents and some Simulator-related traces such as annotations. When you don't want to trace every single object, call this function and then use $ns namtrace-queue, rtModel trace, etc., to insert traces individually. Note that you should use the same file for individual traces and nam configuration. An example for this is available at ns-2/tcl/ex/nam-separate-trace.tcl. 🌸
$ns monitor-queue node1 node2 — arranges for the queue length of the link between nodes node1 and node2 to be tracked. Returns a QueueMonitor object that you can query to learn average queue size etc. [see the QueueMonitor Objects section 💖]
$ns flush-trace — flushes the output channels attached to all the trace objects.
$link trace-dynamics ns fileID [option] — traces the dynamics of this link and writes the output to the fileID filehandle. ns here is an instance of the Simulator or MultiSim object that was created to invoke the simulation.
$ns color id name — creates a color index, which links the number id to the color name name. All colors created before the simulator starts to run get written to the nam trace file, if there is any. 🎀
$ns trace-annotate string — writes an annotation to the ns and nam trace file, if there are any. The string should be wrapped in double quotes so it counts as a single argument.
trace_annotate string — another version of $ns trace-annotate, but it's a global function so the caller doesn't need to know about ns. 🦋
$ns duplex-link-op $node1 $node2 $op $args — performs a given operation $op on the given duplex link ($node1, $node2). The following two operations may be used:
- orient — specifies the nam orientation of the duplex link. Values can be left, right, up, down, their mixture combined by - (e.g., left-down), and a number specifying the angle between the link and the horizontal line.
- queuePos — constructs a queue of the simplex link ($node1, $node2) in nam, and specifies the angle between the horizontal line and the line along which the queued packets will be displayed.
$ns add-agent-trace agent name [fileID] — writes a nam trace line which, when interpreted by nam, creates a trace agent for agent. The trace agent's name will be name. This nam trace agent is used to show the position of the agent and can be used to write nam traces of variables associated with the agent. By default traces get written to the file assigned by namtrace-all. fileID can be used to write traces to another file. 🌟
$agent tracevar name — labels OTcl variable name of $agent to be traced. Then whenever the variable name changes value, a nam trace line gets written to the nam trace file, if there is one. Note that name must be the same as the variable's real OTcl name. 👀
$ns delete-agent-trace agent — writes a nam trace line which, when interpreted by nam, deletes the nam trace associated with agent.
$agent add-var-trace name value [type] — writes a nam trace line which, when interpreted by nam, creates a variable trace with name name and value value. type says what kind of variable it is, e.g. is it a list, an array, or a plain variable. Currently only plain variable is supported, for which type = 'v'. 💜

The following 2 functions should be called after the simulator starts running. You can do that with $ns at. ⏰

$agent delete-var-trace name — writes a nam trace line which, when interpreted by nam, deletes the variable trace name.
$agent update-var-trace name value [type] — writes a nam trace line which, when interpreted by nam, changes the value of the traced variable name. Unlike $agent tracevar, the above 3 functions give you 'manual' variable tracing, where the tracing is done by dropping $agent update-var-trace into OTcl code — whereas tracevar automatically generates nam traces whenever the traced variable changes value. 🔥

The tracefile format is backward compatible with the output files from the ns version 1 simulator, so ns-1 post-processing scripts still work. no cap. 🫡 Trace records of traffic for link objects with Enque, Deque or Drop Tracing look like this:

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

where

       <code> := [hd+-r] 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, so this field may not be useful for packets generated by some agents. 🤷

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

                     <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 look like:

                     <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 Objects 🧮

Integrator Objects support the approximate computation of continuous integrals using discrete sums. The running sum (integral) is computed as:

sum_ +=  [lasty_ * (x - lastx_)]

where (x, y) is the last element entered and (lastx_, lasty_) was the element previous to the one added to the sum. lastx_ and lasty_ get updated as new elements come in. The first sample point defaults to (0,0), which you can change by changing the values of (lastx_,lasty_). ✨

$integrator newpoint x y — adds 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 Objects 📊

Samples Objects support the computation of mean and variance statistics for a given sample. 💖

$samples mean — returns the mean of the sample.
$samples variance — returns the variance of the sample.
$samples cnt — returns a count of the sample points considered.
$samples reset — resets the Samples object so it monitors a fresh set of samples.

There are no configuration parameters or state variables specific to this object.

🛠️ BUILTINS 🛠️

💀 NOTE: this section has not been verified to be up-to-date with the release either, bestie.

Because OTcl is a whole entire full-fledged programming language, it's easy to build high-level simulation constructs out of the ns primitives. Several library routines have been built exactly this way, and they're embedded right into the ns interpreter as methods of the Simulator class. Throughout this section $ns means a Simulator object. 👑

$ns create-connection srcType srcNode dstType dstNode class — creates a source agent of type srcType at node srcNode and connects it to a destination agent of type dstType at node dstNode. It also connects the destination agent to the source agent. The traffic class of both agents gets set to class. This method returns the source agent. 🎀

🌈 EXAMPLE 🌈

okay bestie, here's a whole lil simulation you can literally just run, no cap:

set ns [new Simulator]

#
# 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

so what's happening here, in group-chat terms 💅 — we make a Simulator, we make two nodes, we open out.tr and pipe every link's trace events into it with trace-all, then we wire n0 and n1 together with a 1.5Mb link, 10ms delay, DropTail queuing (FIFO, babe). then two Agent/TCP sources facing two Agent/TCPSinks, connected crosswise, each with an FTP source riding on top. ftp1 goes at time 0.0, ftp2 waits a whole second like the drama queen she is, and at time 10.0 we say exit 0 and run the whole thing. iconic behavior honestly. ✨

🐛 DEBUGGING 🐛

wanna see what's going on under the hood when you build ns from source? turn on debug mode like this:

% ./configure --enable-debug
% make

that's it, that's the whole recipe bestie. if you're the type who needs the full lore on ns debugging, go look at <http://www-mash.cs.berkeley.edu/ns/ns-debugging.html>. 🫶

🦋 DIFFERENCES FROM NS-1 🦋

ngl the whole glow-up here is about composability. in ns-1, the objects were big chunky blobs; in ns-2 they got broken down into simpler components so you can mix and match with way more flexibility. main character energy fr. the full rundown of what changed between ns-1 and ns-2 lives at <http://www-mash.cs.berkeley.edu/ns/ns.html>. 💖

📜 HISTORY 📜

okay storytime, because this is genuinely a little beautiful 😭

work on the LBL Network Simulator started in May 1990, with modifications to S. Keshav's (keshav@research.att.com) REAL network simulator, which he built for his Ph.D. work at U.C. Berkeley. then in Summer 1991 the simulation description language got a whole revamp, and later the NEST threads model got swapped out for an event driven framework and an efficient scheduler. glow-up era. ✨

among other contributions, Sugih Jamin (jamin@usc.edu) brought the calendar-queue based scheduling code to this version of the program, which at the time was known as tcpsim. then in December 1994, McCanne ported tcpsim to C++ and replaced the yacc-based simulation description language with a Tcl interface, plus added preliminary multicast support. and also at that time the name changed from tcpsim to the more generic ns. rebrand of the century honestly.

throughout all of this, Floyd was making modifications to the TCP code and adding 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/. periodt. 👑

👀 SEE ALSO 👀

Tcl(1)
tclsh(1)
nam(1)
otclsh

and now the reading list, because we're scholarly AND cute 📚✨

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.
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://www-nrg.ee.lbl.gov/floyd/red.html.
Floyd, S. Simulator Tests. July 1995. URL ftp://ftp.ee.lbl.gov/papers/simtests.ps.Z.
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.
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.
Floyd, S., Notes of Class-Based Queueing: Setting Parameters. URL ftp://ftp.ee.lbl.gov/papers/ params.ps.Z. September 1995.
Fall, K., and Floyd, S. Comparisons of Tahoe, Reno, and Sack TCP. December 1995. URL ftp://ftp.ee.lbl.gov/papers/sacks.ps.Z.
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>.
M. Shreedhar and G. Varghese. Efficient Fair Queueing Using Deficit Round Robin. In Proc. of SIGCOMM, pp. 231-242, 1995.
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.
Fall, K., Floyd, S., and Henderson, T., Ns Simulator Tests for Reno FullTCP. URL ftp://ftp.ee.lbl.gov/papers/fulltcp.ps. July 1997.
Floyd, S., Jacobson, V., Liu, C.-G., McCanne, S. and Zhang, L., A Reliable Multicast Framework for Light-weight Sessions and Application Level Framing. To appear in IEEE/ACK Transaction on Networking, November 1996. ftp://ftp.ee.lbl.gov/papers/srm1.ps.gz
Fall, K., and Varadhan, K., (eds.), "Ns notes and documentation", work in progress. http://www-mash.cs.berkeley.edu/ns/nsDoc.ps.gz

research using ns is on-going, bestie. a list of recent research contributions employing ns can be found at <http://www-mash.cs.berkeley.edu/ns/ns-research.html>.

work on ns is on-going. information about the most recent version is available at <http://www-mash.cs.berkeley.edu/ns/ns.html>.

a mailing list for ns users and announcements is also available — send mail to ns-users-request@mash.cs.berkeley.edu or ns-announce-request@mash.cs.berkeley.edu to join. questions should be forwarded to ns-users; ns-announce will be low-traffic announcements only. (so like, don't spam the announcement list, we're begging 🙈)

💜 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.

a complete list of contributors to ns is at <http://www-mash.cs.berkeley.edu/ns/ns-contributors.html>. the group project of the century, no cap. 👑

💀 BUGS 💀

not all of the functionality supported in ns-1 has been ported to ns-2. (yes, for real. some stuff just didn't make the move. 😭)
this manual page is incomplete. (they said it, not me!! 🫣)

and that's a wrap on the whole NS(1) page, bestie!! 🌸 the version you just read is dated 25 July 1997, and it's the good old NS(1) man page from the ns source tree — so go forth, build a network, break it, trace it, and slay. 🦋✨ mwah! 💅

📦 where this page comes from

debian bookworm: ns2 2.35+dfsg-5
debian trixie: ns2 2.35+dfsg-9
ubuntu jammy: ns2 2.35+dfsg-3.1
ubuntu noble: ns2 2.35+dfsg-5build2
ubuntu questing: ns2 2.35+dfsg-9
ubuntu resolute: ns2 2.35+dfsg-9build1
ubuntu stonking: ns2 2.35+dfsg-9build1
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-13: a language model's rewrite of the original, under its terms