[ Previous Section | Documentation Home | Next Section ]


This section describes the classes and packages used by OVX to represent various network elements and OpenFlow messages.

2.1 Overview
2.2 Component State Machines
2.3 Component Persistence
2.4 Switches
2.5 Ports
2.6 Links and Routes
2.7 Addresses
2.8 Hosts
2.9 Network Topologies
2.10 Shared Global Mappings
2.11 Messages

2.1 Overview

OVX network representations, both phsyical and virtual, are a collection of switch, port, link, host, and address objects. To a tenant, these components appear no different from actual datapaths, ports, links, and hosts. The global map described in the previous section builds n-to-1 mappings between objects representing physical and virtual components to map tenant topologies onto the infrastructure.

In order to reduce confusion about infrastructure and OVX objects, we follow several conventions throughout these docs:

  • ‘infrastructure’ refers to an operator or provider’s actual network
  • ‘datapath’ will always be used with respect to infrastructure, with ‘switch’ used interchangeably
  • ‘network’ by itself refers to the infrastructure, with ‘physical network’ and ‘virtual network’ referring to OVX’s representation
  • Anything capitalised, such as ‘Switch’ and ‘Link’, are OVX constructs.
  • ‘tenant controller’,’controller’,’Network OS’, and ‘NOS’ are used interchangeably.

2.1.1 Implementing Classes

The current iteration of OVX is implemented in Java. The components are defined as classes within packages under [net.onrc.openvirtex.elements.*], and each component is defined by a base class. The base classes are shown in the table below.

Base Class Representation Definition
Network The full network topology public abstract class Network<T1 extends Switch, T2 extends Port, T3 extends Link>
Switch A switch public abstract class Switch<T extends Port>
Port A port on a switch public class Port<T1 extends Switch, T2 extends Link>
Link A connection between two ports public abstract class Link<T1 extends Port, T2 extends Switch>
Host A network host public class Host
IPAddress An IP Address public abstract class IPAddress

These classes are subclassed to implement physical and virtual versions of each component. The current component classes, and their parent classes, are shown below:

Base Class Physical Component Class Virtual Component Class(es)
Network PhysicalNetwork OVXNetwork
Switch PhysicalSwitch OVXSwitch (child classes OVXSingleSwitch, OVXBigSwitch)
Port PhysicalPort OVXPort
Link PhysicalLink OVXLink, SwitchRoute
Host Host
IPAddress PhysicalIPAddress OVXIPAddress

For example, ‘PhysicalPort’ is a port found on a switch in the network, and an ‘OVXSwitch’ is a virtual switch presented by OVX to a tenant. As a convention, most components that represent the infrastructure have names starting with ‘Physical’, and those in tenant networks, ‘OVX’. Note that Host only has a Virtual representation.

OVX builds up its knowledge of the physical network by populating a PhysicalNetwork instance. The PhysicalNetwork instance is populated by instances of switch, link, and port objects as they are discovered in the infrastructure, via various network discovery techniques. Virtual network representations, or OVXNetwork instances, are created by the operator through API calls that create network objects and maps them onto the PhysicalNetwork components spawned by OVX. Network discovery and the JSONRPC API are described in Sections 3.4 and 3.9, respectively.

Return to index

2.2 Component State Machines

Network elements are associated with several states that are interdependent on the states of other elements. For example, if a switch in the network is powered off, all of its ports and any links from those ports are also torn down, changing the network topology perceived by OVX.

In order to allow OVX to track and describe the states of the various components and how they interact, component classes implement finite state machines (FSMs) whose state transitions are driven by one another. Which FSM drives which is determined by an implicit dependency graph.

This section gives an overview of these FSMs.

2.2.1 Base FSM States

With the exception of Address classes and OVXSwitch child classes, each component class currently possesses four states:

  • INIT : Just created, i.e. its constuructor was just called
  • INACTIVE : Inert to network events i.e. OpenFlow messages and network discovery.
  • ACTIVE : Normal operating state, where all events are handled as expected.
  • STOPPED : Destroyed. The object must be created again to be usable.

