Getting Started With OVSDB

Getting Started With OVSDB

Open Source

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 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.

OVSDB Manager

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

JSON Output

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.

JSON Demarshalling OVSDB

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

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 #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!

About the Author

Brent SalisburyI have over 15 years of experience wearing various hats from, network engineer, architect, devops and software engineer. I currently have the pleasure of working at the company that develops my favorite software I have ever used, Docker. My comments here are my personal thoughts and opinions. More at Brent's BioView all posts by Brent Salisbury →

  1. Saumya HegdeSaumya Hegde10-01-2013

    I have been a silent reader of your blog. Thanks for all the information you put up. I have a query, don’t know if this is the right place to ask, but would you recommend OpenDaylight or Floodlight for a multi-controller data center scenario. Thanks.

  2. Fred HsuFred Hsu10-02-2013

    Great post as always Brent! One questoin, did you have to change any settings on OVS to allow the remote TCP connections to the OVSDB?

    • Brent SalisburyBrent Salisbury10-06-2013

      Hey Fred! sorry for the delay.

      ### Listen ###
      Tells the OVS instance to list on IP: and Port:6630
      ovs-vsctl -vjsonrpc –db=tcp: set-manager ptcp:6630:

      ### Connect to a Manager ###
      Tells the OVS instance to connect to a manager on IP: and Port:6630
      ovs-vsctl -vjsonrpc –db=tcp: set-manager tcp:6630:

      When the OVS is the initiator it will become sending echo hellos to initiate a persistent connection.

      **Note: Check out Fred’s Blog if you have any interest in ODL or SDN for that matter.

  3. UmairUmair10-03-2013

    I must admit I’m lost here with the explanations and examples, Brent. I come from a heavy networking background, not a programming background. So perhaps if you could explain how JSON and POJO have to do with OVSDB and virtual networking, it would help to bridge the gap. There is so much literature out there on networking for server people. It would be nice to get the opposite. this article assumes the reader is a gifted programmer, not a CCIE. Thanks.

    • Brent SalisburyBrent Salisbury10-06-2013

      Hey Umair, with a wire protocol like OVSDB it is just a means to trade information back and forth so that it means the same thing to both sides. So for this we have a DB schema that states what those values need to be and what their functionality is.

      For when we want to extract that data on either side we need to take the values and put them into containers that can be called to extract that data. While not required by any means, to achieve scale and something that could be easily extended it helps to have a structure. When the messages arrive, these objects get populated with information for the extraction to make it easier to call each time.

      The high level for OVSDB is how to provision configurations using its API (JSON-RPC). With regard to network virtualization it is primarily used for attaching VMs to ports based on a controller defining the policy and getting the VM in the right topology group. It also builds the overlay tunnel topology between hypervisors.


  4. Sreenivas MakamSreenivas Makam10-20-2013

    Hi Brent
    I have been reading ur blog for some time and they are very helpful, Thanks.

    I was able to connect to mininet and try the different ovsdb-client options.

    I had few questions in general regarding the ovsdb integration with opendaylight controller.
    1. Once ovsdb plugin is available for opendaylight, we can use the controller to manage the ovsdb switch and all tasks that we could do earlier using ovsdb-client, now we can do using controller. is that correct?
    2. Both ovsdb-client and ovsdb plugin uses json-rpc to talk to ovsdb-server, is that correct?
    3. In open vswitch management protocol draft, there is a connection shown between ovsdb server and ovs-vswitchd. I understand that we talk to ovsdb-server through ovsdb mgmt protocol and to ovs-vswitchd using openflow. what does the connection between ovsdb-server and ovs-vswitchd mean? Does that mean we can program flows dynamically based on certain operations that we do through management protocol?


  5. Brent SalisburyBrent Salisbury10-20-2013

    1. Yessir. You can use ODL to write directly to OVSDB instances.

    2. Yup, the ovs-vsctl and ovsdb-client tools use JSON-RPC as the wire protocol.

    I attached a screen cap of a method from ODL I just added and one from the ova-vsctl client.

    JSON-RPC via ODL:

    Output from ovs-vsctl show using the ovs-vsctl client:

    3. ovs-vswitchd tells the kernel where to forward traffic for a particular flow. Take a peek at this deck from Justin Pettit. OVSDB is L2 aware in the DP so adding MAC addrs is possible but flows get instantiated via OpenFlow.


  6. FaisalFaisal10-31-2013

    Hi Bred ,
    It is a excellent post , Keep writing
    can you pleas suggest a most cheapest hardware switch for playing with SDN ? Is it HP 3500 yl ?

    • UmairUmair10-31-2013

      Hi Faisal, even the HP 2920 supports OpenFlow.

  7. CosminCosmin05-05-2014

    Hi Brent,

    Very nice and useful work you’re doing with all the posts on this blog.
    I went almost through all of them (more than once).
    Regarding this specific blog, I’m a bit confused about the ovsdb-server port as you configured it here (6632). I cannot configure it on my mininet VM, however I can configure the ovs manager port, which is in general 6640 using: ovs-vsctl set-manager tcp:
    Does this configuration have similar effect to setting the ovsdb-server remote socket ?
    What is the difference between them?

    Thank you in advance!

    • Brent SalisburyBrent Salisbury05-06-2014

      Hi Cosmin, When we first started out w/ OVSDB I don’t think the port 6640 was registered with IANA so it was probably just random since 6634 was probably being used for the dpctl tool. So no difference between the ports. If you used vanilla OVS and not Mininet you can bind to any port you want as long as it is not already bound using ovs-vsctl set-manager tcp: like u pointed out in your comment.

      Mininet is using OVS under the hood. There could be something in the wrapper that is preventing it but I would recommend just running OVS and trying it out first.

      You can also set OVS as a listener using ovs-vsctl ptcp:6640. In ODL you can then initiate the OVSDB management connection with the OVSDB plugin using this from the command line :

      osgi> ovsconnect MINI1 6640
      connecting to ovsdb server : …
      Node Name: OVS|MINI1

      The Postman APIs using the OVSDB Plugin APIs are another direct option.

      Here is our initial demonstration from last year with it that might help.

      Download postman and the APIs collection linked on the wiki page above.

      Thanks for pointing out the old port number! I changed it to 6640 in the post.

      Cheers and thanks!