Opendaylight Toolkit: Roll-your-own Opendaylight App

May 1, 2014 by opendaylight 1 Comment

This is a quick introduction to the Opendaylight Toolkit. We will not go over Opendaylight basics here – please refer to our intro tutorial for an overview and intro to Opendaylight.

1. Why Opendaylight Toolkit?

Opendaylight is highly modular and highly customizable. However, the existing release version of the Opendaylight controller may not suit everyone’s needs. The Hydrogen release controller loads nearly 250 bundles on startup, which not only requires more resources than necessary, but also requires running modules that might interfere with what your application intends to do.

To fix this issue, a couple of Opendaylight Developers – Madhu Venugopal of RedHat, Andrew Kim of Cisco, and some others – came up with the idea of a “lean and mean” Opendaylight distribution that could be adapted to the specific needs  of the app developers. The result is the Opendaylight toolkit.  Toolkit lets you get started with simple app skeletons that you can adapt to your needs, which it does using the concept of Maven archetypes. Archetypes are “templates” of applications that can be used to generate your own application with associated Northbound and Web interfaces.

In this post, we will give a quick overview of getting up a simple archetype with a northbound and web, and a L2 learning switch archetype that shows the learned MAC table of the switch.

2. Getting started with Opendaylight Toolkit

To run toolkit, you will need Java 1.7, Maven, etc. Please make sure you have your environment set up, or instead use the SDN Hub VM.

Step 1

To start off, clone the git repository from here. This will create a repository called toolkit. This will create a folder called toolkit with the following contents

ubuntu@ubuntu:~/toolkit$ ls
common  main  pom.xml  web

Step 2

The main folder contains a folder called ‘archetypes’, which contains a variety of templates (some still incomplete). Let us get started using a ‘simple-app’ archetype. First, we need to let Maven know about this specific archetype so that we can generate apps out of this archetype.

ubuntu@ubuntu:~/toolkit$ cd main/archetypes/archetype-app-simple
ubuntu@ubuntu:~/toolkit/main/archetypes/archetype-app-simple$ mvn clean install


