Since its development, I've been seeing a lot of requests for an ns-3-click 101. So with no further ado, here's the first in a series of tutorials to help you get an idea of how to go about using ns-3-click. In this article, I'll provide an idea of what ns-3-click is and how to install it .

1. What is ns-3-click?

ns-3-click, or the NS-3 Click Integration, is a feature of the ns-3 tool which allows a user to use a Click Modular Router instance to handle an ns-3 node's layer 3 functionality. Click is an architecture for designing highly flexible router configurations. Basically, it offers a large number of fine grained packet processing units called "elements", which can be put connected in various combinations into a Click graph. A Click graph defines a particular configuration for a router. The motivation for bringing Click into ns-3 is simple. Click users get to test their Click graphs in a powerful simulation environment which ns-3 offers, and ns-3 benefits from the large feature set that Click brings with it in the form of elements. In ns-3-click, the design choice was to entirely delegate ns-3's layer 3 functionality to Click. This means that an ns-3 node running a Click router will now have to use Click's implementations of ARP, routing tables and so forth.

So before you get started with ns-3-click, I suggest going through [0] and [1]. The first paper should tell you everything you need to know about what Click is, and the second one will inform you about where Click fits into ns-3. The latter will help you understand what ns-3-click can or cannot do for you.

2. Installation

By now, you know what ns-3-click is, and its time to get your hands dirty. The first step is to download and build Click.

$: git clone git://read.cs.ucla.edu/git/click DIR

$: cd DIR

$: ./configure --enable-nsclick --enable-userlevel

Note: If you require additional modules, enable them as required using the --enable-<module> flag.

Now build Click:

$: make

Once this is complete, we need to build ns-3 and point it to the Click source we've just compiled. So let's proceed to fetch and build ns-3. Note that ns-3-click was merged post ns-3.10, and will be released with ns-3.11. It is currently available in ns-3-dev.

$: hg clone http://code.nsnam.org/ns-3-dev

$: cd ns-3-dev

$: ./waf configure --with-nsclick=<path-to-click-source> --enable-examples

Once the last command has finished executing, you should see a list of features/modules that have been enabled. At this point, you should see the following line:

NS-3 Click Integration        : enabled

Now, let's build ns-3:

$: ./waf build

If all goes well, ns-3 should now be built successfully. To test whether things went well, try running one of the example scripts.

$: ./waf --run nsclick-simple-lan

This should generate some PCAP traces (nsclick-simple-lan-*.pcap). If you see packets being exchanged in there, then you're good to go!

This concludes part I of the ns-3-click tutorial. In the next part, I'll provide a code walk through of a simple example script that uses ns-3-click. If you find any bugs with ns-3-click, please don't hesitate to file a bug report on our bugzilla. :)

References

[0] Eddie Kohler, Robert Morris, Benjie Chen, John Jannotti, and M. Frans Kaashoek, "The Click Modular Router". ACM Transactions on Computer Systems 18(3), August 2000, pages 263-297. (Paper from the MIT-PDOS page)

[1] Lalith Suresh P., Ruben Merz, ”NS-3-Click: Click Modular Router Integration for NS-3”. In Proc. of 3rd International ICST Workshop on NS-3 (WNS3), Barcelona, Spain. March, 2011. paper