Jump to: navigation, search

OVSDB:Developer Guide

OpenDaylight OVSDB Architecture

For a deep dive into the ODL OVSDB architecture, see the following:

OVSDB Integration:Design

OpenStack OpenDaylight OVSDB Integration

Neutron and ODL Interactions

The OpenStack integration architecture uses the following technologies:

Getting the code

export ODL_USERNAME=<username for the account you created at OpenDaylight>
git clone ssh://${ODL_USERNAME}@git.opendaylight.org:29418/ovsdb.git;(cd ovsdb; scp -p -P 29418 ${ODL_USERNAME}@git.opendaylight.org:hooks/commit-msg .git/hooks/;chmod 755 .git/hooks/commit-msg;git config remote.origin.push HEAD:refs/for/master)

OpenDaylight Mechanism Driver for Openstack Neutron ML2

This code is a part of OpenStack and can be found at htis OpenStack location.

To make changes to this code, read the NeutronDevelopment page on the OpenStack wiki.

Remember to run the tests before submitting code:

tox -e py27
tox -e pep8

Importing the Code in to Eclipse/IntelliJ

Check out either Eclipse Setup or OpenDaylight_Controller:Developing_With_Intellij

Avoiding conflicting project names

OVSDB Eclipse.png

To avoid Eclipse complaining about having project with a conflicting name in the workspace, ensure that you select Advanced > Name Template > [groupId].[artifactId] when importing the project.

Browsing the code

The code is mirrored to GitHub for those occasions where it's easier to read code online.

Source code organization

The OVSDB project generates 3 x OSGi Bundles:

  • org.opendaylight.ovsdb is the OVSDB Plugin and Library
  • org.opendaylight.ovsdb.neutron is the OpenStack Neutron Integration
  • org.opendaylight.ovsdb.northbound is the Northbound API for the OVSDB Library

These correspond to the ovsdb neutron and northbound directories in the source tree.

commons contains the parent POM file for the project for Maven which is used to get consistency of settings across the project.

distribution contains the OVSDB distribution. This is the latest Virtualization Edition pulled from the Integration project with the local OVSDB artifacts added. This gives developers the ability to run the controller for testing.

resources contains useful scripts, How-To's etc.

Building the code

From the root of the project

mvn clean install

You may need to change your MAVEN_OPTS

export MAVEN_OPTS="-Xmx1024m -XX:MaxPermSize=512m"

Running the distribution

cd distribution/opendaylight/target/distribution.ovsdb-<version>-SNAPSHOT-osgipackage/opendaylight/
./run.sh -debug -Xmx2048m -XX:MaxPermSize=1024m -virt ovsdb

Testing patches

While we do have CI, which is not comprehensive, and therefore it is recommended to test you patches locally before submission.

See Continuous System Integration Test for OVSDB project for info on using robot to test the ovsdb net-virt functionality.

Integration Tests

Net-virt Integration Test Overview

The OVSDB project contains several Integration Test Suites. These tests aim to cover the core Openstack Neutron use cases and are designed to be conveniently run from within the development environment. Integration Tests should be run to validate code changes.

In scope these tests function in the following pattern, (a) create Neutron objects in the neutron md-sal, (b) use ovsdb southbound to instrument OVS configuration, e.g., adding tap ports, (c) check that net-virt has created the correct OVS flow entries.

When must I write/modify Integration Tests?

Unlike unit tests, the integration tests do not aim at 100% code coverage. As stated above, they aim to cover the primary Neutron use cases. As such it is only necessary to modify these tests if you have made changes to the neutron model or functionality, how net-virt implements the OVS flows, or how net-virt responds to the various OVSDB southbound events.

How to run Integration Tests

Instructions on running the integration tests can be found in the OVSDB README: https://github.com/opendaylight/ovsdb/blob/master/README

Neutron Integration

To test patches to the Neutron integration you will need a Multi-Node Devstack Setup There are sample ``local.conf`` files in the ``resources`` folder.

Open vSwitch

To test patches to the library you will need a working Open vSwitch. Packages are available for most Linux distributions. If you would like to run multiple versions of Open vSwitch for testing you can use docker-ovs to run Open vSwitch in Docker containers.


[Mininet http://mininet.org/] is another useful resource for testing patches. Mininet creates multiple Open vSwitches connected in a configurable topology.


The Vagrantfile in the root of the OVSDB source code provides an easy way to create VMs for tests.

Installing Vagrant

Please follow the instructions here to install Vagrant on your machine

Testing with Devstack

First, start the controller from the OVSDB distribution as mentioned here

vagrant up devstack-control
vagrant ssh devstack-control
cd devstack

Get coffee... (a tall one, like a Latte or an Americano)

vagrant up devstack-compute
vagrant ssh devstack-compute
cd devstack

Get another coffee... (something smaller this time. Espresso or Macchiato)

Start testing after stacking is complete.

Maybe create a virtual machine....

nova boot --flavor m1.tiny --image $(nova image-list | grep 'cirros-0.3.1-x86_64-uec\s' | awk '{print $2}') --nic net-id=$(neutron net-list | grep private | awk '{print $2}') test

...or three...

nova boot --flavor m1.tiny --image $(nova image-list | grep 'cirros-0.3.1-x86_64-uec\s' | awk '{print $2}') --nic net-id=$(neutron net-list | grep private | awk '{print $2}') --num-instances 3 test

Testing with Mininet

vagrant up mininet
vagrant ssh mininet

You now have a Mininet installation at your disposal.

Cleaning up

When you are finished, run the following:

vagrant destroy

OpenDaylight OVSDB Developer Getting Started Video Series

  • We created three videos to help folks bootstrap into OVSDB development.

OpenDaylight OVSDB Developer Getting Started

OpenDaylight OVSDB Developer Getting Started - Start Here

OpenDaylight OVSDB Developer Getting Started - Northbound API Usage

OpenDaylight OVSDB Developer Getting Started - Northbound API Usage

OpenDaylight OVSDB Developer Getting Started - Java APIs

OpenDaylight OVSDB Developer Getting Started - Java API

OpenDaylight OVSDB Developer Getting Started - OpenStack Integration OpenFlow v1.0

OpenDaylight OVSDB Developer Getting Started - OpenStack Integration OpenFlow v1.0

Developer Tutorials

OVSDB OpenFlow v1.3 Neutron ML2 Integration

Open vSwitch Database Table Explanations and Simple Jackson Tutorial