How-To: Extending OpenFlow with Vendor messages

This tutorial attempts to describe how to use the OpenFlow vendor message to create custom messages. We first provide an overview of the message structure. We then describe the vendor message implementations found in openflowj, the Java implementations of the OpenFlow protocol used in Floodlight and FlowVisor.

We'll mostly use snippets of the Nicira vendor messages, found in org.openflow.vendor.nicira of the Floodlight source, as working examples in this page. The Nicira extensions add OpenFlow role features, introduced in OpenFlow v1.2, to the v1.0 protocol used in Floodlight.

1. Overview: The Vendor Message

OpenFlow provides a vendor message type as a way to offer third parties a way to customize the protocol without going out of spec. Although called the "Vendor message", this message type provides a handy way for a developer to implement and test out experimental features without wantonly modifying the protocol.

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 organizationally unique identifier (OUI) of the vendor. As an individual, you can randomly pick and use an integral value for this purpose and nothing would balk at this, but this is highly discouraged. The proper conduct for this case is either to use your institution's OUI (if it has one), or to apply for an ID from the Open Networking Foundation (see ​here for details).

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 comes in two types, a Request and Reply, indicated by the data type values 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 general format:

   |<------OpenFlow header------>||<----------------------Vendor Data------------------------>|
   |                             ||<-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 payload in combination make up the full payload of the OpenFlow message, the vendor data.

2. In openflowj

In openflowj, the base interface and framework needed for creating vendor messages are found in the package org.openflow.protocol.vendor. Specifically, openflowj provides developers with a way to define custom vendor data classes.

OFVendorData is the Java interface required by any class defining custom vendor data. OFVendorData imposes just a few methods on a class implementing it:

• getLength() : return length of the data
• readFrom(ChannelBuffer data, int length) : Read the vendor data from the specified ChannelBuffer
• writeTo(ChannelBuffer data) : Write the vendor data to the specified ChannelBuffer

These methods are needed for the serialization/deserialization of the message.

2.1 The Vendor Message Header

What we're referring to as the vendor message header is typically a set of variables defined in the class that implements OFVendorData. The class in which these variables are declared typically becomes the base class for further message types.

For 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 class is extended to implement the Request and Reply message types (OFRoleRequestVendorData and OFRoleReplyVendorData, respectively). Note how the value of dataType is not set here - this value is set with the values declared in each subclass, as we can see here in OFRoleReplyVendorData:

    /**
     * The data type value for a role reply
     */
    public static final int NXT_ROLE_REPLY = 11;

    /**
     * Construct a role reply vendor data with an unspecified role value.
     */
    public OFRoleReplyVendorData() {
        super(NXT_ROLE_REPLY);
    }

super() refers to OFRoleVendorData, a subclass of OFNiciraVendorData. Tracing back a step further, we end up in OFNiciraVendorData whose constructor sets the value of dataType:

   /**
     * Contruct Nicira vendor data with the specified data type
     * @param dataType the data type value at the beginning of the vendor data.
     */
    public OFNiciraVendorData(int dataType) {
        this.dataType = dataType;
    }

The Vendor ID and data type are the only requirements in terms of vendor header content. Given that the methods required by OFVendorData are provided, along with those required for message registration, the message implementation may be structured as needed. The usual additions are various message fields and their getters and setters.

2.2 Message Registration

As expected from the variable structure of vendor messages, a given vendor message must be registered before openflowj can handle it properly. Registration is a two step process:

1. Vendor ID registration
2. Message type registration

We can see 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),(3) followed by each class 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 reply
        OFBasicVendorDataType roleReplyVendorData =                          (3)
                new OFBasicVendorDataType(
                        OFRoleReplyVendorData.NXT_ROLE_REPLY,
                        OFRoleReplyVendorData.getInstantiable());
         niciraVendorId.registerVendorDataType(roleReplyVendorData);

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

There are several things to point out here:

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

2. As seen above in (2) and (3), the class implementing the vendor data should include the method getInstantiable(). OFBasicVendorDataType, is a container for an instantiator of a OFVendorData subclass. By allowing the custom class to provide it a format, OFBasicVendorDataType avoids making assumptions about the structure of the message payload.

2. indicates that we also need a getInstantiable() in our vendor data. 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. Aside from throwing a ClassCastException, this is inconvenient since you won't be able to invoke the class methods specific to your vendor data class for message-specific processing.

2.3 Message Serialization

As mentioned earlier, a 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 vendor data sans the Vendor ID in bytes is also required for properly reading/writing from the ChannelBuffer. We do not count the OpenFlow header length since helper methods take it into account along with the Vendor ID length to produce the full message length.

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 to/from the ChannelBuffer in the same order.

As an example, we can look at OFRoleVendorData, the parent class of the Nicira Request and Reply messages. Since both messages only differ in the values of the role field, the readFrom(), writeTo(), and getLength() methods for the final packet structure are defined in this class. The message structure looks like this:

                     |<-Vendor ID->||<-dataType->|<----payload(4)--->|                             
    [OpenFlow Header][ 0x00002320  ][    10|11   ][      0|1|2       ]

Where the values within the square brackets separated by pipes are the various decimal values that the fields can take. What we had dubbed the vendor payload is one integral value of 4 bytes, used to indicate controller role. The packet structure is reflected in readFrom() and writeTo():

    public void readFrom(ChannelBuffer data, int length) {
        super.readFrom(data, length);
        role = data.readInt();
    }

    public void writeTo(ChannelBuffer data) {
        super.writeTo(data);
        data.writeInt(role);
    }

super() points to OFNiciraVendorData, which takes care of reading and writing the integral dataType field:

    @Override
    public void readFrom(ChannelBuffer data, int length) {
        dataType = data.readInt();
    }

    @Override
    public void writeTo(ChannelBuffer data) {
        data.writeInt(dataType);
    }

As for getLength(), the total returned is the length of the two fields (8 bytes). looking at the two classes side-by-side makes this clear. First OFRoleVendorData:

    @Override
    public int getLength() {
        return super.getLength() + 4;
    }

Then OFNiciraVendorData:

    @Override
    public int getLength() {
        return 4;
    }