ovs\-actions

Section: Open vSwitch Manual (7)
Updated: 2.13.0
Page Index

 

NAME

ovs-actions - OpenFlow actions and instructions with Open vSwitch extensions

 

INTRODUCTION

This document aims to comprehensively document all of the OpenFlow actions and instructions, both standard and non-standard, supported by Open vSwitch, regardless of origin46 The document includes information of interest to Open vSwitch users, such as the semantics of each supported action and the syntax used by Open vSwitch tools, and to developers seeking to build controllers and switches compatible with Open vSwitch, such as the wire format for each supported message46  

Actions

In this document, we define an action as an OpenFlow action, which is a kind of command that specifies what to do with a packet46 Actions are used in OpenFlow flows to describe what to do when the flow matches a packet, and in a few other places in OpenFlow46 Each version of the OpenFlow specification defines standard actions, and beyond that many OpenFlow switches, including Open vSwitch, implement extensions to the standard46

OpenFlow groups actions in two ways: as an action list or an action set, described below46

Action Lists

An action list, a concept present in every version of OpenFlow, is simply an ordered sequence of actions46 The OpenFlow specifications require a switch to execute actions within an action list in the order specified, and to refuse to execute an action list entirely if it cannot implement the actions in that order [OpenFlow 1460, section 3463], with one exception: when an action list outputs multiple packets, the switch may output the packets in an order different from that specified46 Usually, this exception is not important, especially in the common case when the packets are output to different ports46

Action Sets

OpenFlow 1461 introduced the concept of an action set46 An action set is also a sequence of actions, but the switch reorders the actions and drops duplicates according to rules specified in the OpenFlow specifications46 Because of these semantics, some standard OpenFlow actions cannot usefully be included in an action set46 For some, but not all, Open vSwitch extension actions, Open vSwitch defines its own action set semantics and ordering46

The OpenFlow pipeline has an action set associated with it as a packet is processed46 After pipeline processing is otherwise complete, the switch executes the actions in the action set46

Open vSwitch applies actions in an action set in the following order: Except as noted otherwise below, the action set only executes at most a single action of each type, and when more than one action of a given type is present, the one added to the set later replaces the earlier action:

1.
strip_vlan
2.
pop_mpls
3.
decap
4.
encap
5.
push_mpls
6.
push_vlan
7.
dec_ttl
8.
dec_mpls_ttl
9.
dec_nsh_ttl
10.
All of the following actions are executed in the order added to the action set, with cumulative effect46 That is, when multiple actions modify the same part of a field, the later modification takes effect, and when they modify different parts of a field (or different fields), then both modifications are applied:
load
move
mod_dl_dst
mod_dl_src
mod_nw_dst
mod_nw_src
mod_nw_tos
mod_nw_ecn
mod_nw_ttl
mod_tp_dst
mod_tp_src
mod_vlan_pcp
mod_vlan_vid
set_field
set_tunnel
set_tunnel64
11.
set_queue
12.
group, output, resubmit, ct_clear, or ct46 If more than one of these actions is present, then the one listed earliest above is executed and the others are ignored, regardless of the order in which they were added to the action set46 (If none of these actions is present, the action set has no real effect, because the modified packet is not sent anywhere and thus the modifications are not visible46)

An action set may only contain the actions listed above46  

Error Handling

Packet processing can encounter a variety of errors:

Bridge not found
Open vSwitch supports an extension to the standard OpenFlow controller action called a ``continuation,'' which allows the controller to interrupt and later resume the processing of a packet through the switch pipeline46 This error occurs when such a packet's processing cannot be resumed, e46g46 because the bridge processing it has been destroyed46 Open vSwitch reports this error to the controller as Open vSwitch extension error NXR_STALE46
This error prevents packet processing entirely46
Recursion too deep
While processing a given packet, Open vSwitch limits the flow table recursion depth to 64, to ensure that packet processing uses a finite amount of time and space46 Actions that count against the recursion limit include resubmit from a given OpenFlow table to the same or an earlier table, group, and output to patch ports46
A resubmit from one table to a later one (or, equivalently46 a goto_table instruction) does not count against the depth limit because resubmits to strictly monotonically increasing tables will eventually terminate46 OpenFlow tables are most commonly traversed in numerically increasing order, so this limit has little effect on conventionally designed OpenFlow pipelines46
This error terminates packet processing46 Any previous side effects (e46g46 output actions) are retained46
Usually this error indicates a loop or other bug in the OpenFlow flow tables46 To assist debugging, when this error occurs, Open vSwitch 24610 and later logs a trace of the packet execution, as if by ovs-appctl ofproto/trace, rate-limited to one per minute to reduce the log volume46
Too many resubmits
Open vSwitch limits the total number of resubmit actions that a given packet can execute to 4,09646 For this purpose, goto_table instructions and output to the table port are treated like resubmit46 This limits the amount of time to process a single packet46
Unlike the limit on recursion depth, the limit on resubmits counts all resubmits, regardless of direction46
This error has the same effect, including logging, as exceeding the recursion depth limit46
Stack too deep
Open vSwitch limits the amount of data that the push action can put onto the stack at one time to 64 kB of data46
This error terminates packet processing46 Any previous side effects (e46g46 output actions) are retained46
No recirculation context

Recirculation conflict These errors indicate internal errors inside Open vSwitch and should generally not occur46 If you notice recurring log messages about these errors, please report a bug46
Too many MPLS labels
Open vSwitch can process packets with any number of MPLS labels, but its ability to push and pop MPLS labels is limited, currently to 3 labels46 Attempting to push more than the supported number of labels onto a packet, or to pop any number of labels from a packet with more than the supported number, raises this error46
This error terminates packet processing, retaining any previous side effects (e46g46 output actions)46 When this error arises within the execution of a group bucket, it only terminates that bucket's execution, not packet processing overall46
Invalid tunnel metadata
Open vSwitch raises this error when it processes a Geneve packet that has TLV options with an invalid form, e46g46 where the length in a TLV would extend past the end of the options46
This error prevents packet processing entirely46
Unsupported packet type
When a encap action encapsulates a packet, Open vSwitch raises this error if it does not support the combination of the new encapsulation with the current packet46 encap(ethernet) raises this error if the current packet is not an L3 packet, and encap(nsh) raises this error if the current packet is not Ethernet, IPv4, IPv6, or NSH46
When a decap action decapsulates a packet, Open vSwitch raises this error if it does not support the type of inner packet46 decap of an Ethernet header raises this error if a VLAN header is present, decap of a NSH packet raises this error if the NSH inner packet is not Ethernet, IPv4, IPv6, or NSH, and decap of other types of packets is unsupported and also raises this error46
This error terminates packet processing, retaining any previous side effects (e46g46 output actions)46 When this error arises within the execution of a group bucket, it only terminates that bucket's execution, not packet processing overall46
 

Inconsistencies

OpenFlow 1460 allows any action to be part of any flow, regardless of the flow's match46 Some combinations do not make sense, e46g46 an set_nw_tos action in a flow that matches only ARP packets or strip_vlan in a flow that matches packets without VLAN tags46 Other combinations have varying results depending on the kind of packet that the flow processes, e46g46 a set_nw_src action in a flow that does not match on Ethertype will be treated as a no-op when it processes a non-IPv4 packet46 Nevertheless OVS allows all of the above in conformance with OpenFlow 1460, that is, the following will succeed:



$ ovs-ofctl -O OpenFlow10 add-flow br0 arp,actions=mod_nw_tos:12
$ ovs-ofctl -O OpenFlow10 add-flow br0 dl_vlan=0xffff,actions=strip_vlan
$ ovs-ofctl -O OpenFlow10 add-flow br0 actions=mod_nw_src:1462463464

Open vSwitch calls these kinds of combinations inconsistencies between match and actions46 OpenFlow 1461 and later forbid inconsistencies, and disallow the examples described above by preventing such flows from being added46 All of the above, for example, will fail with an error message if one replaces OpenFlow10 by OpenFlow1146

OpenFlow 1461 and later cannot detect and disallow all inconsistencies46 For example, the write_actions instruction arbitrarily delays execution of the actions inside it, which can even be canceled with clear_actions, so that there is no way to ensure that its actions are consistent with the packet at the time they execute46 Thus, actions with write_actions and some other contexts are exempt from consistency requirements46

When OVS executes an action inconsistent with the packet, it treats it as a no-op46  

Inter-Version Compatibility

Open vSwitch supports multiple OpenFlow versions simultaneously on a single switch46 When actions are added with one OpenFlow version and then retrieved with another, Open vSwitch does its best to translate between them46

