VINT/SAMAN/CONSER Conventions

Mailing Lists

• saman-conser for SAMAN/CONSER specific stuff (it is a replacement for the old vint and vint-usc lists)
• ns-developers for ns and nam design/development mail
• ns-developers-cvs only for automated announcements bout ns and nam cvs commits
• ns-announce ns and nam important announcements (like releases)
• ns-edu educational use of ns and nam
• ns-users public discussion list for ns and nam

These lists are subscribed to via their mailman information pages.

Quick Start -- All you need to do

• Get SSH (v2) working:
  • If you don't already have a ssh v2 public/private key pair, do this:

    
    		ssh-keygen -t dsa
    	

  • This will generate the following two files:

    
    		~/.ssh/id_dsa
    		~/.ssh/id_dsa.pub
    	

  • You need to supply the id_dsa.pub file to the person providing accounts on nsnam.isi.edu. (currently, [email protected]). He/she will install this file into your account on nsnam.isi.edu:

    
    		~/.ssh/authorized_keys2
    	

    This serves as an ACL on your account. Any (public) keys listed in this file will be able to use/access your account without a password. This will be very handy for cvs.

  • To verify all worked properly, the following command should work from your computer:

    
    		ssh nsnam.isi.edu date
    	

  • If you local login name differs from the one you have at ISI, you may have to do this:

    
    		ssh nsnam.isi.edu -l username date
    	

• Get the files you need from CVS:
  • Make a working directory to hold the source directories:

    
    		cd
    		mkdir WORK
    		cd WORK
    	

  • First, you will need to obtain OTcl and TclCL, which have been moved to a SourceForge project.

    Complete instructions for retrieving the source from CVS can be found on SourceForge. If you are registered as a project developer, you may use SSH to check out the project. Otherwise, you can use the anonymous CVS access to obtain a copy.

  • Next, you will need to get ns along with anything else you need, such as nam or xgraph.

    The first step is to set some environment variables. You need these:

    
    		CVSROOT=username@nsnam.isi.edu:/nfs/jade/vint/CVSROOT
    		CVS_RSH=ssh
    
    		username is your login name at ISI on nsnam.isi.edu
    	

  • Check out ns:

    		cvs checkout ns-2
    	

  • Check out others you may want:

    		cvs checkout nam-1
    		cvs checkout xgraph
    		cvs checkout conf
    		cvs checkout www
    	

• Build otcl:
  • First, you need the *sources* for tcl/tk. This is because the file otcl.c needs to include tclInt.h (a file used internally by the tcl code).
  • Here's an example from RedHat Linux 7.1 (you will need the source RPM CD or file):

    
    		rpm -i tcltk-8.3.1-53.src.rpm
    		cd /usr/src/redhat/SOURCES
    		tar --bzip -xvf tcl8.3.1.tar.bz2
    
    	

    This places the tcl/tk source tree into the following place:

    
    		/usr/src/redhat/SOURCES/tcl8.3.1
    	

  • Now, build otcl, telling it where to find the include file:

    
    		cd otcl
    		./configure --includedir=/usr/src/redhat/SOURCES/tcl8.3.1/generic
    
    	

    This should have produced the following files: libotcl.{a,so} (depending on your system)

• Build tclcl:
  • This is easy once otcl is built. Just do this:

    		cd ~/WORK/tclcl
    		./configure
    		make
    	

  • This should have produced the following files:

    		libtclcl.a
    	

• Build ns-2:
  • This is also easy once otcl and tclcl are built. Just do this:

    		cd ~/WORK/ns-2
    		./configure
    		make
    	

• Running various programs:
  • For NS, you may need to do the following in order to help it find its dynamic library. Assuming you used a WORK directory, do this:

    
    		LD_LIBRARY_PATH=$HOME/WORK/otcl
    	

CHANGES.html

What is a medium-sized change? A judgement call. Simple bug fixes aren't (the Makefile had an extra .o in OBJS and was breaking, I fixed it). Larger bug fixes are (the tahoe TCP module produced wrong results in a particular case). New features certainly are (multicast code is now present). If in doubt, ask someone.

Before Committing Changes to CVS

Before commiting changes to ns, you should always run the validation test suites (run "./validate" in the top-level ns directory). Since ns is a large and complex piece of software it's critical to locate bugs early.

This applies to even "obviously correct" one-line changes. All too frequently there's a minor error that slips through and someone else has to fix it.

CVS

All of the vint-related project code is stored in a cvs repository under the sub-directories "common" and "vint". Normally, you won't need to worry about path names in the repository and instead will just refer to "module nicknames".

To access the repository, set your environment as follows:

	setenv CVSROOT username@nsnam.isi.edu:/nfs/jade/vint/CVSROOT
	setenv CVS_RSH ssh

For CVS documentation, see

• CVS info pages
• complete CVS documentation and reference material

You can issue normal cvs commands just as if the repository were local. Here are some hints:

