---

   ovs-actions    ( 7 )

---

OUTPUT ACTIONS

These actions send a packet to a physical port or a controller. A packet that never encounters an output action on its trip through the Open vSwitch pipeline is effectively dropped. 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 effect.

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 port. Alternatively, the output port may be read from field, a field or subfield in the syntax described under ``Field Specifications'' above. Either way, if the port is the packet's input port, the packet is not output.

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 port. OpenFlow switch implementations are not required to have a local port, but Open vSwitch bridges always do.

in_port Outputs the packet on the port on which it was received. This is the only standard way to output the packet to the input port (but see ``Output to the Input port'', below).

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 processing. This action is not implemented by all OpenFlow switches, and each switch implements it differently. The section ``The OVS Normal Pipeline'' below documents the OVS implementation.

flood Outputs the packet on all switch physical ports, except the port on which it was received and any ports on which flooding is disabled. Flooding can be disabled automatically on a port by Open vSwitch when IEEE 802.1D 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).

all Outputs the packet on all switch physical ports except the port on which it was received.

controller Sends the packet and its metadata to an OpenFlow controller or controllers encapsulated in an OpenFlow ``packet-in'' message. The separate controller action, described below, provides more options for output to a controller.

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_PORT.

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

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 action. All versions of Open vSwitch treat such an action as a no-op. If a port with the number is created later, then the action will be honored at that point. (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 time.)

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). When output is disabled, output actions (and other actions that output to the port) are allowed but have no effect.

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

Output to the Input Port

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

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

$ 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 port. 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 port. It's difficult to take advantage of output to in_port in this situation. To help, Open vSwitch provides, as an OpenFlow extension, the ability to modify the in_port field. Whatever value is currently in the in_port field is both the port to which output will be dropped and the destination for in_port. 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 port. Output to a register is an OpenFlow extension introduced in Open vSwitch 1.3. Output with truncation is an OpenFlow extension introduced in Open vSwitch 2.6.

The OVS Normal Pipeline This section documents how Open vSwitch implements output to the normal port. The OpenFlow specification places no requirements on how this port works, so all of this documentation is specific to Open vSwitch.

Open vSwitch uses the Open_vSwitch database, detailed in ovs-vswitchd.conf.db(5), to determine the details of the normal pipeline.

The normal pipeline executes the following ingress stages for each packet. Each stage either accepts the packet, in which case the packet goes on to the next stage, or drops the packet, which terminates the pipeline. The result of the ingress stages is a set of output ports, which is the empty set if some ingress stage drops the packet:

1. Input port lookup: Looks up the OpenFlow in_port field's value to the corresponding Port and Interface record in the database.

The in_port is normally the OpenFlow port that the packet was received on. If set_field or another actions changes the in_port, the updated value is honored. Accept the packet if the lookup succeeds, which it normally will. If the lookup fails, for example because in_port was changed to an unknown value, drop the packet.

2. Drop malformed packet: If the packet is malformed enough that it contains only part of an 802.1Q header, then drop the packet with an error.

3. Drop packets sent to a port reserved for mirroring: If the packet was received on a port that is configured as the output port for a mirror (that is, it is the output_port in some Mirror record), then drop the packet.

4. VLAN input processing: This stage determines what VLAN the packet is in. It also verifies that this VLAN is valid for the port; if not, drop the packet. How the VLAN is determined and which ones are valid vary based on the vlan-mode in the input port's Port record:

trunk The packet is in the VLAN specified in its 802.1Q header, or in VLAN 0 if there is no 802.1Q header. The trunks column in the Port record lists the valid VLANs; if it is empty, all VLANs are valid.

access The packet is in the VLAN specified in the tag column of its Port record. The packet must not have an 802.1Q header with a nonzero VLAN ID; if it does, drop the packet.

native-tagged native-untagged Same as trunk except that the VLAN of a packet without an 802.1Q header is not necessarily zero; instead, it is taken from the tag column.

dot1q-tunnel The packet is in the VLAN specified in the tag column of its Port record, which is a QinQ service VLAN with the Ethertype specified by the Port's other_config : qinq-ethtype. If the packet has an 802.1Q header, then it specifies the customer VLAN. The cvlans column specifies the valid customer VLANs; if it is empty, all customer VLANs are valid.

