OpenFlow v1.0 Messages and Structures

Controller-to-Switch Messages

Handshake

class ryu.ofproto.ofproto_v1_0_parser.OFPFeaturesRequest(datapath)

Features request message

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

This message is handled by the Ryu framework, so the Ryu 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 ryu.ofproto.ofproto_v1_0_parser.OFPSwitchFeatures(datapath, datapath_id=None, n_buffers=None, n_tables=None, capabilities=None, actions=None, ports=None)

Features reply message

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

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

Attribute	Description
datapath_id	Datapath unique ID.
n_buffers	Max packets buffered at once.
n_tables	Number of tables supported by datapath.
capabilities	Bitmap of capabilities flag. OFPC_FLOW_STATS OFPC_TABLE_STATS OFPC_PORT_STATS OFPC_STP OFPC_RESERVED OFPC_IP_REASM OFPC_QUEUE_STATS OFPC_ARP_MATCH_IP
actions	Bitmap of supported OFPAT_*.
ports	List of OFPPhyPort instances.

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": {
      "actions": 2115, 
      "capabilities": 169, 
      "datapath_id": 1095522080376, 
      "n_buffers": 0, 
      "n_tables": 255, 
      "ports": {
         "6": {
            "OFPPhyPort": {
               "advertised": 640, 
               "config": 0, 
               "curr": 648, 
               "hw_addr": "f2:0b:a4:7d:f8:ea", 
               "name": "Port6", 
               "peer": 648, 
               "port_no": 6, 
               "state": 2, 
               "supported": 648
            }
         }, 
         "7": {
            "OFPPhyPort": {
               "advertised": 640, 
               "config": 0, 
               "curr": 648, 
               "hw_addr": "f2:0b:a4:d0:3f:70", 
               "name": "Port7", 
               "peer": 648, 
               "port_no": 7, 
               "state": 16, 
               "supported": 648
            }
         }
      }
   }
}

Switch Configuration

class ryu.ofproto.ofproto_v1_0_parser.OFPSetConfig(datapath, flags=None, miss_send_len=None)

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
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)

class ryu.ofproto.ofproto_v1_0_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)

class ryu.ofproto.ofproto_v1_0_parser.OFPGetConfigReply(datapath)

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
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'
    else:
        flags = 'unknown'
    self.logger.debug('OFPGetConfigReply received: '
                      'flags=%s miss_send_len=%d',
                      flags, msg.miss_send_len)

Modify State Messages

class ryu.ofproto.ofproto_v1_0_parser.OFPFlowMod(datapath, match=None, cookie=0, command=0, idle_timeout=0, hard_timeout=0, priority=32768, buffer_id=4294967295, out_port=65535, flags=0, actions=None)

Modify Flow entry message

The controller sends this message to modify the flow table.

Attribute	Description
match	Instance of OFPMatch.
cookie	Opaque controller-issued identifier.
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 0xffffffff). Not meaningful for OFPFC_DELETE*.
out_port	For OFPFC_DELETE* commands, require matching entries to include this as an output port. A value of OFPP_NONE indicates no restriction.
flags	One of the following values. OFPFF_SEND_FLOW_REM OFPFF_CHECK_OVERLAP OFPFF_EMERG
actions	List of OFPAction* instance.

Example:

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

    match = ofp_parser.OFPMatch(in_port=1)
    cookie = 0
    command = ofp.OFPFC_ADD
    idle_timeout = hard_timeout = 0
    priority = 32768
    buffer_id = 0xffffffff
    out_port = ofproto.OFPP_NONE
    flags = 0
    actions = [ofp_parser.OFPActionOutput(ofp.OFPP_NORMAL, 0)]
    req = ofp_parser.OFPFlowMod(
        datapath, match, cookie, command, idle_timeout, hard_timeout,
        priority, buffer_id, out_port, flags, actions)
    datapath.send_msg(req)

JSON Example:

{
   "OFPFlowMod": {
      "actions": [
         {
            "OFPActionOutput": {
               "max_len": 65535, 
               "port": 6
            }
         }
      ], 
      "buffer_id": 65535, 
      "command": 0, 
      "cookie": 0, 
      "flags": 0, 
      "hard_timeout": 0, 
      "idle_timeout": 0, 
      "match": {
         "OFPMatch": {
            "dl_dst": "f2:0b:a4:7d:f8:ea",
            "dl_src": "00:00:00:00:00:00",
            "dl_type": 0, 
            "dl_vlan": 0, 
            "dl_vlan_pcp": 0, 
            "in_port": 0, 
            "nw_dst": "0.0.0.0",
            "nw_proto": 0, 
            "nw_src": "0.0.0.0",
            "nw_tos": 0, 
            "tp_dst": 0, 
            "tp_src": 0, 
            "wildcards": 4194295
         }
      }, 
      "out_port": 65532, 
      "priority": 123
   }
}

class ryu.ofproto.ofproto_v1_0_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 send 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 OFPPhyPort of OFPSwitchFeatures.
config	Bitmap of configuration flags. OFPPC_PORT_DOWN OFPPC_NO_STP OFPPC_NO_RECV OFPPC_NO_RECV_STP OFPPC_NO_FLOOD 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_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)

Queue Configuration Messages

class ryu.ofproto.ofproto_v1_0_parser.OFPQueueGetConfigRequest(datapath, port)

Queue configuration request message

Attribute	Description
port	Port to be queried. Should refer to a valid physical port (i.e. < OFPP_MAX).

Example:

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

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

class ryu.ofproto.ofproto_v1_0_parser.OFPQueueGetConfigReply(datapath)

Queue configuration reply message

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

Attribute	Description
port	Port to be 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)

Read State Messages

class ryu.ofproto.ofproto_v1_0_parser.OFPDescStatsRequest(datapath, flags)

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)

class ryu.ofproto.ofproto_v1_0_parser.OFPDescStatsReply(datapath)

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.EventOFPDescStatsReply, MAIN_DISPATCHER)
def desc_stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.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)

class ryu.ofproto.ofproto_v1_0_parser.OFPFlowStatsRequest(datapath, flags, match, table_id, out_port)

Individual flow statistics request message

The controller uses this message to query individual flow statistics.

Attribute	Description
flags	Zero (none yet defined in the spec).
match	Instance of OFPMatch.
table_id	ID of table to read (from ofp_table_stats), 0xff for all tables or 0xfe for emergency.
out_port	Require matching entries to include this as an output port. A value of OFPP_NONE indicates no restriction.

Example:

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

    match = ofp_parser.OFPMatch(in_port=1)
    table_id = 0xff
    out_port = ofp.OFPP_NONE
    req = ofp_parser.OFPFlowStatsRequest(
        datapath, 0, match, table_id, out_port)

    datapath.send_msg(req)

class ryu.ofproto.ofproto_v1_0_parser.OFPFlowStatsReply(datapath)

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.
match	Instance of OFPMatch.
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. Only meaningful when this is not an exact-match 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.
actions	List of OFPAction* instance

Example:

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

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

class ryu.ofproto.ofproto_v1_0_parser.OFPAggregateStatsRequest(datapath, flags, match, table_id, out_port)

Aggregate flow statistics request message

The controller uses this message to query aggregate flow statictics.

Attribute	Description
flags	Zero (none yet defined in the spec).
match	Fields to match.
table_id	ID of table to read (from ofp_table_stats) 0xff for all tables or 0xfe for emergency.
out_port	Require matching entries to include this as an output port. A value of OFPP_NONE indicates no restriction.

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, match, 0xff, ofp.OFPP_NONE)

    datapath.send_msg(req)

class ryu.ofproto.ofproto_v1_0_parser.OFPAggregateStatsReply(datapath)

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.EventOFPAggregateStatsReply, MAIN_DISPATCHER)
def aggregate_stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.body

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

class ryu.ofproto.ofproto_v1_0_parser.OFPTableStatsRequest(datapath, flags)

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)

