Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Add a side note explaining "modify" and "modify strict"

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...

...


Info

This tutorial is for Floodlight v1.0 and later. If you are using v0.9, v0.91, a copy of the master branch prior to December 30, 2014, or another prior version of Floodlight, this tutorial does not apply. If you are using the old openflow-1.3 branch, you should consider updating to the main repository's v1.2 (or even better master) branch to ensure you have the latest updates.

...

Floodlight v1.0 and up is backed by the new OpenFlowJ-Loxigen library. OpenFlowJ-Loxigen supports multiple OpenFlow versions, from 1.0 to 1.5. Floodlight v1.2 supports up to 1.4 and the master branch supports up to v1.5, through a single, common, version-agnostic API. Developers can take advantage of the API to write applications compatible with switches of multiple and various OpenFlow versions. All OpenFlow concepts and types are accessible from the OpenFlowJ-Loxigen library. The idea is that each OpenFlow version has a factory that can build all types and messages as they are defined for that version of OpenFlow.

OpenFlowJ-Loxigen also sports a new and very much improved way to create OpenFlow Messages, Matches, Actions, FlowMods, etc. The creation of many OpenFlow objects has been greatly simplified using builders, all accessible from a common OpenFlow factory. Simply set your fields and build. The handling of low-level details such as Message lengths wildcards are dealt with behind the scenes. Never again will you have to worry about keeping track of and (in)correctly setting Message lengths. When composing FlowMods, all Match fields are automatically wildcarded, except for those fields you specifically set in the FlowMod. Masked fields are also supported, and the mask can be specified with the Match, which will automatically set the appropriate wildcard bits if necessary. All objects produced from builders are immutable, which allows for safer code and makes your applications easier to debug.

All switches that connect to Floodlight contain a factory for the version of OpenFlow the switch speaks. There can be multiple switches, all speaking different versions of OpenFlow, where OpenFlowJ-Loxigen handles the low-level protocol differences behind the scenes. From the perspective of modules and application developers, the switch is simply exposed as an IOFSwitch, which has the function getOFFactory() to return the OpenFlowJ-Loxigen factory appropriate for the OpenFlow version the switch is speaking. Once you have the correct factory, you can create OpenFlow types and concepts through the common API OpenFlowJ-Loxi exposes.

As such, you do not need to switch APIs when composing your FlowMods and other types. Let's say you wish to build a FlowMod and send it to a switch. Each switch known to the switch manager has a reference to an OpenFlow factory of the same version negotiated in the initial handshake between the switch and the controller. Simply reference the factory from your switch, create the builder, build the FlowMod, and write it to the switch. The same API is exposed for the construction of all OpenFlow objects, regardless of the OpenFlow version. You will however need to know what you are allowed to do for each OpenFlow version; otherwise, if you e.g. tell an OF1.0 switch to perform some action such as add a Group, which is not supported for it's OpenFlow version, the OpenFlowJ-Loxi library will kindly inform you with an UnsupportedOperationException.

There are some other subtle changes introduced, for the better, with OpenFlowJ-Loxigen. For example, many common types such as switch datapath IDs, OpenFlow ports, and IP and MAC addresses are defined by the OpenFlowJ-Loxi library through the DatapathId, OFPort, IPv4Address, and MacAddress, respectively. You are encouraged to explore org.projectfloodlight.openflow.types, where you will find a wide variety of common types that are now conveniently defined in a single location. Like the objects produced from builders above, all types are immutable.

Lastly, OpenFlowJ-Loxigen is open source, has a comprehensive suite of auto-generated protocol unit tests, an automated integration-tested release process, and is in use in production by the current family of commercial BSN products. 

If you want to know more about the architecture of OpenFlowJ-Loxigen, take a look at this wiki page: https://github.com/floodlight/loxigen/wiki/OpenFlowJ-Loxi

Prerequisites and Goals

The goal of this tutorial is to introduce the most common uses of the OpenFlowJ-Loxigen library within a user module. Examples are given on how to perform everyday operations like compose a FlowMod, handle a PacketIn, and many more. These examples introduce the techniques and assume you have a module written in which you can apply them. If you would like to know how to create a module for Floodlight v1.0, please refer to this tutorial.

OpenFlow Concepts

Factories

...

An important note about OFFlowMods: OpenFlow 1.3 removes the default table-miss behavior of forwarding the packet to the controller. Instead, OpenFlow 1.3 specifies the controller should insert a special table-miss flow of zero priority, all MatchFields wildcarded, and with an action list defined by any OFAction's. To support processing of unmatched, table-miss packets in the controller, Floodlight will insert a flow of zero priority, no MatchFields set, and an single output OFAction to send the packet to the controller. This flow will serve as a "catch-all" flow and send the packet as a packet-in message to the controller in the case all other flows in the table do not match the packet. Unlike OpenFlow 1.0 - 1.2 where this behavior is embedded within the flow table itself, in OpenFlow 1.3, it is clearly implemented using an actual flow, visible and modifiable by all models. As such, you should be very careful when writing your OpenFlow 1.3 OFFlowMods. You should ensure they do not replace or remove the default table-miss flow. Otherwise, the controller and thus other modules may not be able to receive any packet-in messages from the switch.

A side note about "strict": according to OpenFlow specification, the flow modification message and flow deletion message support a "strict" version and a "without strict" version. A "strict" means any flow that exactly looks like the match you specify, then the flow(s) will be modified or deleted. While if you choose a version "without strict", it means any flow that look like the match you specify (i.e. the flow contains at least the match you specify, but could contains more match fields) will be modified or deleted. 

Furthermore, in a similar manner to the previous OpenFlow concepts and types covered, an OFFactory can be used to produce each type of OFFlowMod.

...