Inter-version compatibility issues can still arise when different connections use different OpenFlow versions46 Backward compatibility is the most obvious case46 Suppose, for example, that an OpenFlow 1461 session adds a flow with a push_vlan action, for which there is no equivalent in OpenFlow 146046 If an OpenFlow 1460 session retrieves this flow, Open vSwitch must somehow represent the action46

Forward compatibility can also be an issue, because later OpenFlow versions sometimes remove functionality46 The best example is the enqueue action from OpenFlow 1460, which OpenFlow 1461 removed46

In practice, Open vSwitch uses a variety of strategies for inter-version compatibility:

Most standard OpenFlow actions, such as output actions, translate without compatibility issues46
Open vSwitch supports its extension actions in every OpenFlow version, so they do not pose inter-version compatibility problems46
Open vSwitch sometimes adds extension actions to ensure backward or forward compatibility46 For example, for backward compatibility with the group action added in OpenFlow 1461, Open vSwitch includes an OpenFlow 1460 extension group action46

Perfect inter-version compatibility is not possible, so best results require OpenFlow connections to use a consistent version46 One may enforce use of a particular version by setting the protocols column for a bridge, e46g46 to force br0 to use only OpenFlow 1463:



ovs-vsctl set bridge br0 protocols=OpenFlow13
 

Field Specifications

Many Open vSwitch actions refer to fields46 In such cases, fields may usually be referred to by their common names, such as eth_dst for the Ethernet destination field, or by their full OXM or NXM names, such as NXM_OF_ETH_DST or OXM_OF_ETH_DST46 Before Open vSwitch 2467, only OXM or NXM field names were accepted46

Many actions that act on fields can also act on subfields, that is, parts of fields, written as field[start4646end], where start is the first bit and end is the last bit to use in field, e46g46 vlan_tci[13464615] for the VLAN PCP46 A single-bit subfield may also be written as field[offset], e46g46 vlan_tci[13] for the least-significant bit of the VLAN PCP46 Empty brackets may be used to explicitly designate an entire field, e46g46 vlan_tci[] for the entire 16-bit VLAN TCI header46 Before Open vSwitch 2467, brackets were required in field specifications46

See ovs-fields(7) for a list of fields and their names46  

Port Specifications

Many Open vSwitch actions refer to OpenFlow ports46 In such cases, the port may be specified as a numeric port number in the range 0 to 65,535, although Open vSwitch only assigns port numbers in the range 1 through 62,279 to ports46 OpenFlow 1461 and later use 32-bit port numbers, but Open vSwitch never assigns a port number that requires more than 16 bits46

In most contexts, the name of a port may also be used46 (The most obvious context where a port name may not be used is in an ovs-ofctl command along with the --no-names option46) When a port's name contains punctuation or could be ambiguous with other actions, the name may be enclosed in double quotes, with JSON-like string escapes supported (see [RFC 8259])46

Open vSwitch also supports the following standard OpenFlow port names (even in contexts where port names are not otherwise supported)46 The corresponding OpenFlow 1460 and 1461+ port numbers are listed alongside them but should not be used in flow syntax:

in_port (65528 or 0xfff8; 0xfffffff8)
table (65529 or 0xfff9; 0xfffffff9)
normal (65530 or 0xfffa; 0xfffffffa)
flood (65531 or 0xfffb; 0xfffffffb)
all (65532 or 0xfffc; 0xfffffffc)
controller (65533 or 0xfffd; 0xfffffffd)
local (65534 or 0xfffe; 0xfffffffe)
any or none (65535 or 0xffff; 0xffffffff)
unset (not in OpenFlow 1460; 0xfffffff7)
 

OUTPUT ACTIONS

These actions send a packet to a physical port or a controller46 A packet that never encounters an output action on its trip through the Open vSwitch pipeline is effectively dropped46 Because actions are executed in order, a packet modification action that is not eventually followed by an output action will not have an externally visible effect46

 

The output action

Syntax:
port
output:port
output:field
output(port=port, max_len=nbytes)

Outputs the packet to an OpenFlow port most commonly specified as port46 Alternatively, the output port may be read from field, a field or subfield in the syntax described under ``Field Specifications'' above46 Either way, if the port is the packet's input port, the packet is not output46

The port may be one of the following standard OpenFlow ports:

local
Outputs the packet on the ``local port'' that corresponds to the network device that has the same name as the bridge, unless the packet was received on the local port46 OpenFlow switch implementations are not required to have a local port, but Open vSwitch bridges always do46
in_port
Outputs the packet on the port on which it was received46 This is the only standard way to output the packet to the input port (but see ``Output to the Input port'', below)46

The port may also be one of the following additional OpenFlow ports, unless max_len is specified:

normal
Subjects the packet to the device's normal L2/L3 processing46 This action is not implemented by all OpenFlow switches, and each switch implements it differently46
flood
Outputs the packet on all switch physical ports, except the port on which it was received and any ports on which flooding is disabled46 Flooding can be disabled automatically on a port by Open vSwitch when IEEE 802461D spanning tree (STP) or rapid spanning tree (RSTP) is enabled, or by a controller using an OpenFlow OFPT_MOD_PORT request to set the port's OFPPC_NO_FLOOD flag (ovs-ofctl mod-port provides a command-line interface to set this flag)46
all
Outputs the packet on all switch physical ports except the port on which it was received46
controller
Sends the packet and its metadata to an OpenFlow controller or controllers encapsulated in an OpenFlow ``packet-in'' message46 The separate controller action, described below, provides more options for output to a controller46

Open vSwitch rejects output to other standard OpenFlow ports, including none, unset, and port numbers reserved for future use as standard ports, with the error OFPBAC_BAD_OUT_PORT46

With max_len, the packet is truncated to at most nbytes bytes before being output46 In this case, the output port may not be a patch port46 Truncation is just for the single output action, so that later actions in the OpenFlow pipeline work with the complete packet46 The truncation feature is meant for use in monitoring applications, e46g46 for mirroring packets to a collector46

When an output action specifies the number of a port that does not currently exist (and is not in the range for standard ports), the OpenFlow specification allows but does not require OVS to reject the action46 All versions of Open vSwitch treat such an action as a no-op46 If a port with the number is created later, then the action will be honored at that point46 (OpenFlow requires OVS to reject output to a port number that will never be valid, with OFPBAC_BAD_OUT_PORT, but this situation does not arise when OVS is a software switch, since the user can add or renumber ports at any time46)

A controller can suppress output to a port by setting its OFPPC_NO_FORWARD flag using an OpenFlow OFPT_MOD_PORT request (ovs-ofctl mod-port provides a command-line interface to set this flag)46 When output is disabled, output actions (and other actions that output to the port) are allowed but have no effect46

Open vSwitch allows output to a port that does not exist, although OpenFlow allows switches to reject such actions46

Output to the Input Port

OpenFlow requires a switch to ignore attempts to send a packet out its ingress port in the most straightforward way46 For example, output:234 has no effect if the packet has ingress port 23446 The rationale is that dropping these packets makes it harder to loop the network46 Sometimes this behavior can even be convenient, e46g46 it is often the desired behavior in a flow that forwards a packet to several ports (``floods'' the packet)46

Sometimes one really needs to send a packet out its ingress port (``hairpin'')46 In this case, use in_port to explicitly output the packet to its input port, e46g46:



$ ovs-ofctl add-flow br0 in_port=2,actions=in_port

This also works in some circumstances where the flow doesn't match on the input port46 For example, if you know that your switch has five ports numbered 2 through 6, then the following will send every received packet out every port, even its ingress port:



$ ovs-ofctl add-flow br0 actions=2,3,4,5,6,in_port

or, equivalently:



$ ovs-ofctl add-flow br0 actions=all,in_port

Sometimes, in complicated flow tables with multiple levels of resubmit actions, a flow needs to output to a particular port that may or may not be the ingress port46 It's difficult to take advantage of output to in_port in this situation46 To help, Open vSwitch provides, as an OpenFlow extension, the ability to modify the in_port field46 Whatever value is currently in the in_port field is both the port to which output will be dropped and the destination for in_port46 This means that the following adds flows that reliably output to port 2 or to ports 2 through 6, respectively:



$ ovs-ofctl add-flow br0 "in_port=2,actions=load:0->in_port,2"
$ ovs-ofctl add-flow br0 "actions=load:0->in_port,2,3,4,5,6"

If in_port is important for matching or other reasons, one may save and restore it on the stack:



$ ovs-ofctl add-flow br0 actions="push:in_port,\
load:0->in_port,\
2,3,4,5,6,\
pop:in_port"

Conformance:

All versions of OpenFlow and Open vSwitch support output to a literal port46 Output to a register is an OpenFlow extension introduced in Open vSwitch 146346 Output with truncation is an OpenFlow extension introduced in Open vSwitch 246646

 