class ryu.ofproto.ofproto_v1_0_parser.OFPTableStatsReply(datapath)

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.
wildcards	Bitmap of OFPFW_* wildcards that are supported by the table.
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.EventOFPTableStatsReply, MAIN_DISPATCHER)
def stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.body

    tables = []
    for stat in body:
        tables.append('table_id=%d name=%s wildcards=0x%02x '
                      'max_entries=%d active_count=%d '
                      'lookup_count=%d matched_count=%d' %
                      (stat.table_id, stat.name, stat.wildcards,
                       stat.max_entries, stat.active_count,
                       stat.lookup_count, stat.matched_count))
    self.logger.debug('TableStats: %s', tables)

class ryu.ofproto.ofproto_v1_0_parser.OFPPortStatsRequest(datapath, flags, port_no)

Port statistics request message

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

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

Example:

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

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

class ryu.ofproto.ofproto_v1_0_parser.OFPPortStatsReply(datapath)

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.EventOFPPortStatsReply, MAIN_DISPATCHER)
def port_stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.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)

class ryu.ofproto.ofproto_v1_0_parser.OFPQueueStatsRequest(datapath, flags, port_no, queue_id)

Queue statistics request message

The controller uses this message to query queue statictics.

Attribute	Description
flags	Zero (none yet defined in the spec)
port_no	Port number to read (All ports if OFPT_ALL).
queue_id	ID of queue to read (All queues if OFPQ_ALL).

Example:

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

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

class ryu.ofproto.ofproto_v1_0_parser.OFPQueueStatsReply(datapath)

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.EventOFPQueueStatsReply, MAIN_DISPATCHER)
def stats_reply_handler(self, ev):
    msg = ev.msg
    ofp = msg.datapath.ofproto
    body = ev.msg.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)

class ryu.ofproto.ofproto_v1_0_parser.OFPVendorStatsRequest(datapath, flags, vendor, specific_data=None)

Vendor statistics request message

The controller uses this message to query vendor-specific information of a switch.

class ryu.ofproto.ofproto_v1_0_parser.OFPVendorStatsReply(datapath)

Vendor statistics reply message

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

Send Packet Message

class ryu.ofproto.ofproto_v1_0_parser.OFPPacketOut(datapath, buffer_id=None, in_port=None, actions=None, data=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 (0xffffffff if none).
in_port	Packet's input port (OFPP_NONE if none).
actions	ist of OFPAction* instance.
data	Packet data of a binary type value or an instances of packet.Packet.

Example:

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

    buffer_id = 0xffffffff
    in_port = ofp.OFPP_NONE
    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": {
               "max_len": 65535, 
               "port": 65532
            }
         }
      ], 
      "buffer_id": 4294967295, 
      "data": "8guk0D9w8gukffjqCABFAABU+BoAAP8Br4sKAAABCgAAAggAAgj3YAAAMdYCAAAAAACrjS0xAAAAABAREhMUFRYXGBkaGxwdHh8gISIjJCUmJygpKissLS4vAAAAAAAAAAA=", 
      "in_port": 65533
   }
}

Barrier Message

class ryu.ofproto.ofproto_v1_0_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)

class ryu.ofproto.ofproto_v1_0_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')

Asynchronous Messages

Packet-In Message

class ryu.ofproto.ofproto_v1_0_parser.OFPPacketIn(datapath, buffer_id=None, total_len=None, in_port=None, reason=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.
in_port	Port on which frame was received.
reason	Reason packet is being sent. OFPR_NO_MATCH OFPR_ACTION OFPR_INVALID_TTL
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 in_port=%d, '
                      'reason=%s data=%s',
                      msg.buffer_id, msg.total_len, msg.in_port,
                      reason, utils.hex_array(msg.data))

JSON Example:

{
   "OFPPacketIn": {
      "buffer_id": 2, 
      "data": "////////8gukffjqCAYAAQgABgQAAfILpH346goAAAEAAAAAAAAKAAAD", 
      "in_port": 99, 
      "reason": 1, 
      "total_len": 42
   }
}

Flow Removed Message

class ryu.ofproto.ofproto_v1_0_parser.OFPFlowRemoved(datapath)

