Using OESS

This document describes how to use the OESS web interface to create VLANs across the configured OpenFlow infrastructure.  It assumes that you have already installed and configured OESS so that there are a set of discovered links, and that workgroups and users have been defined.

Logging In

Upon successful login, the user will be presented with a splash screen that lists current features and known issues as well as a selector for which workgroup to act in.  In all parts of 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.  Workgroups are needed to support managing a set of resources jointly by a group of users.  Once a workgroup is selected, you can then select from one of 6 options:  view active vlans, look at network status, view the resources, get a list of other users in the workgroup, perform an action such as creating a new vlan, or manage the ACL rules for the interfaces the workgroup owns.

The Active VLANS page lets you see all VLANs in your workgroup.  Search allows you to filter based on the contents of the VLAN description.  The table can be filtered to contain only those with endpoints on a particular node or that have paths that go over a particular node /switch.  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 look at the details of a particular VLAN.  It will show the path of the VLAN the endpoints, and other metadata and the live network utilization by default. The History shows the history of the VLAN and who has edited it in the past.  Scheduled events show actions that have been scheduled such as edit and removal.  The circuit layout tab shows a text representation of the circuit design, and the Raw Circuit Layout displays

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 which flows, it is primarially used for troubleshooting

Network Status

The Network Status tab in the workgroup home page lets you see the status of all network gear and your vlans running over top 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, if the switch is actually down or if the switch is unreachable, it is presumed down

The Circuit Status table displays the state of your vlans, they could be on the primary or backup path, or if both of those paths are inoperable then the system will mark the VLAN as down.

The map currently shows which trunks and switches the workgroup has access to, in the future this will show the operational status of the network in graphical form.

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 yellow if half or less than half of the links are down, orange if more than half of the links are down, red if they are all down, and blue if they are all up.

Creating an Intra-Domain VLAN

To create a new VLAN go to the Wokrgroup Home page, view the Actions tab and select the Create a New VLAN link

From there the system will guide you through a 6 step dialog, the culmination of which is a working VLAN.

Step 1:  Basic Details

The description is a human friendly text for you to remember why the VLAN was created.

Restore to Primary tells the system what to do after it has failed your VLAN over to a backup path and the disuption to the Primary path has cleared up for long enough to consider it stable.  If you set Restore to Primary, the the system automatically put your VLAN back on the forwarding path after a primary path has been stable for a user specified hold time duration.  It should be noted that changing forwarding path does cause a minor disruption to packet forwarding.

The type of Circuit can be either Local or Inter-domain.  Interdomain VLANs are provisioned using IDCP and thus can take a significantly longer time to provision.

Step 2: Endpoints

You can select 2 or more endpoints.  To do so cick on a non grey dot, these represent the switches that the workgroup can access.  Once selected, the list of available ports will display to the right.  Clicking on one of those brings up a pop up to set the vlan tag you would like to use for the traffic to be transmitted or recieved on that port. Once you have the set of desired endpoints defined, select Proceed to Step 3: Primary Path.

Step 3: Select Primary Path

The primary path is the path you prefer you traffic to traverse.  In many cases you may not be overly concerned about the particular path, in such cases you can hit the Suggest Shortest Path button, and OESS will find the best path for you.  Alternatvely if you would like to defined the exact path, you can click links to add or remove them from the path.  The path must connect the endpoints and may not have cycles / loops.

Select Primary Path with Multiple Links

If there is more than one link in between two nodes a dark grey square containing the number of links will appear in the middle of the link. 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. The Suggest Shortest Path button 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.

Step 4: Backup Path

Defining the backup path is the same as the primary however, the system will attempt to calculate a minimally overlapping backup path when you hit Suggest Shortest Path.  Backup paths are optional.

Step 5: Scheduling

You can either immediately provision a circuit or you can schedule it to be added and or removed at a later date and time.  

Shown is an example where we are asking to provisioning immediately but remove later. 

Step 6: Provisioning

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


