The Network Simulator ns-2 at Boston Univeristy CS Dept.: Frequently Asked Questions (or To-be-FAQ)

Notes and Recent Changes:

• NOTE for new users!!!

If you are a new ns user, you should feel lucky, because begining this year (2002), the  NS simulator source tree has been neatly organized to make it more readable. So if you have never touched NS, you should use the new NS version which is available at the director /research/ns/ns-new instead of /research/ns/ns-2 as stated below. And for the dup configuration file (again see below), you should use dup.conf-nsnew instead of dup.conf-sample as a sample. The command for executing NS is newns instead of ns. I apologize if you feel confused, but I do suspect that the change of ns directory structure is not totally finish yet, so I intentionally delayed the merging of the two versions.

If you are an old customer, feel free to use any version. The new version is slightly better than the old one (less than 2 months older) in that it uses a better scheduler (due to a SIGCOMM'01 paper) for simulation purpose and some changes in TCP and RED code to enhance performance.

• Most Recent Changes:
• Ns upgraded to ns-2.1b9 (latest daily snapshot 09/19/2002), updated sample dup configuration files
• TCP and SNOOP protocol bug fixing
• Ns upgraded to ns-2.1b9 (latest daily snapshot 04/25/2002), updated sample dup configuration files
• Optimized for Linux platform.
• Installed latest version of NS (daily snapshot 01/27/2002), updated sample dup configuration files
• Optimized for Linux platform.

• Reminder:
• BU_NS is available on research clusters (whales), so if you can login onto any Linux machines that belong to the research cluster, you should be able to use it.
  

Frequently Asked Questions:

• What is NS simulator?

Ns is a discrete event simulator targeted at networking research. Ns provides substantial support for simulation of TCP, routing, and multicast protocols over wired and wireless (local and satellite) networks. For more information, please visit the official website at: http://www.isi.edu/nsnam/ns


• Where can I get access to NS from BU CS lab?

The latest version (NS daily-snapshot 09/19/2002 and 11/29/2001, will be updated every 4-5 months) of NS is installed in BU CS Research Cluster (a.k.a. whales). The cluster included several PC's with BU Linux installed (greed, gluttony, anger, pryde, and sloth ). BU_NS is compiled under Linux, so you'd better to use it under Linux.


• What kind of stuff do we have?

We are trying our best to include every possible feature of NS in our version, here is the list of what we have now:
• latestNS (version 2.1 beta 9, daily snapshot 04/25/2002). Enriched wireless protocols and simulation scenario.
• latestNS (version 2.1 beta 9, daily snapshot 11/29/2001). So it should have less number of bugs and more functionalities than the stable version (2.1b8).
• NAM 1.11 (daily snapshot 04/25/2002)

Nam is a Tcl/TK based animation tool for viewing network simulation traces and real world packet traces. It supports topology layout, packet level animation, and various data inspection tools.
• tcl-debug (version 2.0) (compatible with tcl8.3)

tcl-debug is a debugging tool for tcl scripts. It's extremely useful when you have no idea where the problems come from. For tcl-debug usage, please visit the official website at: http://expect.nist.gov/tcl-debug/
• xgraph (version 12.1)

Convert trace data to graphical plot, similar to gnuplot
• gt-itm (stable version)

The Georgia Tech Internet Topology Models , probably we should also include BRITE here.
• sgb2ns conversion program

The tool for converting sgb format graphs (e.g. large topology generated by gt-itm) to NS-friendly input.
• ns_ds (obsolete, now ns has the full funcitonality) (latest version 10/05/2000)

NS with Differentiated Services enabled, contributed by Nortel Network Advanced IP Networks group.

If you need some other modules (e.g., more wireless support, link-state routing, etc.), please notice that these modules are available at NS official site as contributed modules. In other words, they are not stable and may not be compatible with the lastest version of NS. However, you are always welcome to contribute your runnable versions to BU_NS.


• What do I need to do to run NS?

NS is probably the most user-unfriendly software in this world, so please don't get mad if the following steps don't work quite well. I'm also assuming that you have access to the Linux clusters. SSH access is strongly recommended because it supports X sessions:
• First you need to properly set your $PATH and $LD_LIBRARY_PATH environment variables. So if you are using csh or tcsh, do something like this (% means prompt sign, you can also put this in your .cshrc or .tcshrc files):
% setenv PATH /research/ns/bin:$PATH
% setenv LD_LIBRARY_PATH \
/research/ns/otcl-1.0:/research/ns/tcl8.3.4/unix:/research/ns/tk8.3.4/unix:$LD_LIBRARY_PATH
If you are using sh or bash, then do the following (and also in your .profile or .login file):
% PATH=/research/ns/bin:$PATH
% LD_LIBRARY_PATH=/research/ns/otcl-1.0:/research/ns/tcl8.3.4/unix:/research/ns/tk8.3.4/unix:$LD_LIBRARY_PATH
Of course you need to export all of these variables if you are under sh or bash.
• (This step is strongly recommended but not required) Build a special directory for running ns program, since most ns code will generate some extremely large trace files, which might become garbage later. So do something like this:
% mkdir ns-for-fun
• Now you are ready to use ns and nam. NS source code provides hundreds of example code on usage of different modules. All of them are under directory /research/ns/ns-2/tcl/ex/. For example, you can try this out:
% cd ns-for-fun
% cp /research/ns/ns-2/tcl/ex/simple-dyn.tcl .
% ns simple-dyn.tcl
Now you should get some output like this in your terminal:
210
0.001
v 2.5 link-down 0 1
v 3.5 link-up 0 1
v 5.5 link-down 0 1
v 6.5 link-up 0 1
running nam...
And there's a small window with two node and one link in it shows up. This is what nam animator gives you. Press the play button, then you will be able to observe a animated network simulator showing how packets are transmitted over a crapy link (sometimes it breaks down so the link becomes red).
• I've barely heard of/never used/never heard of ns, and I don't know what the hell these numbers and animations are. Is there any good tutorial available?

Yes, there are some. I recommend the one written by Marc Greis . These numbers and animations should look more friendly after a tourney throughout the tutorial. Also there's an on-line multimedia tutorial available at UMASS which has a more detailed introduction on using and hacking ns.

• I'm an experienced user of NS, and I want to do some hacking jobs, can this shared NS environment support it?

Indeed it can. One of the NS maintainers (Haobo Yu) had written a perl code called dup for doing this. What you need to do is to download this file and modify the configuration file. This include two parts: to create symbolic links to those files that you want to get from original NS, and to tell Makefile which files are your contributed code. Then run dup, it will generate Makefile in your working directory for making your speical-flavored version of NS. One thing you need to keep in mind is that the configuration file ".dup.conf-<program>" must be put in your home directory instead of your working directory. It should be straightforward to modify dup to remove this requirement, so I won't spend time on explaining that :).
Also, please read dup program and README file carefully before you really start to run it.

Ok, let's do an example, you should be able to find a sample configuration file dup.conf-sampleunder /research/ns/bin . What it does is trying to replace the files /research/ns/ns-2/tcp.cc and /research/ns/ns-2/tcl/lib/ns-lib.tcl with own-written /research/ns/bin/dupexample/tcp.cc and /research/ns/bin/dupexample/ns-lib.tcl file.
The example layout of the modified files tcp.cc and ns-lib.tcl are given under /research/ns/bin/dupexample directory. And then you should do this:

% cp /research/ns/bin/dup.conf-sample ~/.dup.conf-tcpsample
% cd
% mkdir myns
% dup tcpsample myns changetcp
Note, for the last command dup arg1 arg2 arg3, arg1 is the suffix of the dup conf file (e.g., arg1=xxx for .dup.conf-xxx), arg2 is the directory you want to link ns to. In .dup.conf-xxx file, there should be one (or many) line contains "NAME" => "zzz", which is the entry for the configuration file. And "zzz" will be arg3 in the dup command. Now you have a myns directory which looks exactly the same as /research/ns/ns-2. In other words, it looks as if you'd downloaded ns-2.1b9 package and untarred it in your ~/myns directory except now you have your own tcp.cc and ns-lib.tcl file. So now you have to do configure and make, a simple sample script file is available at /research/ns/bin/install_myns , it assumes that you did dup to myns directory:
% cd ~/myns
% /research/ns/bin/install_myns
% mv ~/myns/ns ~/bin/myns
Now you have two version of ns, one is the general version which is called "ns", another is your own version called "myns" which carries more colorful and powerful (I hope) features.

(Please be noted that the sample file given in haoboy's package is a little bit outdated, the one under /research/ns/bin/ is better in this sense).


(Please also be noticed that the all the modified files must be put under the same directory (like what we did in /research/ns/bin/dupexample directory. Then you specify where to link them in your dup configuration file. It's a bit wried but that's how the dup program is designed.

As mentioned in the top of this page, for new version of ns (ns2002) the example dup configuration file is given in dup.conf-nsnew. And a file called dup.conf-contrib is given to show how to add contributed code.



• What if I want to add some contributed code?

Well, you need to go through a little more painful step. That's right, you need to create a new Makefile. The easiest way to do it, IMHO, is to copy /research/ns/ns-2/Makefile.in to your source directory (again let's assume it is under ~/research/changetcp). Let's assume you've created two new files, namely tcp-foo.cc and tcl/foo-bar/tcp-bar.tcl, then you need to add tcp-foo.o (tcl/foo-bar/tcp-bar.tcl ) in the group of files defined by OBJ_CC  (NS_TCL_LIB) variables in Makefile.in . You also need to change the dup configuration file. Basically remove the entry Makefile.in from SRCFILES and add it to MYSRCDIR . Now you should be all set. Again a sample configuration file dup.conf-contrib is provided under /research/ns/bin to reflect these changes.
 

• How can I debug ns?

The default installation of BU_NS has debugging option turned off, and is optimized through Tom Kelly's ns for linux patch , which is said to be able to enhance the speed by up to 50%. To enable debug, try to dup a local copy as illustrated in the previous answer. Then instead of using /research/ns/bin/install_myns, use the script /research/ns/bin/install_dbg_ns . Now you have a copy of ns that is debuggable. Use tcl-debug for debugging tcl code, and any kind of c-debugger you prefer (e.g. gdb, ups) for finer grained debugging.


• What if I have a question that's not answered here?

This webpage only provides information on using and possibly hacking ns installed in Boston University CS Department Linux Cluster. A more detailed FAQ, troubleshooting, etc. can be accessed at NS official website . You can also send your questions to NS Mailing List .


• Is there a mailing list for BU_NS?

There's no mailing list at this time, but there should be one soon. However, here are some rules you need to keep in mind once you join in this community.
The BU_NS mailing list etiquette (directly copied from NS mailing list ):
• Please check the web pages and list archives before posting your question.
• Please keep the body of your post to simple ASCII, not HTML.
• Before posting a question like "did people see my post" or "the list seems down", please check the archives.
• Please don't post subscribe/unsubscribe requests directly to the list, send them to ns-users-REQUEST@isi.edu.


• Related Links
• NS official website .
• Tutorial by Marc Greis .
• NS Tutorial at WPI .
• The Network Simulator: Contributed Code .
• Quality of Service Routing extensions to ns-2 .