Flow removed message

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

Attribute	Description
match	Instance of OFPMatch.
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
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.
packet_count	Number of packets that was associated with the flow.
byte_count	Number of bytes that was associated with the flow.

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: '
                      'match=%s cookie=%d priority=%d reason=%s '
                      'duration_sec=%d duration_nsec=%d '
                      'idle_timeout=%d packet_count=%d byte_count=%d',
                      msg.match, msg.cookie, msg.priority, reason,
                      msg.duration_sec, msg.duration_nsec,
                      msg.idle_timeout, msg.packet_count,
                      msg.byte_count)

Port Status Message

class ryu.ofproto.ofproto_v1_0_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 OFPPhyPort

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)

Error Message

class ryu.ofproto.ofproto_v1_0_parser.OFPErrorMsg(datapath, type_=None, code=None, data=None)

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 ryu.ofproto.ofproto.

Type	Code
OFPET_HELLO_FAILED	OFPHFC_*
OFPET_BAD_REQUEST	OFPBRC_*
OFPET_BAD_ACTION	OFPBAC_*
OFPET_FLOW_MOD_FAILED	OFPFMFC_*
OFPET_PORT_MOD_FAILED	OFPPMFC_*
OFPET_QUEUE_OP_FAILED	OFPQOFC_*

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))

Symmetric Messages

Hello

class ryu.ofproto.ofproto_v1_0_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 Ryu framework, so the Ryu application do not need to process this typically.

Echo Request

class ryu.ofproto.ofproto_v1_0_parser.OFPEchoRequest(datapath, data=None)

Echo request message

This message is handled by the Ryu framework, so the Ryu 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)

Echo Reply

class ryu.ofproto.ofproto_v1_0_parser.OFPEchoReply(datapath, data=None)

Echo reply message

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

Attribute	Description
data	An arbitrary length data.

Example:

@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))

Vendor

class ryu.ofproto.ofproto_v1_0_parser.OFPVendor(datapath)

Vendor message

The controller send this message to send the vendor-specific information to a switch.

Port Structures

class ryu.ofproto.ofproto_v1_0_parser.OFPPhyPort

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_STP OFPPC_NO_RECV OFPPC_NO_RECV_STP OFPPC_NO_FLOOD OFPPC_NO_FWD OFPPC_NO_PACKET_IN
state	Bitmap of port state flags. OFPPS_LINK_DOWN OFPPS_STP_LISTEN OFPPS_STP_LEARN OFPPS_STP_FORWARD OFPPS_STP_BLOCK OFPPS_STP_MASK
curr	Current features.
advertised	Features being advertised by the port.
supported	Features supported by the port.
peer	Features advertised by peer.

Flow Match Structure

class ryu.ofproto.ofproto_v1_0_parser.OFPMatch(wildcards=None, in_port=None, dl_src=None, dl_dst=None, dl_vlan=None, dl_vlan_pcp=None, dl_type=None, nw_tos=None, nw_proto=None, nw_src=None, nw_dst=None, tp_src=None, tp_dst=None, nw_src_mask=32, nw_dst_mask=32)

Flow Match Structure

This class is implementation of the flow match structure having compose/query API.

Attribute	Description
wildcards	Wildcard fields.
(match fields)	For the available match fields, please refer to the following.

Argument	Value	Description
in_port	Integer 16bit	Switch input port.
dl_src	MAC address	Ethernet source address.
dl_dst	MAC address	Ethernet destination address.
dl_vlan	Integer 16bit	Input VLAN id.
dl_vlan_pcp	Integer 8bit	Input VLAN priority.
dl_type	Integer 16bit	Ethernet frame type.
nw_tos	Integer 8bit	IP ToS (actually DSCP field, 6 bits).
nw_proto	Integer 8bit	IP protocol or lower 8 bits of ARP opcode.
nw_src	IPv4 address	IP source address.
nw_dst	IPv4 address	IP destination address.
tp_src	Integer 16bit	TCP/UDP source port.
tp_dst	Integer 16bit	TCP/UDP destination port.
nw_src_mask	Integer 8bit	IP source address mask specified as IPv4 address prefix.
nw_dst_mask	Integer 8bit	IP destination address mask specified as IPv4 address prefix.