[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 9.889s
[INFO] Finished at: Sun May 04 10:32:59 PDT 2014
[INFO] Final Memory: 11M/28M
[INFO] ------------------------------------------------------------------------

Step 3

Now let’s generate an app from the archetype we just installed to the local catalog of archetypes. Note that Maven now knows of the archetype and asks us to choose the ‘app-simple’ archetype to use.

ubuntu@ubuntu:~/toolkit/main/archetypes/archetype-app-simple$ cd ../../../ # back to toolkit/ folder
ubuntu@ubuntu:~/toolkit$ mvn archetype:generate -DarchetypeCatalog=local

Choose archetype:
1: local -> org.opendaylight.toolkit:toolkit-app-simple-archetype (opendaylight-toolkit-app-simple-archetype)
Choose a number or apply filter (format: [groupId:]artifactId, case sensitive contains): : 1
Define value for property 'groupId': : org.sdnhub
Define value for property 'artifactId': : simpleapp
Define value for property 'version':  1.0-SNAPSHOT: :
Define value for property 'package':  org.sdnhub: :
Define value for property 'REST-Resource-Name': : simpleapp
Confirm properties configuration:
groupId: org.sdnhub
artifactId: simpleapp
version: 1.0-SNAPSHOT
package: org.sdnhub
REST-Resource-Name: simpleapp
Y: : Y


[INFO] project created from Archetype in dir: /home/ubuntu/toolkit/simpleapp
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] common ............................................ SKIPPED
[INFO] web ............................................... SKIPPED
[INFO] main .............................................. SKIPPED
[INFO] opendaylight-toolkit .............................. SUCCESS [4:14.385s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 4:16.125s
[INFO] Finished at: Sun May 04 10:39:59 PDT 2014
[INFO] Final Memory: 17M/42M
[INFO] ------------------------------------------------------------------------

Step 4

ubuntu@ubuntu:~/toolkit$ ls common  main  pom.xml  simpleapp  web

As we can see, a simpleapp folder has been created in the top-level directory.

Step 5

Now we have one extra step to get going. There are some web resources (CSS, JS) that we need to download. This requires you to set up node.js and npm (node package manager) and get a web package manager called ‘bower’.

If you have bower installed:

ubuntu@ubuntu:~/toolkit$ cd web/src/main/resources/
ubuntu@ubuntu:~/toolkit/web/src/main/resources/$ for i in css js; do cd $i && bower install && cd -; done

If you do not have bower installed:

ubuntu@ubuntu:~/toolkit/web/src/main/resources$ cd ..
ubuntu@ubuntu:~/toolkit/web/src/main/$ wget
ubuntu@ubuntu:~/toolkit/web/src/main/$ unzip

After either step, please ensure that both resources/css and resources/js folders have an ‘ext/’ folder.

Step 6

Now we’re reaedy to compile the controller and simpleapp. From the toolkit/ folder, do

ubuntu@ubuntu:~/toolkit/$ mvn clean install


[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] common ............................................ SUCCESS [11.835s]
[INFO] web ............................................... SUCCESS [10.150s]
[INFO] main .............................................. SUCCESS [20.155s]
[INFO] simpleapp ......................................... SUCCESS [0.803s]
[INFO] opendaylight-toolkit .............................. SUCCESS [0.161s]
[INFO] ------------------------------------------------------------------------
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 44.374s
[INFO] Finished at: Sun May 04 11:00:46 PDT 2014
[INFO] Final Memory: 33M/86M
[INFO] ------------------------------------------------------------------------

ubuntu@ubuntu:~/toolkit/$ mvn clean install

This will build and install the controller and a minimal set of packages to main/target/

Step 8 – Run the controller

To run the controller,

ubuntu@ubuntu:~/toolkit/$ cd main/target/main-osgipackage/opendaylight
ubuntu@ubuntu:~/toolkit/main/target/main-osgipackage/opendaylight$ ./

Step 9 – Check out the web interface

After 30 seconds, proceed to http://localhost:8080. You will see the web interface (login admin:admin), and be greeted with a page with instructions on how to install apps. As the page says, apps will be displayed on the bar at the top. Currently, the app we generated has not been installed yet. To install it, let’s build it specifically while keeping the controller running

Step 10 – Build simpleapp

ubuntu@ubuntu:~/toolkit/$ cd simpleapp; mvn clean install

Step 11 – Verify simpleapp has been installed

After the app is built, go back to the web console and refresh the page. You will see that  simpleapp now shows up on the omnibar.

3. Tweaking Simpleapp

Simpleapp has a few components: The simpleapp.northbound specifies a number of HTTP-based API endpoints to list, add, update, and remove data from the SimpleData backend. The frontend is rendered using Backbone.js, which is a Javascript-based MVW framework that talks to the northbound and renders data in the frontend. Currently, simpleapp does not have any functionality to talk to network devices or switches – you can add your own southbound interfaces, or check out the next section for a pre-built learningswitch.

4. L2 Learning Switch inside Opendaylight Toolkit

To make it easier to interact with Openflow switches within ODL Toolkit, we have created a sample app. Note that this is not an archetype yet, so you will need to manually rename classes, files and directories. To install this app within toolkit:

Step 1: Check out toolkit-learningswitch from Github

ubuntu@ubuntu:~/toolkit$ git clone
ubuntu@ubuntu:~/toolkit$ cd toolkit-learningswitch; mvn clean install

Step 2: Ensure that the switch bundle has been installed to the running controller

Go to the tab with the controller running, and ensure that the learningswitch bundle has been loaded

osgi> ss learn
"Framework is launched."
id    State       Bundle
61    ACTIVE      org.sdnhub.learningswitch_1.0.0.SNAPSHOT

If you don’t see this or if there are exceptions, kill and restart the controller (this bug is being worked on).

Step 2: Ensure that the switch works using Mininet

In another tab, create a mininet topology and hook it up to the controller. Assuming you are running the controller and the switch on the SDNHub VM,

ubuntu@ubuntu~$ sudo mn --arp --topo single,3 --switch ovsk --controller remote


mininet> h1 ping h2
PING ( 56(84) bytes of data.
64 bytes from icmp_req=3 ttl=64 time=0.266 ms

Step 3: See MAC -> port table on the web console.

Go to the web console and ensure that a third tab has appeared on the omnibar. When you go to this tab, you will see a barebones UI which shows the MAC table for the learningswitch. As before, the frontend is rendered by Backbone.js and the mac and flow tables are exported by

5. Finding your way around the code

In the Learningswitch code,

  • Rules are programmed are inside src/main/java/org/sdnhub/learningswitch/
  • Frontend is rendered in src/main/resources/. Specifically, the basic page template is in src/main/resources/WEB-INF/jsp/main.jsp ; the backbone view is in src/main/resources/js/views, Backbone models are in models/, and page templates in templates/ are rendered using Underscore.js.
  • There’s no need to use Backbone.js. You may completely avoid Backbone by going to js/app.js and writing your own custom JS or use another front-end framework.


One comment on “Opendaylight Toolkit: Roll-your-own Opendaylight App

  1. on July 17, 2014
    Wenbin Wang says:

    I have a question in this step ” L2 Learning Switch inside Opendaylight Toolkit”.
    ” Note that this is not an archetype yet, so you will need to manually rename classes, files and directories.”
    what does it mean ? which class must i rename? Could you explain it in more detail?
    Thank you very much!!!

Leave a Reply