README.ns

Running AODV-UU in the Network Simulator ns-2
=============================================

AODV-UU can be used as a routing agent for mobile nodes in the
Network Simulator "ns-2" (http://www.isi.edu/nsnam/ns/).

This allows for simulations using AODV-UU instead of, for instance,
the AODV implementation that comes with ns-2. Performance of AODV-UU
in ns-2 is very similar to the existing ns-2 AODV implementation. The
main difference is that AODV-UU is draft compliant, and implements
HELLO messages and expanding ring search correctly.

To use AODV-UU in ns-2, you need a Linux system (or other UNIX system which
ns-2 will run on, e.g. Sun Solaris) and the 2.26 or 2.27 version of ns-2. 


Installing ns-2
===============

Download ns-2 version 2.26 from the ns-2 homepage
(http://www.isi.edu/nsnam/ns/ns-build.html#allinone):
http://www.isi.edu/nsnam/dist/ns-allinone-2.26.tar.gz

(For installing ns-2 version 2.27, just replace the version number 2.26
with 2.27).

We strongly recommend the "ns-allinone" package since it contains
all necessary software components.

In the sections that follow, we will assume that you install ns-allinone in
your home directory (~).

Unpack the ns-allinone archive:

  > cd ~
  > tar zxvf ns-allinone-2.26.tar.gz

This will create a "ns-allinone-2.26" subdirectory with all required
files and subdirectories below it.

If you want to run AODV-UU in ns-2, you should install AODV-UU at this
point. Follow the installation instructions in the next section. Then run
the installation script supplied with ns-2 ('install'):

  > cd ~/ns-allinone-2.26
  > ./install

If the installation fails, please see
http://www.isi.edu/nsnam/ns/ns-problems.html for tips and solutions.

When the installation script finishes, it displays important information
about environment variables that need to be set before you can use
ns-2. Follow the instructions very carefully.

When you have updated your login script (e.g. .bashrc or .bash_profile)
according to the instructions, log out of your computer and then login
again. Now try to run the simulator:

  > cd ~/ns-allinone-2.26/bin
  > ./ns

If the installation was successful, ns-2 should display a prompt:

  > % 

(You may now exit ns-2 by pressing Ctrl-C.)


Installing AODV-UU
==================

Important note to Sun Solaris users:

In order to successfully install AODV-UU into ns-2, you may need to
install and use the GNU 'patch' and 'make' utilities instead of using
those that come bundled with Sun Solaris. The utilities are available
from:

http://www.gnu.org/directory/patch.html
http://www.gnu.org/directory/make.html

Not doing so may result in error messages during patching and compilation,
in which case the AODV-UU installation will be unsuccessful.


General instructions:

Download AODV-UU version 0.8 from the AODV-UU homepage
(http://www.docs.uu.se/scanet/aodv/).

Unpack it in the "ns-2.26" directory:

  > cd ~/ns-allinone-2.26/ns-2.26
  > tar zxvf aodv-uu-0.8.tar.gz

This will create an "aodv-uu-0.8" subdirectory with all AODV-UU files in
it. Create a symbolic link named "aodv-uu" that points to the "aodv-uu-0.8"
directory:

  > ln -s ./aodv-uu-0.8 ./aodv-uu

(This is needed for ns-2 to be able to find the AODV-UU files.)

It is also necessary to apply the bundled ns-2 patch to the ns-2
source tree, so that support is added for AODV-UU:

  > cd ~/ns-allinone-2.26/ns-2.26
  > patch -p1 < aodv-uu/ns-2.26-aodv-uu-0.8.patch


Recompiling ns-2
================

If you are installing AODV-UU into an existing, already compiled ns-2
installation, ns-2 needs to be recompiled before the changes take
effect:

  > cd ~/ns-allinone-2.26/ns-2.26
  > ./configure
  > make distclean
  > ./configure
  > make


Using AODV-UU in simulations
============================

Using AODV-UU is straightforward; make sure that mobile nodes are
configured to use "AODVUU" as their routing agent (instead of
e.g. "DSDV" or "AODV") in your OTcl simulation scenario scripts.

This is done with the node-config command, _before_ any mobile nodes are
created:


    $ns_ node-config -adhocRouting AODVUU \
                     -llType LL \
                     -macType Mac/802_11 \
                     -ifqType Queue/DropTail/PriQueue \
                     -ifqLen 50 \
                     -antType Antenna/OmniAntenna \
                     -propType Propagation/TwoRayGround \
                     -phyType Phy/WirelessPhy \
                     -topoInstance $topo \
                     -channel Channel/WirelessChannel \
                     -agentTrace ON \
                     -routerTrace ON \
                     -macTrace ON \
                     -movementTrace ON
    ...


Configuring AODV-UU
===================

Each AODV-UU routing agent instance (one per mobile node) is configured
individually by setting the values of its configuration variables from
OTcl. An example:


    set mobilenode1_ [$ns_ node]        ;# create a mobile node
    $mobilenode1_ random-motion 0       ;# disable random motion

    set r [$mobilenode1_ set ragent_]   ;# get the routing agent
    $r set debug_ 1                     ;# configure the routing agent
    $r set rt_log_interval_ 1000
    $r set log_to_file_ 1


Repeat this procedure for each mobile node in your simulation scenario
script as needed.

The available configuration variables are:


  debug_                    Print log messages on standard output (stdout)
  expanding_ring_search_    Expanding ring search for RREQs
  hello_jittering_          Jittering of HELLO messages
  llfeedback_               Use link layer feedback instead of HELLOs
  local_repair_             Use local repair
  log_to_file_              Write log messages to logfile
  optimized_hellos_         Only use HELLOs when there are active routes
  ratelimit_                Use rate limiting for RREQs and RERRs

  receive_n_hellos_         Receive N HELLOs before treating as neighbor.
                            (Should be set to at least 2 if you use it.)

  rreq_gratuitous_          Force gratuitous flag on all RREQs

  rt_log_interval_          Periodically log routing table to routing table
                            logfile, value is the interval in msecs (0 = off).
                            (Independent of the log_to_file_ setting.)

  unidir_hack_		    Detect and avoid unidirectional links
  wait_on_reboot_	    15-second wait-on-reboot delay
  internet_gw_mode_         Run this node as a gateway

  
If not otherwise mentioned, setting a variable to 0 means "off" and 1 means
"on". In general, the values of these variables should be set before the
simulation begins, i.e., before the "$ns_ run" line at the end of your OTcl
script.

Please note that no error checking is performed on the values of these
variables. Changing them to strange or disallowed values will probably
yield unexpected results.

The default values can be found in the "ns-2.26/tcl/lib/ns-default.tcl"
file.


Link layer feedback or HELLO messages
------------------------------------- 

AODV-UU by default uses link layer feedback to detect broken links.

To use HELLO messages instead, set the "llfeedback_" configuration
variable to zero (0) in your simulation script.


The new AODVNode class in ns-2
==============================

AODV-UU implements a new ns-2 node class called
Node/MobileNode/AODVNode (see tcl/lib/ns-mobilenode.tcl). This class
is based on the SRNode class and allows packets to always pass through
the AODV routing agent. In the original AODV node class
(Node/MobileNode) the port demux lies before the routing agent, which
stops packets from passing through the AODV agent at the destination
node (this is still a problem in the ns-2 AODV implementation). The
new node class puts the AODV-UU agent first at the entry point of a
node and looks something like this:

 
    <-------------------------<------------------------------
   |                                                         |
   |entry_                       local addr                  |
   x------> AODV-UU -> addr demux ------> port demux ----> src/sink
   |                      \                    \ 
   |                       \ defaulttarget_     \ port 255
   |                        \                    \________ null agent 
   |                         \
   |      uptarget_           \
    <---------------------<-- Link Layer
                                  |


In contrast to the SRNode class, the Node/MobileNode/AODVNode class
also has the address demuxer. Address demuxing is therefore not
necessary to implement in the routing agent.


Gateway connectivity in ns-2
============================

Similar to the real world version of AODV-UU, the ns-2 version
supports gateway connectivity using tunnels (see README). Gateways
must be started with the "internet_gw_mode_" runtime option enabled in
the simulation script and must be connected to another network through
a fixed line. Nodes must have hierarchical addresses. See the ns-2
documentation for more information.


Logging 
=======

Logging is useful for debugging purposes and checking routing table
contents. By default, all logging is disabled.

If you wish to change the logging settings, see the previous section on
configuration.

The name of the logfile is "aodv-uu-1.log" and "aodv-uu-1.rtlog"
for the routing table logfile, for node number 1.

Please note that the logging settings of the AODV-UU routing agent have
nothing to do with the trace files that ns-2 creates; those are separate.


Trace log format
================

AODV-UU uses the same trace log format as the existing AODV implementation
that comes with ns-2 (except for the fact that the packet type is
"AODVUU" instead of "AODV").

In ns-2, there are three trace log formats available; the old trace format,
the new trace format and a tagged format. AODV-UU supports the old and the
new trace format (but not the tagged format).

For more information on these two trace formats, see Ch. 16 (Mobile
Networking in ns) of "The ns Manual", sections 16.1.6 (Trace Support) and
16.1.7 (Revised format for wireless traces). The tagged format, introduced
in ns-2.1b9, currently seems to lack documentation altogether.

In the examples below, both the old and the new trace formats are shown
(in that order).


RREP and HELLO messages
-----------------------

s 100.004910093 _1_ RTR  --- 24 AODVUU 40 [0 0 0 0] -------
 [1:255 0:255 255 0] [0x2 0 [1 0] 20000.000000] (REPLY)
                      (1)(2)(3)       (5)
                              (4)

s -t 100.004910093 -Hs 1 -Hd 0 -Ni 1 -Nx 25.05 -Ny 20.05 -Nz 0.00
-Ne -1.000000 -Nl RTR -Nw --- -Ma 0 -Md 0 -Ms 0 -Mt 0 -Is 1.255 -Id 0.255
-It AODVUU -Il 40 -If 0 -Ii 24 -Iv 255 -P aodvuu -Pt 0x2 -Ph 0 -Pd 1
                                                     (1)    (2)   (3)
-Pds 0 -Pl 20000.000000 -Pc REPLY 
    (4)        (5)

s 12.636748053 _0_ RTR  --- 6 AODVUU 40 [0 0 0 0] -------
 [0:255 -1:255 1 0] [0x2 0 [0 5] 2000.000000] (HELLO)
                     (1)(2)(3)      (5)
                             (4)

s -t 12.636748053 -Hs 0 -Hd -2 -Ni 0 -Nx 6.80 -Ny 3.92 -Nz 0.00
-Ne -1.000000 -Nl RTR -Nw --- -Ma 0 -Md 0 -Ms 0 -Mt 0 -Is 0.255 -Id -1.255
-It AODVUU -Il 40 -If 0 -Ii 6 -Iv 1 -P aodvuu -Pt 0x2 -Ph 0 -Pd 0
                                                  (1)    (2)   (3)
-Pds 5 -Pl 2000.000000 -Pc HELLO 
    (4)       (5)

(1): Packet type. 0x2 = RREP.
(2): Hop Count.
(3): Destination IP Address (i.e., node ID number in ns-2).
(4): Destination Sequence Number.
(5): Lifetime.

NOTE: Since HELLO messages are RREP messages, the packet type (1) will be
0x2 for HELLO messages as well.


RREQ messages
-------------

s 127.942238029 _0_ RTR  --- 1 AODVUU 44 [0 0 0 0] -------
 [0:255 -1:255 1 0] [0x1 0 0 [2 0] [0 1]] (REQUEST)
                     (1)(2)  (4)   (6)
                          (3)  (5)   (7)

s -t 127.942238029 -Hs 0 -Hd -2 -Ni 0 -Nx 89.66 -Ny 283.49 -Nz 0.00
-Ne -1.000000 -Nl RTR -Nw --- -Ma 0 -Md 0 -Ms 0 -Mt 0 -Is 0.255 -Id -1.255
-It AODVUU -Il 44 -If 0 -Ii 1 -Iv 1 -P aodvuu -Pt 0x1 -Ph 0 -Pb 0 -Pd 2
                                                  (1)    (2)   (3)   (4)
-Pds 0 -Ps 0 -Pss 1 -Pc REQUEST 
    (5)   (6)    (7)

(1): Packet type. 0x1 = RREQ.
(2): Hop Count.
(3): RREQ ID.
(4): Destination IP Address (i.e., node ID number in ns-2).
(5): Destination Sequence Number.
(6): Originator IP Address (i.e., node ID number in ns-2).
(7): Originator Sequence Number.


RERR messages
-------------

s 189.612645446 _1_ RTR  --- 6808 AODVUU 32 [0 0 0 0] -------
 [1:255 0:255 1 0] [0x3 1 [2 3] 0.000000] (ERROR)
                    (1)(2)(3)      (5)
                            (4)

s -t 189.612645446 -Hs 1 -Hd 0 -Ni 1 -Nx 221.83 -Ny 80.86 -Nz 0.00
-Ne -1.000000 -Nl RTR -Nw --- -Ma 0 -Md 0 -Ms 0 -Mt 0 -Is 1.255 -Id 0.255
-It AODVUU -Il 32 -If 0 -Ii 6808 -Iv 1 -P aodvuu -Pt 0x3 -Ph 1 -Pd 2
                                                     (1)    (2)   (3)
-Pds 3 -Pl 0.000000 -Pc ERROR 
    (4)       (5)

(1): Packet type. 0x3 = RERR.
(2): DestCount.
(3): Unreachable Destination IP Address 1 (i.e., node ID number in ns-2).
(4): Unreachable Destination Sequence Number 1.
(5): Lifetime.

NOTE: A lifetime field is not part of the RERR message. However, this field
was logged by the AODV version supplied with ns-2 because it handles
several message types equally when logging them. The value of this field
was always 0.0 because it was never initialized. For backward compatibility
with the AODV trace log format, we have included it as well (always
displaying a value of 0.0).


RREP-ACK messages
-----------------

Currently, AODV-UU does not utilize RREP-ACK messages. However, tracing
support is in place. For RREP-ACKs, a line in the trace log would end like
this:

... [0x4] (RREP-ACK)
     (1)

... -P aodvuu -Pt 0x4 RREP-ACK
                  (1)

(1): Packet type. 0x4 = RREP-ACK.

NOTE: RREP-ACK messages are not logged at all by the AODV version that comes
with ns-2.


Comparisons with real-life
==========================

The ns-2 "port" of AODV-UU uses the same source code base as the
"real-life" AODV-UU, governing for a function corresponding very closely
to that of the real-life version.

However, not all of the functionality available in the real-life version is
available in the ported version, simply because it isn't applicable to
simulations. More specifically, the following features are NOT available in
the ported version:

Specifying which network interfaces to attach to, daemon mode,
version information, and online help.


Other notes and limitations
===========================

Currently none known.


Future work
===========

* Support for the tagged trace format (introduced in ns-2 2.1b9).
  This would enable customized logging (although strictly not needed).


Questions
=========

If you have any questions or bug reports pertaining to running AODV-UU
in ns-2, you're welcome to e-mail me:

  Björn Wiberg <bjorn.wiberg@home.se>

You may wish to direct Internet gateway-specific questions to Erik
Nordström:

  Erik Nordström <erik.nordstrom@it.uu.se>