Getting Started With OVSDB

Getting Started With OVSDB

OVSDB (Open vSwtich Database) is a management protocol used to manipulate the configuration of Open vSwitches and more recently vendors have begun implementing OVSDB in their Ethernet switches firmware. Some of those vendor data plane implementations are already running OVS under the hood so the implementation should be relatively painless. A project I am involved in developing is the OVSDB implementation in the OpenDaylight SDN platform. I will disclaim this post is relatively self-serving to act as a reference for anyone interested in being part of the Daylight implementation and a little bit about how we are going about coding it. But it is also for anyone interested in getting started with OVSDB. I see OVSDB as a keystone protocol for enabling programmatic networks in the future. Adoption is high underway from almost all networking software and hardware vendors.

The OVSDB schema consists of 13 tables with a database schema schema or blueprint defined in the OVSDB Schema document:

OVSDB Schema →

If you are unfamiliar with Open vSwitch I highly cant recommend enough that you get familiar with it if involved in anything data center related. It is the reference SDN data plane implementation.

Compiling Open vSwitch from Source →

Or download the Mininet image now managed by the On.lab. I personally prefer Mininet for dev/test.

Download Mininet →

Once in Mininet you can download the daily OpenDaylight build from OpenDaylight Jenkins server.

Download the OpenDaylight Daily Build →

From Mininet run the following:

For more on building OpenDaylight from source and other tutorials see here and here.

OpenDaylight OVSDB Implementation

If you have interest in joining some of us in coding OVSDB into OpenDaylight project all are welcome. The following is an architectural overview of the OVSDB project:

OVSDB Architectural Implementation Overview

We can be found on irc.freenode.net in #opendaylight-ovsdb at all bizarre hours of the night and day.

JSON-RPC Transport

OVSDB is a uses JSON-RPC v1.0 to transport the messages.

JSON-RPC is an object that consists of three properties that are serialized into an object to be sent on the wire:

1. Method – A String containing the name of the method to be invoked.
2. Params – An Array of objects to pass as arguments to the method.
3. ID – The request id. This can be of any type. It is used to match the response with the request that it is replying to.

---

OVSDB Schema

The OVSDB manager can programs the OVSDB server daemon which resides in a persistent file on the data path vSwtich filesystem.

This is created during the build using the ovsdb-tool. For example:

The OVSDB manager programs the ovsdb-server process which implments the configuration in OVS. This is separate from the control plane forwarding instantiation by the OpenFlow protocol with the ovs-vswitchd daemon.

The OVSDB tables can be viewed with the following command:

The command can be called remotely also:

Like any database tables it the output contains rows and columns. The relations between the tables are listed in the OSDB schema document. Table rows key on on UUIDs for each object in the tables. For example a new port would have a new row uniquely identified with a UUID in the _uuid column. If that port is part of a particular bridge, that UUID would be listed in the “ports” column of the bridge it is a member of in the bridge table. A snippet of the output of the ovsdb-client dump command is below.

In the following example the UUID c513db7b-ab35-4cf1-9e44-2d5ff2cabe86 is mapped to the name vif0 in a row in the port table. The name is in the “name” column of the row.

For the port to be added to the bridge br0, it is added to the array in the “ports” column in the row keyed on the UUID 3409f223-4a8c-4920-b227-c418cf338c4b that corresponds to name br0.

Using ovs-vsctl you can send commands with the vjsonrpc parameter to show the JSON requests you are sending.

An example output of the vjsonrpc parameter is as follows:

You could start ovs-server with the following to have the JSON-RPC ID, Method and send Parameters be sent to STDOUT with the following:

The ovsdb-client can send raw JSON requests for provisioning to debug or help figure out formatting such as:

Deserializing the JSON data with the Jackson Library

In order to receive the JSON name value pairs and do something meaningful with them, we need to deserialize and serialize the OVSDB JSON into meaningful objects. For this we are using the library called Jackson.

A tiny snippet (1 bridge and 1 port) of raw OVSDB JSON looks like this:

To view the schema for your OVS server you can run the following. Pretty will print the output in a hierarchical format.

Or remote

A snippet in a “pretty” print is the following using a JSON editor. Note, there are lots of online JSON editors http://goo.gl/BEsyZO

Super Simple Jackson Deserialization Example

A completely basic example of Jackson deserialization is the following.

Taking that JSON data, we will add it to a driver class as a string. We will map that String to a POJO (Plain Old Java Object). This will let us break out the names or values.

Next is the POJO.

The little sysout is the following:

This can get very tricky when demarshalling complex JSON such as OVSDB messages. Keys are polymorphic meaning they cannot be defined as an expected name value. The JsonProperty annotations (conceptually the same as JAXB annotations but for JSON) are not required but merely helpers to help define the type. The are helpful when a name or value is an operator in the language. For example, the name “new” is significant to not only the OVSDB schema but also Java. In such a case annotations are very helpful to avoid gross coding tricks in order to get successful bindings.

---

Simplistically, when dealing with tables only, you want to demarshall the elements within the JSON replies and associate those to meaningful identifiers.

This approach and OVSDB in general are incredibly flexible and extensible. To add new elements it can easily be extended rather then replaced, thus extensibility == good.

OVSDB Monitor Method

There are various methods in the OVSDB specification. One we will touch on in this is the monitor method. A monitor method will pull the requested tables and columns and return the associated configuration from OVSDB.

Subsequently, when changes to the specified tables are committed, the changes are automatically sent to the client using the “update” monitor notification (see Section 4.1.6). This monitoring persists until the JSON-RPC session terminates or until the client sends a “monitor_cancel” JSON-RPC request.

After you send your initial monitor request, OVSDB will send you diffs as notifications over the open channel. The keys for the reply are “new” and “old”. This means as the manager you now need to update your cache of the configuration for the element. This is vital for maintaining good state and amazing when talking about a realtime view of the state of network and compute elements. This is a million miles away from SNMP.

An example of an “update” method notification is the following:

Or raw logs from our ODL module:

More on the Monitor method here. The draft is great, Pfaff and Davie did a fantastic job on it. It is why we have not had to ping him once on the #OpenvSwitch irc channel (join that too :-). Course it helps to be working with developers like Madhu, Giovanni, Kyle to name a few.

OpenDaylight Nightly Build

If none of this made any sense, thats ok! There is lots of time to learn new things, this is a long funnel. Take a look at the nightly OpenDaylight build.
Download the Nightly OpenDaylight Build from the ODL Jenkins Server →

On a Mac run the following:

Once the JVM is started, point a browser at http://127.0.0.1:8080

Speak Now or forever Hold Your Peice

There is a books worth of material that could be covered here but only a short blogs worth of time. I am going to get into the Netty I/O socket abstraction library in the next post that is pretty geeky network programming and very important to the OpenDylight controller for non-blocking asynch socket messaging. If interested in exploring the amazing world of OVSDB and SDN with me and the ODL team, check out the OpenDaylight wiki and jump on irc.freenode.net #opendaylight and #opendaylight-ovsdb. There are some brilliant folks who try and find time to help out community which is the core of OSS projects. If there ever was a time to get involved in some form or fashion, this is it. Whether it is coding, blogging, labbing, learning, tweeting it all goes on record as contributing to the community. More soon, cheers!