/
Static Entry Pusher API

Static Entry Pusher API

Jun 04, 2017

This guide is for Floodlight v1.0 and up. If you are using Floodlight v0.91 or earlier or are using a master copy downloaded prior to December 30, 2014, please consider upgrading to the latest release. Please refer to these instructions for help using the Static Flow Pusher for pre-v1.0 releases.

Floodlight master branch as of mid-June 2016 supports pushing groups in addition to flows! We encourage you to upgrade if you're interested in this feature.

Support for OpenFlow 1.5 matches, actions, and instructions has also been added.

Table of Contents

Naming of this Module

Since its inception, the Floodlight controller has provided the ability to install flow table entries via the REST API. This feature was originally debuted as the Static Flow Entry Pusher. However, many if not most developers and users simply referred to this module as the Static Flow Pusher. Now that the Static Flow Pusher also supports the installation of group table entries, the term "flow" in the name is misleading. Thus, going forward, the module will be referred to as the Static Entry Pusher. (Note that the term "static" is also misleading, as the module supports entries with timeouts, but this "non-static" feature is seldom used.)

What is the Static Entry Pusher?

The Static Entry Pusher is a Floodlight module, exposed via a REST API, that allows a user to manually insert flows and groups into an OpenFlow network.

Proactive vs Reactive Entry Insertion

OpenFlow supports two methods of entry insertion: proactive and reactive. Reactive entry insertion occurs when a packet reaches an OpenFlow switch without a matching flow. The packet is sent to the controller, which evaluates it, adds the appropriate entries, and lets the switch continue its forwarding. Alternatively, entries can be inserted proactively by the controller in switches before packets arrive. In the case of proactive flow insertion, the arriving packet will never be sent to the controller for evaluation since it matches the proactively-inserted flow.

Floodlight supports both mechanisms of entry insertion. The Static Entry Pusher is generally useful for proactive entry insertion.

Note that by default, Floodlight loads the Forwarding module which does reactive entry pushing. If you would like to exclusively use static entries, you must remove Forwarding from the floodlight.properties file.

How is the Static Entry Pusher Used?

API Summary

Multiple URIs are available in Floodlight master June 2016 and later. This is for backwards compatibility with folks who have northbound applications that use the URIs present in past controller versions.

Description 

URI

Arguments 

Description 

URI

Arguments 

Add/Delete entry

/wm/<module>/json

<module> see table below

List entries

/wm/<module>/list/<switch>/json

<module> see table below

<switch> is a valid switch DPID formatted as:

-- hex-string, e.g. "00:00:00:00:00:00:00:0c"

-- integer, e.g. "12"

-- keyword "all" for all switches

Clear entries

/wm/<module>/clear/<switch>/json

<module> see table below

<switch> is a valid switch DPID formatted as:

-- hex-string, e.g. "00:00:00:00:00:00:00:0c"

-- integer, e.g. "12"

-- keyword "all" for all switches

The evolution of the Static Entry Pusher module has resulted in modification of the URI over time. Hopefully "staticentrypusher" will stick going forward. Use the following in place of <module> based on your Floodlight version:

<module> in URI

Supported Controller Version(s)

staticentrypusher

master

staticflowpusher

v1.0 - v1.2; master (deprecated)

staticflowentrypusher

v0.91- (see old docs); master (deprecated)

Adding an Entry

The Static Entry Pusher is accessible via a REST API. To add a static entry, the user needs to define the entry in JSON format.

Adding a Flow

For example, to insert a flow on switch 1 that takes packets from port 1 and outputs them on port 2, you can compose the JSON string and simply use a curl command to send the HTTP POST to the controller. The second command will dump the flow so you can see it set.

curl -X POST -d '{"switch":"00:00:00:00:00:00:00:01", "name":"flow-mod-1", "cookie":"0", "priority":"32768", "in_port":"1","active":"true", "actions":"output=2"}' http://<controller_ip>:8080/wm/staticentrypusher/json

Adding a Group

To add a group, the process is very similar to adding a flow. Note the required "entry_type" field to tell the Static Entry Pusher that the data in your message represents a group, not a flow. (If unspecified, "entry_type" defaults to "flow".) Although OpenFlow does not define bucket IDs, a group entry must have a unique bucket ID per bucket to define ordering of the buckets. Buckets are ordered sequentially from lowest ID to highest ID.