The controller action

Syntax:
controller
controller:max_len
controller(key[=value], 464646)

Sends the packet and its metadata to an OpenFlow controller or controllers encapsulated in an OpenFlow ``packet-in'' message46 The supported options are:

max_len=max_len
Limit to max_len the number of bytes of the packet to send in the ``packet-in46'' A max_len of 0 prevents any of the packet from being sent (thus, only metadata is included)46 By default, the entire packet is sent, equivalent to a max_len of 6553546
reason=reason
Specify reason as the reason for sending the message in the ``packet-in46'' The supported reasons are no_match, action, invalid_ttl, action_set, group, and packet_out46 The default reason is action46
id=controller_id
Specify controller_id, a 16-bit integer, as the connection ID of the OpenFlow controller or controllers to which the ``packet-in'' message should be sent46 The default is zero46 Zero is also the default connection ID for each controller connection, and a given controller connection will only have a nonzero connection ID if its controller uses the NXT_SET_CONTROLLER_ID Open vSwitch extension to OpenFlow46
userdata=hh464646
Supplies the bytes represented as hex digits hh as additional data to the controller in the ``packet-in'' message46 Pairs of hex digits may be separated by periods for readability46
pause
Causes the switch to freeze the packet's trip through Open vSwitch flow tables and serializes that state into the packet-in message as a ``continuation,'' an additional property in the NXT_PACKET_IN2 message46 The controller can later send the continuation back to the switch in an NXT_RESUME message, which will restart the packet's traversal from the point where it was interrupted46 This permits an OpenFlow controller to interpose on a packet midway through processing in Open vSwitch46

Conformance:

All versions of OpenFlow and Open vSwitch support controller action and its max_len option46 The userdata and pause options require the Open vSwitch NXAST_CONTROLLER2 extension action added in Open vSwitch 246646 In the absence of these options, the reason (other than reason=action) and controller_id (option than controller_id=0) options require the Open vSwitch NXAST_CONTROLLER extension action added in Open vSwitch 146646

 

The enqueue action

Syntax:
enqueue(port,queue)
enqueue:port:queue

Enqueues the packet on the specified queue within port port46

port must be an OpenFlow port number or name as described under ``Port Specifications'' above46 port may be in_port or local but the other standard OpenFlow ports are not allowed46

queue must be a a number between 0 and 4294967294 (0xfffffffe), inclusive46 The number of actually supported queues depends on the switch46 Some OpenFlow implementations do not support queuing at all46 In Open vSwitch, the supported queues vary depending on the operating system, datapath, and hardware in use46 Use the QoS and Queue tables in the Open vSwitch database to configure queuing on individual OpenFlow ports (see ovs-vswitchd46conf46db(5) for more information)46

Conformance:

Only OpenFlow 1460 supports enqueue46 OpenFlow 1461 added the set_queue action to use in its place along with output46

Open vSwitch translates enqueue to a sequence of three actions in OpenFlow 1461 or later: set_queue:queue, output:port, pop_queue46 This is equivalent in behavior as long as the flow table does not otherwise use set_queue, but it relies on the pop_queue Open vSwitch extension action46

 

The bundle and bundle_load actions

Syntax:
bundle(fields, basis, algorithm, ofport, slaves:port464646)
bundle_load(fields, basis, algorithm, ofport, dst, slaves:port464646)

These actions choose a port (``slave'') from a comma-separated OpenFlow port list46 After selecting the port, bundle outputs to it, whereas bundle_load writes its port number to dst, which must be a 16-bit or wider field or subfield in the syntax described under ``Field Specifications'' above46

These actions hash a set of fields using basis as a universal hash parameter, then apply the bundle link selection algorithm to choose a port46

fields must be one of the following46 For the options with ``symmetric'' in the name, reversing source and destination addresses yields the same hash:

eth_src
Ethernet source address46
nw_src
IPv4 or IPv6 source address46
nw_dst
IPv4 or IPv6 destination address46
symmetric_l4
Ethernet source and destination, Ethernet type, VLAN ID or IDs (if any), IPv4 or IPv6 source and destination, IP protocol, TCP or SCTP (but not UDP) source and destination46
symmetric_l3l4
IPv4 or IPv6 source and destination, IP protocol, TCP or SCTP (but not UDP) source and destination46
symmetric_l3l4+udp
Like symmetric_l3l4 but include UDP ports46

algorithm must be one of the following:

active_backup
Chooses the first live port listed in slaves46
hrw (Highest Random Weight)
Computes the following, considering only the live ports in slaves:


for
i in [1,n_slaves]:
weights[i] = hash(flow, i)
slave = { i such that weights[i] >= weights[j] for all j != i }
This algorithm is specified by RFC 299246

The algorithms take port liveness into account when selecting slaves46 The definition of whether a port is live is subject to change46 It currently takes into account carrier status and link monitoring protocols such as BFD and CFM46 If none of the slaves is live, bundle does not output the packet and bundle_load stores OFPP_NONE (65535) in the output field46

Example: bundle(eth_src,0,hrw,ofport,slaves:4,8) uses an Ethernet source hash with basis 0, to select between OpenFlow ports 4 and 8 using the Highest Random Weight algorithm46

Conformance:

Open vSwitch 1462 introduced the bundle and bundle_load OpenFlow extension actions46

 

The group action

Syntax:
group:group

Outputs the packet to the OpenFlow group group, which must be a number in the range 0 to 4294967040 (0xffffff00)46 The group must exist or Open vSwitch will refuse to add the flow46 When a group is deleted, Open vSwitch also deletes all of the flows that output to it46

Groups contain action sets, whose semantics are described above in the section ``Action Sets''46 The semantics of action sets can be surprising to users who expect action list semantics, since action sets reorder and sometimes ignore actions46

A group action usually executes the action set or sets in one or more group buckets46 Open vSwitch saves the packet and metadata before it executes each bucket, and then restores it afterward46 Thus, when a group executes more than one bucket, this means that each bucket executes on the same packet and metadata46 Moreover, regardless of the number of buckets executed, the packet and metadata are the same before and after executing the group46

Sometimes saving and restoring the packet and metadata can be undesirable46 In these situations, workarounds are possible46 For example, consider a pipeline design in which a select group bucket is to communicate to a later stage of processing a value based on which bucket was selected46 An obvious design would be for the bucket to communicate the value via set_field on a register46 This does not work because registers are part of the metadata that group saves and restores46 The following alternative bucket designs do work:

Recursively invoke the rest of the pipeline with resubmit46
Use resubmit into a table that uses push to put the value on the stack for the caller to pop off46 This works because group preserves only packet data and metadata, not the stack46
(This design requires indirection through resubmit because actions sets may not contain push or pop actions46)

An exit action within a group bucket terminates only execution of that bucket, not other buckets or the overall pipeline46

Conformance:

OpenFlow 1461 introduced group46 Open vSwitch 2466 and later also supports group as an extension to OpenFlow 146046  

ENCAPSULATION AND DECAPSULATION ACTIONS

 

The strip_vlan and pop actions

Syntax:
strip_vlan
pop_vlan

Removes the outermost VLAN tag, if any, from the packet46

The two names for this action are synonyms with no semantic difference46 The OpenFlow 1460 specification uses the name strip_vlan and later versions use pop_vlan, but OVS accepts either name regardless of version46

In OpenFlow 1461 and later, consistency rules allow strip_vlan only in a flow that matches only packets with a VLAN tag (or following an action that pushes a VLAN tag, such as push_vlan)46 See ``Inconsistencies'', above, for more information46

Conformance:

All versions of OpenFlow and Open vSwitch support this action46

 

The push_vlan action

Syntax:
push_vlan:ethertype

Pushes a new outermost VLAN onto the packet46 Uses TPID ethertype, which must be 0x8100 for an 802461Q C-tag or 0x88a8 for a 802461ad S-tag46

Conformance:

OpenFlow 1461 and later supports this action46 Open vSwitch 2468 added support for multiple VLAN tags (with a limit of 2) and 802461ad S-tags46

 

The push_mpls action

Syntax:
push_mpls:ethertype

Pushes a new outermost MPLS label stack entry (LSE) onto the packet and changes the packet's Ethertype to ethertype, which must be either B0x8847 or 0x884846

If the packet did not already contain any MPLS labels, initializes the new LSE as:

Label
2, if the packet contains IPv6, 0 otherwise46
TC
The low 3 bits of the packet's DSCP value, or 0 if the packet is not IP46
TTL
Copied from the IP TTL, or 64 if the packet is not IP46

If the packet did already contain an MPLS label, initializes the new outermost label as a copy of the existing outermost label46

OVS currently supports at most 3 MPLS labels46