Example:

>>> # compose
>>> match = parser.OFPMatch(
...     in_port=1,
...     dl_type=0x0800,
...     dl_src='aa:bb:cc:dd:ee:ff',
...     nw_src='192.168.0.1')
>>> # query
>>> if 'nw_src' in match:
...     print match['nw_src']
...
'192.168.0.1'

Action Structures

class ryu.ofproto.ofproto_v1_0_parser.OFPActionHeader(type_, len_)

class ryu.ofproto.ofproto_v1_0_parser.OFPAction

class ryu.ofproto.ofproto_v1_0_parser.OFPActionOutput(port, max_len=65509)

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.

Note::

The reason of this magic number (0xffe5) is because there is no good constant in of1.0. The same value as OFPCML_MAX of of1.2 and of1.3 is used.

class ryu.ofproto.ofproto_v1_0_parser.OFPActionVlanVid(vlan_vid)

Set the 802.1q VLAN id action

This action indicates the 802.1q VLAN id to be set.

Attribute	Description
vlan_vid	VLAN id.

class ryu.ofproto.ofproto_v1_0_parser.OFPActionVlanPcp(vlan_pcp)

Set the 802.1q priority action

This action indicates the 802.1q priority to be set.

Attribute	Description
vlan_pcp	VLAN priority.

class ryu.ofproto.ofproto_v1_0_parser.OFPActionStripVlan

Strip the 802.1q header action

This action indicates the 802.1q priority to be striped.

class ryu.ofproto.ofproto_v1_0_parser.OFPActionDlAddr(dl_addr)

class ryu.ofproto.ofproto_v1_0_parser.OFPActionSetDlSrc(dl_addr)

Set the ethernet source address action

This action indicates the ethernet source address to be set.

Attribute	Description
dl_addr	Ethernet address.

class ryu.ofproto.ofproto_v1_0_parser.OFPActionSetDlDst(dl_addr)

Set the ethernet destination address action

This action indicates the ethernet destination address to be set.

Attribute	Description
dl_addr	Ethernet address.

class ryu.ofproto.ofproto_v1_0_parser.OFPActionNwAddr(nw_addr)

class ryu.ofproto.ofproto_v1_0_parser.OFPActionSetNwSrc(nw_addr)

Set the IP source address action

This action indicates the IP source address to be set.

Attribute	Description
nw_addr	IP address.

class ryu.ofproto.ofproto_v1_0_parser.OFPActionSetNwDst(nw_addr)

Set the IP destination address action

This action indicates the IP destination address to be set.

Attribute	Description
nw_addr	IP address.

class ryu.ofproto.ofproto_v1_0_parser.OFPActionSetNwTos(tos)

Set the IP ToS action

This action indicates the IP ToS (DSCP field, 6 bits) to be set.

Attribute	Description
tos	IP ToS (DSCP field, 6 bits).

class ryu.ofproto.ofproto_v1_0_parser.OFPActionTpPort(tp)

class ryu.ofproto.ofproto_v1_0_parser.OFPActionSetTpSrc(tp)

Set the TCP/UDP source port action

This action indicates the TCP/UDP source port to be set.

Attribute	Description
tp	TCP/UDP port.

class ryu.ofproto.ofproto_v1_0_parser.OFPActionSetTpDst(tp)

Set the TCP/UDP destination port action

This action indicates the TCP/UDP destination port to be set.

Attribute	Description
tp	TCP/UDP port.

class ryu.ofproto.ofproto_v1_0_parser.OFPActionEnqueue(port, queue_id)

Output to queue action

This action indicates send packets to given queue on port.

Attribute	Description
port	Port that queue belongs.
queue_id	Where to enqueue the packets.

class ryu.ofproto.ofproto_v1_0_parser.OFPActionVendor(vendor=None)

Vendor action

This action is an extensible action for the vendor.