Using OESS

This document describes how to use the OESS web interface to create layer-2 circuits across the configured OpenFlow and/or MPLS infrastructure. It assumes that you have already installed and configured OESS, that nodes have been configured in OESS and links discovered, and that workgroups and users have been defined.

Logging In

Upon successful login, you will be presented with a page to choose which workgroup you will work as; the page also lists current features and known issues. In all parts of the UI, if you run into issues you can select the Feedback button to email the developers. If your account has been granted administration rights, you will also see an Admin button on the upper right.


Each user belongs to one or more workgroups. A workgroup allows a group of users to jointly manage a set of resources - a workgroup may own network interfaces and circuits (also called VLANs in a couple of places in OESS). Once a workgroup is selected, you can then select from one of six options: view the Active VLANS, view the current Network Status, view the Available Resources (the interfaces (and VLAN tags thereupon) the workgroup may use when creating circuits), get a list of other Users in the workgroup, perform Actions such as creating a new circuit, or manage the ACL rules for the interfaces the workgroup owns.

The Active VLANS tab lets you see all the circuits your workgroup owns, as well as other circuits using your workgroup's interfaces (the latter show up in gray text). Search allows you to filter based on the contents of the circuit descriptions. The table also can be filtered to contain only circuits with endpoints on a particular node or that have paths that go over a particular node. Clicking on a row in this table will take you to the Circuit Details for that circuit, where you can look at live traffic or edit the circuit.

Circuit Details

The Circuit Details page is where you go to examine or change a particular circuit. It shows the circuit's description, its endpoints, and its metadata. When you first go to the page, you'll see the circuit's path through the network and live network Utilization. The History tab shows the history of the circuit and who has edited it in the past. Scheduled Events shows any actions that have been scheduled for the future, such as edits and removals. The Circuit Layout tab shows a text representation of the circuit design, and for OpenFlow-based circuits, the Raw Circuit Layout tab displays the OpenFlow rules used to construct the circuit.

From this page, one can edit, delete, or reprovision the circuit. Reprovisioning is only needed in cases where you suspect the switch or controller have lost track of OpenFlow rules or MPLS configuration relating to the circuit; it is primarially used for troubleshooting.

Network Status

The Network Status tab in the workgroup homepage lets you see the status of all network gear, as well as the status of your circuits running over those switches.

The Link Status table displays the up or down status of the Ethernet circuits connecting switches.

The Switch Status table displays the operational status of each switch, with separate statuses for OpenFlow and MPLS operation. If the switch is unreachable, it is presumed down.

The Circuit Status table displays the status of your circuits. They could be on their primary or backup path. If both of those paths are inoperable, then the system will mark the circuit as down.

The map also shows which links and switches the workgroup has access to; switches the workgroup can't use as a circuit's endpoint are grayed out.

Network Status with Multiple Links

If there are multiple links between two nodes, the status of the individual links can be seen by hovering over the link. The links that are up will be displayed in blue and the down links in red. The status of the links can also be viewed in the Link Status table. The line representing the links will appear blue if all of the links are up, yellow if half or less of the links are down, orange if more than half of the links are down, and red if they are all down.

Creating a Circuit

To create a new circuit, go to the workgroup homepage, select the Actions tab, and click the Create a New VLAN link.

From there, the system will guide you through several steps, the culmination of which is a working circuit.

Step 1.1:  Basic Details

The description is a human-friendly bit of text for you to remember the purpose of the circuit and to look it up later. You should put something in the Description text box.

Step 1.2: Endpoints

On the same page where you set the circuit's description, you also choose the circuit's endpoints. A circuit must have at least two endpoint.

To choose an endpoint, click on one of the non-gray dots - these represent the switches that the workgroup can use for endpoints. Once selected, the list of available interfaces will display to the right.

Clicking on one of the interfaces in the list brings up a pop-up to set the VLAN tag you would like to use for the traffic to be transmitted/received on that interface. Once you select the VLAN tag and click Save, you can start on adding another endpoint.

Note that a circuit is either OpenFlow-based or MPLS-based; it can't use both. Which Control Type the circuit is depends on the interfaces you use for endpoints. The screenshots from here on out will be for an OpenFlow circuit; the steps for an MPLS circuit are similar, with differences noted.

Once you have the set of desired endpoints defined, click on Proceed to Next Step: Circuit Options (if this is an OpenFlow circuit) or Proceed to Next Step: Primary Path (if this is an MPLS circuit).

