The road to an ns-3-click Hello World!

The GSoC coding period started three days ago, on the 24th of this month. I did begin working on ns-3-click in the beginning of the month itself though. Although I had just included it as a one-liner in my proposal, “linking NS-3 with Click” wasn’t exactly the most straightforward of steps for me. Reason? NS-3 uses waf for managing its build process. Since I’m new to waf, it took me a few days to figure out, but yes, I managed to link NS-3 with To build NS-3 with Click Integration enabled, just perform the following steps:

$: cd <to-click-source>
$: ./configure --enable-nsclick --disable-linuxmodule --enable-userlevel
$: make && sudo make install
$: cd <to-ns-3-click>
$: ./waf --with-nsclick=<click-installation-prefix>

Once the above was done, I could start implementing the required classes as soon as the coding period began. If you have a look at src/routing/click, you’ll find the Ipv4ExternalRouting and Ipv4ClickRouting classes. Ipv4ExternalRouting has been maintained to hold generic external routing code, which is then sub-classed to implement the External Router specific code. The gist of my work involves completing one half of a Simulator API which allows an external simulator to talk with Click. The fun part about the work so far, is executing random methods from the API to see what the Click code is expecting from NS-3. So far, I never once needed to peek into Click’s side of the Simulator API (I last saw all that code while making my proposal)! The first thing I tried was running simclick_click_create() with a sample .click file (the one I initially used was ns-2.34/tcl/ex/ Since I had included debug statements in all the Click service methods (look under simclick_sim_command()), a simple run of the code told me whatever I needed to implement first. And the services I needed to code were:


Figuring that out was easy enough. I began by writing dummy code for the above services. I then implemented a function I named Ipv4ClickRouting::TestInit(), which would call simclick_click_create(). This allowed me to begin initialising Click Router Instances within NS-3! So we’re now through step number 1. 🙂

The next step involves being able to execute simclick_click_run(). It is ultimately this method from the Simulator API that the NS-3 Simulator should call everytime it needs to execute a Click router for a particular node in the simulation. I included this command inside the Ipv4ClickRouting::TestInit() as well, and gave it another run. As expected, it seemed that the Click code needed the SIMCLICK_SCHEDULE service. This was basically Click asking NS-3 to schedule a specific simulation node to execute at a particular time. Why was this an easy guess? Because once a Click Router is initialised, the Click Driver code would need to schedule itself to run again at a later time. In an integration with NS-3, the Click Driver would want NS-3 to get the Click Instance to run. Why? Because Click needs to synchronise to NS-3’s simulation time, not the other way around. 🙂 So the requirement here is that NS-3 should drive the Click code.

So step  number 2 was to code out the SIMCLICK_SCHEDULE service. This was fairly easy as well, for which I added some more methods to the Ipv4ClickRouting class. After this step, I noticed another Click script in ns-2.34/tcl/ex named ‘’. This one seemed ideally suited for testing purposes, because it consisted of just two ethernet interfaces, eth0 and eth1. Any packet received on eth0 is sent to eth1 and vice versa. Exactly what the doctor ordered for Click newbies like myself!

The last bit of testing code I checked in a few hours ago seems like a working example for the integration. Try doing an hg clone of the ns-3-click code, and running scratch/ As of now, the code simply initialises an Ipv4ClickRouting instance and creates a Click Router instance for the configuration. In the 20th second of the simulation, a packet is sent down eth0, and received via simclick_sim_send() from eth1. This repeats every second until the simulation is done.

This sure feels good! 🙂

UPDATE: The code’s been improved since then. The hacks have been removed and replaced with actual code. Check out Just specify the .click configuration file you need to use in your simulation script. Note that the file must be in your ns-3 top level directory.


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s