For example, an administratively disabled Port is INACTVE, and a OVXSwitch removed from the Network by an operator is STOPPED.

The FSMs are currently implemented as a Java Enums. This approach was chosen for the ease of modification – if a new state is needed, we just simply add another state and a (set of) default behaviors to the FSM. The FSMs for each component class is named State, e.g. SwitchState for the FSMs for PhysicalSwitch and OVXSwitch.

2.2.2 Component FSM Interface

Component classes with FSMs implement Interface Component, which defines a set of methods for moving between states. For uniformity, each method is associated with a general set of actions required to functionally move a component between states:

  • register() [INIT -> INACTIVE] : add component to mappings and storage, checking that dependencies are met (Example: A new port may not be created if a switch doesn’t exist)
  • boot() [INACTIVE -> ACTIVE] : open control channels, activate dependent components (Example: bring a link up if the ports on both end are boot()ed)
  • teardown() [ACTIVE -> INACTIVE] : close control channels, deactivate dependent components (Example: If a port is torn down, links to/from it are also torn down)
  • unregister() [INACTIVE -> STOPPED] : remove from mappings and storage, deactivating or unregistering dependent components as necessary (Example: A link will no longer exist, so must be unregister()ed if either one or both ports it connects is unregister()ed)

Fig.2.1 summarizes a generic Component FSM and associated methods for moving between states. Each OVX class derived from the components in the previous section implements Component and an FSM in some form or another.

Component FSM

Note, a component can only be activated/stopped from the INACTIVE state to guarantee that dependencies are handled safely before something is put to work or removed from the network representation(s). This section discusses how component FSMs are coupled together in order to fulfill component dependencies and to implement network state synchronization.

Return to index

2.3 Component Persistence

Virtual components are configured by an administrator. The administrator might want the configurations to persist across reboots of OVX. OVX has the ability to store configurations in a remote database for recovery after reboot.

The classes of components that can be stored implement the interface Persistable, which has the following abstract methods:

Method Return Description Example
getDBName() String Database name “VNET”
getDBIndex() Map<String,Object> Unique index of document in which a Component’s data is stored Key=”tenantId”, Value=Tenant ID (Integer)
getDBKey() String Key of document in which a virtual component’s data is stored “switches”, “links”, “ports”, “routes”, “hosts”
getDBObject() Map<String,Object> List element which is added to the list of the value (see the details below)

Persistable is defined in [net.onrc.openvirtex.elements]. These methods enable each component that implements Persistable to be serialized/deserialized to/from the database. Further detail can be found here.

The remaining subsections describe the various packages containing the definitions of the classes that implement various elements.

Return to index

2.4 Switches [package net.onrc.openvirtex.elements.datapath]

A Switch is a representation of a datapath, described by a set of ports, a switch ID (DPID), and descriptions of capabilities/attributes, and a channel:

protected boolean isConnected = false;          // Channel liveness indication
protected OVXDescriptionStatistics desc = null; // Switch statistics
// T extends Port.
protected HashMap<Short, T> portMap             // The ports on this switch, keyed by port number
protected OFFeaturesReply featuresReply         // The Features Reply
protected Long switchId                         // The DPID of the switch
protected Channel channel                       // The control channel to the datapath

Switch subclasses serve as ‘anchor points’ for the OpenFlow channel between OVX and the tenant NOS (OVXSwitch) and OVX and datapaths (PhysicalSwitch). All messages that reach OVX are either handled directly in the north- or south-bound event loops, or passed through a Switch via the sendMsg() and handleIO() methods for message-specific handling. The following classes extend Switch:

PhysicalSwitch (extends Switch) represents a switch in the network that has connected to OVX. The properties of a PhysicalSwitch are populated by the contents of OpenFlow messages received by OVX during the handshake with the switch, and status messages received during the runtime. PhysicalSwitch maintains a representation of the flow table found in the switch and a XID translator for unaliasing OpenFlow XIDs of control traffic to/from the tenant controllers.


  • StatisticsManager statsMan : statistics collection from associated datapath
  • AtomicReference<Map<Integer, List<OVXFlowStatisticsReply>>> flowStats : Flow table, entries keyed by tenant
  • AtomicReference<Map<Short, OVXPortStatisticsReply>> portStats : port statistics keyed by port number
  • XidTranslator<OVXSwitch> translator : XID (de)multiplexer
  • SwitchState state : the FSM for the PhysicalSwitch instance