Step 2: Circuit Options (OpenFlow only)

For OpenFlow circuits, there are a couple of options that can be selected for the circuit.

Restore To Primary controls whether, if the circuit is using its backup path and the primary path becomes usable, OESS will automatically switch the circuit to use the primary path again. Clicking on the button toggles whether this is enabled or disabled; if enabled, you can set the length of time the primary path should be usable before the path restoration occurs.

Multipoint Static MAC Routing can be used to control which endpoint(s) a frame on the circuit is sent to based on the frame's destination MAC address. This is described in more detail in a different part of this documentation.

When you're done setting any options, click Proceed to Next Step: Primary Path.

Step 3: Primary Path

The primary path is the path you prefer you traffic to traverse. It is required for OpenFlow circuits, and optional for MPLS circuits - if not specified, the MPLS switches will use the path they determine to currently be the best. If you don't have particular requirements for the path an OpenFlow circuit should take, you can hit the Suggest Shortest Path button, and OESS will find the best path for you. Alternatvely, if you would like to define the exact path, you can click links to add or remove them from the path.  The path must connect all the endpoints, and it must be acyclic - it can't have loops.

Select Primary Path with Multiple Links

If there is more than one link between two nodes, you will have to choose one when manually specifying a path. To manually select a specific link, click the line representing the multiple links. The Select Link panel will appear with a selector containing all of the links between the two nodes. Choose the link you would like to use in your path and then click the Select button to add it to the path. Suggest Shortest Path will determine the shortest path in this situation by choosing the link where the sum of the circuits provisioned on the link and its metric is the smallest. (The metric of a link is set by the OESS administrators behind the scenes - it reflects the cost of using a circuit.)

When you're done specifying the primary path (or if this is an MPLS circuit that doesn't need a primary path), click the Proceed to Next Step: Backup Path (OpenFlow circuits) or Proceed to Next Step: Scheduling (MPLS circuits) button.

Step 4: Backup Path (OpenFlow circuits only)

Defining the backup path is the same as the primary. However, if you hit Suggest Shortest Path, the system will calculate the shortest backup path that doesn't re-use any of the links in the primary path. Backup paths are optional.

Step 5: Scheduling

You can either immediately provision a circuit or schedule it to be added at a later date and time. Similarly, you can schedule the circuit to be removed at a later date and time, or you can just let it persist indefinitely (you can always manually remove it later).

Shown is an example where we are asking to provision immediately and automatically remove later. 

When you're done with scheduling, click Proceed to Next Step: Review Design.

Step 6: Provisioning

In this final step, you are given the ability to review your design before asking the system to make it happen. Nothing will happen until you click Submit Circuit Request.

Once you click Submit Circuit Request, the system will try to create the circuit you requested, and inform you as to the results.


The ACL section displays a list of all of the interfaces owned by the current workgroup. This section allows you to view the current ACL rules applied to a given interface. These rules can be added, edited, removed, and reordered.

Viewing ACL Rules

To view the ACL rules currently applied to a given interface, click on the row for that interface in the Interfaces owned by this Workgroup table. An Interface ACL table containing the rules will be displayed. Each rule allows or denies a workgroup (or all workgroups) the right to use a range of VLAN tags as circuit endpoints. The rules are executed top to bottom, using first-match-wins semantics.

