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 README.md 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] BUILD SUCCESS [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] [INFO] common ............................................ SKIPPED [INFO] web ............................................... SKIPPED [INFO] main .............................................. SKIPPED [INFO] opendaylight-toolkit .............................. SUCCESS [4:14.385s] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [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 README.md 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 https://www.dropbox.com/s/i652ysfb9rg6qx7/odl-toolkit-web-resources.zip ubuntu@ubuntu:~/toolkit/web/src/main/$ unzip odl-toolkit-web-resources.zip
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] [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] BUILD SUCCESS [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$ ./run.sh
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 https://github.com/oakenshield/toolkit-learningswitch.git 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 10.0.0.2 (10.0.0.2) 56(84) bytes of data. 64 bytes from 10.0.0.2: icmp_req=3 ttl=64 time=0.266 ms ^C
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 AppNorthbound.java.
5. Finding your way around the code
In the Learningswitch code,
- Rules are programmed are inside src/main/java/org/sdnhub/learningswitch/
internal/Learningswitch.java - 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.