PhysicalSwitch also contains an inner class, SwitchDeregAction, for synchronizing the state of virtual elements with that of the PhysicalSwitch(es) that they map to. Section 3.6 delves further into state management within OVX.

OVXSwitch (extends Switch) is the parent class for representations of OVX’s virtual switches i.e. the switches visible to the tenant controllers. OVXSwitch implements the FeaturesReply messages sent to tenants, and maintains the virtual flow table and a buffer map for unaliasing PacketIns by buffer ID. In addition, OVXSwitch is capable of connecting to multiple controllers and handling controller roles. Role management is discussed in Section 3.4.


  • LRULinkedHashMap<Integer, OVXPacketIn> bufferMap
  • Integer tenantId : The ID of the tenant network this switch belongs to
  • OVXFlowTable flowTable : The structure holding the switch’s flow entries
  • XidTranslator<Channel> channelMux : Channel (de)multiplexer, for multiple NOS connections
  • RoleManager roleMan: management of Role messages from tenant controllers
  • SwitchState state : the FSM for the OVXSwitch instance

In addition, OVXSwitch directly implements some OFFeaturesReply fields :

// Note, some attributes of a virtual switch are fixed:
protected static int supportedActions = 0xFFF; // The supported actions.
protected static int bufferDimension = 4096;   // The buffer dimension.
protected Short missSendLen = 128;             // The miss send len. Default in spec is 128
protected OVXSwitchCapabilities capabilities;  // The capabilities.

The two child classes of OVXSwitch represent two modes of switch virtualization:

OVXSingleSwitch : A virtual switch that maps to a single switch in the network

OVXBigSwitch : A virtual switch that maps to multiple switches in the network, and treats the group of switches as the crossbars within a single Big Virtual Switch (BVS). OVXBigSwitch maintains a route table for paths across its virtual crossbar.


  • RoutingAlgorithms alg : Algorithm for calculating paths, either manually specified (manual) or shortest path (spf)
  • HashMap<OVXPort, HashMap<OVXPort, SwitchRoute>> routeMap : Map of routes through the BVS, given ingress and egress ports

Fig 2.2 shows the three Switch classes in context to a virtualized network.


Fig 2.2 : Each PhysicalSwitch (psw1, 2 and 3) directly maps to a switch (switch1, 2, and 3) in the infrastructure. Virtual switch vsw1 is an OVXSingleSwitch instance mapped directly onto PhysicalSwitch psw1. vsw2 is an OVXBigSwitch instance mapped to psw2 and psw3, and uses the link between them as a SwitchRoute. A tenant network can have both types of OVXSwitch as long as they don’t use the same PhysicalSwitches i.e. overlap in the PhysicalNetwork. Finally, Switch instances are the termination points of the OpenFlow channels (blue).

Return to index

2.5 Ports [package net.onrc.openvirtex.elements.port]

Switch ports are represented as Port subclass instances stored in the Switch portMap structure. Ports have attributes inherited from the OpenFlow ofp_phy_port structure. OVX adds the following for context:

// T1 extends Switch, T2 extends Link
protected MACAddress mac           // the hardware address of the port
protected Boolean isEdge           // true if this port is an edge
protected T1 parentSwitch          // the switch that this port belongs to
protected LinkPair<T2> portLink    // if not an edge, the Links to/from this port

For detail about ofp_phy_port, refer to the OpenFlow specifications. The flag isEdge is true for a Port if no links are attached to it. Note, Ports also have a state attribute that is part of ofp_phy_port that is unrelated to a Port’s FSM, but whose value is affected by the Port child class FSM. This is described in Section 3.6.