• To checkout the ns-2 source tree, run:

  	cvs checkout ns-2
  

  This will create a directory called "ns-2" in your current directory. It will also automatically unpack the "conf" module into "ns-2/conf. This is where you find all the autoconf configuration scripts that are shared across several of our projects. Now that you have a working ns-2 directory, you can edit your local copy.

• At any time check the status of a file with:

  	cvs status filename
  

  or a directory:

  	cvs status .
  

• You can also diff your changes relative to the tree that you checked out:

  	cvs diff file
  

  or

  	cvs diff
  

  to run diff over the whole tree.
  However, note that these diffs are only relative to the version you have currrently checked out. If you wish to see diffs relative to the most recent versions, you should use the "-D" option described next.

• A real handy option is "-D". This let's you specify dates in user-friendly formats. So you can say something like:

  	cvs diff -D "last week"
  

  or

          cvs diff -D now
  

  or

  	cvs checkout -D "one hour ago"
  

• Once you are happy with your changes, you can "commit" them back to the repository. Run the following command in the top-level directory (e.g., the ns-2 directory that you originally created):

  	cvs commit
  

• You can safely update your copy of the tree with:

  	cvs update
  

  This pulls all the files in that other users have modified but you have not. If there is a file that has been modified and committed by another use, "update" will warn you about the conflicts. Further, it will add conflict markers in the relevant files. The conflict markers are three lines of the form,

          <<<<<<<
              block 1, present in your working copy
          =======
              block 2, currently in the repository
          >>>>>>>

  separating out the two blocks of code that led to the conflict. Block 1 is the version you had in your working directory, while block 2 is the version that is currently in the repository. You can choose either block, or completely replace both blocks with a new block of code. In any case, you must resolve the conflict, and remove all conflict markers before you commit your changes. CVS will refuse to commit a file that has conflict markers at the start of a line.

• You can remove a file from the tree as follows:

  	rm file
  	cvs remove file
  

  You then need to run "cvs commit" to actually commit the removal to the repository.

• To add a new file, create it somewhere in the source tree. Beware that you should not have two filenames in the same directory that only differ in case, as some file systems don't distinguish between uppercase and lowercase letters. Issue

  	cvs add file
  

  to add it to the CVS repository. If you have a binary file, don't forget to add the binary flag:

      cvs add -kb binary_file
  

  Again, you must use "cvs commit" to actually push it to the repository. You should also add the file to the FILES file (although someday this may be done automatically).

• Don't try to put symbolic links in the repository. You have to instead create a script that makes the links on checkout. This is a hassle.

• Other modules that you can access are

  www-vint

  This module gets you this html file, and other html files, that are stored in the vint subdirectory on your local machine.

  Tcl

  This module gets you the files necessary for configuring the Tcl code for ns.

  ns-2

  This module gets you the complete set of files for ns version 2.

  nam

  This module gets you the nam sources.

Release tags, Branch tags, and working with branch tags

Periodic releases of ns-2.0 are marked as ns-2.0a###, where ``###'' is a monotonically increasing count. Each completed release will be tagged with the tag keyword ns-2_0a###. Note that we change the dot(.) to underscore(_) because tags in CVS cannot have dots in them.

        cvs rtag ns-2_0a### ns-2

        cvs checkout -r ns-2_0a15 ns-2

        cvs rtag -b -r ns-2_0a15 ns-2_0a15-bKVa1 ns-2

        cvs checkout -r ns-2_0a15-bKVa1 ns-2
	cd ns-2

	cvs update -r ns-2_0a15-bKVa1 

   cvs commit

	cvs diff -r ns-2_0a15 -r ns-2_0a15-bKVa1

        cvs rtag ns-2_0a15-bKVa2 ns-2

        cvs update -A ns-2

        cvs checkout ns-2
        cvs update -j ns-2_0a15-bKVa1
	cvs commit

Binary Releases

All release binaries should be put in the /nfs/web/isi.edu/htdocs/nsnam/dist/binary directory. This directory maps to http://www.isi.edu/nsnam/dist/binary on the website. After making a relase please update the ns and nam web pages to reflect the current version.

CVS Accounts

To be able to access new cvs repository, you also need to have an account created on nsnam.isi.edu, which can be accessed only via ssh.

CVS and Subdirectories

By default, CVS does not create subdirectories when you do a cvs update. If you know someone's added a new subdirectory, make sure you do cvs update -d when updating.

Hint: to make this the default behavior put one line in your ~/.cvsrc:

update -d

Accounts on nsnam.isi.edu

Everyone who wants to use CVS needs an account on nsnam.isi.edu. E-mail account requests with your ~/.ssh/identity.pub info to Kun-chan Lan ([email protected]) for an account.

Procedure to add a new account on nsnam.isi.edu

1. add or modify /etc/passwd for the new user
   • If they're at ISI, look up their user id and group id on a server and home dir and do "useradd -c 'Real Name' -d /home/dir -g group -G nsnam -u uid loginid"
   • If they're not at ISI, useradd -c "Real Name" -G nsnam loginid