This action applies only to Ethernet packets46

Conformance:

Open vSwitch 14611 introduced support for MPLS46 OpenFlow 1461 and later support push_mpls46 Open vSwitch implements push_mpls as an extension to OpenFlow 146046

 

The pop_mpls action

Syntax:
pop_mpls:ethertype

Strips the outermost MPLS label stack entry and changes the packet's Ethertype to ethertype46

This action applies only to Ethernet packets with at least one MPLS label46 If there is more than one MPLS label, then ethertype should be an MPLS Ethertype (B0x8847 or 0x8848)46

Conformance:

Open vSwitch 14611 introduced support for MPLS46 OpenFlow 1461 and later support pop_mpls46 Open vSwitch implements pop_mpls as an extension to OpenFlow 146046

 

The encap action

Syntax:
encap(nsh([md_type=md_type], [tlv(class,type,value)]464646))
encap(ethernet)

The encap action encapsulates a packet with a specified header46 It has variants for different kinds of encapsulation46

The encap(nsh(464646)) variant encapsulates an Ethernet frame with NSH46 The md_type may be 1 or 2 for metadata type 1 or 2, defaulting to 146 For metadata type 2, TLVs may be specified with class as a 16-bit hexadecimal integer beginning with 0x, type as an 8-bit decimal integer, and value a sequence of pairs of hex digits beginning with 0x46 For example:

encap(nsh(md_type=1))
Encapsulates the packet with an NSH header with metadata type 146
encap(nsh(md_type=2,tlv(0x1000,10,0x12345678)))
Encapsulates the packet with an NSH header, NSH metadata type 2, and an NSH TLV with class 0x1000, type 10, and the 4-byte value 0x1234567846

The encap(ethernet) variant encapsulate a bare L3 packet in an Ethernet frame46 The Ethernet type is initialized to the L3 packet's type, e46g46 0x0800 if the L3 packet is IPv446 The Ethernet source and destination are initially zeroed46

Conformance:

This action is an Open vSwitch extension to OpenFlow 1463 and later, introduced in Open vSwitch 246846

 

The decap action

Syntax:
decap

Removes an outermost encapsulation from the packet:

If the packet is an Ethernet packet, removes the Ethernet header, which changes the packet into a bare L3 packet46 If the packet has VLAN tags, raises an unsupported packet type error (see ``Error Handling'', above)46
Otherwise, if the packet is an NSH packet, removes the NSH header, revealing the inner packet46 Open vSwitch supports Ethernet, IPv4, IPv6, and NSH inner packet types46 Other types raise unsupported packet type errors46
Otherwise, raises an unsupported packet type error46

Conformance:

This action is an Open vSwitch extension to OpenFlow 1463 and later, introduced in Open vSwitch 246846  

FIELD MODIFICATION ACTIONS

These actions modify packet data and metadata fields46

 

The set_field and load actions

Syntax:
set_field:value[/mask]->dst
load:value->dst

These actions loads a literal value into a field or part of a field46 The set_field action takes value in the customary syntax for field dst, e46g46 00:11:22:33:44:55 for an Ethernet address, and dst as the field's name46 The optional mask allows part of a field to be set46

The load action takes value as an integer value (in decimal or prefixed by 0x for hexadecimal) and dst as a field or subfield in the syntax described under ``Field Specifications'' above46

The following all set the Ethernet source address to 00:11:22:33:44:55:

set_field:00:11:22:33:44:55->eth_src
load:0x001122334455->eth_src
load:0x001122334455->OXM_OF_ETH_SRC[]

The following all set the multicast bit in the Ethernet destination address:

set_field:01:00:00:00:00:00/01:00:00:00:00:00->eth_dst
load:1->eth_dst[40]

Open vSwitch prohibits a set_field or load action whose dst is not guaranteed to be part of the packet; for example, set_field of nw_dst is only allowed in a flow that matches on Ethernet type 0x80046 In some cases, such as in an action set, Open vSwitch can't statically check that dst is part of the packet, and in that case if it is not then Open vSwitch treats the action as a no-op46

Conformance:

Open vSwitch 1461 introduced NXAST_REG_LOAD as a extension to OpenFlow 1460 and used load to express it46 Later, OpenFlow 1462 introduced a standard OFPAT_SET_FIELD action that was restricted to loading entire fields, so Open vSwitch added the form set_field with this restriction46 OpenFlow 1465 extended OFPAT_SET_FIELD to the point that it became a superset of NXAST_REG_LOAD46 Open vSwitch translates either syntax as necessary for the OpenFlow version in use: in OpenFlow 1460 and 1461, NXAST_REG_LOAD; in OpenFlow 1462, 1463, and 1464, NXAST_REG_LOAD for load or for loading a subfield, OFPAT_SET_FIELD otherwise; and OpenFlow 1465 and later, OFPAT_SET_FIELD46

 

The move action

Syntax:
move:src->dst

Copies the named bits from field or subfield src to field or subfield dst46 src and dst should fields or subfields in the syntax described under ``Field Specifications'' above46 The two fields or subfields must have the same width46

Examples:

move:reg0[046465]->reg1[26464631] copies the six bits numbered 0 through 5 in register 0 into bits 26 through 31 of register 146
move:reg0[0464615]->vlan_tci copies the least significant 16 bits of register 0 into the VLAN TCI field46

Conformance:

In OpenFlow 1460 through 1464, move ordinarily uses an Open vSwitch extension to OpenFlow46 In OpenFlow 1465, move uses the OpenFlow 1465 standard OFPAT_COPY_FIELD action46 The ONF has also made OFPAT_COPY_FIELD available as an extension to OpenFlow 146346 Open vSwitch 2464 and later understands this extension and uses it if a controller uses it, but for backward compatibility with older versions of Open vSwitch, ovs-ofctl does not use it46

 

The mod_dl_src and mod_dl_dst actions

Syntax:
mod_dl_src:mac
mod_dl_dst:mac

Sets the Ethernet source or destination address, respectively, to mac, which should be expressed in the form xx:xx:xx:xx:xx:xx46

For L3-only packets, that is, those that lack an Ethernet header, this action has no effect46

Conformance:

OpenFlow 1460 and 1461 have specialized actions for these purposes46 OpenFlow 1462 and later do not, so Open vSwitch translates them to appropriate OFPAT_SET_FIELD actions for those versions,

 

The mod_nw_src and mod_nw_dst actions

Syntax:
mod_nw_src:ip
mod_nw_dst:ip

Sets the IPv4 source or destination address, respectively, to ip, which should be expressed in the form w46x46y46z46

In OpenFlow 1461 and later, consistency rules allow these actions only in a flow that matches only packets that contain an IPv4 header (or following an action that adds an IPv4 header, e46g46 pop_mpls:0x0800)46 See ``Inconsistencies'', above, for more information46

Conformance:

OpenFlow 1460 and 1461 have specialized actions for these purposes46 OpenFlow 1462 and later do not, so Open vSwitch translates them to appropriate OFPAT_SET_FIELD actions for those versions,

 

The mod_nw_tos and mod_nw_ecn actions

Syntax:
mod_nw_tos:tos
mod_nw_ecn:ecn

The mod_nw_tos action sets the DSCP bits in the IPv4 ToS/DSCP or IPv6 traffic class field to tos, which must be a multiple of 4 between 0 and 25546 This action does not modify the two least significant bits of the ToS field (the ECN bits)46

The mod_nw_ecn action sets the ECN bits in the IPv4 ToS or IPv6 traffic class field to ecn, which must be a value between 0 and 3, inclusive46 This action does not modify the six most significant bits of the field (the DSCP bits)46

In OpenFlow 1461 and later, consistency rules allow these actions only in a flow that matches only packets that contain an IPv4 or IPv6 header (or following an action that adds such a header)46 See ``Inconsistencies'', above, for more information46

Conformance:

OpenFlow 1460 has a mod_nw_tos action but not mod_nw_ecn46 Open vSwitch implements the latter in OpenFlow 1460 as an extension using NXAST_REG_LOAD46 OpenFlow 1461 has specialized actions for these purposes46 OpenFlow 1462 and later do not, so Open vSwitch translates them to appropriate OFPAT_SET_FIELD actions for those versions,

 

The mod_tp_src and mod_tp_dst actions

Syntax:
mod_tp_src:port
mod_tp_dst:port

Sets the TCP or UDP or SCTP source or destination port, respectively, to port46 Both IPv4 and IPv6 are supported46

In OpenFlow 1461 and later, consistency rules allow these actions only in a flow that matches only packets that contain a TCP or UDP or SCTP header46 See ``Inconsistencies'', above, for more information46

Conformance:

OpenFlow 1460 and 1461 have specialized actions for these purposes46 OpenFlow 1462 and later do not, so Open vSwitch translates them to appropriate OFPAT_SET_FIELD actions for those versions,

 

The dec_ttl action

Syntax:
dec_ttl
dec_ttl(id1, [id2]464646)

Decrement TTL of IPv4 packet or hop limit of IPv6 packet46 If the TTL or hop limit is initially 0 or 1, no decrement occurs, as packets reaching TTL zero must be rejected46 Instead, Open vSwitch sends a ``packet-in'' message with reason code OFPR_INVALID_TTL to each connected controller that has enabled receiving such messages, and stops processing the current set of actions46 (However, if the current set of actions was reached through resubmit, the remaining actions in outer levels resume processing46)

As an Open vSwitch extension to OpenFlow, this action supports the ability to specify a list of controller IDs46 Open vSwitch will only send the message to controllers with the given ID or IDs46 Specifying no list is equivalent to specifying a single controller ID of zero46

Sets the TCP or UDP or SCTP source or destination port, respectively, to port46 Both IPv4 and IPv6 are supported46

In OpenFlow 1461 and later, consistency rules allow these actions only in a flow that matches only packets that contain an IPv4 or IPv6 header46 See ``Inconsistencies'', above, for more information46

Conformance:

All versions of OpenFlow and Open vSwitch support this action46

 

The set_mpls_label, set_mpls_tc, and set_mpls_ttl actions

Syntax:
set_mpls_label:label
set_mpls_tc:tc
set_mpls_ttl:ttl

The set_mpls_label action sets the label of the packet's outer MPLS label stack entry46 label should be a 20-bit value that is decimal by default; use a 0x prefix to specify the value in hexadecimal46

The set_mpls_tc action sets the traffic class of the packet's outer MPLS label stack entry46 tc should be in the range 0 to 7, inclusive46

The set_mpls_ttl action sets the TTL of the packet's outer MPLS label stack entry46 ttl should be in the range 0 to 255 inclusive46

In OpenFlow 1461 and later, consistency rules allow these actions only in a flow that matches only packets that contain an MPLS label (or following an action that adds an MPLS label, e46g46 push_mpls:0x8847)46 See ``Inconsistencies'', above, for more information46

Conformance:

OpenFlow 1460 does not support MPLS, but Open vSwitch implements these actions as extensions46 OpenFlow 1461 has specialized actions for these purposes46 OpenFlow 1462 and later do not, so Open vSwitch translates them to appropriate OFPAT_SET_FIELD actions for those versions,

 

The dec_mpls_ttl and dec_nsh_ttl actions

Syntax:
dec_mpls_ttl
dec_nsh_ttl

These actions decrement the TTL of the packet's outer MPLS label stack entry or its NSH header, respectively46 If the TTL is initially 0 or 1, no decrement occurs46 Instead, Open vSwitch sends a ``packet-in'' message with reason code BOFPR_INVALID_TTL to OpenFlow controllers with ID 0, if it has enabled receiving them46 Processing the current set of actions then stops46 (However, if the current set of actions was reached through resubmit, remaining actions in outer levels resume processing46)

In OpenFlow 1461 and later, consistency rules allow this actions only in a flow that matches only packets that contain an MPLS label or an NSH header, respectively46 See ``Inconsistencies'', above, for more information46

Conformance:

Open vSwitch 14611 introduced support for MPLS46 OpenFlow 1461 and later support dec_mpls_ttl46 Open vSwitch implements dec_mpls_ttl as an extension to OpenFlow 146046

Open vSwitch 2468 introduced support for NSH, although the NSH draft changed after release so that only Open vSwitch 2469 and later conform to the final protocol specification46 The dec_nsh_ttl action and NSH support in general is an Open vSwitch extension not supported by any version of OpenFlow46

 

The check_pkt_larger action

Syntax:
check_pkt_larger(pkt_len)->dst

Checks if the packet is larger than the specified length in pkt_len46 If so, stores 1 in dst, which should be a 1-bit field; if not, stores 046

The packet length to check againt the argument pkt_len includes the L2 header and L2 payload of the packet, but not the VLAN tag (if present)46

Examples:

check_pkt_larger(1500)->reg0[0]
check_pkt_larger(8000)->reg9[10]

This action was added in Open vSwitch 24611469046  

METADATA ACTIONS

 

The set_tunnel action

Syntax:
set_tunnel:id
set_tunnel64:id

Many kinds of tunnels support a tunnel ID, e46g46 VXLAN and Geneve have a 24-bit VNI, and GRE has an optional 32-bit key46 This action sets the value used for tunnel ID in such tunneled packets, although whether it is used for a particular tunnel depends on the tunnel's configuration46 See the tunnel ID documentation in ovs-fields(7) for more information46

Conformance:

These actions are OpenFlow extensions46 set_tunnel was introduced in Open vSwitch 146046 set_tunnel64, which is needed if id is wider than 32 bits, was added in Open vSwitch 146146 Both actions always set the entire tunnel ID field46

Open vSwitch supports these actions in all versions of OpenFlow, but in OpenFlow 1462 and later it translates them to an appropriate standardized OFPAT_SET_FIELD action46

 

The set_queue and pop_queue actions

Syntax:
set_queue:queue
pop_queue

The set_queue action sets the queue ID to be used for subsequent output actions to queue, which must be a 32-bit integer46 The range of meaningful values of queue, and their meanings, varies greatly from one OpenFlow implementation to another46 Even within a single implementation, there is no guarantee that all OpenFlow ports have the same queues configured or that all OpenFlow ports in an implementation can be configured the same way queue-wise46 For more information, see the documentation for the output queue field in ovs-fields(7)46

The pop_queue restores the output queue to the default that was set when the packet entered the switch (generally 0)46

Four billion queues ought to be enough for anyone: <URL: https://mailman.stanford.edu/pipermail/openflow-spec/2009-August/000394.html >

Conformance:

OpenFlow 1461 introduced the set_queue action46 Open vSwitch also supports it as an extension in OpenFlow 146046

The pop_queue action is an Open vSwitch extension46  

FIREWALLING ACTIONS

Open vSwitch is often used to implement a firewall46 The preferred way to implement a firewall is ``connection tracking,'' that is, to keep track of the connection state of individual TCP sessions46 The ct action described in this section, added in Open vSwitch 2465, implements connection tracking46 For new deployments, it is the recommended way to implement firewalling with Open vSwitch46

Before ct was added, Open vSwitch did not have built-in support for connection tracking46 Instead, Open vSwitch supported the learn action, which allows a received packet to add a flow to an OpenFlow flow table46 This could be used to implement a primitive form of connection tracking: packets passing through the firewall in one direction could create flows that allowed response packets back through the firewall in the other direction46 The additional fin_timeout action allowed the learned flows to expire quickly after TCP session termination46

 

The ct action

Syntax:
ct(argument]464646)
ct(commit[, argument]464646)

The action has two modes of operation, distinguished by whether commit is present46 The following arguments may be present in either mode:

zone=value
A zone is a 16-bit id that isolates connections into separate domains, allowing overlapping network addresses in different zones46 If a zone is not provided, then the default is 046 The value may be specified either as a 16-bit integer literal or a field or subfield in the syntax described under ``Field Specifications'' above46

Without commit, this action sends the packet through the connection tracker46 The connection tracker keeps track of the state of TCP connections for packets passed through it46 For each packet through a connection, it checks that it satisfies TCP invariants and signals the connection state to later actions using the ct_state metadata field, which is documented in ovs-fields(7)46

In this form, ct forks the OpenFlow pipeline:

In one fork, ct passes the packet to the connection tracker46 Afterward, it reinjects the packet into the OpenFlow pipeline with the connection tracking fields initialized46 The ct_state field is initialized with connection state and ct_zone to the connection tracking zone specified on the zone argument46 If the connection is one that is already tracked, ct_mark and ct_label to its existing mark and label, respectively; otherwise they are zeroed46 In addition, ct_nw_proto, ct_nw_src, ct_nw_dst, ct_ipv6_src, ct_ipv6_dst, ct_tp_src, and ct_tp_dst are initialized appropriately for the original direction connection46 See the resubmit action for a way to search the flow table with the connection tracking original direction fields swapped with the packet 5-tuple fields46 See ovs-fields(7) for details on the connection tracking fields46
In the other fork, the original instance of the packet continues independent processing following the ct action46 The ct_state field and other connection tracking metadata are cleared46

Without commit, the ct action accepts the following arguments:

table=table
Sets the OpenFlow table where the packet is reinjected46 The table must be a number between 0 and 254 inclusive, or a table's name46 If table is not specified, then the packet is not reinjected46
nat