In the example below, the Demo workgroup will be denied access to VLAN tags 700 to 799 and granted access to VLAN tags 1-699 and 800-4095 (as well as the special "untagged" tag, i.e., Ethernet frames that don't have a VLAN tag) on the interface et-2/0/0.0 on All other workgroups will have access to VLAN tags 1 through 4089 (as well as "untagged") on et-2/0/0.0. Had the first two rules been swapped, the Demo workgroup would have access to VLAN tags 1-4089 and "untagged" as well, as tags in the range 700-799 would match the "allow All" rule first, and the rule for Demo would never be reached; similarly, the rule for TR-CPS is currently superfluous.

Adding an ACL Rule

To add an ACL rule, click the Add ACL button below the Interface ACL table. A dialog box will be displayed containing the following fields:

  • Workgroup - The workgroup that the rule should be applied to; as a special case, a rule can also apply to All workgroups
  • Permission - Whether this rule should allow or deny the workgroup access to the specified range of VLAN tags
  • VLAN Range - The range of VLAN tags that this rule should apply to (the second field can be left blank to apply the rule to a single tag)
  • Notes - Any notes that the user may wish to be add about the rule

Once the fields have been filled out, the Save button should be clicked to add the rule.

Editing an ACL Rule

To edit an ACL rule, click the rule's row in the Interface ACL table. A dialog box almost identical to the Add Interface ACL dialog will appear with the current values filled out. Modify the fields and click the Save button to apply the changes (or Cancel to discard the changes).

Removing an ACL Rule

To remove an ACL rule, click the rule's row in the Interface ACL table. The Edit Interface ACL dialog box will appear. At the bottom of the dialog box is a Remove button. Click the button to remove the rule.

Reordering ACL Rules

To reorder the existing ACL rules, click the Enable Reordering button below the Interface ACL table. After this button has been clicked, a row can be dragged and dropped within the table to its new position. (ACL rules can't be edited or removed until the Disable Reordering button is clicked.)

Multipoint Static MAC Circuits

The multipoint static-MAC-address feature allows you to add devices' MAC addresses to each endpoint of a circuit. Traffic with a destination MAC address matching a defined MAC address will be routed directly to the endpoint on which it was assigned - as opposed to the default behavior of sending all traffic to all of the non-origin endpoints. This can be useful on circuits with more than two endpoints.

NOTE: This option is available only for OpenFlow-based circuits. Whether or not MAC addresses are used to limit the destination endpoints in an MPLS-based circuit is dependent on whether nodes' Ethernet-over-MPLS implementations handle MAC address learning.

Adding a Multipoint Circuit with Static MAC Routing

Start by creating a circuit, as detailed in another section of this documentation. The circuit must be OpenFlow-based, which is controlled by which interfaces are used as endpoints. On the Options page, you'll find an option at the top called Multipoint Static MAC Routing, which is disabled by default. Click the button to the right of Multipoint Static MAC Routing to enable it. Follow the steps below, which also take place on the Options page, for adding, editing, and removing static MAC addresses on endpoints. The remainder of the circuit editing and provisioning process is unchanged from any other circuit.

Adding a Static MAC Address to an Endpoint

To add static MAC addresses to an endpoint, click the Edit button on the endpoint's row in the Endpoints table. This will bring up a dialog called Static MAC Addresses & VLAN Tag for Interface [interface name], which is where you will add and/or remove static MAC addresses for that endpoint.

To add a MAC address to the endpoint, enter the MAC address in the input box to the left of the Add MAC Address button, then click the Add MAC Address button. The MAC address will be added to the table above, which contains all of the MAC addresses to be associated with the endpoint. Once you have added all the MAC addresses you wish to associate with the endpoint, click the Save button to apply the changes to the endpoint's configuration.

Removing a Static MAC Address from an Endpoint

To remove a static MAC address from an endpoint, you use the same dialog as when adding a static MAC address. To the right of each MAC address in the current list associated with the endpoint, there is a Delete button; click that button to remove the corresponding MAC address. When you're done removing (and possibly also adding) MAC addresses from the endpoint's list, click Save to apply your changes. If you don't want to save the changes you made, click the X in the upper-right corner.

You can also remove an endpoint from the circuit outright by clicking the Remove button at the bottom of the dialog.

Trunk Edge Circuit Termination

If you are in a use case in which you are maintaining a hybrid network (i.e., one that is only partially managed by OESS), terminating a circuit on a trunk interface (as opposed to a network edge) can be a useful way to transmit traffic from an OESS-controlled segment of the network to a segement which is being managed by another controller or by hand.

Setting up a Trunk Edge Circuit Termination

To begin creation of a circuit with a trunk edge, the trunk interface must be assigned to a workgroup. As a user that's an OESS administrator, go to the Admin section, then to the Workgroups tab, and select the workgroup you want.

Click on the Add Interface button.

Select the endpoint you wish to do the termination on. Then select the trunk interface, just like you would select any other interface to assign to the workgroup.

After that is set up, go to the Workgroups (i.e., non-admin) section of OESS using the workgroup you just modified. 

Click on Create a New VLAN underneath the Actions tab, and when you reach the Endpoints section, select the trunk interface.

Design the rest of the circuit as desired, and when it’s provisioned successfully, you will have a circuit with trunk edge circuit termination capabilities.