OVX implements the following two Port child classes:
PhysicalPort (extends Port<PhysicalSwitch, PhysicalLink>) is a port on a PhysicalSwitch. The number of ports and their properties are found from the switch’s Features Reply. The PhysicalPort maintains the mapping between it and the virtual ports that map to it in ovxPortMap. One PhysicalPort maps to at most one OVXPort per tenant network.


  • Map<Integer, HashMap<Integer, OVXPort>> ovxPortMap
  • PortState pstate : the state of the port according to its FSM

OVXPort (extends Port<OVXSwitch, OVXLink>) is a port on a OVXSwitch. OVXPorts are instantiated via administrative configuration.


  • Integer tenantId : tenant ID of the network that this port’s OVXSwitch belongs to
  • PhysicalPort physicalPort : The PhysicalPort the port maps to
  • PortState pstate : the state of the port according to its FSM

Return to index

2.6 Links and Routes [package]

OVX represents interconnects between Switches and Ports with Links. Links are defined by two endpoints, a source and destination Switch/Port pair:

protected T1 srcPort        // source Port
protected T1 distort        // destination Port

// endpoint Switches are fetched from the parentSwitch attributes of the Ports
public T2 getSrcSwitch() {
    return (T2) this.srcPort.getParentSwitch();
public T2 getDstSwitch() {
    return (T2) this.dstPort.getParentSwitch();

Links are directional, so a pair of them is used to represent a bidirectional link. This is the LinkPair referred to by Port. There are three classes that extend Link:

  • PhysicalLink (extends Link<PhysicalPort, PhysicalSwitch>) interconnects two PhysicalSwitches via PhysicalPorts, and maps 1:1 onto links in the network. OVX finds PhysicalLinks through topology discovery during runtime.


  • Integer linkId : Globally-unique ID of link
  • AtomicInteger linkIds : global ID counter, for linkId generation
  • LinkState state : The FSM associated with a PhysicalLink

  • OVXLink (extends Link<OVXPort, OVXSwitch>) interconnects two OVXPorts on two OVXSwitches within the same tenant network. An OVXLink may map onto one or more adjacent PhysicalLinks. OVXLinks are configured by the tenant.


  • Integer linkId : link ID, unique to a tenant network
  • Integer tenantId : unique ID of tenant network
  • Mappable map : pointer to global map
  • LinkState state : The FSM associated with an OVXLink
  • RoutingAlgorithms alg : The method for mapping an OVXLink onto a set of PhysicalLinks. The two current options are static (manual) or shortest path (spf).

  • SwitchRoute (extends Link<OVXPort, PhysicalSwitch>) interconnects two OVXPorts on the same OVXBigSwitch, defining a traffic path across its crossbars. SwitchRoutes may map onto one or more adjacent PhysicalLinks, and are defined by two types of endpoints:

  • BVS ingress/egress port : OVXPorts visible to the tenant as ports on the switch

  • SwitchRoute endpoints : PhysicalPorts internal to the BVS at either ends of the chain of PhysicalLinks


  • Integer routeId : SwitchRoute’s ID, unique within an OVXBigSwitch
  • OVXSwitch sw : the switch the SwitchRoute belongs to
  • RouteState state : the SwitchRoute’s FSM
  • PhysicalPort inPort : ingress SwitchRoute endpoint
  • PhysicalPort outPort : egress SwitchRoute endpoint

SwitchRoutes may be specified by a tenant, or generated through the OVXBigSwitch instance’s RoutingAlgorithm. Figures 2.3 and 2.4 summarize the structures and relationships between the three types of links.

Link subclases.

Fig 2.3 : Top) Two PhysicalLinks connecting PhysicalPorts (white circles) on three PhysicalSwitches (ps1, ps2, and ps3). Middle) An OVXLink connects two OVXSwitches (vs1, vs2) by their OVXPorts (black circles). vs1 and vs2 map to ps1 and ps3, respectively. The OVXLink maps over two PhysicalLinks, but appears as a single hop to a tenant, to which ps2 is invisible. Bottom) A SwitchRoute internally connects two OVXPorts on the same BVS. A SwitchRoute has an external (OVXPort) and internal (PhysicalPort) endpoints.

topology summary.