The interface ACL section displays a list of all of the interfaces owned by the 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 an interface in the Interfaces owned by this Workgroup table. The Interface ACL table will be created containing the rules. The rules are executed top to bottom. In the example below the Demo workgroup will be denied access to VLANs 100 to 300 and granted access to VLAN Ranges 1 through 99 and 301 through 4096 on the xe-5/0/1.0 interface . All other workgroups will have access to VLAN ranges 1 through 4096 on the xe-5/0/1.0 interface. Had the rules been in the reverse order the Demo workgroup would have been granted access to VLAN Ranges 1 through 4096 and the deny rule woudl be rendered moot since it would always match the allow rule first.

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
  • Permission - Whether this rule should allow or deny the workgroup access to the specified VLAN Range
  • VLAN Range - The range of VLANs that this rule should apply to. (The second field can be left blank to apply the rule to a single VLAN)
  • 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 row containing the rule to edit in the Interface ACL table. A dialog box 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.

Removing an ACL Rule

To remove an ACL Rule, click the row containing the rule to remove 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 ACL rules, click the Enable Reordering button below the Interface ACL table. After this button has been clicked, a row can be drag and dropped within the table to its new position. (ACL rules will not be able to be edited or removed until the Disable Reordering button is clicked).

Multipoint Static MAC Addresses

The multipoint static MAC address feature allows you to add devices' MAC addresses to each endpoint of a multipoint circuit. Traffic with a destination MAC address matching the defined MAC Addresses will be routed directly to the endpoint on which it was assigned as opposed to the default behaviour of sending the traffic to all of the endpoints.

Adding a Multipoint Circuit with Static MAC Routing

Start by clicking the Create a New VLAN link on the Actions panel. This will bring you to the Basic Details page in the circuit provisioning process. Click the Multipoint Static MAC Routing radio button to enable the feature. Click the Proceed to Step 2: Endpoints button at the top of the page and follow the steps below for adding, editing, and removing static mac enabled endpoints. The remainder of the circuit editing and provisioning process is unchanged from any other circuit.

Adding a Static MAC Enabled Endpoint

To add a static mac enabled endpoint start by clicking a node from the network map. This will result in a list of interfaces generated to the right of the map. Click an interface to create the interface add panel. The panel will allow you to choose a vlan tag and add mac addresses to the endpoint. To add a mac addresses to the endpoint enter the mac address in the input box to the left of the Add MAC Address button and then click the Add MAC Address button. The mac address will be added to the table above that consists of all the mac addresses to be associated with the endpoint. Once you have selected the vlan tag and added all the mac addresses you wish to be associated to the endpoint, click the Save button to add the endpoint to the circuit.

Editing/Removing a Static MAC Enabled Endpoint

To edit a static mac enabled endpoint, click the Edit button in the far right column in the Endpoints table. This will display the endpoint edit panel underneath the corresponding row in the table. The value of the vlan tag can be changed in the VLAN Tag input box. MAC addresses can be removed from the endpoint by clicking the Delete button in the right column of the table containing the mac addresses currently associated with the endpoint. New mac addresses can be associated to the circuit by entering the mac address in the input box to the left of the Add MAC Address button and then clicking the Add MAC Address button. Click the Save button to apply any changes.

To remove a static mac enabled endpoint, click the Edit button in the far right column in the Endpoints table. This will display the endpoint edit panel underneath the corresponding row in the table. Now click the Remove button at the bottom of the panel.

Trunk Edge Circuit Terminations

If you are in a use case in which you are maintaining a hybrid network, a trunk edge circuit termination is a useful way to transmit traffic from an OESS controlled segment of the network to a segement under another controller.

Setting up a Trunk Edge Circuit Termination

To begin creation of a circuit with trunk edge circuit, 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, and select an interface with a Trunk role.

After that is set up, go into the workgroups 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 endpoint where you added the trunk interface to. There must be at least one trunk interface the trunk edge circuit termination to work.

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