nat(type=addrs[:ports][,flag]464646)
Specify address and port translation for the connection being tracked46 The type must be src, for source address/port translation (SNAT), or dst, for destination address/port translation (DNAT)46 Setting up address translation for a new connection takes effect only if the connection is later committed with ct(commit464646)46
The src and dst options take the following arguments:
addrs
The IP address addr or range addr1-addr2 from which the translated address should be selected46 If only one address is given, then that address will always be selected, otherwise the address selection can be informed by the optional persistent flag as described below46 Either IPv4 or IPv6 addresses can be provided, but both addresses must be of the same type, and the datapath behavior is undefined in case of providing IPv4 address range for an IPv6 packet, or IPv6 address range for an IPv4 packet46 IPv6 addresses must be bracketed with [ and ] if a port range is also given46
ports
The L4 port or range port1-port2 from which the translated port should be selected46 When a port range is specified, fallback to ephemeral ports does not happen, else, it will46 The port number selection can be informed by the optional random and hash flags described below46 The userspace datapath only supports the hash behavior46
The optional flags are:
random
The selection of the port from the given range should be done using a fresh random number46 This flag is mutually exclusive with hash46
hash
The selection of the port from the given range should be done using a datapath specific hash of the packet's IP addresses and the other, non-mapped port number46 This flag is mutually exclusive with random46
persistent
The selection of the IP address from the given range should be done so that the same mapping can be provided after the system restarts46
If alg is specified for the committing ct action that also includes nat with a src or dst attribute, then the datapath tries to set up the helper to be NAT-aware46 This functionality is datapath specific and may not be supported by all datapaths46
A ``bare'' nat argument with no options will only translate the packet being processed in the way the connection has been set up with an earlier, committed ct action46 A nat action with src or dst, when applied to a packet belonging to an established (rather than new) connection, will behave the same as a bare nat46
Open vSwitch 2466 introduced nat46 Linux 4466 was the earliest upstream kernel that implemented ct support for nat46

With commit, the connection tracker commits the connection to the connection tracking module46 The commit flag should only be used from the pipeline within the first fork of ct without commit46 Information about the connection is stored beyond the lifetime of the packet in the pipeline46 Some ct_state flags are only available for committed connections46

The following options are available only with commit:

force
A committed connection always has the directionality of the packet that caused the connection to be committed in the first place46 This is the ``original direction'' of the connection, and the opposite direction is the ``reply direction''46 If a connection is already committed, but it is in the wrong direction, force effectively terminates the existing connection and starts a new one in the current direction46 This flag has no effect if the original direction of the connection is already the same as that of the current packet46
exec(action464646)
Perform each action within the context of connection tracking46 Only actions which modify the ct_mark or ct_label fields are accepted within exec action, and these fields may only be modified with this option46 For example:
set_field:value[/mask]->ct_mark
Store a 32-bit metadata value with the connection46 Subsequent lookups for packets in this connection will populate ct_mark when the packet is sent to the connection tracker with the table specified46
set_field:value[/mask]->ct_label
Store a 128-bit metadata value with the connection46 Subsequent lookups for packets in this connection will populate ct_label when the packet is sent to the connection tracker with the table specified46
alg=alg
Specify application layer gateway alg to track specific connection types46 If subsequent related connections are sent through the ct action, then the rel flag in the ct_state field will be set46 Supported types include:
ftp
Look for negotiation of FTP data connections46 Specify this option for FTP control connections to detect related data connections and populate the rel flag for the data connections46
tftp
Look for negotiation of TFTP data connections46 Specify this option for TFTP control connections to detect related data connections and populate the rel flag for the data connections46
Related connections inherit ct_mark from that stored with the original connection (i46e46 the connection created by ct(alg=464646))46

With the Linux datapath, global sysctl options affect ct behavior46 In particular, if net46netfilter46nf_conntrack_helper is enabled, which it is by default until Linux 4467, then application layer gateway helpers may be executed even if alg is not specified46 For security reasons, the netfilter team recommends users disable this option46 For further details, please see <URL: http://www.netfilter.org/news.html#2012-04-03 > 46

The ct action may be used as a primitive to construct stateful firewalls by selectively committing some traffic, then matching ct_state to allow established connections while denying new connections46 The following flows provide an example of how to implement a simple firewall that allows new connections from port 1 to port 2, and only allows established connections to send traffic from port 2 to port 1:



table=0,priority=1,action=drop
table=0,priority=10,arp,action=normal
table=0,priority=100,ip,ct_state=-trk,action=ct(table=1)
table=1,in_port=1,ip,ct_state=+trk+new,action=ct(commit),2
table=1,in_port=1,ip,ct_state=+trk+est,action=2
table=1,in_port=2,ip,ct_state=+trk+new,action=drop
table=1,in_port=2,ip,ct_state=+trk+est,action=1

If ct is executed on IPv4 (or IPv6) fragments, then the message is implicitly reassembled before sending to the connection tracker and refragmented upon output, to the original maximum received fragment size46 Reassembly occurs within the context of the zone, meaning that IP fragments in different zones are not assembled together46 Pipeline processing for the initial fragments is halted46 When the final fragment is received, the message is assembled and pipeline processing continues for that flow46 Packet ordering is not guaranteed by IP protocols, so it is not possible to determine which IP fragment will cause message reassembly (and therefore continue pipeline processing)46 As such, it is strongly recommended that multiple flows should not execute ct to reassemble fragments from the same IP message46

Conformance:

The ct action was introduced in Open vSwitch 246546 Some of its features were introduced later, noted individually above46

 

The ct_clear action

Syntax:
ct_clear

Clears connection tracking state from the flow, zeroing ct_state, ct_zone, ct_mark, and ct_label46

This action was introduced in Open vSwitch 2466469046

 

The learn action

Syntax:
learn(argument464646)

The learn action adds or modifies a flow in an OpenFlow table, similar to ovs-ofctl --strict mod-flows46 The arguments specify the match fields, actions, and other properties of the flow to be added or modified46

Match fields for the new flow are specified as follows46 At least one match field should ordinarily be specified:

field=value
Specifies that field, in the new flow, must match the literal value, e46g46 dl_type=0x80046 Shorthand match syntax, such as ip in place of dl_type=0x800, is not supported46
field=src
Specifies that field in the new flow must match src taken from the packet currently being processed46 For example, udp_dst=udp_src, applied to a UDP packet with source port 53, creates a flow which matches udp_dst=5346 field and src must have the same width46
field
Shorthand for the previous form when field and src are the same46 For example, udp_dst, applied to a UDP packet with destination port 53, creates a flow which matches udp_dst=5346

The field and src arguments above should be fields or subfields in the syntax described under ``Field Specifications'' above46

Match field specifications must honor prerequisites for both the flow with the learn and the new flow that it creates46 Consider the following complete flow, in the syntax accepted by ovs-ofctl46 If the flow's match on udp were omitted, then the flow would not satisfy the prerequisites for the learn action's use of udp_src46 If dl_type=0x800 or nw_proto were omitted from learn, then the new flow would not satisfy the prerequisite for its match on udp_dst46 For more information on prerequisites, please refer to ovs-fields(7):



udp, actions=learn(dl_type=0x800, nw_proto=17, udp_dst=udp_src)

Actions for the new flow are specified as follows46 At least one action should ordinarily be specified:

load:value->dst
Adds a load action to the new flow that loads the literal value into dst46 The syntax is the same as the load action explained in the ``Header Modification'' section46
load:src->dst
Adds a load action to the new flow that loads src, a field or subfield from the packet being processed, into dst46
output:field
Adds an output action to the new flow's actions that outputs to the OpenFlow port taken from field, which must be a field as described above46
fin_idle_timeout=seconds

fin_hard_timeout=seconds
Adds a fin_timeout action with the specified arguments to the new flow46 This feature was added in Open vSwitch 1465469046

The following additional arguments are optional:

idle_timeout=seconds

hard_timeout=seconds
priority=value
cookie=value
send_flow_rem
These arguments have the same meaning as in the usual flow syntax documented in ovs-ofctl(8)46
table=table
The table in which the new flow should be inserted46 Specify a decimal number between 0 and 254 inclusive or the name of a table46 The default, if table is unspecified, is table 1 (not 0)46
delete_learned
When this flag is specified, deleting the flow that contains the learn action will also delete the flows created by learn46 Specifically, when the last learn action with this flag and particular table and cookie values is removed, the switch deletes all of the flows in the specified table with the specified cookie46
This flag was added in Open vSwitch 246446
limit=number
If the number of flows in the new flow's table with the same cookie exceeds number, the action will not add a new flow46 By default, or with limit=0, there is no limit46
This flag was added in Open vSwitch 246846
result_dst=field[bit]
If learn fails (because the number of flows exceeds limit), the action sets field[bit] to 0, otherwise it will be set to 146 field[bit] must be a single bit46
This flag was added in Open vSwitch 246846