Fig 2.4 : various Links with respect to the network mappings. On the top are two tenants, and bottom, OVX’s network view (PhysicalNetwork). Note, there is only one PhysicalNetwork instance but we show two for clarity. Right) Tenant 1 has two OVXLinks, vlink1 and vlink2. Vlink1 corresponds to the path ps1-ps3-ps2 across PhysicalLinks l2 and l3, whereas vlink2 is a 1:1 mapping onto l5. Left) Tenant 2 contains both OVXLinks (red) and a SwitchRoute joining the ports in the OVXBigSwitch vs2, the latter mapped to l3 (blue).

2.6.1 Virtual Link Resilience

Virtual Links (OVXLinks and SwitchRoutes) are associated with one or more lists of PhysicalLinks. We refer to these lists as paths. The priority of a Virtual Link is the priority value of its primary path. The primary path is either the only path set for the Virtual Link, or the path with the highest priority. When multiple paths are tied to a Virtual Link, the unused paths can be used to introduce component resilience, facilitated by the following:

  • private byte priority : The current priority of the Virtual Link
  • private final TreeMap<Byte, List<PhysicalLink>> backupRoutes : container holding alternative paths, keyed on priority
  • private final TreeMap<Byte, List<PhysicalLink>> unusableRoutes : container holding failed paths, keyed on priority

The details of resilience are discussed in Section 3.8.

Return to index

2.7 Addresses [package net.onrc.openvirtex.elements.address]

IP addresses are formatted integers associated with network hosts. OVX identifies two types of IP address, used in the virtualization process:

  • The OVXIPAddress is a network host’s IP address, assigned to the host through external means. The OVXIPAddress is unique to a tenant network.
  • The PhysicalIPAddress is assigned by OVX and is unique to the whole network. OVXIPAddresses are mapped to PhysicalIPAddresses in the core of the network in order to distinguish traffic from different tenants. This process is described further in Section 3.5, Address Virtualization.

Return to index

2.8 Hosts [package]

Hosts represent endpoints for traffic flows across tenant networks. Hosts are defined by attachment points, addresses, and a unique ID:

private final Integer hostId;               // OVX-asigned UUID
private final MACAddress mac;               // MAC address of host in the network
private final OVXPort port;                 // Attachment point
private OVXIPAddress ipAddress;             // Network address
private HostState state                     // Host FSM

OVX Hosts are virtual constructs, and do not have separate physical and virtual representations. A physical representations of a hosts is generated by finding Physical equivalents of its attachment point and network address:

public HashMap<String, Object> convertToPhysical() {
            HashMap<String, Object> map = new HashMap<String, Object>();
    map.put("hostId", this.hostId);
    map.put("dpid", this.port.getPhysicalPort().getParentSwitch().getSwitchName());

    // Find Physical attachment point that corresponds to Host's virtual one
    map.put("port", port.getPhysicalPortNumber());
    map.put("mac", this.mac.toString());

    // Find Host's PhysicalIP, if it has one
    if (this.ipAddress.getIp() != 0)
            try {
                    map.put("ipAddress", OVXMap.getInstance().getPhysicalIP(this.ipAddress, this.port.getTenantId()).toSimpleString());

Note, isEdge stays true for an OVXPort that is a Host attachment point.

Return to index

2.9 Networks [package]

Bringing everything together, the Network class stores mappings that describe the relationships amongst switches, links, ports, and hosts within a network:

protected final Set<T1> switchSet;                  // set of all switches found in this network
protected final Set<T3> linkSet;                    // set of all links within this network
protected final Map<Long, T1> dpidMap;              // mapping between switches and their DPIDs
protected final Map<T2, T2> neighborPortMap;        // mapping between ports that are endpoints of the same link
protected final Map<T1, HashSet<T1>> neighborMap;   // mapping between a switch and its adjacencies

Note that Networks don’t record SwitchRoute or which Port belongs on which Switch, as they are stored in (i.e. subcomponents of) Switch. Currently there are two network representations derived from the Network class:

PhysicalNetwork is the singleton class that represents OVX’s view of the network. Ideally, PhysicalNetwork is an exact, one-to-one copy of the infrastructure and its state. PhysicalNetwork maintains LLDP-based topology discovery on a per-switch basis, and a HashedWheelTimer to drive the topology discovery and statistics collection processes. We detail network discovery in Section 3.4.


  • PhysicalNetwork instance : singleton instance of PhysicalNetwork
  • ArrayList<Uplink> uplinkList :
  • ConcurrentHashMap<Long, SwitchDiscoveryManager> discoveryManager : mapping between switches (by DPID) and topology/port state discovery managers
  • HashedWheelTimer timer : timer for launching periodic tasks
  • NetworkState state : The PhysicalNetwork FSM

OVXNetwork is the network representation presented to a tenant. OVX maintains a OVXNetwork instance per tenant, identified by a unique tenant ID and mapped back to PhysicalNetwork. The topology of virtual networks are configured via OVX’s API. We look at the API in Section 3.9. OVXNetwork instances maintain unique identifiers for its components, as well as notions of traffic flows between hosts, which require them to be aware of network hosts.


  • Integer tenantId : the unique ID of this tenant network
  • HashSet<String> controllerUrls : The tenant’s controller(s)
  • IPAddress network : the network address block used by tenant
  • short mask : the network mask used by tenant
  • HashMap<IPAddress, MACAddress> gwsMap :
  • BitSetIndex dpidCounter, linkCounter, ipCounter, hostCounter : Generators for unique DPIDs, link IDs, IP addresses, and Host IDs
  • Map<OVXPort, Host> hostMap : map of hosts and their attachment points in the virtual network
  • OVXFlowManager flowManager : tracks flows based on Ethernet source and destination
  • NetworkState state : The OVXNetwork FSM

Return to index

2.10 Shared Global Mappings: [package net.onrc.openvirtex.elements], ovxPortMap

The mapping between the physical network and the tenant networks are stored in the globally accessible, single-instance OVXMap structure. The Mappable interface defines the methods available for manipulating the mappings.

OVXMap holds a collection of Java Maps keyed on various Network components or their identifiers:

HashMap Key Values
virtualSwitchMap OVXSwitch PhysicalSwitches
physicalSwitchMap PhysicalSwitch Map<TenantID,OVXSwitch>
virtualLinkMap OVXLink PhysicalLinks
physicalLinkMap PhysicalLink Map<TenantID,OVXLink>
routetoLinkMap SwitchRoute PhysicalLinks
phyLinktoRouteMap PhysicalLink SwitchRoutes using PhysicalLink, keyed on TenantID
networkMap TenantID OVXNetwork
physicalIPMap PhysicalIPAddress (as String) OVXIPAddress
virtualIPMap OVXIPAddress PhysicalIPAddress
macMap MACAddress (as String) Tenant ID as integral value

In addition to OVXMap, PhysicalPort’s ovxPortMap stores the OVXPorts mapped to a PhysicalPort directly in the PhysicalPort instance.

Return to index

2.11 Messages [package net.onrc.openvirtex.messages]

OVX handles OpenFlow messages as specialized message class instances. Each OpenFlow message [org.openflow.protocol] has an OVX equivalent i.e. a class with a name that begins with with ‘OVX’ instead of ‘OF’ that subclasses the message class. These message classes implement either one of the following interfaces:
* Virtualizable (public void virtualize(PhysicalSwitch sw)) : handle tenant-bound messages from the datapath represented by PhysicalSwitch sw. This involves determining which tenant(s) should receive the message, and for each tenant that should, rewriting message contents to correspond with what is consistent with the tenant’s OVXNetwork topology.
* Devirtualizable (public void devirtualize(OVXSwitch sw)) : handle network-bound messages written to OVXSwitch sw by a tenant controller. This involves determining which datapaths the messages apply to, and rewriting message contents to fit the context of the network.

Fig.1.2 from the previous section illustrates this. Section 3.3 describes the core event loop that invokes these methods, and Section 3.5 describes the message (de)virtualization process.

Return to index

[ Previous Section | Documentation Home | Next Section ]

Please send feedback and questions to ovx-discuss – at –