2. add new user into group "nsnam" in /etc/group
3. add new user into /etc/sendmail.cE
4. Get their ssh info

Big-memory Simulations

We have a large-memory machine for doing big simulations. Ask for an account on big.isi.edu. Currently this machine is on Haobo's desk and runs FreeBSD.

Additional SSH Details

The -v option is useful in helping to diagnose problems with ssh. When ssh is working properly, it should look something like this:

unix> ssh -v nsnam.isi.edu
OpenSSH_2.5.2p2, SSH protocols 1.5/2.0, OpenSSL 0x0090600f
debug1: Seeding random number generator
debug1: Rhosts Authentication disabled, originating port will not be trusted.
debug1: ssh_connect: getuid 1003 geteuid 0 anon 1
debug1: Connecting to nsnam.isi.edu [128.9.160.91] port 22.
debug1: Connection established.
debug1: unknown identity file /home/username/.ssh/identity
debug1: identity file /home/username/.ssh/identity type -1
debug1: unknown identity file /home/username/.ssh/id_rsa
debug1: identity file /home/username/.ssh/id_rsa type -1
debug1: identity file /home/username/.ssh/id_dsa type 2
debug1: Remote protocol version 1.99, remote software version OpenSSH_2.5.2p2
debug1: match: OpenSSH_2.5.2p2 pat ^OpenSSH
Enabling compatibility mode for protocol 2.0
debug1: Local version string SSH-2.0-OpenSSH_2.5.2p2
debug1: send KEXINIT
debug1: done
debug1: wait KEXINIT
debug1: got kexinit: diffie-hellman-group-exchange-sha1,diffie-hellman-group1-sha1
debug1: got kexinit: ssh-rsa,ssh-dss
debug1: got kexinit: aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,aes192-cbc,aes256-cbc,rijndael128-cbc,rijndael192-cbc,rijndael256-cbc,[email protected]
debug1: got kexinit: aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,aes192-cbc,aes256-cbc,rijndael128-cbc,rijndael192-cbc,rijndael256-cbc,[email protected]
debug1: got kexinit: hmac-md5,hmac-sha1,hmac-ripemd160,[email protected],hmac-sha1-96,hmac-md5-96
debug1: got kexinit: hmac-md5,hmac-sha1,hmac-ripemd160,[email protected],hmac-sha1-96,hmac-md5-96
debug1: got kexinit: none,zlib
debug1: got kexinit: none,zlib
debug1: got kexinit: 
debug1: got kexinit: 
debug1: first kex follow: 0 
debug1: reserved: 0 
debug1: done
debug1: kex: server->client aes128-cbc hmac-md5 none
debug1: kex: client->server aes128-cbc hmac-md5 none
debug1: Sending SSH2_MSG_KEX_DH_GEX_REQUEST.
debug1: Wait SSH2_MSG_KEX_DH_GEX_GROUP.
debug1: Got SSH2_MSG_KEX_DH_GEX_GROUP.
debug1: dh_gen_key: priv key bits set: 119/256
debug1: bits set: 1002/2049
debug1: Sending SSH2_MSG_KEX_DH_GEX_INIT.
debug1: Wait SSH2_MSG_KEX_DH_GEX_REPLY.
debug1: Got SSH2_MSG_KEXDH_REPLY.
debug1: Host 'nsnam.isi.edu' is known and matches the RSA host key.
debug1: Found key in /home/username/.ssh/known_hosts2:2
debug1: bits set: 1025/2049
debug1: ssh_rsa_verify: signature correct
debug1: Wait SSH2_MSG_NEWKEYS.
debug1: GOT SSH2_MSG_NEWKEYS.
debug1: send SSH2_MSG_NEWKEYS.
debug1: done: send SSH2_MSG_NEWKEYS.
debug1: done: KEX2.
debug1: send SSH2_MSG_SERVICE_REQUEST
debug1: service_accept: ssh-userauth
debug1: got SSH2_MSG_SERVICE_ACCEPT
debug1: authentications that can continue: publickey,keyboard-interactive
debug1: next auth method to try is publickey
debug1: try privkey: /home/username/.ssh/identity
debug1: try privkey: /home/username/.ssh/id_rsa
debug1: try pubkey: /home/username/.ssh/id_dsa
debug1: input_userauth_pk_ok: pkalg ssh-dss blen 433 lastkey 0x8088228 hint 2
debug1: read SSH2 private key done: name dsa w/o comment success 1
debug1: sig size 20 20
debug1: ssh-userauth2 successful: method publickey
debug1: channel 0: new [client-session]
debug1: send channel open 0
debug1: Entering interactive session.
debug1: client_init id 0 arg 0
debug1: Requesting X11 forwarding with authentication spoofing.
debug1: channel request 0: shell
debug1: channel 0: open confirm rwindow 0 rmax 16384
Last login: Mon Jun 25 16:14:09 2001 from starbucks.hell.com
DELL-installed Red Hat Linux Thu Oct 14 09:20:18 CDT 1999
[username@vir username]$