curl -X POST -d '{"switch":"00:00:00:00:00:00:00:01", "entry_type":"group", "name":"group-mod-1", "active":"true", "group_type":"select", "group_id":"1", "group_buckets":[ {"bucket_id":"1", "bucket_watch_group":"any", "bucket_weight":"50", "bucket_actions":"output=2"}, {"bucket_id":"2", "bucket_watch_group":"any", "bucket_weight":"50", "bucket_actions":"output=3"} ]}' http://<controller_ip>:8080/wm/staticentrypusher/json

Listing Entries

To get a list of all static entries, the Static Entry Pusher REST API accepts an HTTP GET to the path specified in API Summary above. You can query for static flows on a per-switch basis or ask the controller for all static entries across all switches.

curl http://<controller_ip>:8080/wm/staticentrypusher/list/00:00:00:00:00:00:00:01/json curl http://<controller_ip>:8080/wm/staticentrypusher/list/all/json

Clearing Entries

To clear entries per switch or globally:

curl http://<controller_ip>:8080/wm/staticentrypusher/clear/00:00:00:00:00:00:00:01/json curl http://<controller_ip>:8080/wm/staticentrypusher/clear/all/json

Deleting Entries

To delete a static entry you send an HTTP DELETE that includes the name of the entry used during insertion.

curl -X DELETE -d '{"name":"flow-mod-1"}' http://<controller_ip>:8080/wm/staticentrypusher/json

Entry Composition

The syntax to compose a flow versus a group entry varies due to the different structure of each. To avoid presenting information in duplicate, this section first presents required and optional properties for both flow and group entries. The sections following this dive into properties only defined for flows and only defined for groups.

Common to Both Flow and Group Entries

The following tables define properties for both flow and group entries.

Required Entry Properties

Key

Value

Notes

name

<string>

Name of the entry.
This is used as the primary key for the entry.
The name must be globally unique.

switch

<switch DPID>

DPID of the switch to which this entry should be added.
xx:xx:xx:xx:xx:xx:xx:xx

entry_type

<string>

"flow" for flow entries (default; can omit key)

"group" for group entries (required)

Optional Entry Properties

Key

Value

Notes

active

<boolean>

"true" or "false"

Reserved Port Keywords

<reserved_port>

Notes

all

All switch ports

controller

Controller(s)

flood

All ports except ingress port and those disabled for flooding, e.g. by STP

in_port

Packet's ingress port

local

Local network stack of switch; i.e. to/from switch OS

normal

Process using switch's normal L2/L3 pipeline

any

Any switch port

Reserved Group Keywords

<reserved_group>

Notes

all

All switch groups

any

Any switch group

Optional Actions

Key 

Value

Prerequisite Matches

OpenFlow Versions

Notes

Key 

Value

Prerequisite Matches

OpenFlow Versions

Notes

output

<number> or <reserved_port>

 

all

No "drop" option. (Instead, specify no action to drop packets.)
Can be hexadecimal (with leading 0x) or decimal.

See table above for <reserved_port> values.

group

<number>

 

OpenFlow 1.1+

Can be hexadecimal (with leading 0x) or decimal.

enqueue

<number>:<number>

 

OpenFlow 1.0

First number is port number, second is queue ID.  
Can be hexadecimal (with leading 0x) or decimal.

set_queue

<number>

 

OpenFlow 1.1+

Can be hexadecimal (with leading 0x) or decimal.

strip_vlan

 

eth_vlan_vid = something

OpenFlow 1.0

 

set_vlan_vid

<number>

eth_vlan_vid = something 

OpenFlow 1.0

Can be hexadecimal (with leading 0x) or decimal.

set_vlan_pcp

<number>

eth_vlan_vid = something

all

Can be hexadecimal (with leading 0x) or decimal.

push_vlan

<eth-type-number>

 

OpenFlow 1.1+

Can be hexadecimal (with leading 0x) or decimal.

Must be followed by a separate action to set the VLAN VID.

pop_vlan

 

eth_vlan_vid = something