By itself, the learn action can only put two kinds of actions into the flows that it creates: load and output actions46 If learn is used in isolation, these are severe limits46

However, learn is not meant to be used in isolation46 It is a primitive meant to be used together with other Open vSwitch features to accomplish a task46 Its existing features are enough to accomplish most tasks46

Here is an outline of a typical pipeline structure that allows for versatile behavior using learn:

Flows in table A contain a learn action, that populates flows in table L, that use a load action to populate register R with information about what was learned46
Flows in table B contain two sequential resubmit actions: one to table L and another one to table B+146
Flows in table B+1 match on register R and act differently depending on what the flows in table L loaded into it46

This approach can be used to implement many learn-based features46 For example:

Resubmit to a table selected based on learned information, e46g46 see <URL: https://mail.openvswitch.org/pipermail/ovs-discuss/2016-June/021694.html > 46
MAC learning in the middle of a pipeline, as described in the ``Open vSwitch Advanced Features Tutorial'' in the OVS documentation46
TCP state based firewalling, by learning outgoing connections based on SYN packets and matching them up with incoming packets46 (This is usually better implemented using the ct action46)
At least some of the features described in T46 A46 Hoff, ``Extending Open vSwitch to Facilitate Creation of Stateful SDN Applications''46

Conformance:

The learn action is an Open vSwitch extension to OpenFlow added in Open vSwitch 146346 Some features of learn were added in later versions, as noted individually above46

 

The fin_timeout action

Syntax:
fin_timeout(key=value464646)

This action changes the idle timeout or hard timeout, or both, of the OpenFlow flow that contains it, when the flow matches a TCP packet with the FIN or RST flag46 When such a packet is observed, the action reduces the rule's timeouts to those specified on the action46 If the rule's existing timeout is already shorter than the one that the action specifies, then that timeout is unaffected46

The timeouts are specified as key-value pairs:

