How-To: Extending OpenFlow with Vendor messages

OpenFlow provides a vendor message type as a way to offer third parties a way to customize the protocol without going out of spec. This tutorial attempts to describe the openflowj implementations of the vendor type message and how to use them in Floodlight. We'll mostly use snippets of the Nicira vendor messages, found in org.openflow.vendor.nicira, as examples in this page.

Overview

Vendor messages are identified by OpenFlow message type (OFType) value of 4. In addition to the standard OpenFlow header, The vendor type message has its own message header and a fully customizable payload.

A vendor message header contains a vendor ID and a data type. The vendor ID identifies the vendor implementing the custom message, and is typically the OUI of the vendor. The data type is used to indicate any subtypes that this message may have. For example, Nicira's vendor messages use Nicira's OUI (002320) as the vendor ID and come in two types, a Request and Reply, indicated by the data types of "10" and "11".

The rest of the message is the vendor message payload, and can be freely defined. To sum it up, the full OpenFlow vendor message takes on the following format:

<-------OpenFlow header-------><---Vendor message header--><----Vendor message payload----->
[OF ver(1)|OFType(1)|length(2)][Vendor ID(2-8)|dataType(4)][user-defined structures(varied)]

Where the numbers in the parenthesis denote the field size in Bytes. The Vendor message header and payloads, in combination, make up the full payload of the vendor message.

In openflowj

The base interface and framework needed for defining vendor messages are found in the package org.openflow.protocol.vendor.

OFVendorData is the Java interface for the full payload. All vendor type messages must implement OFVendorData. The vendor message header is typically defined in the class that implements this interface. As an example, the vendor ID and data type are part of OFNiciraVendorData, the base class for all Nicira vendor messages:

public class OFNiciraVendorData implements OFVendorData {

    public static final int NX_VENDOR_ID = 0x00002320;
    /**
     * The value of the integer data type 
     * at the beginning of the vendor data 
     */
    protected int dataType;         
...

This base class is extended to implement the Request and Reply message types (OFRoleRequestVendorData and OFRoleReplyVendorData, respectively).

The Vendor ID and data type are the only requirements in terms of vendor header content. The rest may be structured as needed, such as various message fields, getters and setters, and ChannelBuffer manipulators, which we'll discuss in the section on serialization.

Message Registration

The Vendor ID and message classes must be registered before it can properly be parsed. This is a two step process:

1. Vendor ID registration
2. Message type registration

We cn confirm this by taking a look at the method initVendorMessages() from Floodlight's core controller class Controller. We see that (1) the vendor ID is registered first, and (2) followed by each subclass representing a message type:

    // Configure openflowj to be able to parse the role request/reply vendor messages.
    // first register the vendor ID
        OFBasicVendorId niciraVendorId = new OFBasicVendorId(                (1)       
                OFNiciraVendorData.NX_VENDOR_ID, 4);               
        OFVendorId.registerVendorId(niciraVendorId);

    // then each data type, starting with reqest 
        OFBasicVendorDataType roleRequestVendorData =                        (2)
                new OFBasicVendorDataType(
                        OFRoleRequestVendorData.NXT_ROLE_REQUEST,
                        OFRoleRequestVendorData.getInstantiable());
        niciraVendorId.registerVendorDataType(roleRequestVendorData);
    
   //then the repy
        OFBasicVendorDataType roleReplyVendorData =                          (3)
                new OFBasicVendorDataType(
                        OFRoleReplyVendorData.NXT_ROLE_REPLY,
                        OFRoleReplyVendorData.getInstantiable());
         niciraVendorId.registerVendorDataType(roleReplyVendorData);

Where NXT_ROLE_REQUEST and NXT_ROLE_REPLY are the request and reply data type values for the two Nicira vendor message data types.

Several things to point out here:

• Since vendor IDs may vary in length, we indicate the length in bytes that the vendor ID is when we instantiate the OFBasicVendorId. In (1) we provide the constructor with the value 4 along with the actual Vendor ID, indicating that the Nicira vendor ID is an integer (4 bytes long).

• As seen above in (2) and (3), the class implementing the vendor data should be instantiable, so that it can be registered properly. The method getInstantiable() should be available in your message classes for this purpose. The following snippet was taken from OFRoleRequestVendorData, but the structure will pretty much be the same for any vendor data class (e.g. replace OFRoleRequestVendorData below with your class):

      protected static Instantiable<OFVendorData> instantiable =
              new Instantiable<OFVendorData>() {
                  public OFVendorData instantiate() {
                      return new OFRoleRequestVendorData();
                  }
              };
  
      /**
       * @return a subclass of Instantiable<OFVendorData> that instantiates
       *         an instance of OFRoleRequestVendorData.
       */
      public static Instantiable<OFVendorData> getInstantiable() {
          return instantiable;
      }
  

A non-registered Vendor message data payload is interpreted simply as a byte array (OFByteArrayVendorData to be precise), and cannot be cast to your message (sub)class(es) for further handling.

Message Serialization

Each class implementing OFVendorData must have a readFrom(ChannelBuffer data, int length) and writeTo(ChannelBuffer data) method for reading and writing the data from/to a ChannelBuffer. A getLength() method that returns the size of the messages is also required for reading. This value does not count the OpenFlow header, which is added in by helper methods to produce the full message length. The message length must be correct in order for it to be processed by the OpenFlow channel pipeline.

The packet structure is determined by the order in which the various fields are written to the ChannelBuffer, so readFrom() and writeTo() should read/write the fields in the same order.

In Floodlight

Floodlight uses openflowj as its OpenFlow implementation. Custom vendor messages are usually placed in their own packages, such as org.openflow.vendor.nicira for Nicira messages. Message registration occurs, as mentioned before, in method initVendorMessages() in Controller.java, found in net.floodlightcontroller.core.internal.