OpenFlow 1.1+

 

set_eth_src

<MAC address>

 

OpenFlow 1.0 - 1.1

xx:xx:xx:xx:xx:xx

set_eth_dst

<MAC address>

 

OpenFlow 1.0 - 1.1

xx:xx:xx:xx:xx:xx

set_ip_tos

<number>

eth_type = 0x0800 || 0x86dd

OpenFlow 1.0

Can be hexadecimal (with leading 0x) or decimal.

set_ip_ecn

<number>

eth_type = 0x0800 || 0x86dd

OpenFlow 1.1

Can be hexadecimal (with leading 0x) or decimal.

set_ipv4_src

<IPv4 address>

eth_type = 0x0800

OpenFlow 1.0 - 1.1

xx.xx.xx.xx

set_ipv4_dst

<IPv4 address>

eth_type = 0x0800

OpenFlow 1.0 - 1.1

xx.xx.xx.xx

set_ip_ttl

<number>

eth_type = 0x0800 || 0x86dd

OpenFlow 1.1+

Can be hexadecimal (with leading 0x) or decimal.

dec_ip_ttl

 

eth_type = 0x0800 || 0x86dd

OpenFlow 1.1+

Can be hexadecimal (with leading 0x) or decimal.

copy_ip_ttl_in

 

eth_type = 0x0800 || 0x86dd

OpenFlow 1.1+

 

copy_ip_ttl_out

 

eth_type = 0x0800 || 0x86dd

OpenFlow 1.1+

 

set_mpls_label

<number>

eth_type = 0x8847 || 0x8848

OpenFlow 1.1+

Can be hexadecimal (with leading 0x) or decimal.

set_mpls_tc

<number>

eth_type = 0x8847 || 0x8848

OpenFlow 1.1+

Can be hexadecimal (with leading 0x) or decimal.

set_mpls_ttl

<number>

eth_type = 0x8847 || 0x8848

OpenFlow 1.1+

Can be hexadecimal (with leading 0x) or decimal.

dec_mpls_ttl

 

eth_type = 0x8847 || 0x8848

OpenFlow 1.1+

 

push_mpls

<number>

 

OpenFlow 1.1+

Can be hexadecimal (with leading 0x) or decimal.

pop_mpls

<number>

eth_type = 0x8847 || 0x8848

OpenFlow 1.1+

Can be hexadecimal (with leading 0x) or decimal.

push_pbb

<number>

 

OpenFlow 1.1+

Can be hexadecimal (with leading 0x) or decimal.

pop_pbb

 

eth_type = 0x88e7

OpenFlow 1.1+

 

set_tp_src

<number>

ip_proto = 0x06 || 0x11 || 0x84

OpenFlow 1.0

Can be hexadecimal (with leading 0x) or decimal.

set_tp_dst

<number>

ip_proto = 0x06 || 0x11 || 0x84

OpenFlow 1.0

Can be hexadecimal (with leading 0x) or decimal.

set_field

<OXM->value>

See match table above.

OpenFlow 1.2+

e.g. "set_field=eth_src->00:11:22:33:44:55"

meter

<number>

 

OpenFlow 1.5+

Replaces "instruction_goto_meter"

Can be hexadecimal (with leading 0x) or decimal.

copy_field

<copy field>

 

OpenFlow 1.5+

JSON object.

See copy field table.

Flow Entries

The following tables define properties for flow entries only.

Optional Flow Entry Properties

Key

Value

Notes

priority

<number>

Default is 32767.
Max is 32767.

table

<number>

Default flow table is used if omitted.

idle_timeout

<number>

Default of zero, which is no-timeout.

hard_timeout

<number>

Default of zero, which is no-timeout.

cookie

<number>

Can be hexadecimal (with leading 0x) or decimal.

cookie_mask

<number>

Can be hexadecimal (with leading 0x) or decimal.

Optional Flow Entry Match Fields

Key 

Value 

Prerequisite Matches

OpenFlow Versions

Notes 

in_port

<number>

<reserved_port>

 

all

Switch port on which the packet is received.

Can be hexadecimal (with leading 0x) or decimal.

See reserved port table.

eth_type

<number>

 

all