5. Drop reserved multicast addresses: If the packet is addressed to a reserved Ethernet multicast address and the Bridge record does not have other_config : forward-bpdu set to true, drop the packet.

6. LACP bond admissibility: This step applies only if the input port is a member of a bond (a Port with more than one Interface) and that bond is configured to use LACP. Otherwise, skip to the next step.

The behavior here depends on the state of LACP negotiation:

• If LACP has been negotiated with the peer, accept the packet if the bond member is enabled (i.e. carrier is up and it hasn't been administratively disabled). Otherwise, drop the packet.

• If LACP negotiation is incomplete, then drop the packet. There is one exception: if fallback to active-backup mode is enabled, continue with the next step, pretending that the active- backup balancing mode is in use.

7. Non-LACP bond admissibility: This step applies if the input port is a member of a bond without LACP configured, or if a LACP bond falls back to active- backup as described in the previous step. If neither of these applies, skip to the next step.

If the packet is an Ethernet multicast or broadcast, and not received on the bond's active member, drop the packet.

The remaining behavior depends on the bond's balancing mode:

L4 (aka TCP balancing) Drop the packet (this balancing mode is only supported with LACP).

Active-backup Accept the packet only if it was received on the active member.

SLB (Source Load Balancing) Drop the packet if the bridge has not learned the packet's source address (in its VLAN) on the port that received it. Otherwise, accept the packet unless it is a gratuitous ARP. Otherwise, accept the packet if the MAC entry we found is ARP-locked. Otherwise, drop the packet. (See the ``SLB Bonding'' section in the OVS bonding document for more information and a rationale.)

8. Learn source MAC: If the source Ethernet address is not a multicast address, then insert a mapping from packet's source Ethernet address and VLAN to the input port in the bridge's MAC learning table. (This is skipped if the packet's VLAN is listed in the switch's Bridge record in the flood_vlans column, since there is no use for MAC learning when all packets are flooded.)

When learning happens on a non-bond port, if the packet is a gratuitous ARP, the entry is marked as ARP-locked. The lock expires after 5 seconds. (See the ``SLB Bonding'' section in the OVS bonding document for more information and a rationale.)

9. IP multicast path: If multicast snooping is enabled on the bridge, and the packet is an Ethernet multicast but not an Ethernet broadcast, and the packet is an IP packet, then the packet takes a special processing path. This path is not yet documented here.

10. Output port set: Search the MAC learning table for the port corresponding to the packet's Ethernet destination and VLAN. If the search finds an entry, the output port set is just the learned port. Otherwise (including the case where the packet is an Ethernet multicast or in flood_vlans), the output port set is all of the ports in the bridge that belong to the packet's VLAN, except for any ports that were disabled for flooding via OpenFlow or that are configured in a Mirror record as a mirror destination port.

The following egress stages execute once for each element in the set of output ports. They execute (conceptually) in parallel, so that a decision or action taken for a given output port has no effect on those for another one:

1. Drop loopback: If the output port is the same as the input port, drop the packet.

2. VLAN output processing: This stage adjusts the packet to represent the VLAN in the correct way for the output port. Its behavior varies based on the vlan-mode in the output port's Port record:

trunk native-tagged native-untagged If the packet is in VLAN 0 (for native-untagged, if the packet is in the native VLAN) drops any 802.1Q header. Otherwise, ensures that there is an 802.1Q header designating the VLAN.

access Remove any 802.1Q header that was present.

dot1q-tunnel Ensures that the packet has an outer 802.1Q header with the QinQ Ethertype and the specified configured tag, and an inner 802.1Q header with the packet's VLAN.

3. VLAN priority tag processing: If VLAN output processing discarded the 802.1Q headers, but priority tags are enabled with other_config : priority-tags in the output port's Port record, then a priority-only tag is added (perhaps only if the priority would be nonzero, depending on the configuration).

4. Bond member choice: If the output port is a bond, the code chooses a particular member. This step is skipped for non-bonded ports.

If the bond is configured to use LACP, but LACP negotiation is incomplete, then normally the packet is dropped. The exception is that if fallback to active- backup mode is enabled, the egress pipeline continues choosing a bond member as if active-backup mode was in use.

For active-backup mode, the output member is the active member. Other modes hash appropriate header fields and use the hash value to choose one of the enabled members.

5. Output: The pipeline sends the packet to the output port.

The controller action Syntax: controller controller:max_len controller(key[=value], ...)

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

max_len=max_len Limit to max_len the number of bytes of the packet to send in the ``packet-in.'' A max_len of 0 prevents any of the packet from being sent (thus, only metadata is included). By default, the entire packet is sent, equivalent to a max_len of 65535.

reason=reason Specify reason as the reason for sending the message in the ``packet-in.'' The supported reasons are no_match, action, invalid_ttl, action_set, group, and packet_out. The default reason is action.

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 sent. The default is zero. 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 OpenFlow.

userdata=hh... Supplies the bytes represented as hex digits hh as additional data to the controller in the ``packet- in'' message. Pairs of hex digits may be separated by periods for readability.

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 message. 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 interrupted. This permits an OpenFlow controller to interpose on a packet midway through processing in Open vSwitch.

Conformance:

All versions of OpenFlow and Open vSwitch support controller action and its max_len option. The userdata and pause options require the Open vSwitch NXAST_CONTROLLER2 extension action added in Open vSwitch 2.6. 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 1.6.

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

Enqueues the packet on the specified queue within port port.

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

queue must be a a number between 0 and 4294967294 (0xfffffffe), inclusive. The number of actually supported queues depends on the switch. Some OpenFlow implementations do not support queuing at all. In Open vSwitch, the supported queues vary depending on the operating system, datapath, and hardware in use. Use the QoS and Queue tables in the Open vSwitch database to configure queuing on individual OpenFlow ports (see ovs-vswitchd.conf.db(5) for more information).

Conformance:

Only OpenFlow 1.0 supports enqueue. OpenFlow 1.1 added the set_queue action to use in its place along with output.

Open vSwitch translates enqueue to a sequence of three actions in OpenFlow 1.1 or later: set_queue:queue, output:port, pop_queue. 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 action.

The bundle and bundle_load actions Syntax: bundle(fields, basis, algorithm, ofport, members:port...) bundle_load(fields, basis, algorithm, ofport, dst, members:port...)

These actions choose a port (a ``member'') from a comma-separated OpenFlow port list. 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'' above.

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

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

eth_src Ethernet source address.

nw_src IPv4 or IPv6 source address.

nw_dst IPv4 or IPv6 destination address.

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 destination.

symmetric_l3l4 IPv4 or IPv6 source and destination, IP protocol, TCP or SCTP (but not UDP) source and destination.

symmetric_l3l4+udp Like symmetric_l3l4 but include UDP ports.

algorithm must be one of the following:

active_backup Chooses the first live port listed in members.

hrw (Highest Random Weight) Computes the following, considering only the live ports in members:

for i in [1,n_members]: weights[i] = hash(flow, i) member = { i such that weights[i] >= weights[j] for all j != i }

This algorithm is specified by RFC 2992.

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

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

Conformance:

Open vSwitch 1.2 introduced the bundle and bundle_load OpenFlow extension actions.

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). The group must exist or Open vSwitch will refuse to add the flow. When a group is deleted, Open vSwitch also deletes all of the flows that output to it.

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

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

Sometimes saving and restoring the packet and metadata can be undesirable. In these situations, workarounds are possible. 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 selected. An obvious design would be for the bucket to communicate the value via set_field on a register. This does not work because registers are part of the metadata that group saves and restores. The following alternative bucket designs do work:

• Recursively invoke the rest of the pipeline with resubmit.

• Use resubmit into a table that uses push to put the value on the stack for the caller to pop off. This works because group preserves only packet data and metadata, not the stack.

(This design requires indirection through resubmit because actions sets may not contain push or pop actions.)

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

Conformance:

OpenFlow 1.1 introduced group. Open vSwitch 2.6 and later also supports group as an extension to OpenFlow 1.0.