OpenFlow v1.2 Messages and Structures

Controller-to-Switch Messages

Handshake

class os_ken.ofproto.ofproto_v1_2_parser.OFPFeaturesRequest(datapath)

Features request message

The controller sends a feature request to the switch upon session establishment.

This message is handled by the OSKen framework, so the OSKen application do not need to process this typically.

Example:

def send_features_request(self, datapath):
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPFeaturesRequest(datapath)
    datapath.send_msg(req)

JSON Example:

{
   "OFPFeaturesRequest": {}
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPSwitchFeatures(datapath, datapath_id=None, n_buffers=None, n_tables=None, capabilities=None, ports=None)

Features reply message

The switch responds with a features reply message to a features request.

This message is handled by the OSKen framework, so the OSKen application do not need to process this typically.

Example:

@set_ev_cls(ofp_event.EventOFPSwitchFeatures, CONFIG_DISPATCHER)
def switch_features_handler(self, ev):
    msg = ev.msg

    self.logger.debug('OFPSwitchFeatures received: '
                      'datapath_id=0x%016x n_buffers=%d '
                      'n_tables=%d capabilities=0x%08x ports=%s',
                      msg.datapath_id, msg.n_buffers, msg.n_tables,
                      msg.capabilities, msg.ports)

JSON Example:

{
   "OFPSwitchFeatures": {
      "capabilities": 79, 
      "datapath_id": 9210263729383, 
      "n_buffers": 0, 
      "n_tables": 255, 
      "ports": {
         "6": {
            "OFPPort": {
               "advertised": 10240, 
               "config": 0, 
               "curr": 10248, 
               "curr_speed": 5000, 
               "hw_addr": "f2:0b:a4:7d:f8:ea", 
               "max_speed": 5000, 
               "name": "Port6", 
               "peer": 10248, 
               "port_no": 6, 
               "state": 4, 
               "supported": 10248
            }
         }, 
         "7": {
            "OFPPort": {
               "advertised": 10240, 
               "config": 0, 
               "curr": 10248, 
               "curr_speed": 5000, 
               "hw_addr": "f2:0b:a4:d0:3f:70", 
               "max_speed": 5000, 
               "name": "Port7", 
               "peer": 10248, 
               "port_no": 7, 
               "state": 4, 
               "supported": 10248
            }
         }
      }
   }
}

Switch Configuration

class os_ken.ofproto.ofproto_v1_2_parser.OFPSetConfig(datapath, flags=0, miss_send_len=0)

Set config request message

The controller sends a set config request message to set configuraion parameters.

Attribute	Description
flags	One of the following configuration flags. OFPC_FRAG_NORMAL OFPC_FRAG_DROP OFPC_FRAG_REASM OFPC_FRAG_MASK OFPC_INVALID_TTL_TO_CONTROLLER
miss_send_len	Max bytes of new flow that datapath should send to the controller

Example:

def send_set_config(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPSetConfig(datapath, ofp.OFPC_FRAG_NORMAL, 256)
    datapath.send_msg(req)

JSON Example:

{
   "OFPSetConfig": {
      "flags": 0, 
      "miss_send_len": 128
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPGetConfigRequest(datapath)

Get config request message

The controller sends a get config request to query configuration parameters in the switch.

Example:

def send_get_config_request(self, datapath):
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPGetConfigRequest(datapath)
    datapath.send_msg(req)

JSON Example:

{
   "OFPGetConfigRequest": {}
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPGetConfigReply(datapath, flags=None, miss_send_len=None)

Get config reply message

The switch responds to a configuration request with a get config reply message.

Attribute	Description
flags	One of the following configuration flags. OFPC_FRAG_NORMAL OFPC_FRAG_DROP OFPC_FRAG_REASM OFPC_FRAG_MASK OFPC_INVALID_TTL_TO_CONTROLLER
miss_send_len	Max bytes of new flow that datapath should send to the controller

Example:

@set_ev_cls(ofp_event.EventOFPGetConfigReply, MAIN_DISPATCHER)
def get_config_reply_handler(self, ev):
    msg = ev.msg
    dp = msg.datapath
    ofp = dp.ofproto

    if msg.flags == ofp.OFPC_FRAG_NORMAL:
        flags = 'NORMAL'
    elif msg.flags == ofp.OFPC_FRAG_DROP:
        flags = 'DROP'
    elif msg.flags == ofp.OFPC_FRAG_REASM:
        flags = 'REASM'
    elif msg.flags == ofp.OFPC_FRAG_MASK:
        flags = 'MASK'
    elif msg.flags == ofp.OFPC_INVALID_TTL_TO_CONTROLLER:
        flags = 'INVALID TTL TO CONTROLLER'
    else:
        flags = 'unknown'
    self.logger.debug('OFPGetConfigReply received: '
                      'flags=%s miss_send_len=%d',
                      flags, msg.miss_send_len)

JSON Example:

{
   "OFPGetConfigReply": {
      "flags": 0, 
      "miss_send_len": 128
   }
}

Flow Table Configuration

class os_ken.ofproto.ofproto_v1_2_parser.OFPTableMod(datapath, table_id, config)

Flow table configuration message

The controller sends this message to configure table state.

Attribute	Description
table_id	ID of the table (OFPTT_ALL indicates all tables)
config	Bitmap of the following flags. OFPTC_TABLE_MISS_CONTROLLER OFPTC_TABLE_MISS_CONTINUE OFPTC_TABLE_MISS_DROP OFPTC_TABLE_MISS_MASK

Example:

def send_table_mod(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPTableMod(datapath, ofp.OFPTT_ALL,
                                 ofp.OFPTC_TABLE_MISS_DROP)
    datapath.send_msg(req)

JSON Example:

{
   "OFPTableMod": {
      "config": 0, 
      "table_id": 255
   }
}

Modify State Messages

class os_ken.ofproto.ofproto_v1_2_parser.OFPFlowMod(datapath, cookie=0, cookie_mask=0, table_id=0, command=0, idle_timeout=0, hard_timeout=0, priority=0, buffer_id=4294967295, out_port=0, out_group=0, flags=0, match=None, instructions=None)

Modify Flow entry message

The controller sends this message to modify the flow table.

Attribute	Description
cookie	Opaque controller-issued identifier
cookie_mask	Mask used to restrict the cookie bits that must match when the command is OPFFC_MODIFY* or OFPFC_DELETE*
table_id	ID of the table to put the flow in
command	One of the following values. OFPFC_ADD OFPFC_MODIFY OFPFC_MODIFY_STRICT OFPFC_DELETE OFPFC_DELETE_STRICT
idle_timeout	Idle time before discarding (seconds)
hard_timeout	Max time before discarding (seconds)
priority	Priority level of flow entry
buffer_id	Buffered packet to apply to (or OFP_NO_BUFFER)
out_port	For OFPFC_DELETE* commands, require matching entries to include this as an output port
out_group	For OFPFC_DELETE* commands, require matching entries to include this as an output group
flags	One of the following values. OFPFF_SEND_FLOW_REM OFPFF_CHECK_OVERLAP OFPFF_RESET_COUNTS
match	Instance of OFPMatch
instructions	list of OFPInstruction* instance

Example:

def send_flow_mod(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    cookie = cookie_mask = 0
    table_id = 0
    idle_timeout = hard_timeout = 0
    priority = 32768
    buffer_id = ofp.OFP_NO_BUFFER
    match = ofp_parser.OFPMatch(in_port=1, eth_dst='ff:ff:ff:ff:ff:ff')
    actions = [ofp_parser.OFPActionOutput(ofp.OFPP_NORMAL, 0)]
    inst = [ofp_parser.OFPInstructionActions(ofp.OFPIT_APPLY_ACTIONS,
                                             actions)]
    req = ofp_parser.OFPFlowMod(datapath, cookie, cookie_mask,
                                table_id, ofp.OFPFC_ADD,
                                idle_timeout, hard_timeout,
                                priority, buffer_id,
                                ofp.OFPP_ANY, ofp.OFPG_ANY,
                                ofp.OFPFF_SEND_FLOW_REM,
                                match, inst)
    datapath.send_msg(req)

JSON Example:

{
   "OFPFlowMod": {
      "buffer_id": 65535, 
      "command": 0, 
      "cookie": 0, 
      "cookie_mask": 0, 
      "flags": 0, 
      "hard_timeout": 0, 
      "idle_timeout": 0, 
      "instructions": [
         {
            "OFPInstructionActions": {
               "actions": [
                  {
                     "OFPActionSetField": {
                        "field": {
                           "OXMTlv": {
                              "field": "vlan_vid", 
                              "mask": null, 
                              "value": 258
                           }
                        },
                        "len": 16,
                        "type": 25
                     }
                  }, 
                  {
                     "OFPActionOutput": {
                        "len": 16, 
                        "max_len": 65535, 
                        "port": 6, 
                        "type": 0
                     }
                  }
               ], 
               "len": 40, 
               "type": 3
            }
         }, 
         {
            "OFPInstructionActions": {
               "actions": [
                  {
                     "OFPActionSetField": {
                        "field": {
                           "OXMTlv": {
                              "field": "eth_src", 
                              "mask": null, 
                              "value": "01:02:03:04:05:06"
                           }
                        },
                        "len": 16,
                        "type": 25
                     }
                  }
               ], 
               "len": 24, 
               "type": 4
            }
         }
      ], 
      "match": {
         "OFPMatch": {
            "length": 14, 
            "oxm_fields": [
               {
                  "OXMTlv": {
                     "field": "eth_dst", 
                     "mask": null, 
                     "value": "f2:0b:a4:7d:f8:ea"
                  }
               }
            ], 
            "type": 1
         }
      }, 
      "out_group": 4294967295, 
      "out_port": 4294967295, 
      "priority": 123, 
      "table_id": 1
   }
}

{
   "OFPFlowMod": {
      "buffer_id": 65535, 
      "command": 0, 
      "cookie": 0, 
      "cookie_mask": 0, 
      "flags": 0, 
      "hard_timeout": 0, 
      "idle_timeout": 0, 
      "instructions": [
         {
            "OFPInstructionGotoTable": {
               "len": 8, 
               "table_id": 1, 
               "type": 1
            }
         }
      ], 
      "match": {
         "OFPMatch": {
            "length": 22, 
            "oxm_fields": [
               {
                  "OXMTlv": {
                     "field": "in_port", 
                     "mask": null, 
                     "value": 6
                  }
               }, 
               {
                  "OXMTlv": {
                     "field": "eth_src", 
                     "mask": null, 
                     "value": "f2:0b:a4:7d:f8:ea"
                  }
               }
            ], 
            "type": 1
         }
      }, 
      "out_group": 4294967295, 
      "out_port": 4294967295, 
      "priority": 123, 
      "table_id": 0
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPGroupMod(datapath, command=0, type_=0, group_id=0, buckets=None)

Modify group entry message

The controller sends this message to modify the group table.

Attribute	Description
command	One of the following values. OFPGC_ADD OFPGC_MODIFY OFPGC_DELETE
type	One of the following values. OFPGT_ALL OFPGT_SELECT OFPGT_INDIRECT OFPGT_FF
group_id	Group identifier
buckets	list of OFPBucket

type attribute corresponds to type_ parameter of __init__.

Example:

def send_group_mod(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    port = 1
    max_len = 2000
    actions = [ofp_parser.OFPActionOutput(port, max_len)]

    weight = 100
    watch_port = 0
    watch_group = 0
    buckets = [ofp_parser.OFPBucket(weight, watch_port, watch_group,
                                    actions)]

    group_id = 1
    req = ofp_parser.OFPGroupMod(datapath, ofp.OFPGC_ADD,
                                 ofp.OFPGT_SELECT, group_id, buckets)
    datapath.send_msg(req)

JSON Example:

{
   "OFPGroupMod": {
      "buckets": [
         {
            "OFPBucket": {
               "actions": [
                  {
                     "OFPActionOutput": {
                        "len": 16, 
                        "max_len": 65535, 
                        "port": 2, 
                        "type": 0
                     }
                  }
               ], 
               "len": 32, 
               "watch_group": 1, 
               "watch_port": 1, 
               "weight": 1
            }
         }
      ], 
      "command": 0, 
      "group_id": 1, 
      "type": 0
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPPortMod(datapath, port_no=0, hw_addr='00:00:00:00:00:00', config=0, mask=0, advertise=0)

Port modification message

The controller sneds this message to modify the behavior of the port.

Attribute	Description
port_no	Port number to modify
hw_addr	The hardware address that must be the same as hw_addr of OFPPort of OFPSwitchFeatures
config	Bitmap of configuration flags. OFPPC_PORT_DOWN OFPPC_NO_RECV OFPPC_NO_FWD OFPPC_NO_PACKET_IN
mask	Bitmap of configuration flags above to be changed
advertise	Bitmap of the following flags. OFPPF_10MB_HD OFPPF_10MB_FD OFPPF_100MB_HD OFPPF_100MB_FD OFPPF_1GB_HD OFPPF_1GB_FD OFPPF_10GB_FD OFPPF_40GB_FD OFPPF_100GB_FD OFPPF_1TB_FD OFPPF_OTHER OFPPF_COPPER OFPPF_FIBER OFPPF_AUTONEG OFPPF_PAUSE OFPPF_PAUSE_ASYM

Example:

def send_port_mod(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    port_no = 3
    hw_addr = 'fa:c8:e8:76:1d:7e'
    config = 0
    mask = (ofp.OFPPC_PORT_DOWN | ofp.OFPPC_NO_RECV |
            ofp.OFPPC_NO_FWD | ofp.OFPPC_NO_PACKET_IN)
    advertise = (ofp.OFPPF_10MB_HD | ofp.OFPPF_100MB_FD |
                 ofp.OFPPF_1GB_FD | ofp.OFPPF_COPPER |
                 ofp.OFPPF_AUTONEG | ofp.OFPPF_PAUSE |
                 ofp.OFPPF_PAUSE_ASYM)
    req = ofp_parser.OFPPortMod(datapath, port_no, hw_addr, config,
                                mask, advertise)
    datapath.send_msg(req)

JSON Example:

{
   "OFPPortMod": {
      "advertise": 4096, 
      "config": 0, 
      "hw_addr": "00-11-00-00-11-11", 
      "mask": 0, 
      "port_no": 1
   }
}

Read State Messages

class os_ken.ofproto.ofproto_v1_2_parser.OFPDescStatsRequest(datapath, flags=0)

Description statistics request message

The controller uses this message to query description of the switch.

Attribute	Description
flags	Zero (none yet defined in the spec)

Example:

def send_desc_stats_request(self, datapath):
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPDescStatsRequest(datapath)
    datapath.send_msg(req)

JSON Example:

{
   "OFPDescStatsRequest": {
      "flags": 0
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPDescStats(mfr_desc, hw_desc, sw_desc, serial_num, dp_desc)

Description statistics reply message

The switch responds with a stats reply that include this message to a description statistics request.

Attribute	Description
mfr_desc	Manufacturer description
hw_desc	Hardware description
sw_desc	Software description
serial_num	Serial number
dp_desc	Human readable description of datapath

Example:

@set_ev_cls(ofp_event.EventOFPStatsReply, MAIN_DISPATCHER)
def stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.body

    if msg.type == ofp.OFPST_DESC:
        self.desc_stats_reply_handler(body)

def desc_stats_reply_handler(self, body):
    self.logger.debug('DescStats: mfr_desc=%s hw_desc=%s sw_desc=%s '
                      'serial_num=%s dp_desc=%s',
                      body.mfr_desc, body.hw_desc, body.sw_desc,
                      body.serial_num, body.dp_desc)

JSON Example:

{
   "OFPStatsReply": {
      "body": {
         "OFPDescStats": {
            "dp_desc": "dp", 
            "hw_desc": "hw", 
            "mfr_desc": "mfr", 
            "serial_num": "serial", 
            "sw_desc": "sw"
         }
      }, 
      "flags": 0, 
      "type": 0
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPFlowStatsRequest(datapath, table_id=255, out_port=4294967295, out_group=4294967295, cookie=0, cookie_mask=0, match=None, flags=0)

Individual flow statistics request message

The controller uses this message to query individual flow statistics.

Attribute	Description
table_id	ID of table to read
out_port	Require matching entries to include this as an output port
out_group	Require matching entries to include this as an output group
cookie	Require matching entries to contain this cookie value
cookie_mask	Mask used to restrict the cookie bits that must match
match	Instance of OFPMatch
flags	Zero (none yet defined in the spec)

Example:

def send_flow_stats_request(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    cookie = cookie_mask = 0
    match = ofp_parser.OFPMatch(in_port=1)
    req = ofp_parser.OFPFlowStatsRequest(datapath,
                                         ofp.OFPTT_ALL,
                                         ofp.OFPP_ANY, ofp.OFPG_ANY,
                                         cookie, cookie_mask, match)
    datapath.send_msg(req)

JSON Example:

{
   "OFPFlowStatsRequest": {
      "cookie": 0, 
      "cookie_mask": 0, 
      "flags": 0, 
      "match": {
         "OFPMatch": {
            "length": 4, 
            "oxm_fields": [], 
            "type": 1
         }
      }, 
      "out_group": 4294967295, 
      "out_port": 4294967295, 
      "table_id": 0
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPFlowStats(table_id, duration_sec, duration_nsec, priority, idle_timeout, hard_timeout, cookie, packet_count, byte_count, match, instructions=None, length=None)

Individual flow statistics reply message

The switch responds with a stats reply that include this message to an individual flow statistics request.

Attribute	Description
table_id	ID of table flow came from
duration_sec	Time flow has been alive in seconds
duration_nsec	Time flow has been alive in nanoseconds beyond duration_sec
priority	Priority of the entry
idle_timeout	Number of seconds idle before expiration
hard_timeout	Number of seconds before expiration
cookie	Opaque controller-issued identifier
packet_count	Number of packets in flow
byte_count	Number of bytes in flow
match	Instance of OFPMatch
instructions	list of OFPInstruction* instance

Example:

@set_ev_cls(ofp_event.EventOFPStatsReply, MAIN_DISPATCHER)
def stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.body

    if msg.type == ofp.OFPST_FLOW:
         self.flow_stats_reply_handler(body)

def flow_stats_reply_handler(self, body):
    flows = []
    for stat in body:
        flows.append('table_id=%s '
                     'duration_sec=%d duration_nsec=%d '
                     'priority=%d '
                     'idle_timeout=%d hard_timeout=%d '
                     'cookie=%d packet_count=%d byte_count=%d '
                     'match=%s instructions=%s' %
                     (stat.table_id,
                      stat.duration_sec, stat.duration_nsec,
                      stat.priority,
                      stat.idle_timeout, stat.hard_timeout,
                      stat.cookie, stat.packet_count, stat.byte_count,
                      stat.match, stat.instructions))
    self.logger.debug('FlowStats: %s', flows)

JSON Example:

{
   "OFPStatsReply": {
      "body": [
         {
            "OFPFlowStats": {
               "byte_count": 0, 
               "cookie": 0, 
               "duration_nsec": 115277000, 
               "duration_sec": 358, 
               "hard_timeout": 0, 
               "idle_timeout": 0, 
               "instructions": [], 
               "length": 56, 
               "match": {
                  "OFPMatch": {
                     "length": 4, 
                     "oxm_fields": [], 
                     "type": 1
                  }
               }, 
               "packet_count": 0, 
               "priority": 65535, 
               "table_id": 0
            }
         }, 
         {
            "OFPFlowStats": {
               "byte_count": 0, 
               "cookie": 0, 
               "duration_nsec": 115055000, 
               "duration_sec": 358, 
               "hard_timeout": 0, 
               "idle_timeout": 0, 
               "instructions": [
                  {
                     "OFPInstructionActions": {
                        "actions": [
                           {
                              "OFPActionOutput": {
                                 "len": 16, 
                                 "max_len": 0, 
                                 "port": 4294967290, 
                                 "type": 0
                              }
                           }
                        ], 
                        "len": 24, 
                        "type": 4
                     }
                  }
               ], 
               "length": 88, 
               "match": {
                  "OFPMatch": {
                     "length": 10, 
                     "oxm_fields": [
                        {
                           "OXMTlv": {
                              "field": "eth_type", 
                              "mask": null, 
                              "value": 2054
                           }
                        }
                     ], 
                     "type": 1
                  }
               }, 
               "packet_count": 0, 
               "priority": 65534, 
               "table_id": 0
            }
         }, 
         {
            "OFPFlowStats": {
               "byte_count": 238, 
               "cookie": 0, 
               "duration_nsec": 511582000, 
               "duration_sec": 316220, 
               "hard_timeout": 0, 
               "idle_timeout": 0, 
               "instructions": [
                  {
                     "OFPInstructionGotoTable": {
                        "len": 8, 
                        "table_id": 1, 
                        "type": 1
                     }
                  }
               ], 
               "length": 80, 
               "match": {
                  "OFPMatch": {
                     "length": 22, 
                     "oxm_fields": [
                        {
                           "OXMTlv": {
                              "field": "in_port", 
                              "mask": null, 
                              "value": 6
                           }
                        }, 
                        {
                           "OXMTlv": {
                              "field": "eth_src", 
                              "mask": null, 
                              "value": "f2:0b:a4:7d:f8:ea"
                           }
                        }
                     ], 
                     "type": 1
                  }
               }, 
               "packet_count": 3, 
               "priority": 123, 
               "table_id": 0
            }
         }, 
         {
            "OFPFlowStats": {
               "byte_count": 98, 
               "cookie": 0, 
               "duration_nsec": 980901000, 
               "duration_sec": 313499, 
               "hard_timeout": 0, 
               "idle_timeout": 0, 
               "instructions": [
                  {
                     "OFPInstructionActions": {
                        "actions": [
                           {
                              "OFPActionOutput": {
                                 "len": 16, 
                                 "max_len": 65535, 
                                 "port": 4294967293, 
                                 "type": 0
                              }
                           }
                        ], 
                        "len": 24, 
                        "type": 3
                     }
                  }
               ], 
               "length": 80, 
               "match": {
                  "OFPMatch": {
                     "length": 4, 
                     "oxm_fields": [], 
                     "type": 1
                  }
               }, 
               "packet_count": 1, 
               "priority": 0, 
               "table_id": 0
            }
         }
      ], 
      "flags": 0, 
      "type": 1
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPAggregateStatsRequest(datapath, table_id=255, out_port=4294967295, out_group=4294967295, cookie=0, cookie_mask=0, match=None, flags=0)

Aggregate flow statistics request message

The controller uses this message to query aggregate flow statictics.

Attribute	Description
table_id	ID of table to read
out_port	Require matching entries to include this as an output port
out_group	Require matching entries to include this as an output group
cookie	Require matching entries to contain this cookie value
cookie_mask	Mask used to restrict the cookie bits that must match
match	Instance of OFPMatch
flags	Zero (none yet defined in the spec)

Example:

def send_aggregate_stats_request(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    cookie = cookie_mask = 0
    match = ofp_parser.OFPMatch(in_port=1)
    req = ofp_parser.OFPAggregateStatsRequest(datapath, 0,
                                              ofp.OFPTT_ALL,
                                              ofp.OFPP_ANY,
                                              ofp.OFPG_ANY,
                                              cookie, cookie_mask,
                                              match)
    datapath.send_msg(req)

JSON Example:

{
   "OFPAggregateStatsRequest": {
      "cookie": 0, 
      "cookie_mask": 0, 
      "flags": 0, 
      "match": {
         "OFPMatch": {
            "length": 4, 
            "oxm_fields": [], 
            "type": 1
         }
      }, 
      "out_group": 4294967295, 
      "out_port": 4294967295, 
      "table_id": 255
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPAggregateStatsReply(packet_count, byte_count, flow_count)

Aggregate flow statistics reply message

The switch responds with a stats reply that include this message to an aggregate flow statistics request.

Attribute	Description
packet_count	Number of packets in flows
byte_count	Number of bytes in flows
flow_count	Number of flows

Example:

@set_ev_cls(ofp_event.EventOFPStatsReply, MAIN_DISPATCHER)
def stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.body

    if msg.type == ofp.OFPST_AGGREGATE:
        self.aggregate_stats_reply_handler(body)

def aggregate_stats_reply_handler(self, body):
    self.logger.debug('AggregateStats: packet_count=%d byte_count=%d '
                      'flow_count=%d',
                      body.packet_count, body.byte_count,
                      body.flow_count)

JSON Example:

{
   "OFPStatsReply": {
      "body": {
         "OFPAggregateStatsReply": {
            "byte_count": 574, 
            "flow_count": 6, 
            "packet_count": 7
         }
      }, 
      "flags": 0, 
      "type": 2
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPTableStatsRequest(datapath, flags=0)

Table statistics request message

The controller uses this message to query flow table statictics.

Attribute	Description
flags	Zero (none yet defined in the spec)

Example:

def send_table_stats_request(self, datapath):
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPTableStatsRequest(datapath)
    datapath.send_msg(req)

JSON Example:

{
   "OFPTableStatsRequest": {
      "flags": 0
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPTableStats(table_id, name, match, wildcards, write_actions, apply_actions, write_setfields, apply_setfields, metadata_match, metadata_write, instructions, config, max_entries, active_count, lookup_count, matched_count)

Table statistics reply message

The switch responds with a stats reply that include this message to a table statistics request.

Attribute	Description
table_id	ID of table
name	table name
match	Bitmap of (1 << OFPXMT_*) that indicate the fields the table can match on
wildcards	Bitmap of (1 << OFPXMT_*) wildcards that are supported by the table
write_actions	Bitmap of OFPAT_* that are supported by the table with OFPIT_WRITE_ACTIONS
apply_actions	Bitmap of OFPAT_* that are supported by the table with OFPIT_APPLY_ACTIONS
write_setfields	Bitmap of (1 << OFPXMT_*) header fields that can be set with OFPIT_WRITE_ACTIONS
apply_setfields	Bitmap of (1 << OFPXMT_*) header fields that can be set with OFPIT_APPLY_ACTIONS
metadata_match	Bits of metadata table can match
metadata_write	Bits of metadata table can write
instructions	Bitmap of OFPIT_* values supported
config	Bitmap of OFPTC_* values
max_entries	Max number of entries supported
active_count	Number of active entries
lookup_count	Number of packets looked up in table
matched_count	Number of packets that hit table

Example:

@set_ev_cls(ofp_event.EventOFPStatsReply, MAIN_DISPATCHER)
def stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.body

    if msg.type == ofp.OFPST_TABLE:
        self.table_stats_reply_handler(body)

def table_stats_reply_handler(self, body):
    tables = []
    for stat in body:
        tables.append('table_id=%d active_count=%d lookup_count=%d '
                      ' matched_count=%d' %
                      (stat.table_id, stat.active_count,
                       stat.lookup_count, stat.matched_count))
    self.logger.debug('TableStats: %s', tables)

class os_ken.ofproto.ofproto_v1_2_parser.OFPPortStatsRequest(datapath, port_no=4294967295, flags=0)

Port statistics request message

The controller uses this message to query information about ports statistics.

Attribute	Description
port_no	Port number to read (OFPP_ANY to all ports)
flags	Zero (none yet defined in the spec)

Example:

def send_port_stats_request(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPPortStatsRequest(datapath, ofp.OFPP_ANY)
    datapath.send_msg(req)

JSON Example:

{
   "OFPPortStatsRequest": {
      "flags": 0, 
      "port_no": 4294967295
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPPortStats(port_no, rx_packets, tx_packets, rx_bytes, tx_bytes, rx_dropped, tx_dropped, rx_errors, tx_errors, rx_frame_err, rx_over_err, rx_crc_err, collisions)

Port statistics reply message

The switch responds with a stats reply that include this message to a port statistics request.

Attribute	Description
port_no	Port number
rx_packets	Number of received packets
tx_packets	Number of transmitted packets
rx_bytes	Number of received bytes
tx_bytes	Number of transmitted bytes
rx_dropped	Number of packets dropped by RX
tx_dropped	Number of packets dropped by TX
rx_errors	Number of receive errors
tx_errors	Number of transmit errors
rx_frame_err	Number of frame alignment errors
rx_over_err	Number of packet with RX overrun
rx_crc_err	Number of CRC errors
collisions	Number of collisions

Example:

@set_ev_cls(ofp_event.EventOFPStatsReply, MAIN_DISPATCHER)
def stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.body

    if msg.type == ofp.OFPST_PORT:
        self.port_stats_reply_handler(body)

def port_stats_reply_handler(self, body):
    ports = []
    for stat in body:
        ports.append('port_no=%d '
                     'rx_packets=%d tx_packets=%d '
                     'rx_bytes=%d tx_bytes=%d '
                     'rx_dropped=%d tx_dropped=%d '
                     'rx_errors=%d tx_errors=%d '
                     'rx_frame_err=%d rx_over_err=%d rx_crc_err=%d '
                     'collisions=%d' %
                     (stat.port_no,
                      stat.rx_packets, stat.tx_packets,
                      stat.rx_bytes, stat.tx_bytes,
                      stat.rx_dropped, stat.tx_dropped,
                      stat.rx_errors, stat.tx_errors,
                      stat.rx_frame_err, stat.rx_over_err,
                      stat.rx_crc_err, stat.collisions))
    self.logger.debug('PortStats: %s', ports)

JSON Example:

{
   "OFPStatsReply": {
      "body": [
         {
            "OFPPortStats": {
               "collisions": 0, 
               "port_no": 7, 
               "rx_bytes": 0, 
               "rx_crc_err": 0, 
               "rx_dropped": 0, 
               "rx_errors": 0, 
               "rx_frame_err": 0, 
               "rx_over_err": 0, 
               "rx_packets": 0, 
               "tx_bytes": 336, 
               "tx_dropped": 0, 
               "tx_errors": 0, 
               "tx_packets": 4
            }
         }, 
         {
            "OFPPortStats": {
               "collisions": 0, 
               "port_no": 6, 
               "rx_bytes": 336, 
               "rx_crc_err": 0, 
               "rx_dropped": 0, 
               "rx_errors": 0, 
               "rx_frame_err": 0, 
               "rx_over_err": 0, 
               "rx_packets": 4, 
               "tx_bytes": 336, 
               "tx_dropped": 0, 
               "tx_errors": 0, 
               "tx_packets": 4
            }
         }
      ], 
      "flags": 0, 
      "type": 4
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPQueueStatsRequest(datapath, port_no=4294967295, queue_id=4294967295, flags=0)

Queue statistics request message

The controller uses this message to query queue statictics.

Attribute	Description
port_no	Port number to read
queue_id	ID of queue to read
flags	Zero (none yet defined in the spec)

Example:

def send_queue_stats_request(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPQueueStatsRequest(datapath, ofp.OFPP_ANY,
                                          ofp.OFPQ_ALL)
    datapath.send_msg(req)

JSON Example:

{
   "OFPQueueStatsRequest": {
      "flags": 0, 
      "port_no": 4294967295, 
      "queue_id": 4294967295
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPQueueStats(port_no, queue_id, tx_bytes, tx_packets, tx_errors)

Queue statistics reply message

The switch responds with a stats reply that include this message to an aggregate flow statistics request.

Attribute	Description
port_no	Port number
queue_id	ID of queue
tx_bytes	Number of transmitted bytes
tx_packets	Number of transmitted packets
tx_errors	Number of packets dropped due to overrun

Example:

@set_ev_cls(ofp_event.EventOFPStatsReply, MAIN_DISPATCHER)
def stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.body

    if msg.type == ofp.OFPST_QUEUE:
        self.queue_stats_reply_handler(body)

def queue_stats_reply_handler(self, body):
    queues = []
    for stat in body:
        queues.append('port_no=%d queue_id=%d '
                      'tx_bytes=%d tx_packets=%d tx_errors=%d ' %
                      (stat.port_no, stat.queue_id,
                       stat.tx_bytes, stat.tx_packets, stat.tx_errors))
    self.logger.debug('QueueStats: %s', queues)

JSON Example:

{
   "OFPStatsReply": {
      "body": [
         {
            "OFPQueueStats": {
               "port_no": 7, 
               "queue_id": 1, 
               "tx_bytes": 0, 
               "tx_errors": 0, 
               "tx_packets": 0
            }
         }, 
         {
            "OFPQueueStats": {
               "port_no": 6, 
               "queue_id": 1, 
               "tx_bytes": 0, 
               "tx_errors": 0, 
               "tx_packets": 0
            }
         }, 
         {
            "OFPQueueStats": {
               "port_no": 7, 
               "queue_id": 2, 
               "tx_bytes": 0, 
               "tx_errors": 0, 
               "tx_packets": 0
            }
         }
      ], 
      "flags": 0, 
      "type": 5
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPGroupStatsRequest(datapath, group_id=4294967292, flags=0)

Group statistics request message

The controller uses this message to query statistics of one or more groups.

Attribute	Description
group_id	ID of group to read (OFPG_ALL to all groups)
flags	Zero (none yet defined in the spec)

Example:

def send_group_stats_request(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPGroupStatsRequest(datapath, ofp.OFPG_ALL)
    datapath.send_msg(req)

class os_ken.ofproto.ofproto_v1_2_parser.OFPGroupStats(group_id, ref_count, packet_count, byte_count, bucket_counters, length=None)

Group statistics reply message

The switch responds with a stats reply that include this message to a group statistics request.

Attribute	Description
group_id	Group identifier
ref_count	Number of flows or groups that directly forward to this group
packet_count	Number of packets processed by group
byte_count	Number of bytes processed by group
bucket_counters	List of OFPBucketCounter instance

Example:

@set_ev_cls(ofp_event.EventOFPStatsReply, MAIN_DISPATCHER)
def stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.body

    if msg.type == ofp.OFPST_GROUP:
        self.group_stats_reply_handler(body)

def group_stats_reply_handler(self, body):
    groups = []
    for stat in body:
        groups.append('group_id=%d ref_count=%d packet_count=%d '
                      'byte_count=%d bucket_counters=%s' %
                      (stat.group_id,
                       stat.ref_count, stat.packet_count,
                       stat.byte_count, stat.bucket_counters))
    self.logger.debug('GroupStats: %s', groups)

class os_ken.ofproto.ofproto_v1_2_parser.OFPGroupDescStatsRequest(datapath, flags=0)

Group description request message

The controller uses this message to list the set of groups on a switch.

Attribute	Description
flags	Zero (none yet defined in the spec)

Example:

def send_group_desc_stats_request(self, datapath):
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPGroupDescStatsRequest(datapath)
    datapath.send_msg(req)

JSON Example:

{
   "OFPGroupDescStatsRequest": {
      "flags": 0
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPGroupDescStats(type_, group_id, buckets, length=None)

Group description reply message

The switch responds with a stats reply that include this message to a group description request.

Attribute	Description
type	One of OFPGT_*
group_id	Group identifier
buckets	List of OFPBucket instance

type attribute corresponds to type_ parameter of __init__.

Example:

@set_ev_cls(ofp_event.EventOFPStatsReply, MAIN_DISPATCHER)
def stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.body

    if msg.type == ofp.OFPST_GROUP_DESC:
        self.group_desc_stats_reply_handler(body)

def group_desc_stats_reply_handler(self, body):
    descs = []
    for stat in body:
        descs.append('type=%d group_id=%d buckets=%s' %
                     (stat.type, stat.group_id, stat.buckets))
    self.logger.debug('GroupDescStats: %s', descs)

JSON Example:

{
   "OFPStatsReply": {
      "body": [
         {
            "OFPGroupDescStats": {
               "buckets": [
                  {
                     "OFPBucket": {
                        "actions": [
                           {
                              "OFPActionOutput": {
                                 "len": 16, 
                                 "max_len": 65535, 
                                 "port": 2, 
                                 "type": 0
                              }
                           }
                        ], 
                        "len": 32, 
                        "watch_group": 1, 
                        "watch_port": 1, 
                        "weight": 1
                     }
                  }
               ], 
               "group_id": 1, 
               "length": 40, 
               "type": 0
            }
         }
      ], 
      "flags": 0, 
      "type": 7
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPGroupFeaturesStatsRequest(datapath, flags=0)

Group features request message

The controller uses this message to list the capabilities of groups on a switch.

Attribute	Description
flags	Zero (none yet defined in the spec)

Example:

def send_group_features_stats_request(self, datapath):
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPGroupFeaturesStatsRequest(datapath)
    datapath.send_msg(req)

JSON Example:

{
   "OFPGroupFeaturesStatsRequest": {
      "flags": 0
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPGroupFeaturesStats(types, capabilities, max_groups, actions, length=None)

Group features reply message

The switch responds with a stats reply that include this message to a group features request.

Attribute	Description
types	Bitmap of OFPGT_* values supported
capabilities	Bitmap of OFPGFC_* capability supported
max_groups	Maximum number of groups for each type
actions	Bitmaps of OFPAT_* that are supported

Example:

@set_ev_cls(ofp_event.EventOFPStatsReply, MAIN_DISPATCHER)
def stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.body

    if msg.type == ofp.OFPST_GROUP_FEATURES:
        self.group_features_stats_reply_handler(body)

def group_features_stats_reply_handler(self, body):
    self.logger.debug('GroupFeaturesStats: types=%d '
                      'capabilities=0x%08x max_groups=%s '
                      'actions=%s',
                      body.types, body.capabilities, body.max_groups,
                      body.actions)

JSON Example:

{
   "OFPStatsReply": {
      "body": {
         "OFPGroupFeaturesStats": {
            "actions": [
               67082241, 
               67082241, 
               67082241, 
               67082241
            ], 
            "capabilities": 5, 
            "length": 40, 
            "max_groups": [
               16777216, 
               16777216, 
               16777216, 
               16777216
            ], 
            "types": 15
         }
      }, 
      "flags": 0, 
      "type": 8
   }
}

Queue Configuration Messages

class os_ken.ofproto.ofproto_v1_2_parser.OFPQueueGetConfigRequest(datapath, port)

Queue configuration request message

Attribute	Description
port	Port to be queried (OFPP_ANY to all configured queues)

Example:

def send_queue_get_config_request(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPQueueGetConfigRequest(datapath, ofp.OFPP_ANY)
    datapath.send_msg(req)

JSON Example:

{
   "OFPQueueGetConfigRequest": {
      "port": 4294967295
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPQueueGetConfigReply(datapath, port=None, queues=None)

Queue configuration reply message

The switch responds with this message to a queue configuration request.

Attribute	Description
port	Port which was queried
queues	list of OFPPacketQueue instance

Example:

@set_ev_cls(ofp_event.EventOFPQueueGetConfigReply, MAIN_DISPATCHER)
def queue_get_config_reply_handler(self, ev):
    msg = ev.msg

    self.logger.debug('OFPQueueGetConfigReply received: '
                      'port=%s queues=%s',
                      msg.port, msg.queues)

JSON Example:

{
   "OFPQueueGetConfigReply": {
      "port": 4294967295, 
      "queues": [
         {
            "OFPPacketQueue": {
               "len": 48, 
               "port": 77, 
               "properties": [
                  {
                     "OFPQueuePropMinRate": {
                        "len": 16, 
                        "property": 1, 
                        "rate": 10
                     }
                  }, 
                  {
                     "OFPQueuePropMaxRate": {
                        "len": 16, 
                        "property": 2, 
                        "rate": 900
                     }
                  }
               ], 
               "queue_id": 99
            }
         }, 
         {
            "OFPPacketQueue": {
               "len": 48, 
               "port": 77, 
               "properties": [
                  {
                     "OFPQueuePropMinRate": {
                        "len": 16, 
                        "property": 1, 
                        "rate": 100
                     }
                  }, 
                  {
                     "OFPQueuePropMaxRate": {
                        "len": 16, 
                        "property": 2, 
                        "rate": 200
                     }
                  }
               ], 
               "queue_id": 88
            }
         }
      ]
   }
}

Packet-Out Message

class os_ken.ofproto.ofproto_v1_2_parser.OFPPacketOut(datapath, buffer_id=None, in_port=None, actions=None, data=None, actions_len=None)

Packet-Out message

The controller uses this message to send a packet out throught the switch.

Attribute	Description
buffer_id	ID assigned by datapath (OFP_NO_BUFFER if none)
in_port	Packet's input port or OFPP_CONTROLLER
actions	list of OpenFlow action class
data	Packet data of a binary type value or an instances of packet.Packet.

Example:

def send_packet_out(self, datapath, buffer_id, in_port):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    actions = [ofp_parser.OFPActionOutput(ofp.OFPP_FLOOD, 0)]
    req = ofp_parser.OFPPacketOut(datapath, buffer_id,
                                  in_port, actions)
    datapath.send_msg(req)

JSON Example:

{
   "OFPPacketOut": {
      "actions": [
         {
            "OFPActionOutput": {
               "len": 16, 
               "max_len": 65535, 
               "port": 4294967292, 
               "type": 0
            }
         }
      ], 
      "actions_len": 16, 
      "buffer_id": 4294967295, 
      "data": "8guk0D9w8gukffjqCABFAABU+BoAAP8Br4sKAAABCgAAAggAAgj3YAAAMdYCAAAAAACrjS0xAAAAABAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vAAAAAAAAAAA=", 
      "in_port": 4294967293
   }
}

Barrier Message

class os_ken.ofproto.ofproto_v1_2_parser.OFPBarrierRequest(datapath)

Barrier request message

The controller sends this message to ensure message dependencies have been met or receive notifications for completed operations.

Example:

def send_barrier_request(self, datapath):
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPBarrierRequest(datapath)
    datapath.send_msg(req)

JSON Example:

{
   "OFPBarrierRequest": {}
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPBarrierReply(datapath)

Barrier reply message

The switch responds with this message to a barrier request.

Example:

@set_ev_cls(ofp_event.EventOFPBarrierReply, MAIN_DISPATCHER)
def barrier_reply_handler(self, ev):
    self.logger.debug('OFPBarrierReply received')

JSON Example:

{
   "OFPBarrierReply": {}
}

Role Request Message

class os_ken.ofproto.ofproto_v1_2_parser.OFPRoleRequest(datapath, role, generation_id)

Role request message

The controller uses this message to change its role.

Attribute	Description
role	One of the following values. OFPCR_ROLE_NOCHANGE OFPCR_ROLE_EQUAL OFPCR_ROLE_MASTER OFPCR_ROLE_SLAVE
generation_id	Master Election Generation ID

Example:

def send_role_request(self, datapath):
    ofp = datapath.ofproto
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPRoleRequest(datapath, ofp.OFPCR_ROLE_EQUAL, 0)
    datapath.send_msg(req)

JSON Example:

{
   "OFPRoleRequest": {
      "generation_id": 17294086455919964160, 
      "role": 2
   }
}

class os_ken.ofproto.ofproto_v1_2_parser.OFPRoleReply(datapath, role=None, generation_id=None)

Role reply message

The switch responds with this message to a role request.

Attribute	Description
role	One of the following values. OFPCR_ROLE_NOCHANGE OFPCR_ROLE_EQUAL OFPCR_ROLE_MASTER OFPCR_ROLE_SLAVE
generation_id	Master Election Generation ID

Example:

@set_ev_cls(ofp_event.EventOFPRoleReply, MAIN_DISPATCHER)
def role_reply_handler(self, ev):
    msg = ev.msg
    dp = msg.datapath
    ofp = dp.ofproto

    if msg.role == ofp.OFPCR_ROLE_NOCHANGE:
        role = 'NOCHANGE'
    elif msg.role == ofp.OFPCR_ROLE_EQUAL:
        role = 'EQUAL'
    elif msg.role == ofp.OFPCR_ROLE_MASTER:
        role = 'MASTER'
    elif msg.role == ofp.OFPCR_ROLE_SLAVE:
        role = 'SLAVE'
    else:
        role = 'unknown'

    self.logger.debug('OFPRoleReply received: '
                      'role=%s generation_id=%d',
                      role, msg.generation_id)

JSON Example:

{
   "OFPRoleReply": {
      "generation_id": 17294086455919964160, 
      "role": 3
   }
}

Asynchronous Messages

Packet-In Message

class os_ken.ofproto.ofproto_v1_2_parser.OFPPacketIn(datapath, buffer_id=None, total_len=None, reason=None, table_id=None, match=None, data=None)

Packet-In message

The switch sends the packet that received to the controller by this message.

Attribute	Description
buffer_id	ID assigned by datapath
total_len	Full length of frame
reason	Reason packet is being sent. OFPR_NO_MATCH OFPR_ACTION OFPR_INVALID_TTL
table_id	ID of the table that was looked up
match	Instance of OFPMatch
data	Ethernet frame

Example:

@set_ev_cls(ofp_event.EventOFPPacketIn, MAIN_DISPATCHER)
def packet_in_handler(self, ev):
    msg = ev.msg
    dp = msg.datapath
    ofp = dp.ofproto

    if msg.reason == ofp.OFPR_NO_MATCH:
        reason = 'NO MATCH'
    elif msg.reason == ofp.OFPR_ACTION:
        reason = 'ACTION'
    elif msg.reason == ofp.OFPR_INVALID_TTL:
        reason = 'INVALID TTL'
    else:
        reason = 'unknown'

    self.logger.debug('OFPPacketIn received: '
                      'buffer_id=%x total_len=%d reason=%s '
                      'table_id=%d match=%s data=%s',
                      msg.buffer_id, msg.total_len, reason,
                      msg.table_id, msg.match,
                      utils.hex_array(msg.data))

JSON Example:

{
   "OFPPacketIn": {
      "buffer_id": 2, 
      "data": "////////8gukffjqCAYAAQgABgQAAfILpH346goAAAEAAAAAAAAKAAAD", 
      "match": {
         "OFPMatch": {
            "length": 80, 
            "oxm_fields": [
               {
                  "OXMTlv": {
                     "field": "in_port", 
                     "mask": null, 
                     "value": 6
                  }
               }, 
               {
                  "OXMTlv": {
                     "field": "eth_type", 
                     "mask": null, 
                     "value": 2054
                  }
               }, 
               {
                  "OXMTlv": {
                     "field": "eth_dst", 
                     "mask": null, 
                     "value": "ff:ff:ff:ff:ff:ff"
                  }
               }, 
               {
                  "OXMTlv": {
                     "field": "eth_src", 
                     "mask": null, 
                     "value": "f2:0b:a4:7d:f8:ea"
                  }
               }, 
               {
                  "OXMTlv": {
                     "field": "arp_op", 
                     "mask": null, 
                     "value": 1
                  }
               }, 
               {
                  "OXMTlv": {
                     "field": "arp_spa", 
                     "mask": null, 
                     "value": "10.0.0.1"
                  }
               }, 
               {
                  "OXMTlv": {
                     "field": "arp_tpa", 
                     "mask": null, 
                     "value": "10.0.0.3"
                  }
               }, 
               {
                  "OXMTlv": {
                     "field": "arp_sha", 
                     "mask": null, 
                     "value": "f2:0b:a4:7d:f8:ea"
                  }
               }, 
               {
                  "OXMTlv": {
                     "field": "arp_tha", 
                     "mask": null, 
                     "value": "00:00:00:00:00:00"
                  }
               }
            ], 
            "type": 1
         }
      }, 
      "reason": 1, 
      "table_id": 1, 
      "total_len": 42
   }
}

Flow Removed Message

class os_ken.ofproto.ofproto_v1_2_parser.OFPFlowRemoved(datapath, cookie=None, priority=None, reason=None, table_id=None, duration_sec=None, duration_nsec=None, idle_timeout=None, hard_timeout=None, packet_count=None, byte_count=None, match=None)

Flow removed message

When flow entries time out or are deleted, the switch notifies controller with this message.

Attribute	Description
cookie	Opaque controller-issued identifier
priority	Priority level of flow entry
reason	One of the following values. OFPRR_IDLE_TIMEOUT OFPRR_HARD_TIMEOUT OFPRR_DELETE OFPRR_GROUP_DELETE
table_id	ID of the table
duration_sec	Time flow was alive in seconds
duration_nsec	Time flow was alive in nanoseconds beyond duration_sec
idle_timeout	Idle timeout from original flow mod
hard_timeout	Hard timeout from original flow mod
packet_count	Number of packets that was associated with the flow
byte_count	Number of bytes that was associated with the flow
match	Instance of OFPMatch

Example:

@set_ev_cls(ofp_event.EventOFPFlowRemoved, MAIN_DISPATCHER)
def flow_removed_handler(self, ev):
    msg = ev.msg
    dp = msg.datapath
    ofp = dp.ofproto

    if msg.reason == ofp.OFPRR_IDLE_TIMEOUT:
        reason = 'IDLE TIMEOUT'
    elif msg.reason == ofp.OFPRR_HARD_TIMEOUT:
        reason = 'HARD TIMEOUT'
    elif msg.reason == ofp.OFPRR_DELETE:
        reason = 'DELETE'
    elif msg.reason == ofp.OFPRR_GROUP_DELETE:
        reason = 'GROUP DELETE'
    else:
        reason = 'unknown'

    self.logger.debug('OFPFlowRemoved received: '
                      'cookie=%d priority=%d reason=%s table_id=%d '
                      'duration_sec=%d duration_nsec=%d '
                      'idle_timeout=%d hard_timeout=%d '
                      'packet_count=%d byte_count=%d match.fields=%s',
                      msg.cookie, msg.priority, reason, msg.table_id,
                      msg.duration_sec, msg.duration_nsec,
                      msg.idle_timeout, msg.hard_timeout,
                      msg.packet_count, msg.byte_count, msg.match)

JSON Example:

{
   "OFPFlowRemoved": {
      "byte_count": 86, 
      "cookie": 0, 
      "duration_nsec": 48825000, 
      "duration_sec": 3, 
      "hard_timeout": 0, 
      "idle_timeout": 3, 
      "match": {
         "OFPMatch": {
            "length": 14, 
            "oxm_fields": [
               {
                  "OXMTlv": {
                     "field": "eth_dst", 
                     "mask": null, 
                     "value": "f2:0b:a4:7d:f8:ea"
                  }
               }
            ], 
            "type": 1
         }
      }, 
      "packet_count": 1, 
      "priority": 65535, 
      "reason": 0, 
      "table_id": 0
   }
}

Port Status Message

class os_ken.ofproto.ofproto_v1_2_parser.OFPPortStatus(datapath, reason=None, desc=None)

Port status message

The switch notifies controller of change of ports.

Attribute	Description
reason	One of the following values. OFPPR_ADD OFPPR_DELETE OFPPR_MODIFY
desc	instance of OFPPort

Example:

@set_ev_cls(ofp_event.EventOFPPortStatus, MAIN_DISPATCHER)
def port_status_handler(self, ev):
    msg = ev.msg
    dp = msg.datapath
    ofp = dp.ofproto

    if msg.reason == ofp.OFPPR_ADD:
        reason = 'ADD'
    elif msg.reason == ofp.OFPPR_DELETE:
        reason = 'DELETE'
    elif msg.reason == ofp.OFPPR_MODIFY:
        reason = 'MODIFY'
    else:
        reason = 'unknown'

    self.logger.debug('OFPPortStatus received: reason=%s desc=%s',
                      reason, msg.desc)

JSON Example:

{
   "OFPPortStatus": {
      "desc": {
         "OFPPort": {
            "advertised": 10240, 
            "config": 0, 
            "curr": 10248, 
            "curr_speed": 5000, 
            "hw_addr": "f2:0b:a4:d0:3f:70", 
            "max_speed": 5000, 
            "name": "\u79c1\u306e\u30dd\u30fc\u30c8", 
            "peer": 10248, 
            "port_no": 7, 
            "state": 4, 
            "supported": 10248
         }
      }, 
      "reason": 0
   }
}

Error Message

class os_ken.ofproto.ofproto_v1_2_parser.OFPErrorMsg(datapath, type_=None, code=None, data=None, **kwargs)

Error message

The switch notifies controller of problems by this message.

Attribute	Description
type	High level type of error
code	Details depending on the type
data	Variable length data depending on the type and code

type attribute corresponds to type_ parameter of __init__.

Types and codes are defined in os_ken.ofproto.ofproto.

Type	Code
OFPET_HELLO_FAILED	OFPHFC_*
OFPET_BAD_REQUEST	OFPBRC_*
OFPET_BAD_ACTION	OFPBAC_*
OFPET_BAD_INSTRUCTION	OFPBIC_*
OFPET_BAD_MATCH	OFPBMC_*
OFPET_FLOW_MOD_FAILED	OFPFMFC_*
OFPET_GROUP_MOD_FAILED	OFPGMFC_*
OFPET_PORT_MOD_FAILED	OFPPMFC_*
OFPET_TABLE_MOD_FAILED	OFPTMFC_*
OFPET_QUEUE_OP_FAILED	OFPQOFC_*
OFPET_SWITCH_CONFIG_FAILED	OFPSCFC_*
OFPET_ROLE_REQUEST_FAILED	OFPRRFC_*
OFPET_EXPERIMENTER	N/A

If type == OFPET_EXPERIMENTER, this message has also the following attributes.

Attribute	Description
exp_type	Experimenter defined type
experimenter	Experimenter ID

Example:

@set_ev_cls(ofp_event.EventOFPErrorMsg,
            [HANDSHAKE_DISPATCHER, CONFIG_DISPATCHER, MAIN_DISPATCHER])
def error_msg_handler(self, ev):
    msg = ev.msg

    self.logger.debug('OFPErrorMsg received: type=0x%02x code=0x%02x '
                      'message=%s',
                      msg.type, msg.code, utils.hex_array(msg.data))

JSON Example:

{
   "OFPErrorMsg": {
      "code": 11, 
      "data": "ZnVnYWZ1Z2E=", 
      "type": 2
   }
}

{
   "OFPErrorMsg": {
      "code": null,
      "data": "amlra2VuIGRhdGE=",
      "exp_type": 60000,
      "experimenter": 999999,
      "type": 65535
   }
}

Symmetric Messages

Hello

class os_ken.ofproto.ofproto_v1_2_parser.OFPHello(datapath)

Hello message

When connection is started, the hello message is exchanged between a switch and a controller.

This message is handled by the OSKen framework, so the OSKen application do not need to process this typically.

JSON Example:

{
   "OFPHello": {}
}

Echo Request

class os_ken.ofproto.ofproto_v1_2_parser.OFPEchoRequest(datapath, data=None)

Echo request message

This message is handled by the OSKen framework, so the OSKen application do not need to process this typically.

Attribute	Description
data	An arbitrary length data

Example:

def send_echo_request(self, datapath, data):
    ofp_parser = datapath.ofproto_parser

    req = ofp_parser.OFPEchoRequest(datapath, data)
    datapath.send_msg(req)

@set_ev_cls(ofp_event.EventOFPEchoRequest,
            [HANDSHAKE_DISPATCHER, CONFIG_DISPATCHER, MAIN_DISPATCHER])
def echo_request_handler(self, ev):
    self.logger.debug('OFPEchoRequest received: data=%s',
                      utils.hex_array(ev.msg.data))

JSON Example:

{
   "OFPEchoRequest": {
      "data": "aG9nZQ=="
   }
}

Echo Reply

class os_ken.ofproto.ofproto_v1_2_parser.OFPEchoReply(datapath, data=None)

Echo reply message

This message is handled by the OSKen framework, so the OSKen application do not need to process this typically.

Attribute	Description
data	An arbitrary length data

Example:

def send_echo_reply(self, datapath, data):
    ofp_parser = datapath.ofproto_parser

    reply = ofp_parser.OFPEchoReply(datapath, data)
    datapath.send_msg(reply)

@set_ev_cls(ofp_event.EventOFPEchoReply,
            [HANDSHAKE_DISPATCHER, CONFIG_DISPATCHER, MAIN_DISPATCHER])
def echo_reply_handler(self, ev):
    self.logger.debug('OFPEchoReply received: data=%s',
                      utils.hex_array(ev.msg.data))

JSON Example:

{
   "OFPEchoReply": {
      "data": "aG9nZQ=="
   }
}

Experimenter

class os_ken.ofproto.ofproto_v1_2_parser.OFPExperimenter(datapath, experimenter=None, exp_type=None, data=None)

Experimenter extension message

Attribute	Description
experimenter	Experimenter ID
exp_type	Experimenter defined
data	Experimenter defined arbitrary additional data

JSON Example:

{
   "OFPExperimenter": {
      "data": "bmF6bw==", 
      "exp_type": 123456789, 
      "experimenter": 98765432
   }
}

Port Structures

class os_ken.ofproto.ofproto_v1_2_parser.OFPPort(port_no, hw_addr, name, config, state, curr, advertised, supported, peer, curr_speed, max_speed)

Description of a port

Attribute	Description
port_no	Port number and it uniquely identifies a port within a switch.
hw_addr	MAC address for the port.
name	Null-terminated string containing a human-readable name for the interface.
config	Bitmap of port configration flags. OFPPC_PORT_DOWN OFPPC_NO_RECV OFPPC_NO_FWD OFPPC_NO_PACKET_IN
state	Bitmap of port state flags. OFPPS_LINK_DOWN OFPPS_BLOCKED OFPPS_LIVE
curr	Current features.
advertised	Features being advertised by the port.
supported	Features supported by the port.
peer	Features advertised by peer.
curr_speed	Current port bitrate in kbps.
max_speed	Max port bitrate in kbps.

Flow Match Structure

class os_ken.ofproto.ofproto_v1_2_parser.OFPMatch(type_=None, length=None, _ordered_fields=None, **kwargs)

Flow Match Structure

This class is implementation of the flow match structure having compose/query API. There are new API and old API for compatibility. the old API is supposed to be removed later.

You can define the flow match by the keyword arguments. The following arguments are available.

Argument	Value	Description
in_port	Integer 32bit	Switch input port
in_phy_port	Integer 32bit	Switch physical input port
metadata	Integer 64bit	Metadata passed between tables
eth_dst	MAC address	Ethernet destination address
eth_src	MAC address	Ethernet source address
eth_type	Integer 16bit	Ethernet frame type
vlan_vid	Integer 16bit	VLAN id
vlan_pcp	Integer 8bit	VLAN priority
ip_dscp	Integer 8bit	IP DSCP (6 bits in ToS field)
ip_ecn	Integer 8bit	IP ECN (2 bits in ToS field)
ip_proto	Integer 8bit	IP protocol
ipv4_src	IPv4 address	IPv4 source address
ipv4_dst	IPv4 address	IPv4 destination address
tcp_src	Integer 16bit	TCP source port
tcp_dst	Integer 16bit	TCP destination port
udp_src	Integer 16bit	UDP source port
udp_dst	Integer 16bit	UDP destination port
sctp_src	Integer 16bit	SCTP source port
sctp_dst	Integer 16bit	SCTP destination port
icmpv4_type	Integer 8bit	ICMP type
icmpv4_code	Integer 8bit	ICMP code
arp_op	Integer 16bit	ARP opcode
arp_spa	IPv4 address	ARP source IPv4 address
arp_tpa	IPv4 address	ARP target IPv4 address
arp_sha	MAC address	ARP source hardware address
arp_tha	MAC address	ARP target hardware address
ipv6_src	IPv6 address	IPv6 source address
ipv6_dst	IPv6 address	IPv6 destination address
ipv6_flabel	Integer 32bit	IPv6 Flow Label
icmpv6_type	Integer 8bit	ICMPv6 type
icmpv6_code	Integer 8bit	ICMPv6 code
ipv6_nd_target	IPv6 address	Target address for ND
ipv6_nd_sll	MAC address	Source link-layer for ND
ipv6_nd_tll	MAC address	Target link-layer for ND
mpls_label	Integer 32bit	MPLS label
mpls_tc	Integer 8bit	MPLS TC
pbb_uca	Integer 8bit	PBB UCA header field (EXT-256 Old version of ONF Extension)
tcp_flags	Integer 16bit	TCP flags (EXT-109 ONF Extension)
actset_output	Integer 32bit	Output port from action set metadata (EXT-233 ONF Extension)

Example:

>>> # compose
>>> match = parser.OFPMatch(
...     in_port=1,
...     eth_type=0x86dd,
...     ipv6_src=('2001:db8:bd05:1d2:288a:1fc0:1:10ee',
...               'ffff:ffff:ffff:ffff::'),
...     ipv6_dst='2001:db8:bd05:1d2:288a:1fc0:1:10ee')
>>> # query
>>> if 'ipv6_src' in match:
...     print match['ipv6_src']
...
('2001:db8:bd05:1d2:288a:1fc0:1:10ee', 'ffff:ffff:ffff:ffff::')

Note

For the list of the supported Nicira experimenter matches, please refer to os_ken.ofproto.nx_match.

Note

For VLAN id match field, special values are defined in OpenFlow Spec.

1. Packets with and without a VLAN tag

   • Example:

     match = parser.OFPMatch()
     

   • Packet Matching

     non-VLAN-tagged	MATCH
     VLAN-tagged(vlan_id=3)	MATCH
     VLAN-tagged(vlan_id=5)	MATCH

2. Only packets without a VLAN tag

   • Example:

     match = parser.OFPMatch(vlan_vid=0x0000)
     

   • Packet Matching

     non-VLAN-tagged	MATCH
     VLAN-tagged(vlan_id=3)	x
     VLAN-tagged(vlan_id=5)	x

3. Only packets with a VLAN tag regardless of its value

   • Example:

     match = parser.OFPMatch(vlan_vid=(0x1000, 0x1000))
     

   • Packet Matching

     non-VLAN-tagged	x
     VLAN-tagged(vlan_id=3)	MATCH
     VLAN-tagged(vlan_id=5)	MATCH

4. Only packets with VLAN tag and VID equal

   • Example:

     match = parser.OFPMatch(vlan_vid=(0x1000 | 3))
     

   • Packet Matching

     non-VLAN-tagged	x
     VLAN-tagged(vlan_id=3)	MATCH
     VLAN-tagged(vlan_id=5)	x

Flow Instruction Structures

class os_ken.ofproto.ofproto_v1_2_parser.OFPInstructionGotoTable(table_id, type_=None, len_=None)

Goto table instruction

This instruction indicates the next table in the processing pipeline.

Attribute	Description
table_id	Next table

class os_ken.ofproto.ofproto_v1_2_parser.OFPInstructionWriteMetadata(metadata, metadata_mask, type_=None, len_=None)

Write metadata instruction

This instruction writes the masked metadata value into the metadata field.

Attribute	Description
metadata	Metadata value to write
metadata_mask	Metadata write bitmask

class os_ken.ofproto.ofproto_v1_2_parser.OFPInstructionActions(type_, actions=None, len_=None)

Actions instruction

This instruction writes/applies/clears the actions.

Attribute	Description
type	One of following values. OFPIT_WRITE_ACTIONS OFPIT_APPLY_ACTIONS OFPIT_CLEAR_ACTIONS
actions	list of OpenFlow action class

type attribute corresponds to type_ parameter of __init__.

Action Structures

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionOutput(port, max_len=65509, type_=None, len_=None)

Output action

This action indicates output a packet to the switch port.

Attribute	Description
port	Output port
max_len	Max length to send to controller

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionGroup(group_id=0, type_=None, len_=None)

Group action

This action indicates the group used to process the packet.

Attribute	Description
group_id	Group identifier

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionSetQueue(queue_id, type_=None, len_=None)

Set queue action

This action sets the queue id that will be used to map a flow to an already-configured queue on a port.

Attribute	Description
queue_id	Queue ID for the packets

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionSetMplsTtl(mpls_ttl, type_=None, len_=None)

Set MPLS TTL action

This action sets the MPLS TTL.

Attribute	Description
mpls_ttl	MPLS TTL

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionDecMplsTtl(type_=None, len_=None)

Decrement MPLS TTL action

This action decrements the MPLS TTL.

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionSetNwTtl(nw_ttl, type_=None, len_=None)

Set IP TTL action

This action sets the IP TTL.

Attribute	Description
nw_ttl	IP TTL

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionDecNwTtl(type_=None, len_=None)

Decrement IP TTL action

This action decrements the IP TTL.

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionCopyTtlOut(type_=None, len_=None)

Copy TTL Out action

This action copies the TTL from the next-to-outermost header with TTL to the outermost header with TTL.

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionCopyTtlIn(type_=None, len_=None)

Copy TTL In action

This action copies the TTL from the outermost header with TTL to the next-to-outermost header with TTL.

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionPushVlan(ethertype=33024, type_=None, len_=None)

Push VLAN action

This action pushes a new VLAN tag to the packet.

Attribute	Description
ethertype	Ether type. The default is 802.1Q. (0x8100)

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionPushMpls(ethertype=34887, type_=None, len_=None)

Push MPLS action

This action pushes a new MPLS header to the packet.

Attribute	Description
ethertype	Ether type

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionPopVlan(type_=None, len_=None)

Pop VLAN action

This action pops the outermost VLAN tag from the packet.

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionPopMpls(ethertype=2048, type_=None, len_=None)

Pop MPLS action

This action pops the MPLS header from the packet.

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionSetField(field=None, **kwargs)

Set field action

This action modifies a header field in the packet.

The set of keywords available for this is same as OFPMatch.

Example:

set_field = OFPActionSetField(eth_src="00:00:00:00:00:00")

class os_ken.ofproto.ofproto_v1_2_parser.OFPActionExperimenter(experimenter, type_=None, len_=None)

Experimenter action

This action is an extensible action for the experimenter.

Attribute	Description
experimenter	Experimenter ID

Note

For the list of the supported Nicira experimenter actions, please refer to os_ken.ofproto.nx_actions.