idle_timeout=seconds
Causes the flow to expire after the given number of seconds of inactivity46
hard_timeout=seconds
Causes the flow to expire after the given number of seconds, regardless of activity46 (seconds specifies time since the flow's creation, not since the receipt of the FIN or RST46)

This action is normally added to a learned flow by the learn action46 It is unlikely to be useful otherwise46

Conformance:

This Open vSwitch extension action was added in Open vSwitch 1465469046  

PROGRAMMING AND CONTROL FLOW ACTIONS

 

The resubmit action

Syntax:
resubmit:port
resubmit([port],[table][,ct])

Searches an OpenFlow flow table for a matching flow and executes the actions found, if any, before continuing to the following action in the current flow entry46 Arguments can customize the search:

If port is given as an OpenFlow port number or name, then it specifies a value to use for the input port metadata field as part of the search, in place of the input port currently in the flow46 Specifying in_port as port is equivalent to omitting it46
If table is given as an integer between 0 and 254 or a table name, it specifies the OpenFlow table to search46 If it is not specified, the table from the current flow is used46
If ct is specified, then the search is done with packet 5-tuple fields swapped with the corresponding conntrack original direction tuple fields46 See the documentation for ct above, for more information about connection tracking, or ovs-fields(7) for details about the connection tracking fields46
This flag requires a valid connection tracking state as a match prerequisite in the flow where this action is placed46 Examples of valid connection tracking state matches include ct_state=+new, ct_state=+est, ct_state=+rel, and ct_state=+trk-inv46

The changes, if any, to the input port and connection tracking fields are just for searching the flow table46 The changes are not visible to actions or to later flow table lookups46

The most common use of resubmit is to visit another flow table without port or ct, like this: resubmit(,table)46

Recursive resubmit actions are permitted46

Conformance:

The resubmit action is an Open vSwitch extension46 However, the goto_table instruction in OpenFlow 1461 and later can be viewed as a kind of restricted resubmit46

Open vSwitch 14624690 added table46 Open vSwitch 2467 added ct46

Open vSwitch imposes a limit on resubmit recursion that varies among version:

Open vSwitch 1460461 and earlier did not support recursion46
Open vSwitch 1460462 and 1460463 limited recursion to 8 levels46
Open vSwitch 1461 and 1462 limited recursion to 16 levels46
Open vSwitch 1462 through 1468 limited recursion to 32 levels46
Open vSwitch 1469 through 2460 limited recursion to 64 levels46
Open vSwitch 2461 through 2465 limited recursion to 64 levels and impose a total limit of 4,096 resubmits per flow translation (earlier versions did not impose any total limit)46
Open vSwitch 2466 and later imposes the same limits as 2465, with one exception: resubmit from table x to any table y > x does not count against the recursion depth limit46

 

The clone action

Syntax:
clone(action464646)

Executes each nested action, saving much of the packet and pipeline state beforehand and then restoring it afterward46 The state that is saved and restored includes all flow data and metadata (including, for example, in_port and ct_state), the stack accessed by push and pop actions, and the OpenFlow action set46

This action was added in Open vSwitch 2466469046

 

The push and pop actions

Syntax:
push:src
pop:dst

The push action pushes src on a general-purpose stack46 The pop action pops an entry off the stack into dst46 src and dst should be fields or subfields in the syntax described under ``Field Specifications'' above46

Controllers can use the stack for saving and restoring data or metadata around resubmit actions, for swapping or rearranging data and metadata, or for other purposes46 Any data or metadata field, or part of one, may be pushed, and any modifiable field or subfield may be popped46

The number of bits pushed in a stack entry do not have to match the number of bits later popped from that entry46 If more bits are popped from an entry than were pushed, then the entry is conceptually left-padded with 0-bits as needed46 If fewer bits are popped than pushed, then bits are conceptually trimmed from the left side of the entry46

The stack's size is limited46 The limit is intended to be high enough that ``normal'' use will not pose problems46 Stack overflow or underflow is an error that stops action execution (see ``Stack too deep'' under ``Error Handling'', above)46

Examples:

push:reg2[046465] or push:NXM_NX_REG2[046465] pushes on the stack the 6 bits in register 2 bits 0 through 546
pop:reg2[046465] or pop:NXM_NX_REG2[046465] pops the value from top of the stack and copy bits 0 through 5 of that value into bits 0 through 5 of register 246

Conformance:

Open vSwitch 1462 introduced push and pop as OpenFlow extension actions46

 

The exit action

Syntax:
exit

This action causes Open vSwitch to immediately halt execution of further actions46 Actions which have already been executed are unaffected46 Any further actions, including those which may be in other tables, or different levels of the resubmit call stack, are ignored46 However, an exit action within a group bucket terminates only execution of that bucket, not other buckets or the overall pipeline46 Actions in the action set are still executed (specify clear_actions before exit to discard them)46

 

The multipath action

Syntax:
multipath(fields, basis, algorithm, n_links, arg, dst)

Hashes fields using basis as a universal hash parameter, then the applies multipath link selection algorithm (with parameter arg) to choose one of n_links output links numbered 0 through n_links minus 1, and stores the link into dst, which must be a field or subfield in the syntax described under ``Field Specifications'' above46

The bundle or bundle_load actions are usually easier to use than multipath46

fields must be one of the following:

eth_src
Hashes Ethernet source address only46
symmetric_l4
Hashes Ethernet source, destination, and type, VLAN ID, IPv4/IPv6 source, destination, and protocol, and TCP or SCTP (but not UDP) ports46 The hash is computed so that pairs of corresponding flows in each direction hash to the same value, in environments where L2 paths are the same in each direction46 UDP ports are not included in the hash to support protocols such as VXLAN that use asymmetric ports in each direction46
symmetric_l3l4
Hashes IPv4/IPv6 source, destination, and protocol, and TCP or SCTP (but not UDP) ports46 Like symmetric_l4, this is a symmetric hash, but by excluding L2 headers it is more effective in environments with asymmetric L2 paths (e46g46 paths involving VRRP IP addresses on a router)46 Not an effective hash function for protocols other than IPv4 and IPv6, which hash to a constant zero46
symmetric_l3l4+udp
Like symmetric_l3l4+udp, but UDP ports are included in the hash46 This is a more effective hash when asymmetric UDP protocols such as VXLAN are not a consideration46
symmetric_l3
Hashes network source address and network destination address46
nw_src
Hashes network source address only46
nw_dst
Hashes network destination address only46

The algorithm used to compute the final result link must be one of the following:

modulo_n
Computes link = hash(flow) % n_links46
This algorithm redistributes all traffic when n_links changes46 It has O(1) performance46
Use 65535 for max_link to get a raw hash value46
This algorithm is specified by RFC 299246
hash_threshold
Computes link = hash(flow) / (MAX_HASH / n_links)46
Redistributes between one-quarter and one-half of traffic when n_links changes46 It has O(1) performance46
This algorithm is specified by RFC 299246
hrw (Highest Random Weight)
Computes the following:


for
i in [0,n_links]:
weights[i] = hash(flow, i)
link = { i such that weights[i] >= weights[j] for all j != i }
Redistributes 1/n_links of traffic when n_links changes46 It has O(n_links) performance46 If n_links is greater than a threshold (currently 64, but subject to change), Open vSwitch will substitute another algorithm automatically46
This algorithm is specified by RFC 299246
iter_hash (Iterative Hash)
Computes the following:


i = 0
repeat:
i = i + 1
link = hash(flow, i) % arg
while link > max_link
Redistributes 1/n_links of traffic when n_links changes46 O(1) performance when arg/max_link is bounded by a constant46
Redistributes all traffic when arg changes46
arg must be greater than max_link and for best performance should be no more than approximately max_link * 246 If arg is outside the acceptable range, Open vSwitch will automatically substitute the least power of 2 greater than max_link46
This algorithm is specific to Open vSwitch46

Only the iter_hash algorithm uses arg46

It is an error if max_link is greater than or equal to 2**n_bits46

Conformance:

This is an OpenFlow extension added in Open vSwitch 146146  

OTHER ACTIONS

 

The conjunction action

Syntax:
conjunction(id, k/n)

This action allows for sophisticated ``conjunctive match'' flows46 Refer to ``Conjunctive Match Fields'' in ovs-fields(7) for details46

A flow that has one or more conjunction actions may not have any other actions except for note actions46

Conformance:

Open vSwitch 2464 introduced the conjunction action and conj_id field46 They are Open vSwitch extensions to OpenFlow46

 

The note action

Syntax:
note:[hh]464646

This action does nothing at all46 OpenFlow controllers may use it to annotate flows with more data than can fit in a flow cookie46

The action may include any number of bytes represented as hex digits hh46 Periods may separate pairs of hex digits, for readability46 The note action's format doesn't include an exact length for its payload, so the provided bytes will be padded on the right by enough bytes with value 0 to make the total number 6 more than a multiple of 846

Conformance:

This action is an extension to OpenFlow introduced in Open vSwitch 146146

 

The sample action

Syntax:
sample(argument464646)

Samples packets and sends one sample for every sampled packet46

The following argument forms are accepted:

probability=packets
The number of sampled packets out of 6553546 Must be greater or equal to 146
collector_set_id=id
The unsigned 32-bit integer identifier of the set of sample collectors to send sampled packets to46 Defaults to 046
obs_domain_id=id
When sending samples to IPFIX collectors, the unsigned 32-bit integer Observation Domain ID sent in every IPFIX flow record46 Defaults to 046
obs_point_id=id
When sending samples to IPFIX collectors, the unsigned 32-bit integer Observation Point ID sent in every IPFIX flow record46 Defaults to 046
sampling_port=port
Sample packets on port, which should be the ingress or egress port46 This option, which was added in Open vSwitch 24654690, allows the IPFIX implementation to export egress tunnel information46
ingress

egress
Specifies explicitly that the packet is being sampled on ingress to or egress from the switch46 IPFIX reports sent by Open vSwitch before version 24654690 did not include a direction46 From 24654690 until 24664690, IPFIX reports inferred a direction from sampling_port: if it was the packet's output port, then the direction was reported as egress, otherwise as ingress46 Open vSwitch 24664690 introduced these options, which allow the inferred direction to be overridden46 This is particularly useful when the ingress (or egress) port is not a tunnel46

Refer to ovs-vswitchd46conf46db(5) for more details on configuring sample collector sets46

Conformance:

This action is an OpenFlow extension added in Open vSwitch 246446  

INSTRUCTIONS

Every version of OpenFlow includes actions46 OpenFlow 1461 introduced the higher-level, related concept of instructions46 In OpenFlow 1461 and later, actions within a flow are always encapsulated within an instruction46 Each flow has at most one instruction of each kind, which are executed in the following fixed order defined in the OpenFlow specification:

1.
Meter
2.
Apply-Actions
3.
Clear-Actions
4.
Write-Actions
5.
Write-Metadata
6.
Stat-Trigger (not supported by Open vSwitch)
7.
Goto-Table

The most important instruction is Apply-Actions46 This instruction encapsulates any number of actions, which the instruction executes46 Open vSwitch does not explicitly represent Apply-Actions46 Instead, any action by itself is implicitly part of an Apply-Actions instructions46

Open vSwitch syntax requires other instructions, if present, to be in the order listed above46 Otherwise it will flag an error46

 

The meter action and instruction

Syntax:
meter:meter_id

Apply meter meter_id46 If a meter band rate is exceeded, the packet may be dropped, or modified, depending on the meter band type46

Conformance:

OpenFlow 1463 introduced the meter instruction46 OpenFlow 1465 changes meter from an instruction to an action46

OpenFlow 1465 allows implementations to restrict meter to be the first action in an action list and to exclude meter from action sets, for better compatibility with OpenFlow 1463 and 146446 Open vSwitch restricts the meter action both ways46

Open vSwitch 2460 introduced OpenFlow protocol support for meters, but it did not include a datapath implementation46 Open vSwitch 2467 added meter support to the userspace datapath46 Open vSwitch 24610 added meter support to the kernel datapath46 Open vSwitch 24612 added support for meter as an action in OpenFlow 146546

 

The clear_actions instruction

Syntax:
clear_actions

Clears the action set46 See ``Action Sets'', above, for more information46

Conformance:

OpenFlow 1461 introduced clear_actions46 Open vSwitch 2461 added support for clear_actions46

 

The write_actions instruction

Syntax:
write_actions(action464646)

Adds each action to the action set46 The action set is carried between flow tables and then executed at the end of the pipeline46 Only certain actions may be written to the action set46 See ``Action Sets'', above, for more information46

Conformance:

OpenFlow 1461 introduced write_actions46 Open vSwitch 2461 added support for write_actions46

 

The write_metadata instruction

Syntax:
write_metadata:value[/mask]

Updates the flow's metadata field46 If mask is omitted, metadata is set exactly to value; if mask is specified, then a 1-bit in mask indicates that the corresponding bit in metadata will be replaced with the corresponding bit from value46 Both value and mask are 64-bit values that are decimal by default; use a 0x prefix to specify them in hexadecimal46

The metadata field can also be matched in the flow table and updated with actions such as set_field and move46

Conformance:

OpenFlow 1461 introduced write_metadata46 Open vSwitch 2461 added support for write_metadata46

 

The goto_table instruction

Syntax:
goto_table:table

Jumps to table as the next table in the process pipeline46 The table may be a number between 0 and 254 or a table name46

It is an error if table is less than or equal to the table of the flow that contains it; that is, goto_table must move forward in the OpenFlow pipeline46 Since goto_table must be the last instruction in a flow, it never leads to recursion46 The resubmit extension action is more flexible46

Conformance:

OpenFlow 1461 introduced goto_table46 Open vSwitch 2461 added support for goto_table46


 

Index

NAME
INTRODUCTION
Actions
Error Handling
Inconsistencies
Inter-Version Compatibility
Field Specifications
Port Specifications
OUTPUT ACTIONS
The output action
The controller action
The enqueue action
The bundle and bundle_load actions
The group action
ENCAPSULATION AND DECAPSULATION ACTIONS
The strip_vlan and pop actions
The push_vlan action
The push_mpls action
The pop_mpls action
The encap action
The decap action
FIELD MODIFICATION ACTIONS
The set_field and load actions
The move action
The mod_dl_src and mod_dl_dst actions
The mod_nw_src and mod_nw_dst actions
The mod_nw_tos and mod_nw_ecn actions
The mod_tp_src and mod_tp_dst actions
The dec_ttl action
The set_mpls_label, set_mpls_tc, and set_mpls_ttl actions
The dec_mpls_ttl and dec_nsh_ttl actions
The check_pkt_larger action
METADATA ACTIONS
The set_tunnel action
The set_queue and pop_queue actions
FIREWALLING ACTIONS
The ct action
The ct_clear action
The learn action
The fin_timeout action
PROGRAMMING AND CONTROL FLOW ACTIONS
The resubmit action
The clone action
The push and pop actions
The exit action
The multipath action
OTHER ACTIONS
The conjunction action
The note action
The sample action
INSTRUCTIONS
The meter action and instruction
The clear_actions instruction
The write_actions instruction
The write_metadata instruction
The goto_table instruction
LinuxReviews : manual page archive : man7