1OVS-ACTIONS(7) Open vSwitch OVS-ACTIONS(7)
2
6 ovs-actions - OpenFlow actions and instructions with Open vSwitch ex‐
7 tensions
8
10 This document aims to comprehensively document all of the OpenFlow ac‐
11 tions and instructions, both standard and non-standard, supported by
12 Open vSwitch, regardless of origin. The document includes information
13 of interest to Open vSwitch users, such as the semantics of each sup‐
14 ported action and the syntax used by Open vSwitch tools, and to devel‐
15 opers seeking to build controllers and switches compatible with Open
16 vSwitch, such as the wire format for each supported message.
17 Actions
19 In this document, we define an action as an OpenFlow action, which is a
20 kind of command that specifies what to do with a packet. Actions are
21 used in OpenFlow flows to describe what to do when the flow matches a
22 packet, and in a few other places in OpenFlow. Each version of the
23 OpenFlow specification defines standard actions, and beyond that many
24 OpenFlow switches, including Open vSwitch, implement extensions to the
25 standard.
26 OpenFlow groups actions in two ways: as an action list or an action
28 set, described below.
29 Action Lists
31 An action list, a concept present in every version of OpenFlow, is sim‐
32 ply an ordered sequence of actions. The OpenFlow specifications re‐
33 quire a switch to execute actions within an action list in the order
34 specified, and to refuse to execute an action list entirely if it can‐
35 not implement the actions in that order [OpenFlow 1.0, section 3.3],
36 with one exception: when an action list outputs multiple packets, the
37 switch may output the packets in an order different from that speci‐
38 fied. Usually, this exception is not important, especially in the com‐
39 mon case when the packets are output to different ports.
40 Action Sets
42 OpenFlow 1.1 introduced the concept of an action set. An action set is
43 also a sequence of actions, but the switch reorders the actions and
44 drops duplicates according to rules specified in the OpenFlow specifi‐
45 cations. Because of these semantics, some standard OpenFlow actions
46 cannot usefully be included in an action set. For some, but not all,
47 Open vSwitch extension actions, Open vSwitch defines its own action set
48 semantics and ordering.
49 The OpenFlow pipeline has an action set associated with it as a packet
51 is processed. After pipeline processing is otherwise complete, the
52 switch executes the actions in the action set.
53 Open vSwitch applies actions in an action set in the following order:
55 Except as noted otherwise below, the action set only executes at most a
56 single action of each type, and when more than one action of a given
57 type is present, the one added to the set later replaces the earlier
58 action:
59 1. strip_vlan
61 2. pop_mpls
63 3. decap
65 4. encap
67 5. push_mpls
69 6. push_vlan
71 7. dec_ttl
73 8. dec_mpls_ttl
75 9. dec_nsh_ttl
77 10. All of the following actions are executed in the order added to
79 the action set, with cumulative effect. That is, when multiple
80 actions modify the same part of a field, the later modification
81 takes effect, and when they modify different parts of a field
82 (or different fields), then both modifications are applied:
83 • load
85 • move
87 • mod_dl_dst
89 • mod_dl_src
91 • mod_nw_dst
93 • mod_nw_src
95 • mod_nw_tos
97 • mod_nw_ecn
99 • mod_nw_ttl
101 • mod_tp_dst
103 • mod_tp_src
105 • mod_vlan_pcp
107 • mod_vlan_vid
109 • set_field
111 • set_tunnel
113 • set_tunnel64
115 11. set_queue
117 12. group, output, resubmit, ct_clear, or ct. If more than one of
119 these actions is present, then the one listed earliest above is
120 executed and the others are ignored, regardless of the order in
121 which they were added to the action set. (If none of these ac‐
122 tions is present, the action set has no real effect, because the
123 modified packet is not sent anywhere and thus the modifications
124 are not visible.)
125 An action set may only contain the actions listed above.
127 Error Handling
129 Packet processing can encounter a variety of errors:
130 Bridge not found
132 Open vSwitch supports an extension to the standard OpenFlow con‐
133 troller action called a continuation, which allows the con‐
134 troller to interrupt and later resume the processing of a packet
135 through the switch pipeline. This error occurs when such a
136 packet’s processing cannot be resumed, e.g. because the bridge
137 processing it has been destroyed. Open vSwitch reports this er‐
138 ror to the controller as Open vSwitch extension error NXR_STALE.
139 This error prevents packet processing entirely.
141 Recursion too deep
143 While processing a given packet, Open vSwitch limits the flow
144 table recursion depth to 64, to ensure that packet processing
145 uses a finite amount of time and space. Actions that count
146 against the recursion limit include resubmit from a given Open‐
147 Flow table to the same or an earlier table, group, and output to
148 patch ports.
149 A resubmit from one table to a later one (or, equivalently, a
151 goto_table instruction) does not count against the depth limit
152 because resubmits to strictly monotonically increasing tables
153 will eventually terminate. OpenFlow tables are most commonly
154 traversed in numerically increasing order, so this limit has
155 little effect on conventionally designed OpenFlow pipelines.
156 This error terminates packet processing. Any previous side ef‐
158 fects (e.g. output actions) are retained.
159 Usually this error indicates a loop or other bug in the OpenFlow
161 flow tables. To assist debugging, when this error occurs, Open
162 vSwitch 2.10 and later logs a trace of the packet execution, as
163 if by ovs-appctl ofproto/trace, rate-limited to one per minute
164 to reduce the log volume.
165 Too many resubmits
167 Open vSwitch limits the total number of resubmit actions that a
168 given packet can execute to 4,096. For this purpose, goto_table
169 instructions and output to the table port are treated like re‐
170 submit. This limits the amount of time to process a single
171 packet.
172 Unlike the limit on recursion depth, the limit on resubmits
174 counts all resubmits, regardless of direction.
175 This error has the same effect, including logging, as exceeding
177 the recursion depth limit.
178 Stack too deep
180 Open vSwitch limits the amount of data that the push action can
181 put onto the stack at one time to 64 kB of data.
182 This error terminates packet processing. Any previous side ef‐
184 fects (e.g. output actions) are retained.
185 No recirculation context / Recirculation conflict
187 These errors indicate internal errors inside Open vSwitch and
188 should generally not occur. If you notice recurring log mes‐
189 sages about these errors, please report a bug.
190 Too many MPLS labels
192 Open vSwitch can process packets with any number of MPLS labels,
193 but its ability to push and pop MPLS labels is limited, cur‐
194 rently to 3 labels. Attempting to push more than the supported
195 number of labels onto a packet, or to pop any number of labels
196 from a packet with more than the supported number, raises this
197 error.
198 This error terminates packet processing, retaining any previous
200 side effects (e.g. output actions). When this error arises
201 within the execution of a group bucket, it only terminates that
202 bucket’s execution, not packet processing overall.
203 Invalid tunnel metadata
205 Open vSwitch raises this error when it processes a Geneve packet
206 that has TLV options with an invalid form, e.g. where the length
207 in a TLV would extend past the end of the options.
208 This error prevents packet processing entirely.
210 Unsupported packet type
212 When a encap action encapsulates a packet, Open vSwitch raises
213 this error if it does not support the combination of the new en‐
214 capsulation with the current packet. encap(ethernet) raises
215 this error if the current packet is not an L3 packet, and en‐
216 cap(nsh) raises this error if the current packet is not Ether‐
217 net, IPv4, IPv6, or NSH.
218 The decap action is supported only for packet types ethernet,
220 NSH and MPLS. Openvswitch raises this error for other packet
221 types. When a decap action decapsulates a packet, Open vSwitch
222 raises this error if it does not support the type of inner
223 packet. decap of an Ethernet header raises this error if a VLAN
224 header is present, decap of a NSH packet raises this error if
225 the NSH inner packet is not Ethernet, IPv4, IPv6, or NSH.
226 This error terminates packet processing, retaining any previous
228 side effects (e.g. output actions). When this error arises
229 within the execution of a group bucket, it only terminates that
230 bucket’s execution, not packet processing overall.
231 Inconsistencies
233 OpenFlow 1.0 allows any action to be part of any flow, regardless of
234 the flow’s match. Some combinations do not make sense, e.g. an
235 set_nw_tos action in a flow that matches only ARP packets or strip_vlan
236 in a flow that matches packets without VLAN tags. Other combinations
237 have varying results depending on the kind of packet that the flow pro‐
238 cesses, e.g. a set_nw_src action in a flow that does not match on
239 Ethertype will be treated as a no-op when it processes a non-IPv4
240 packet. Nevertheless OVS allows all of the above in conformance with
241 OpenFlow 1.0, that is, the following will succeed:
242 $ ovs-ofctl -O OpenFlow10 add-flow br0 arp,actions=mod_nw_tos:12
244 $ ovs-ofctl -O OpenFlow10 add-flow br0 dl_vlan=0xffff,actions=strip_vlan
245 $ ovs-ofctl -O OpenFlow10 add-flow br0 actions=mod_nw_src:1.2.3.4
246 Open vSwitch calls these kinds of combinations inconsistencies between
248 match and actions. OpenFlow 1.1 and later forbid inconsistencies, and
249 disallow the examples described above by preventing such flows from be‐
250 ing added. All of the above, for example, will fail with an error mes‐
251 sage if one replaces OpenFlow10 by OpenFlow11.
252 OpenFlow 1.1 and later cannot detect and disallow all inconsistencies.
254 For example, the write_actions instruction arbitrarily delays execution
255 of the actions inside it, which can even be canceled with clear_ac‐
256 tions, so that there is no way to ensure that its actions are consis‐
257 tent with the packet at the time they execute. Thus, actions with
258 write_actions and some other contexts are exempt from consistency re‐
259 quirements.
260 When OVS executes an action inconsistent with the packet, it treats it
262 as a no-op.
263 Inter-Version Compatibility
265 Open vSwitch supports multiple OpenFlow versions simultaneously on a
266 single switch. When actions are added with one OpenFlow version and
267 then retrieved with another, Open vSwitch does its best to translate
268 between them.
269 Inter-version compatibility issues can still arise when different con‐
271 nections use different OpenFlow versions. Backward compatibility is
272 the most obvious case. Suppose, for example, that an OpenFlow 1.1 ses‐
273 sion adds a flow with a push_vlan action, for which there is no equiva‐
274 lent in OpenFlow 1.0. If an OpenFlow 1.0 session retrieves this flow,
275 Open vSwitch must somehow represent the action.
276 Forward compatibility can also be an issue, because later OpenFlow ver‐
278 sions sometimes remove functionality. The best example is the enqueue
279 action from OpenFlow 1.0, which OpenFlow 1.1 removed.
280 In practice, Open vSwitch uses a variety of strategies for inter-ver‐
282 sion compatibility:
283 • Most standard OpenFlow actions, such as output actions, translate
285 without compatibility issues.
286 • Open vSwitch supports its extension actions in every OpenFlow ver‐
288 sion, so they do not pose inter-version compatibility problems.
289 • Open vSwitch sometimes adds extension actions to ensure backward or
291 forward compatibility. For example, for backward compatibility with
292 the group action added in OpenFlow 1.1, Open vSwitch includes an
293 OpenFlow 1.0 extension group action.
294 Perfect inter-version compatibility is not possible, so best results
296 require OpenFlow connections to use a consistent version. One may en‐
297 force use of a particular version by setting the protocols column for a
298 bridge, e.g. to force br0 to use only OpenFlow 1.3:
299 ovs-vsctl set bridge br0 protocols=OpenFlow13
301 Field Specifications
303 Many Open vSwitch actions refer to fields. In such cases, fields may
304 usually be referred to by their common names, such as eth_dst for the
305 Ethernet destination field, or by their full OXM or NXM names, such as
306 NXM_OF_ETH_DST or OXM_OF_ETH_DST. Before Open vSwitch 2.7, only OXM or
307 NXM field names were accepted.
308 Many actions that act on fields can also act on subfields, that is,
310 parts of fields, written as field[start..end], where start is the first
311 bit and end is the last bit to use in field, e.g. vlan_tci[13..15] for
312 the VLAN PCP. A single-bit subfield may also be written as field[off‐
313 set], e.g. vlan_tci[13] for the least-significant bit of the VLAN PCP.
314 Empty brackets may be used to explicitly designate an entire field,
315 e.g. vlan_tci[] for the entire 16-bit VLAN TCI header. Before Open
316 vSwitch 2.7, brackets were required in field specifications.
317 See ovs-fields(7) for a list of fields and their names.
319 Port Specifications
321 Many Open vSwitch actions refer to OpenFlow ports. In such cases, the
322 port may be specified as a numeric port number in the range 0 to
323 65,535, although Open vSwitch only assigns port numbers in the range 1
324 through 62,279 to ports. OpenFlow 1.1 and later use 32-bit port num‐
325 bers, but Open vSwitch never assigns a port number that requires more
326 than 16 bits.
327 In most contexts, the name of a port may also be used. (The most obvi‐
329 ous context where a port name may not be used is in an ovs-ofctl com‐
330 mand along with the --no-names option.) When a port’s name contains
331 punctuation or could be ambiguous with other actions, the name may be
332 enclosed in double quotes, with JSON-like string escapes supported (see
333 [RFC 8259]).
334 Open vSwitch also supports the following standard OpenFlow port names
336 (even in contexts where port names are not otherwise supported). The
337 corresponding OpenFlow 1.0 and 1.1+ port numbers are listed alongside
338 them but should not be used in flow syntax:
339 • in_port (65528 or 0xfff8; 0xfffffff8)
341 • table (65529 or 0xfff9; 0xfffffff9)
343 • normal (65530 or 0xfffa; 0xfffffffa)
345 • flood (65531 or 0xfffb; 0xfffffffb)
347 • all (65532 or 0xfffc; 0xfffffffc)
349 • controller (65533 or 0xfffd; 0xfffffffd)
351 • local (65534 or 0xfffe; 0xfffffffe)
353 • any or none (65535 or 0xffff; 0xffffffff)
355 • unset (not in OpenFlow 1.0; 0xfffffff7)
357
359 These actions send a packet to a physical port or a controller. A
360 packet that never encounters an output action on its trip through the
361 Open vSwitch pipeline is effectively dropped. Because actions are exe‐
362 cuted in order, a packet modification action that is not eventually
363 followed by an output action will not have an externally visible ef‐
364 fect.
365 The output action
367 Syntax:
368 port
369 output:port
370 output:field
371 output(port=port, max_len=nbytes)
372 Outputs the packet to an OpenFlow port most commonly specified as port.
375 Alternatively, the output port may be read from field, a field or sub‐
376 field in the syntax described under Field Specifications above. Either
377 way, if the port is the packet’s input port, the packet is not output.
378 The port may be one of the following standard OpenFlow ports:
380 local Outputs the packet on the local port that corresponds to the
382 network device that has the same name as the bridge, unless
383 the packet was received on the local port. OpenFlow switch
384 implementations are not required to have a local port, but
385 Open vSwitch bridges always do.
386 in_port
388 Outputs the packet on the port on which it was received.
389 This is the only standard way to output the packet to the in‐
390 put port (but see Output to the Input port, below).
391 The port may also be one of the following additional OpenFlow ports,
393 unless max_len is specified:
394 normal Subjects the packet to the device’s normal L2/L3 processing.
396 This action is not implemented by all OpenFlow switches, and
397 each switch implements it differently. The section The OVS
398 Normal Pipeline below documents the OVS implementation.
399 flood Outputs the packet on all switch physical ports, except the
401 port on which it was received and any ports on which flooding
402 is disabled. Flooding can be disabled automatically on a
403 port by Open vSwitch when IEEE 802.1D spanning tree (STP) or
404 rapid spanning tree (RSTP) is enabled, or by a controller us‐
405 ing an OpenFlow OFPT_MOD_PORT request to set the port’s OF‐
406 PPC_NO_FLOOD flag (ovs-ofctl mod-port provides a command-line
407 interface to set this flag).
408 all Outputs the packet on all switch physical ports except the
410 port on which it was received.
411 controller
413 Sends the packet and its metadata to an OpenFlow controller
414 or controllers encapsulated in an OpenFlow packet-in message.
415 The separate controller action, described below, provides
416 more options for output to a controller.
417 Open vSwitch rejects output to other standard OpenFlow ports, including
419 none, unset, and port numbers reserved for future use as standard
420 ports, with the error OFPBAC_BAD_OUT_PORT.
421 With max_len, the packet is truncated to at most nbytes bytes before
423 being output. In this case, the output port may not be a patch port.
424 Truncation is just for the single output action, so that later actions
425 in the OpenFlow pipeline work with the complete packet. The truncation
426 feature is meant for use in monitoring applications, e.g. for mirroring
427 packets to a collector.
428 When an output action specifies the number of a port that does not cur‐
430 rently exist (and is not in the range for standard ports), the OpenFlow
431 specification allows but does not require OVS to reject the action.
432 All versions of Open vSwitch treat such an action as a no-op. If a
433 port with the number is created later, then the action will be honored
434 at that point. (OpenFlow requires OVS to reject output to a port num‐
435 ber that will never be valid, with OFPBAC_BAD_OUT_PORT, but this situa‐
436 tion does not arise when OVS is a software switch, since the user can
437 add or renumber ports at any time.)
438 A controller can suppress output to a port by setting its OFPPC_NO_FOR‐
440 WARD flag using an OpenFlow OFPT_MOD_PORT request (ovs-ofctl mod-port
441 provides a command-line interface to set this flag). When output is
442 disabled, output actions (and other actions that output to the port)
443 are allowed but have no effect.
444 Open vSwitch allows output to a port that does not exist, although
446 OpenFlow allows switches to reject such actions.
447 Conformance
449 All versions of OpenFlow and Open vSwitch support output to a
450 literal port. Output to a register is an OpenFlow extension in‐
451 troduced in Open vSwitch 1.3. Output with truncation is an
452 OpenFlow extension introduced in Open vSwitch 2.6.
453 Output to the Input Port
455 OpenFlow requires a switch to ignore attempts to send a packet out its
456 ingress port in the most straightforward way. For example, output:234
457 has no effect if the packet has ingress port 234. The rationale is
458 that dropping these packets makes it harder to loop the network. Some‐
459 times this behavior can even be convenient, e.g. it is often the de‐
460 sired behavior in a flow that forwards a packet to several ports
461 (floods the packet).
462 Sometimes one really needs to send a packet out its ingress port (hair‐
464 pin). In this case, use in_port to explicitly output the packet to its
465 input port, e.g.:
466 $ ovs-ofctl add-flow br0 in_port=2,actions=in_port
468 This also works in some circumstances where the flow doesn’t match on
470 the input port. For example, if you know that your switch has five
471 ports numbered 2 through 6, then the following will send every received
472 packet out every port, even its ingress port:
473 $ ovs-ofctl add-flow br0 actions=2,3,4,5,6,in_port
475 or, equivalently:
477 $ ovs-ofctl add-flow br0 actions=all,in_port
479 Sometimes, in complicated flow tables with multiple levels of resubmit
481 actions, a flow needs to output to a particular port that may or may
482 not be the ingress port. It’s difficult to take advantage of output to
483 in_port in this situation. To help, Open vSwitch provides, as an Open‐
484 Flow extension, the ability to modify the in_port field. Whatever
485 value is currently in the in_port field is both the port to which out‐
486 put will be dropped and the destination for in_port. This means that
487 the following adds flows that reliably output to port 2 or to ports 2
488 through 6, respectively:
489 $ ovs-ofctl add-flow br0 "in_port=2,actions=load:0->in_port,2"
491 $ ovs-ofctl add-flow br0 "actions=load:0->in_port,2,3,4,5,6"
492 If in_port is important for matching or other reasons, one may save and
494 restore it on the stack:
495 $ ovs-ofctl add-flow br0 \
497 actions="push:in_port,load:0->in_port,2,3,4,5,6,pop:in_port"
498 The OVS Normal Pipeline
500 This section documents how Open vSwitch implements output to the normal
501 port. The OpenFlow specification places no requirements on how this
502 port works, so all of this documentation is specific to Open vSwitch.
503 Open vSwitch uses the Open_vSwitch database, detailed in
505 ovs-vswitchd.conf.db(5), to determine the details of the normal pipe‐
506 line.
507 The normal pipeline executes the following ingress stages for each
509 packet. Each stage either accepts the packet, in which case the packet
510 goes on to the next stage, or drops the packet, which terminates the
511 pipeline. The result of the ingress stages is a set of output ports,
512 which is the empty set if some ingress stage drops the packet:
513 1. Input port lookup: Looks up the OpenFlow in_port field’s value to
515 the corresponding Port and Interface record in the database.
516 The in_port is normally the OpenFlow port that the packet was re‐
518 ceived on. If set_field or another actions changes the in_port,
519 the updated value is honored. Accept the packet if the lookup suc‐
520 ceeds, which it normally will. If the lookup fails, for example
521 because in_port was changed to an unknown value, drop the packet.
522 2. Drop malformed packet: If the packet is malformed enough that it
524 contains only part of an 802.1Q header, then drop the packet with
525 an error.
526 3. Drop packets sent to a port reserved for mirroring: If the packet
528 was received on a port that is configured as the output port for a
529 mirror (that is, it is the output_port in some Mirror record), then
530 drop the packet.
531 4. VLAN input processing: This stage determines what VLAN the packet
533 is in. It also verifies that this VLAN is valid for the port; if
534 not, drop the packet. How the VLAN is determined and which ones
535 are valid vary based on the vlan-mode in the input port’s Port
536 record:
537 trunk The packet is in the VLAN specified in its 802.1Q header,
539 or in VLAN 0 if there is no 802.1Q header. The trunks
540 column in the Port record lists the valid VLANs; if it is
541 empty, all VLANs are valid.
542 access The packet is in the VLAN specified in the tag column of
544 its Port record. The packet must not have an 802.1Q
545 header with a nonzero VLAN ID; if it does, drop the
546 packet.
547 native-tagged / native-untagged
549 Same as trunk except that the VLAN of a packet without an
550 802.1Q header is not necessarily zero; instead, it is
551 taken from the tag column.
552 dot1q-tunnel
554 The packet is in the VLAN specified in the tag column of
555 its Port record, which is a QinQ service VLAN with the
556 Ethertype specified by the Port’s other_con‐
557 fig:qinq-ethtype. If the packet has an 802.1Q header,
558 then it specifies the customer VLAN. The cvlans column
559 specifies the valid customer VLANs; if it is empty, all
560 customer VLANs are valid.
561 5. Drop reserved multicast addresses: If the packet is addressed to a
563 reserved Ethernet multicast address and the Bridge record does not
564 have other_config:forward-bpdu set to true, drop the packet.
565 6. LACP bond admissibility: This step applies only if the input port
567 is a member of a bond (a Port with more than one Interface) and
568 that bond is configured to use LACP. Otherwise, skip to the next
569 step.
570 The behavior here depends on the state of LACP negotiation:
572 • If LACP has been negotiated with the peer, accept the packet
574 if the bond member is enabled (i.e. carrier is up and it
575 hasn’t been administratively disabled). Otherwise, drop the
576 packet.
577 • If LACP negotiation is incomplete, then drop the packet.
579 There is one exception: if fallback to active-backup mode is
580 enabled, continue with the next step, pretending that the ac‐
581 tive-backup balancing mode is in use.
582 7. Non-LACP bond admissibility: This step applies if the input port is
584 a member of a bond without LACP configured, or if a LACP bond falls
585 back to active-backup as described in the previous step. If nei‐
586 ther of these applies, skip to the next step.
587 If the packet is an Ethernet multicast or broadcast, and not re‐
589 ceived on the bond’s active member, drop the packet.
590 The remaining behavior depends on the bond’s balancing mode:
592 L4 (aka TCP balancing)
594 Drop the packet (this balancing mode is only supported
595 with LACP).
596 Active-backup
598 Accept the packet only if it was received on the active
599 member.
600 SLB (Source Load Balancing)
602 Drop the packet if the bridge has not learned the
603 packet’s source address (in its VLAN) on the port that
604 received it. Otherwise, accept the packet unless it is a
605 gratuitous ARP. Otherwise, accept the packet if the MAC
606 entry we found is ARP-locked. Otherwise, drop the
607 packet. (See the SLB Bonding section in the OVS bonding
608 document for more information and a rationale.)
609 8. Learn source MAC: If the source Ethernet address is not a multicast
611 address, then insert a mapping from packet’s source Ethernet ad‐
612 dress and VLAN to the input port in the bridge’s MAC learning ta‐
613 ble. (This is skipped if the packet’s VLAN is listed in the
614 switch’s Bridge record in the flood_vlans column, since there is no
615 use for MAC learning when all packets are flooded.)
616 When learning happens on a non-bond port, if the packet is a gratu‐
618 itous ARP, the entry is marked as ARP-locked. The lock expires af‐
619 ter 5 seconds. (See the SLB Bonding section in the OVS bonding
620 document for more information and a rationale.)
621 9. IP multicast path: If multicast snooping is enabled on the bridge,
623 and the packet is an Ethernet multicast but not an Ethernet broad‐
624 cast, and the packet is an IP packet, then the packet takes a spe‐
625 cial processing path. This path is not yet documented here.
626 10. Output port set: Search the MAC learning table for the port corre‐
628 sponding to the packet’s Ethernet destination and VLAN. If the
629 search finds an entry, the output port set is just the learned
630 port. Otherwise (including the case where the packet is an Ether‐
631 net multicast or in flood_vlans), the output port set is all of the
632 ports in the bridge that belong to the packet’s VLAN, except for
633 any ports that were disabled for flooding via OpenFlow or that are
634 configured in a Mirror record as a mirror destination port.
635 The following egress stages execute once for each element in the set of
637 output ports. They execute (conceptually) in parallel, so that a deci‐
638 sion or action taken for a given output port has no effect on those for
639 another one:
640 1. Drop loopback: If the output port is the same as the input port,
642 drop the packet.
643 2. VLAN output processing: This stage adjusts the packet to represent
645 the VLAN in the correct way for the output port. Its behavior
646 varies based on the vlan-mode in the output port’s Port record:
647 trunk / native-tagged / native-untagged
649 If the packet is in VLAN 0 (for native-untagged, if the
650 packet is in the native VLAN) drops any 802.1Q header.
651 Otherwise, ensures that there is an 802.1Q header desig‐
652 nating the VLAN.
653 access Remove any 802.1Q header that was present.
655 dot1q-tunnel
657 Ensures that the packet has an outer 802.1Q header with
658 the QinQ Ethertype and the specified configured tag, and
659 an inner 802.1Q header with the packet’s VLAN.
660 3. VLAN priority tag processing: If VLAN output processing discarded
662 the 802.1Q headers, but priority tags are enabled with other_con‐
663 fig:priority-tags in the output port’s Port record, then a prior‐
664 ity-only tag is added (perhaps only if the priority would be non‐
665 zero, depending on the configuration).
666 4. Bond member choice: If the output port is a bond, the code chooses a
668 particular member. This step is skipped for non-bonded ports.
669 If the bond is configured to use LACP, but LACP negotiation is in‐
671 complete, then normally the packet is dropped. The exception is
672 that if fallback to active-backup mode is enabled, the egress pipe‐
673 line continues choosing a bond member as if active-backup mode was
674 in use.
675 For active-backup mode, the output member is the active member.
677 Other modes hash appropriate header fields and use the hash value to
678 choose one of the enabled members.
679 5. Output: The pipeline sends the packet to the output port.
681 The controller action
683 Syntax:
684 controller
685 controller:max_len
686 controller(key[=value], ...)
687 Sends the packet and its metadata to an OpenFlow controller or con‐
690 trollers encapsulated in an OpenFlow packet-in message. The supported
691 options are:
692 max_len=max_len
694 Limit to max_len the number of bytes of the packet to send in
695 the packet-in. A max_len of 0 prevents any of the packet
696 from being sent (thus, only metadata is included). By de‐
697 fault, the entire packet is sent, equivalent to a max_len of
698 65535.
699 reason=reason
701 Specify reason as the reason for sending the message in the
702 packet-in. The supported reasons are no_match, action, in‐
703 valid_ttl, action_set, group, and packet_out. The default
704 reason is action.
705 id=controller_id
707 Specify controller_id, a 16-bit integer, as the connection ID
708 of the OpenFlow controller or controllers to which the
709 packet-in message should be sent. The default is zero. Zero
710 is also the default connection ID for each controller connec‐
711 tion, and a given controller connection will only have a non‐
712 zero connection ID if its controller uses the NXT_SET_CON‐
713 TROLLER_ID Open vSwitch extension to OpenFlow.
714 userdata=hh...
716 Supplies the bytes represented as hex digits hh as additional
717 data to the controller in the packet-in message. Pairs of
718 hex digits may be separated by periods for readability.
719 pause Causes the switch to freeze the packet’s trip through Open
721 vSwitch flow tables and serializes that state into the
722 packet-in message as a continuation, an additional property
723 in the NXT_PACKET_IN2 message. The controller can later send
724 the continuation back to the switch in an NXT_RESUME message,
725 which will restart the packet’s traversal from the point
726 where it was interrupted. This permits an OpenFlow con‐
727 troller to interpose on a packet midway through processing in
728 Open vSwitch.
729 Conformance
731 All versions of OpenFlow and Open vSwitch support controller ac‐
732 tion and its max_len option. The userdata and pause options re‐
733 quire the Open vSwitch NXAST_CONTROLLER2 extension action added
734 in Open vSwitch 2.6. In the absence of these options, the reason
735 (other than reason=action) and controller_id (option than con‐
736 troller_id=0) options require the Open vSwitch NXAST_CONTROLLER
737 extension action added in Open vSwitch 1.6.
738 The enqueue action
740 Syntax:
741 enqueue(port,queue)
742 enqueue:port:queue
743 Enqueues the packet on the specified queue within port port.
746 port must be an OpenFlow port number or name as described under Port
748 Specifications above. port may be in_port or local but the other stan‐
749 dard OpenFlow ports are not allowed.
750 queue must be a number between 0 and 4294967294 (0xfffffffe), inclu‐
752 sive. The number of actually supported queues depends on the switch.
753 Some OpenFlow implementations do not support queuing at all. In Open
754 vSwitch, the supported queues vary depending on the operating system,
755 datapath, and hardware in use. Use the QoS and Queue tables in the
756 Open vSwitch database to configure queuing on individual OpenFlow ports
757 (see ovs-vswitchd.conf.db(5) for more information).
758 Conformance
760 Only OpenFlow 1.0 supports enqueue. OpenFlow 1.1 added the
761 set_queue action to use in its place along with output.
762 Open vSwitch translates enqueue to a sequence of three actions
764 in OpenFlow 1.1 or later: set_queue:queue,output:port,pop_queue.
765 This is equivalent in behavior as long as the flow table does
766 not otherwise use set_queue, but it relies on the pop_queue Open
767 vSwitch extension action.
768 The bundle and bundle_load actions
770 Syntax:
771 bundle(fields,basis,algorithm,ofport,members:port...)
772 bundle_load(fields,basis,algorithm,ofport,dst,members:port...)
773 These actions choose a port (a member) from a comma-separated OpenFlow
776 port list. After selecting the port, bundle outputs to it, whereas
777 bundle_load writes its port number to dst, which must be a 16-bit or
778 wider field or subfield in the syntax described under Field Specifica‐
779 tions above.
780 These actions hash a set of fields using basis as a universal hash pa‐
782 rameter, then apply the bundle link selection algorithm to choose a
783 port.
784 fields must be one of the following. For the options with symmetric in
786 the name, reversing source and destination addresses yields the same
787 hash:
788 eth_src
790 Ethernet source address.
791 nw_src IPv4 or IPv6 source address.
793 nw_dst IPv4 or IPv6 destination address.
795 symmetric_l4
797 Ethernet source and destination, Ethernet type, VLAN ID or
798 IDs (if any), IPv4 or IPv6 source and destination, IP proto‐
799 col, TCP or SCTP (but not UDP) source and destination.
800 symmetric_l3l4
802 IPv4 or IPv6 source and destination, IP protocol, TCP or SCTP
803 (but not UDP) source and destination.
804 symmetric_l3l4+udp
806 Like symmetric_l3l4 but include UDP ports.
807 algorithm must be one of the following:
809 active_backup
811 Chooses the first live port listed in members.
812 hrw (Highest Random Weight)
814 Computes the following, considering only the live ports in
815 members:
816 for i in [1, n_members]:
818 weights[i] = hash(flow, i)
819 member = { i such that weights[i] >= weights[j] for all j != i }
820 This algorithm is specified by RFC 2992.
822 The algorithms take port liveness into account when selecting members.
824 The definition of whether a port is live is subject to change. It cur‐
825 rently takes into account carrier status and link monitoring protocols
826 such as BFD and CFM. If none of the members is live, bundle does not
827 output the packet and bundle_load stores OFPP_NONE (65535) in the out‐
828 put field.
829 Example: bundle(eth_src,0,hrw,ofport,members:4,8) uses an Ethernet
831 source hash with basis 0, to select between OpenFlow ports 4 and 8 us‐
832 ing the Highest Random Weight algorithm.
833 Conformance
835 Open vSwitch 1.2 introduced the bundle and bundle_load OpenFlow
836 extension actions.
837 The group action
839 Syntax:
840 group:group
841 Outputs the packet to the OpenFlow group group, which must be a number
844 in the range 0 to 4294967040 (0xffffff00). The group must exist or
845 Open vSwitch will refuse to add the flow. When a group is deleted,
846 Open vSwitch also deletes all of the flows that output to it.
847 Groups contain action sets, whose semantics are described above in the
849 section Action Sets. The semantics of action sets can be surprising to
850 users who expect action list semantics, since action sets reorder and
851 sometimes ignore actions.
852 A group action usually executes the action set or sets in one or more
854 group buckets. Open vSwitch saves the packet and metadata before it
855 executes each bucket, and then restores it afterward. Thus, when a
856 group executes more than one bucket, this means that each bucket exe‐
857 cutes on the same packet and metadata. Moreover, regardless of the
858 number of buckets executed, the packet and metadata are the same before
859 and after executing the group.
860 Sometimes saving and restoring the packet and metadata can be undesir‐
862 able. In these situations, workarounds are possible. For example,
863 consider a pipeline design in which a select group bucket is to commu‐
864 nicate to a later stage of processing a value based on which bucket was
865 selected. An obvious design would be for the bucket to communicate the
866 value via set_field on a register. This does not work because regis‐
867 ters are part of the metadata that group saves and restores. The fol‐
868 lowing alternative bucket designs do work:
869 • Recursively invoke the rest of the pipeline with resubmit.
871 • Use resubmit into a table that uses push to put the value on the
873 stack for the caller to pop off. This works because group pre‐
874 serves only packet data and metadata, not the stack.
875 (This design requires indirection through resubmit because actions
877 sets may not contain push or pop actions.)
878 An exit action within a group bucket terminates only execution of that
880 bucket, not other buckets or the overall pipeline.
881 Conformance
883 OpenFlow 1.1 introduced group. Open vSwitch 2.6 and later also
884 supports group as an extension to OpenFlow 1.0.
885
887 The strip_vlan and pop actions
888 Syntax:
889 strip_vlan
890 pop_vlan
891 Removes the outermost VLAN tag, if any, from the packet.
894 The two names for this action are synonyms with no semantic difference.
896 The OpenFlow 1.0 specification uses the name strip_vlan and later ver‐
897 sions use pop_vlan, but OVS accepts either name regardless of version.
898 In OpenFlow 1.1 and later, consistency rules allow strip_vlan only in a
900 flow that matches only packets with a VLAN tag (or following an action
901 that pushes a VLAN tag, such as push_vlan). See Inconsistencies,
902 above, for more information.
903 Conformance
905 All versions of OpenFlow and Open vSwitch support this action.
906 The push_vlan action
908 Syntax:
909 push_vlan:ethertype
910 Pushes a new outermost VLAN onto the packet. Uses TPID ethertype,
913 which must be 0x8100 for an 802.1Q C-tag or 0x88a8 for a 802.1ad S-tag.
914 Conformance
916 OpenFlow 1.1 and later supports this action. Open vSwitch 2.8
917 added support for multiple VLAN tags (with a limit of 2) and
918 802.1ad S-tags.
919 The push_mpls action
921 Syntax:
922 push_mpls:ethertype
923 Pushes a new outermost MPLS label stack entry (LSE) onto the packet and
926 changes the packet’s Ethertype to ethertype, which must be either
927 B0x8847 or 0x8848. If the packet did not already contain any MPLS la‐
928 bels, initializes the new LSE as:
929 Label 2, if the packet contains IPv6, 0 otherwise.
931 TC The low 3 bits of the packet’s DSCP value, or 0 if the packet
933 is not IP.
934 TTL Copied from the IP TTL, or 64 if the packet is not IP.
936 If the packet did already contain an MPLS label, initializes the new
938 outermost label as a copy of the existing outermost label.
939 OVS currently supports at most 3 MPLS labels.
941 This action applies only to Ethernet packets.
943 Conformance
945 Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and
946 later support push_mpls. Open vSwitch implements push_mpls as
947 an extension to OpenFlow 1.0.
948 The pop_mpls action
950 Syntax:
951 pop_mpls:ethertype
952 Strips the outermost MPLS label stack entry and changes the packet’s
955 Ethertype to ethertype. This action applies only to Ethernet packets
956 with at least one MPLS label. If there is more than one MPLS label,
957 then ethertype should be an MPLS Ethertype (B0x8847 or 0x8848).
958 Conformance
960 Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and
961 later support pop_mpls. Open vSwitch implements pop_mpls as an
962 extension to OpenFlow 1.0.
963 The encap action
965 Syntax:
966 encap(nsh([md_type=md_type], [tlv(class,type,value)]...))
967 encap(ethernet)
968 encap(mpls)
969 encap(mpls_mc)
970 The encap action encapsulates a packet with a specified header. It has
973 variants for different kinds of encapsulation.
974 The encap(nsh(...)) variant encapsulates an Ethernet frame with NSH.
976 The md_type may be 1 or 2 for metadata type 1 or 2, defaulting to 1.
977 For metadata type 2, TLVs may be specified with class as a 16-bit hexa‐
978 decimal integer beginning with 0x, type as an 8-bit decimal integer,
979 and value a sequence of pairs of hex digits beginning with 0x. For ex‐
980 ample:
981 encap(nsh(md_type=1))
983 Encapsulates the packet with an NSH header with metadata type
984 1.
985 encap(nsh(md_type=2,tlv(0x1000,10,0x12345678)))
987 Encapsulates the packet with an NSH header, NSH metadata type
988 2, and an NSH TLV with class 0x1000, type 10, and the 4-byte
989 value 0x12345678.
990 The encap(ethernet) variant encapsulate a bare L3 packet in an Ethernet
992 frame. The Ethernet type is initialized to the L3 packet’s type, e.g.
993 0x0800 if the L3 packet is IPv4. The Ethernet source and destination
994 are initially zeroed.
995 The encap(mpls) variant adds a MPLS header at the start of the packet.
997 When encap(ethernet) is applied after this action, the ethertype of
998 ethernet header will be populated with MPLS unicast ethertype (0x8847).
999 The encap(mpls_mc) variant adds a MPLS header at the start of the
1001 packet. When encap(ethernet) is applied after this action, the ether‐
1002 type of ethernet header will be populated with MPLS multicast ethertype
1003 (0x8848).
1004 Conformance
1006 This action is an Open vSwitch extension to OpenFlow 1.3 and
1007 later, introduced in Open vSwitch 2.8.
1008 The MPLS support for this action is added in Open vSwitch 2.17.
1010 The decap action
1012 Syntax:
1013 decap
1014 decap(packet_type(ns=namespace,type=type))
1015 Removes an outermost encapsulation from the packet:
1018 • If the packet is an Ethernet packet, removes the Ethernet header,
1020 which changes the packet into a bare L3 packet. If the packet has
1021 VLAN tags, raises an unsupported packet type error (see Error Han‐
1022 dling, above).
1023 • Otherwise, if the packet is an NSH packet, removes the NSH header,
1025 revealing the inner packet. Open vSwitch supports Ethernet, IPv4,
1026 IPv6, and NSH inner packet types. Other types raise unsupported
1027 packet type errors.
1028 • Otherwise, if the packet is encapsulated inside a MPLS header, re‐
1030 moves the MPLS header and classifies the inner packet as mentioned
1031 in the packet type argument of the decap. The packet_type field
1032 specifies the type of the packet in the format specified in Open‐
1033 Flow 1.5 chapter 7.2.3.11 Packet Type Match Field. The inner
1034 packet will be incorrectly classified, if the inner packet is dif‐
1035 ferent from mentioned in the packet_type field.
1036 • Otherwise, raises an unsupported packet type error.
1038 Conformance
1040 This action is an Open vSwitch extension to OpenFlow 1.3 and
1041 later, introduced in Open vSwitch 2.8.
1042 The MPLS support for this action is added in Open vSwitch 2.17.
1044
1046 These actions modify packet data and metadata fields.
1047 The set_field and load actions
1049 Syntax:
1050 set_field:value[/mask]->dst
1051 load:value->dst
1052 These actions loads a literal value into a field or part of a field.
1055 The set_field action takes value in the customary syntax for field dst,
1056 e.g. 00:11:22:33:44:55 for an Ethernet address, and dst as the field’s
1057 name. The optional mask allows part of a field to be set.
1058 The load action takes value as an integer value (in decimal or prefixed
1060 by 0x for hexadecimal) and dst as a field or subfield in the syntax de‐
1061 scribed under Field Specifications above.
1062 The following all set the Ethernet source address to 00:11:22:33:44:55:
1064 • set_field:00:11:22:33:44:55->eth_src
1066 • load:0x001122334455->eth_src
1068 • load:0x001122334455->OXM_OF_ETH_SRC[]
1070 The following all set the multicast bit in the Ethernet destination ad‐
1072 dress:
1073 • set_field:01:00:00:00:00:00/01:00:00:00:00:00->eth_dst
1075 • load:1->eth_dst[40]
1077 Open vSwitch prohibits a set_field or load action whose dst is not
1079 guaranteed to be part of the packet; for example, set_field of nw_dst
1080 is only allowed in a flow that matches on Ethernet type 0x800. In some
1081 cases, such as in an action set, Open vSwitch can’t statically check
1082 that dst is part of the packet, and in that case if it is not then Open
1083 vSwitch treats the action as a no-op.
1084 Conformance
1086 Open vSwitch 1.1 introduced NXAST_REG_LOAD as a extension to
1087 OpenFlow 1.0 and used load to express it. Later, OpenFlow 1.2
1088 introduced a standard OFPAT_SET_FIELD action that was restricted
1089 to loading entire fields, so Open vSwitch added the form
1090 set_field with this restriction. OpenFlow 1.5 extended OF‐
1091 PAT_SET_FIELD to the point that it became a superset of NX‐
1092 AST_REG_LOAD. Open vSwitch translates either syntax as neces‐
1093 sary for the OpenFlow version in use: in OpenFlow 1.0 and 1.1,
1094 NXAST_REG_LOAD; in OpenFlow 1.2, 1.3, and 1.4, NXAST_REG_LOAD
1095 for load or for loading a subfield, OFPAT_SET_FIELD otherwise;
1096 and OpenFlow 1.5 and later, OFPAT_SET_FIELD.
1097 The move action
1099 Syntax:
1100 move:src->dst
1101 Copies the named bits from field or subfield src to field or subfield
1104 dst. src and dst should fields or subfields in the syntax described
1105 under Field Specifications above. The two fields or subfields must
1106 have the same width.
1107 Examples:
1109 • move:reg0[0..5]->reg1[26..31] copies the six bits numbered 0
1111 through 5 in register 0 into bits 26 through 31 of register 1.
1112 • move:reg0[0..15]->vlan_tci copies the least significant 16 bits of
1114 register 0 into the VLAN TCI field.
1115 Conformance
1117 In OpenFlow 1.0 through 1.4, move ordinarily uses an Open
1118 vSwitch extension to OpenFlow. In OpenFlow 1.5, move uses the
1119 OpenFlow 1.5 standard OFPAT_COPY_FIELD action. The ONF has also
1120 made OFPAT_COPY_FIELD available as an extension to OpenFlow 1.3.
1121 Open vSwitch 2.4 and later understands this extension and uses
1122 it if a controller uses it, but for backward compatibility with
1123 older versions of Open vSwitch, ovs-ofctl does not use it.
1124 The mod_dl_src and mod_dl_dst actions
1126 Syntax:
1127 mod_dl_src:mac
1128 mod_dl_dst:mac
1129 Sets the Ethernet source or destination address, respectively, to mac,
1132 which should be expressed in the form xx:xx:xx:xx:xx:xx.
1133 For L3-only packets, that is, those that lack an Ethernet header, this
1135 action has no effect.
1136 Conformance
1138 OpenFlow 1.0 and 1.1 have specialized actions for these pur‐
1139 poses. OpenFlow 1.2 and later do not, so Open vSwitch trans‐
1140 lates them to appropriate OFPAT_SET_FIELD actions for those ver‐
1141 sions,
1142 The mod_nw_src and mod_nw_dst actions
1144 Syntax:
1145 mod_nw_src:ip
1146 mod_nw_dst:ip
1147 Sets the IPv4 source or destination address, respectively, to ip, which
1150 should be expressed in the form w.x.y.z.
1151 In OpenFlow 1.1 and later, consistency rules allow these actions only
1153 in a flow that matches only packets that contain an IPv4 header (or
1154 following an action that adds an IPv4 header, e.g. pop_mpls:0x0800).
1155 See Inconsistencies, above, for more information.
1156 Conformance
1158 OpenFlow 1.0 and 1.1 have specialized actions for these pur‐
1159 poses. OpenFlow 1.2 and later do not, so Open vSwitch trans‐
1160 lates them to appropriate OFPAT_SET_FIELD actions for those ver‐
1161 sions,
1162 The mod_nw_tos and mod_nw_ecn actions
1164 Syntax:
1165 mod_nw_tos:tos
1166 mod_nw_ecn:ecn
1167 The mod_nw_tos action sets the DSCP bits in the IPv4 ToS/DSCP or IPv6
1170 traffic class field to tos, which must be a multiple of 4 between 0 and
1171 255. This action does not modify the two least significant bits of the
1172 ToS field (the ECN bits).
1173 The mod_nw_ecn action sets the ECN bits in the IPv4 ToS or IPv6 traffic
1175 class field to ecn, which must be a value between 0 and 3, inclusive.
1176 This action does not modify the six most significant bits of the field
1177 (the DSCP bits).
1178 In OpenFlow 1.1 and later, consistency rules allow these actions only
1180 in a flow that matches only packets that contain an IPv4 or IPv6 header
1181 (or following an action that adds such a header). See Inconsistencies,
1182 above, for more information.
1183 Conformance
1185 OpenFlow 1.0 has a mod_nw_tos action but not mod_nw_ecn. Open
1186 vSwitch implements the latter in OpenFlow 1.0 as an extension
1187 using NXAST_REG_LOAD. OpenFlow 1.1 has specialized actions for
1188 these purposes. OpenFlow 1.2 and later do not, so Open vSwitch
1189 translates them to appropriate OFPAT_SET_FIELD actions for those
1190 versions.
1191 The mod_tp_src and mod_tp_dst actions
1193 Syntax:
1194 mod_tp_src:port
1195 mod_tp_dst:port
1196 Sets the TCP or UDP or SCTP source or destination port, respectively,
1199 to port. Both IPv4 and IPv6 are supported.
1200 In OpenFlow 1.1 and later, consistency rules allow these actions only
1202 in a flow that matches only packets that contain a TCP or UDP or SCTP
1203 header. See Inconsistencies, above, for more information.
1204 Conformance
1206 OpenFlow 1.0 and 1.1 have specialized actions for these pur‐
1207 poses. OpenFlow 1.2 and later do not, so Open vSwitch trans‐
1208 lates them to appropriate OFPAT_SET_FIELD actions for those ver‐
1209 sions,
1210 The dec_ttl action
1212 Syntax:
1213 dec_ttl
1214 dec_ttl(id1[,id2[, ...]])
1215 Decrement TTL of IPv4 packet or hop limit of IPv6 packet. If the TTL
1218 or hop limit is initially 0 or 1, no decrement occurs, as packets
1219 reaching TTL zero must be rejected. Instead, Open vSwitch sends a
1220 packet-in message with reason code OFPR_INVALID_TTL to each connected
1221 controller that has enabled receiving such messages, and stops process‐
1222 ing the current set of actions. (However, if the current set of ac‐
1223 tions was reached through resubmit, the remaining actions in outer lev‐
1224 els resume processing.)
1225 As an Open vSwitch extension to OpenFlow, this action supports the
1227 ability to specify a list of controller IDs. Open vSwitch will only
1228 send the message to controllers with the given ID or IDs. Specifying
1229 no list is equivalent to specifying a single controller ID of zero.
1230 In OpenFlow 1.1 and later, consistency rules allow these actions only
1232 in a flow that matches only packets that contain an IPv4 or IPv6
1233 header. See Inconsistencies, above, for more information.
1234 Conformance
1236 All versions of OpenFlow and Open vSwitch support this action.
1237 The set_mpls_label, set_mpls_tc, and set_mpls_ttl actions
1239 Syntax:
1240 set_mpls_label:label
1241 set_mpls_tc:tc
1242 set_mpls_ttl:ttl
1243 The set_mpls_label action sets the label of the packet’s outer MPLS la‐
1246 bel stack entry. label should be a 20-bit value that is decimal by de‐
1247 fault; use a 0x prefix to specify the value in hexadecimal.
1248 The set_mpls_tc action sets the traffic class of the packet’s outer
1250 MPLS label stack entry. tc should be in the range 0 to 7, inclusive.
1251 The set_mpls_ttl action sets the TTL of the packet’s outer MPLS label
1253 stack entry. ttl should be in the range 0 to 255 inclusive. In Open‐
1254 Flow 1.1 and later, consistency rules allow these actions only in a
1255 flow that matches only packets that contain an MPLS label (or following
1256 an action that adds an MPLS label, e.g. push_mpls:0x8847). See
1257 Inconsistencies, above, for more information.
1258 Conformance
1260 OpenFlow 1.0 does not support MPLS, but Open vSwitch implements
1261 these actions as extensions. OpenFlow 1.1 has specialized ac‐
1262 tions for these purposes. OpenFlow 1.2 and later do not, so
1263 Open vSwitch translates them to appropriate OFPAT_SET_FIELD ac‐
1264 tions for those versions,
1265 The dec_mpls_ttl and dec_nsh_ttl actions
1267 Syntax:
1268 dec_mpls_ttl
1269 dec_nsh_ttl
1270 These actions decrement the TTL of the packet’s outer MPLS label stack
1273 entry or its NSH header, respectively. If the TTL is initially 0 or 1,
1274 no decrement occurs. Instead, Open vSwitch sends a packet-in message
1275 with reason code BOFPR_INVALID_TTL to OpenFlow controllers with ID 0,
1276 if it has enabled receiving them. Processing the current set of ac‐
1277 tions then stops. (However, if the current set of actions was reached
1278 through resubmit, remaining actions in outer levels resume processing.)
1279 In OpenFlow 1.1 and later, consistency rules allow this actions only in
1281 a flow that matches only packets that contain an MPLS label or an NSH
1282 header, respectively. See Inconsistencies, above, for more informa‐
1283 tion.
1284 Conformance
1286 Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and
1287 later support dec_mpls_ttl. Open vSwitch implements
1288 dec_mpls_ttl as an extension to OpenFlow 1.0.
1289 Open vSwitch 2.8 introduced support for NSH, although the NSH
1291 draft changed after release so that only Open vSwitch 2.9 and
1292 later conform to the final protocol specification. The
1293 dec_nsh_ttl action and NSH support in general is an Open vSwitch
1294 extension not supported by any version of OpenFlow.
1295 The check_pkt_larger action
1297 Syntax:
1298 check_pkt_larger(pkt_len)->dst
1299 Checks if the packet is larger than the specified length in pkt_len.
1302 If so, stores 1 in dst, which should be a 1-bit field; if not, stores
1303 0.
1304 The packet length to check against the argument pkt_len includes the L2
1306 header and L2 payload of the packet, but not the VLAN tag (if present).
1307 Examples:
1309 • check_pkt_larger(1500)->reg0[0]
1311 • check_pkt_larger(8000)->reg9[10]
1313 This action was added in Open vSwitch 2.12.
1315 The delete_field action
1317 Syntax:
1318 delete_field:field
1319 The delete_field action deletes a field in the syntax described under
1322 Field Specifications above. Currently, only the tun_metadta fields are
1323 supported.
1324 This action was added in Open vSwitch 2.14.
1326
1328 The set_tunnel action
1329 Syntax:
1330 set_tunnel:id
1331 set_tunnel64:id
1332 Many kinds of tunnels support a tunnel ID, e.g. VXLAN and Geneve have a
1335 24-bit VNI, and GRE has an optional 32-bit key. This action sets the
1336 value used for tunnel ID in such tunneled packets, although whether it
1337 is used for a particular tunnel depends on the tunnel’s configuration.
1338 See the tunnel ID documentation in ovs-fields(7) for more information.
1339 Conformance
1341 These actions are OpenFlow extensions. set_tunnel was intro‐
1342 duced in Open vSwitch 1.0. set_tunnel64, which is needed if id
1343 is wider than 32 bits, was added in Open vSwitch 1.1. Both ac‐
1344 tions always set the entire tunnel ID field. Open vSwitch sup‐
1345 ports these actions in all versions of OpenFlow, but in OpenFlow
1346 1.2 and later it translates them to an appropriate standardized
1347 OFPAT_SET_FIELD action.
1348 The set_queue and pop_queue actions
1350 Syntax:
1351 set_queue:queue
1352 pop_queue
1353 The set_queue action sets the queue ID to be used for subsequent output
1356 actions to queue, which must be a 32-bit integer. The range of mean‐
1357 ingful values of queue, and their meanings, varies greatly from one
1358 OpenFlow implementation to another. Even within a single implementa‐
1359 tion, there is no guarantee that all OpenFlow ports have the same
1360 queues configured or that all OpenFlow ports in an implementation can
1361 be configured the same way queue-wise. For more information, see the
1362 documentation for the output queue field in ovs-fields(7).
1363 The pop_queue restores the output queue to the default that was set
1365 when the packet entered the switch (generally 0).
1366 Four billion queues ought to be enough for anyone:
1368 https://mailman.stanford.edu/pipermail/openflow-spec/2009-August/000394.html
1369 Conformance
1371 OpenFlow 1.1 introduced the set_queue action. Open vSwitch also
1372 supports it as an extension in OpenFlow 1.0.
1373 The pop_queue action is an Open vSwitch extension.
1375
1377 Open vSwitch is often used to implement a firewall. The preferred way
1378 to implement a firewall is connection tracking, that is, to keep track
1379 of the connection state of individual TCP sessions. The ct action de‐
1380 scribed in this section, added in Open vSwitch 2.5, implements connec‐
1381 tion tracking. For new deployments, it is the recommended way to im‐
1382 plement firewalling with Open vSwitch.
1383 Before ct was added, Open vSwitch did not have built-in support for
1385 connection tracking. Instead, Open vSwitch supported the learn action,
1386 which allows a received packet to add a flow to an OpenFlow flow table.
1387 This could be used to implement a primitive form of connection track‐
1388 ing: packets passing through the firewall in one direction could create
1389 flows that allowed response packets back through the firewall in the
1390 other direction. The additional fin_timeout action allowed the learned
1391 flows to expire quickly after TCP session termination.
1392 The ct action
1394 Syntax:
1395 ct([argument]...)
1396 ct(commit[,argument]...)
1397 The action has two modes of operation, distinguished by whether commit
1400 is present. The following arguments may be present in either mode:
1401 zone=value
1403 A zone is a 16-bit id that isolates connections into separate
1404 domains, allowing overlapping network addresses in different
1405 zones. If a zone is not provided, then the default is 0. The
1406 value may be specified either as a 16-bit integer literal or
1407 a field or subfield in the syntax described under Field Spec‐
1408 ifications above.
1409 Without commit, this action sends the packet through the connection
1411 tracker. The connection tracker keeps track of the state of TCP con‐
1412 nections for packets passed through it. For each packet through a con‐
1413 nection, it checks that it satisfies TCP invariants and signals the
1414 connection state to later actions using the ct_state metadata field,
1415 which is documented in ovs-fields(7).
1416 In this form, ct forks the OpenFlow pipeline:
1418 • In one fork, ct passes the packet to the connection tracker. Af‐
1420 terward, it reinjects the packet into the OpenFlow pipeline with
1421 the connection tracking fields initialized. The ct_state field is
1422 initialized with connection state and ct_zone to the connection
1423 tracking zone specified on the zone argument. If the connection
1424 is one that is already tracked, ct_mark and ct_label to its exist‐
1425 ing mark and label, respectively; otherwise they are zeroed. In
1426 addition, ct_nw_proto, ct_nw_src, ct_nw_dst, ct_ipv6_src,
1427 ct_ipv6_dst, ct_tp_src, and ct_tp_dst are initialized appropri‐
1428 ately for the original direction connection. See the resubmit ac‐
1429 tion for a way to search the flow table with the connection track‐
1430 ing original direction fields swapped with the packet 5-tuple
1431 fields. See ovs-fields(7) for details on the connection tracking
1432 fields.
1433 • In the other fork, the original instance of the packet continues
1435 independent processing following the ct action. The ct_state
1436 field and other connection tracking metadata are cleared.
1437 Without commit, the ct action accepts the following arguments:
1439 table=table
1441 Sets the OpenFlow table where the packet is reinjected. The
1442 table must be a number between 0 and 254 inclusive, or a ta‐
1443 ble’s name. If table is not specified, then the packet is
1444 not reinjected.
1445 nat
1447 nat(type=addrs[:ports][,flag]...)
1449 Specify address and port translation for the connection being
1450 tracked. The type must be src, for source address/port
1451 translation (SNAT), or dst, for destination address/port
1452 translation (DNAT). Setting up address translation for a new
1453 connection takes effect only if the connection is later com‐
1454 mitted with ct(commit ...).
1455 The src and dst options take the following arguments:
1457 addrs The IP address addr or range addr1-addr2 from
1459 which the translated address should be selected.
1460 If only one address is given, then that address
1461 will always be selected, otherwise the address se‐
1462 lection can be informed by the optional persistent
1463 flag as described below. Either IPv4 or IPv6 ad‐
1464 dresses can be provided, but both addresses must
1465 be of the same type, and the datapath behavior is
1466 undefined in case of providing IPv4 address range
1467 for an IPv6 packet, or IPv6 address range for an
1468 IPv4 packet. IPv6 addresses must be bracketed
1469 with [ and ] if a port range is also given.
1470 ports The L4 port or range port1-port2 from which the
1472 translated port should be selected. When a port
1473 range is specified, fallback to ephemeral ports
1474 does not happen, else, it will. The port number
1475 selection can be informed by the optional random
1476 and hash flags described below. The userspace
1477 datapath only supports the hash behavior.
1478 The optional flags are:
1480 random The selection of the port from the given range
1482 should be done using a fresh random number. This
1483 flag is mutually exclusive with hash.
1484 hash The selection of the port from the given range
1486 should be done using a datapath specific hash of
1487 the packet’s IP addresses and the other,
1488 non-mapped port number. This flag is mutually ex‐
1489 clusive with random.
1490 persistent
1492 The selection of the IP address from the given
1493 range should be done so that the same mapping can
1494 be provided after the system restarts.
1495 If alg is specified for the committing ct action that also
1497 includes nat with a src or dst attribute, then the datapath
1498 tries to set up the helper to be NAT-aware. This functional‐
1499 ity is datapath specific and may not be supported by all
1500 datapaths.
1501 A bare nat argument with no options will only translate the
1503 packet being processed in the way the connection has been set
1504 up with an earlier, committed ct action. A nat action with
1505 src or dst, when applied to a packet belonging to an estab‐
1506 lished (rather than new) connection, will behave the same as
1507 a bare nat.
1508 For SNAT, there is a special case when the src IP address is
1510 configured as all 0’s, i.e., nat(src=0.0.0.0). In this case,
1511 when a source port collision is detected during the commit,
1512 the source port will be translated to an ephemeral port. If
1513 there is no collision, no SNAT is performed.
1514 Open vSwitch 2.6 introduced nat. Linux 4.6 was the earliest
1516 upstream kernel that implemented ct support for nat.
1517 With commit, the connection tracker commits the connection to the con‐
1519 nection tracking module. The commit flag should only be used from the
1520 pipeline within the first fork of ct without commit. Information about
1521 the connection is stored beyond the lifetime of the packet in the pipe‐
1522 line. Some ct_state flags are only available for committed connec‐
1523 tions.
1524 The following options are available only with commit:
1526 force A committed connection always has the directionality of the
1528 packet that caused the connection to be committed in the
1529 first place. This is the original direction of the connec‐
1530 tion, and the opposite direction is the reply direction. If
1531 a connection is already committed, but it is in the wrong di‐
1532 rection, force effectively terminates the existing connection
1533 and starts a new one in the current direction. This flag has
1534 no effect if the original direction of the connection is al‐
1535 ready the same as that of the current packet.
1536 exec(action...)
1538 Perform each action within the context of connection track‐
1539 ing. Only actions which modify the ct_mark or ct_label
1540 fields are accepted within exec action, and these fields may
1541 only be modified with this option. For example:
1542 set_field:value[/mask]->ct_mark
1544 Store a 32-bit metadata value with the connection.
1545 Subsequent lookups for packets in this connection will
1546 populate ct_mark when the packet is sent to the con‐
1547 nection tracker with the table specified.
1548 set_field:value[/mask]->ct_label
1550 Store a 128-bit metadata value with the connection.
1551 Subsequent lookups for packets in this connection will
1552 populate ct_label when the packet is sent to the con‐
1553 nection tracker with the table specified.
1554 alg=alg
1556 Specify application layer gateway alg to track specific con‐
1557 nection types. If subsequent related connections are sent
1558 through the ct action, then the rel flag in the ct_state
1559 field will be set. Supported types include:
1560 ftp Look for negotiation of FTP data connections. Specify
1562 this option for FTP control connections to detect re‐
1563 lated data connections and populate the rel flag for
1564 the data connections.
1565 tftp Look for negotiation of TFTP data connections. Spec‐
1567 ify this option for TFTP control connections to detect
1568 related data connections and populate the rel flag for
1569 the data connections.
1570 Related connections inherit ct_mark from that stored with the
1572 original connection (i.e. the connection created by
1573 ct(alg=...).
1574 With the Linux datapath, global sysctl options affect ct behavior. In
1576 particular, if net.netfilter.nf_conntrack_helper is enabled, which it
1577 is by default until Linux 4.7, then application layer gateway helpers
1578 may be executed even if alg is not specified. For security reasons,
1579 the netfilter team recommends users disable this option. For further
1580 details, please see http://www.netfilter.org/news.html#2012-04-03 .
1581 The ct action may be used as a primitive to construct stateful fire‐
1583 walls by selectively committing some traffic, then matching ct_state to
1584 allow established connections while denying new connections. The fol‐
1585 lowing flows provide an example of how to implement a simple firewall
1586 that allows new connections from port 1 to port 2, and only allows es‐
1587 tablished connections to send traffic from port 2 to port 1:
1588 table=0,priority=1,action=drop
1590 table=0,priority=10,arp,action=normal
1591 table=0,priority=100,ip,ct_state=-trk,action=ct(table=1)
1592 table=1,in_port=1,ip,ct_state=+trk+new,action=ct(commit),2
1593 table=1,in_port=1,ip,ct_state=+trk+est,action=2
1594 table=1,in_port=2,ip,ct_state=+trk+new,action=drop
1595 table=1,in_port=2,ip,ct_state=+trk+est,action=1
1596 If ct is executed on IPv4 (or IPv6) fragments, then the message is im‐
1598 plicitly reassembled before sending to the connection tracker and re‐
1599 fragmented upon output, to the original maximum received fragment size.
1600 Reassembly occurs within the context of the zone, meaning that IP frag‐
1601 ments in different zones are not assembled together. Pipeline process‐
1602 ing for the initial fragments is halted. When the final fragment is
1603 received, the message is assembled and pipeline processing continues
1604 for that flow. Packet ordering is not guaranteed by IP protocols, so
1605 it is not possible to determine which IP fragment will cause message
1606 reassembly (and therefore continue pipeline processing). As such, it is
1607 strongly recommended that multiple flows should not execute ct to re‐
1608 assemble fragments from the same IP message.
1609 Conformance
1611 The ct action was introduced in Open vSwitch 2.5. Some of its
1612 features were introduced later, noted individually above.
1613 The ct_clear action
1615 Syntax:
1616 ct_clear
1617 Clears connection tracking state from the flow, zeroing ct_state,
1620 ct_zone, ct_mark, and ct_label.
1621 This action was introduced in Open vSwitch 2.7.
1623 The learn action
1625 Syntax:
1626 learn(argument...)
1627 The learn action adds or modifies a flow in an OpenFlow table, similar
1630 to ovs-ofctl --strict mod-flows. The arguments specify the match
1631 fields, actions, and other properties of the flow to be added or modi‐
1632 fied.
1633 Match fields for the new flow are specified as follows. At least one
1635 match field should ordinarily be specified:
1636 field=value
1638 Specifies that field, in the new flow, must match the literal
1639 value, e.g. dl_type=0x800. Shorthand match syntax, such as
1640 ip in place of dl_type=0x800, is not supported.
1641 field=src
1643 Specifies that field in the new flow must match src taken
1644 from the packet currently being processed. For example,
1645 udp_dst=udp_src, applied to a UDP packet with source port 53,
1646 creates a flow which matches udp_dst=53. field and src must
1647 have the same width.
1648 field Shorthand for the previous form when field and src are the
1650 same. For example, udp_dst, applied to a UDP packet with
1651 destination port 53, creates a flow which matches udp_dst=53.
1652 The field and src arguments above should be fields or subfields in the
1654 syntax described under Field Specifications above.
1655 Match field specifications must honor prerequisites for both the flow
1657 with the learn and the new flow that it creates. Consider the follow‐
1658 ing complete flow, in the syntax accepted by ovs-ofctl. If the flow’s
1659 match on udp were omitted, then the flow would not satisfy the prereq‐
1660 uisites for the learn action’s use of udp_src. If dl_type=0x800 or
1661 nw_proto were omitted from learn, then the new flow would not satisfy
1662 the prerequisite for its match on udp_dst. For more information on
1663 prerequisites, please refer to ovs-fields(7):
1664 udp, actions=learn(dl_type=0x800, nw_proto=17, udp_dst=udp_src)
1666 Actions for the new flow are specified as follows. At least one action
1668 should ordinarily be specified:
1669 load:value->dst
1671 Adds a load action to the new flow that loads the literal
1672 value into dst. The syntax is the same as the load action
1673 explained in the Field Modification Actions section.
1674 load:src->dst
1676 Adds a load action to the new flow that loads src, a field or
1677 subfield from the packet being processed, into dst.
1678 output:field
1680 Adds an output action to the new flow’s actions that outputs
1681 to the OpenFlow port taken from field, which must be a field
1682 as described above.
1683 fin_idle_timeout=seconds / fin_hard_timeout=seconds
1685 Adds a fin_timeout action with the specified arguments to the
1686 new flow. This feature was added in Open vSwitch 1.6.
1687 The following additional arguments are optional:
1689 idle_timeout=seconds
1690 hard_timeout=seconds
1692 priority=value
1694 cookie=value
1696 send_flow_rem
1698 These arguments have the same meaning as in the usual flow
1699 syntax documented in ovs-ofctl(8).
1700 table=table
1702 The table in which the new flow should be inserted. Specify
1703 a decimal number between 0 and 254 inclusive or the name of a
1704 table. The default, if table is unspecified, is table 1 (not
1705 0).
1706 delete_learned
1708 When this flag is specified, deleting the flow that contains
1709 the learn action will also delete the flows created by learn.
1710 Specifically, when the last learn action with this flag and
1711 particular table and cookie values is removed, the switch
1712 deletes all of the flows in the specified table with the
1713 specified cookie.
1714 This flag was added in Open vSwitch 2.4.
1716 limit=number
1718 If the number of flows in the new flow’s table with the same
1719 cookie exceeds number, the action will not add a new flow.
1720 By default, or with limit=0, there is no limit.
1721 This flag was added in Open vSwitch 2.8.
1723 result_dst=field[bit]
1725 If learn fails (because the number of flows exceeds limit),
1726 the action sets field[bit] to 0, otherwise it will be set to
1727 1. field[bit] must be a single bit.
1728 This flag was added in Open vSwitch 2.8.
1730 By itself, the learn action can only put two kinds of actions into the
1732 flows that it creates: load and output actions. If learn is used in
1733 isolation, these are severe limits.
1734 However, learn is not meant to be used in isolation. It is a primitive
1736 meant to be used together with other Open vSwitch features to accom‐
1737 plish a task. Its existing features are enough to accomplish most
1738 tasks.
1739 Here is an outline of a typical pipeline structure that allows for ver‐
1741 satile behavior using learn:
1742 • Flows in table A contain a learn action, that populates flows in
1744 table L, that use a load action to populate register R with infor‐
1745 mation about what was learned.
1746 • Flows in table B contain two sequential resubmit actions: one to
1748 table L and another one to table B + 1.
1749 • Flows in table B + 1 match on register R and act differently de‐
1751 pending on what the flows in table L loaded into it.
1752 This approach can be used to implement many learn-based features. For
1754 example:
1755 • Resubmit to a table selected based on learned information, e.g.
1757 see
1758 https://mail.openvswitch.org/pipermail/ovs-discuss/2016-June/021694.html
1759 .
1760 • MAC learning in the middle of a pipeline, as described in the Open
1762 vSwitch Advanced Features Tutorial in the OVS documentation.
1763 • TCP state based firewalling, by learning outgoing connections
1765 based on SYN packets and matching them up with incoming packets.
1766 (This is usually better implemented using the ct action.)
1767 • At least some of the features described in T. A. Hoff, Extending
1769 Open vSwitch to Facilitate Creation of Stateful SDN Applications.
1770 Conformance
1772 The learn action is an Open vSwitch extension to OpenFlow added
1773 in Open vSwitch 1.3. Some features of learn were added in later
1774 versions, as noted individually above.
1775 The fin_timeout action
1777 Syntax:
1778 fin_timeout(key=value...)
1779 This action changes the idle timeout or hard timeout, or both, of the
1782 OpenFlow flow that contains it, when the flow matches a TCP packet with
1783 the FIN or RST flag. When such a packet is observed, the action re‐
1784 duces the rule’s timeouts to those specified on the action. If the
1785 rule’s existing timeout is already shorter than the one that the action
1786 specifies, then that timeout is unaffected.
1787 The timeouts are specified as key-value pairs:
1789 idle_timeout=seconds
1791 Causes the flow to expire after the given number of seconds
1792 of inactivity.
1793 hard_timeout=seconds
1795 Causes the flow to expire after the given number of seconds,
1796 regardless of activity. (seconds specifies time since the
1797 flow’s creation, not since the receipt of the FIN or RST.)
1798 This action is normally added to a learned flow by the learn action.
1800 It is unlikely to be useful otherwise.
1801 Conformance
1803 This Open vSwitch extension action was added in Open vSwitch
1804 1.6.
1805
1807 The resubmit action
1808 Syntax:
1809 resubmit:port
1810 resubmit([port],[table][,ct])``
1811 Searches an OpenFlow flow table for a matching flow and executes the
1814 actions found, if any, before continuing to the following action in the
1815 current flow entry. Arguments can customize the search:
1816 • If port is given as an OpenFlow port number or name, then it spec‐
1818 ifies a value to use for the input port metadata field as part of
1819 the search, in place of the input port currently in the flow.
1820 Specifying in_port as port is equivalent to omitting it.
1821 • If table is given as an integer between 0 and 254 or a table name,
1823 it specifies the OpenFlow table to search. If it is not speci‐
1824 fied, the table from the current flow is used.
1825 • If ct is specified, then the search is done with packet 5-tuple
1827 fields swapped with the corresponding conntrack original direction
1828 tuple fields. See the documentation for ct above, for more infor‐
1829 mation about connection tracking, or ovs-fields(7) for details
1830 about the connection tracking fields.
1831 This flag requires a valid connection tracking state as a match
1833 prerequisite in the flow where this action is placed. Examples of
1834 valid connection tracking state matches include ct_state=+new,
1835 ct_state=+est, ct_state=+rel, and ct_state=+trk-inv.
1836 The changes, if any, to the input port and connection tracking fields
1838 are just for searching the flow table. The changes are not visible to
1839 actions or to later flow table lookups.
1840 The most common use of resubmit is to visit another flow table without
1842 port or ct, like this: resubmit(,table).
1843 Recursive resubmit actions are permitted.
1845 Conformance
1847 The resubmit action is an Open vSwitch extension. However, the
1848 goto_table instruction in OpenFlow 1.1 and later can be viewed
1849 as a kind of restricted resubmit.
1850 Open vSwitch 1.3 added table. Open vSwitch 2.7 added ct.
1852 Open vSwitch imposes a limit on resubmit recursion that varies
1854 among version:
1855 • Open vSwitch 1.0.1 and earlier did not support recursion.
1857 • Open vSwitch 1.0.2 and 1.0.3 limited recursion to 8 levels.
1859 • Open vSwitch 1.1 and 1.2 limited recursion to 16 levels.
1861 • Open vSwitch 1.2 through 1.8 limited recursion to 32 lev‐
1863 els.
1864 • Open vSwitch 1.9 through 2.0 limited recursion to 64 lev‐
1866 els.
1867 • Open vSwitch 2.1 through 2.5 limited recursion to 64 levels
1869 and impose a total limit of 4,096 resubmits per flow trans‐
1870 lation (earlier versions did not impose any total limit).
1871 • Open vSwitch 2.6 and later imposes the same limits as 2.5,
1873 with one exception: resubmit from table x to any table y >
1874 x does not count against the recursion depth limit.
1875 The clone action
1877 Syntax:
1878 clone(action...)
1879 Executes each nested action, saving much of the packet and pipeline
1882 state beforehand and then restoring it afterward. The state that is
1883 saved and restored includes all flow data and metadata (including, for
1884 example, in_port and ct_state), the stack accessed by push and pop ac‐
1885 tions, and the OpenFlow action set.
1886 This action was added in Open vSwitch 2.7.
1888 The push and pop actions
1890 Syntax:
1891 push:src
1892 pop:dst
1893 The push action pushes src on a general-purpose stack. The pop action
1896 pops an entry off the stack into dst. src and dst should be fields or
1897 subfields in the syntax described under Field Specifications above.
1898 Controllers can use the stack for saving and restoring data or metadata
1900 around resubmit actions, for swapping or rearranging data and metadata,
1901 or for other purposes. Any data or metadata field, or part of one, may
1902 be pushed, and any modifiable field or subfield may be popped.
1903 The number of bits pushed in a stack entry do not have to match the
1905 number of bits later popped from that entry. If more bits are popped
1906 from an entry than were pushed, then the entry is conceptually
1907 left-padded with 0-bits as needed. If fewer bits are popped than
1908 pushed, then bits are conceptually trimmed from the left side of the
1909 entry.
1910 The stack’s size is limited. The limit is intended to be high enough
1912 that normal use will not pose problems. Stack overflow or underflow is
1913 an error that stops action execution (see Stack too deep under Error
1914 Handling, above).
1915 Examples:
1917 • push:reg2[0..5] or push:NXM_NX_REG2[0..5] pushes on the stack the
1919 6 bits in register 2 bits 0 through 5.
1920 • pop:reg2[0..5] or pop:NXM_NX_REG2[0..5] pops the value from top of
1922 the stack and copy bits 0 through 5 of that value into bits 0
1923 through 5 of register 2.
1924 Conformance
1926 Open vSwitch 1.2 introduced push and pop as OpenFlow extension
1927 actions.
1928 The exit action
1930 Syntax:
1931 exit
1932 This action causes Open vSwitch to immediately halt execution of fur‐
1935 ther actions. Actions which have already been executed are unaffected.
1936 Any further actions, including those which may be in other tables, or
1937 different levels of the resubmit call stack, are ignored. However, an
1938 exit action within a group bucket terminates only execution of that
1939 bucket, not other buckets or the overall pipeline. Actions in the ac‐
1940 tion set are still executed (specify clear_actions before exit to dis‐
1941 card them).
1942 The multipath action
1944 Syntax:
1945 multipath(fields,basis,algorithm,n_links,arg,dst)
1946 Hashes fields using basis as a universal hash parameter, then the ap‐
1949 plies multipath link selection algorithm (with parameter arg) to choose
1950 one of n_links output links numbered 0 through n_links minus 1, and
1951 stores the link into dst, which must be a field or subfield in the syn‐
1952 tax described under Field Specifications above.
1953 The bundle or bundle_load actions are usually easier to use than multi‐
1955 path.
1956 fields must be one of the following:
1958 eth_src
1960 Hashes Ethernet source address only.
1961 symmetric_l4
1963 Hashes Ethernet source, destination, and type, VLAN ID,
1964 IPv4/IPv6 source, destination, and protocol, and TCP or SCTP
1965 (but not UDP) ports. The hash is computed so that pairs of
1966 corresponding flows in each direction hash to the same value,
1967 in environments where L2 paths are the same in each direc‐
1968 tion. UDP ports are not included in the hash to support pro‐
1969 tocols such as VXLAN that use asymmetric ports in each direc‐
1970 tion.
1971 symmetric_l3l4
1973 Hashes IPv4/IPv6 source, destination, and protocol, and TCP
1974 or SCTP (but not UDP) ports. Like symmetric_l4, this is a
1975 symmetric hash, but by excluding L2 headers it is more effec‐
1976 tive in environments with asymmetric L2 paths (e.g. paths in‐
1977 volving VRRP IP addresses on a router). Not an effective
1978 hash function for protocols other than IPv4 and IPv6, which
1979 hash to a constant zero.
1980 symmetric_l3l4+udp
1982 Like symmetric_l3l4+udp, but UDP ports are included in the
1983 hash. This is a more effective hash when asymmetric UDP pro‐
1984 tocols such as VXLAN are not a consideration.
1985 symmetric_l3
1987 Hashes network source address and network destination ad‐
1988 dress.
1989 nw_src Hashes network source address only.
1991 nw_dst Hashes network destination address only.
1993 The algorithm used to compute the final result link must be one of the
1995 following:
1996 modulo_n
1998 Computes link = hash(flow) % n_links.
1999 This algorithm redistributes all traffic when n_links
2001 changes. It has O(1) performance.
2002 Use 65535 for max_link to get a raw hash value.
2004 This algorithm is specified by RFC 2992.
2006 hash_threshold
2008 Computes link = hash(flow) / (MAX_HASH / n_links).
2009 Redistributes between one-quarter and one-half of traffic
2011 when n_links changes. It has O(1) performance.
2012 This algorithm is specified by RFC 2992.
2014 hrw (Highest Random Weight)
2016 Computes the following:
2017 for i in [0, n_links]:
2019 weights[i] = hash(flow, i)
2020 link = { i such that weights[i] >= weights[j] for all j != i }
2021 Redistributes 1 / n_links of traffic when n_links changes.
2023 It has O(n_links) performance. If n_links is greater than a
2024 threshold (currently 64, but subject to change), Open vSwitch
2025 will substitute another algorithm automatically.
2026 This algorithm is specified by RFC 2992.
2028 iter_hash (Iterative Hash)
2030 Computes the following:
2031 i = 0
2033 repeat:
2034 i = i + 1
2035 link = hash(flow, i) % arg
2036 while link > max_link
2037 Redistributes 1 / n_links of traffic when n_links changes.
2039 O(1) performance when arg / max_link is bounded by a con‐
2040 stant.
2041 Redistributes all traffic when arg changes.
2043 arg must be greater than max_link and for best performance
2045 should be no more than approximately max_link * 2. If arg is
2046 outside the acceptable range, Open vSwitch will automatically
2047 substitute the least power of 2 greater than max_link.
2048 This algorithm is specific to Open vSwitch.
2050 Only the iter_hash algorithm uses arg.
2052 It is an error if max_link is greater than or equal to 2**n_bits.
2054 Conformance
2056 This is an OpenFlow extension added in Open vSwitch 1.1.
2057
2059 The conjunction action
2060 Syntax:
2061 conjunction(id, k/n)
2062 This action allows for sophisticated conjunctive match flows. Refer to
2065 Conjunctive Match Fields in ovs-fields(7) for details.
2066 A flow that has one or more conjunction actions may not have any other
2068 actions except for note actions.
2069 Conformance
2071 Open vSwitch 2.4 introduced the conjunction action and conj_id
2072 field. They are Open vSwitch extensions to OpenFlow.
2073 The note action
2075 Syntax:
2076 note:[hh]...
2077 This action does nothing at all. OpenFlow controllers may use it to
2080 annotate flows with more data than can fit in a flow cookie.
2081 The action may include any number of bytes represented as hex digits
2083 hh. Periods may separate pairs of hex digits, for readability. The
2084 note action’s format doesn’t include an exact length for its payload,
2085 so the provided bytes will be padded on the right by enough bytes with
2086 value 0 to make the total number 6 more than a multiple of 8.
2087 Conformance
2089 This action is an extension to OpenFlow introduced in Open
2090 vSwitch 1.1.
2091 The sample action
2093 Syntax:
2094 sample(argument...)
2095 Samples packets and sends one sample for every sampled packet.
2098 The following argument forms are accepted:
2100 probability=packets
2102 The number of sampled packets out of 65535. Must be greater
2103 or equal to 1.
2104 collector_set_id=id
2106 The unsigned 32-bit integer identifier of the set of sample
2107 collectors to send sampled packets to. Defaults to 0.
2108 obs_domain_id=id
2110 When sending samples to IPFIX collectors, the unsigned 32-bit
2111 integer Observation Domain ID sent in every IPFIX flow
2112 record. Defaults to 0.
2113 obs_point_id=id
2115 When sending samples to IPFIX collectors, the unsigned 32-bit
2116 integer Observation Point ID sent in every IPFIX flow record.
2117 Defaults to 0.
2118 sampling_port=port
2120 Sample packets on port, which should be the ingress or egress
2121 port. This option, which was added in Open vSwitch 2.6, al‐
2122 lows the IPFIX implementation to export egress tunnel infor‐
2123 mation.
2124 ingress
2126 egress Specifies explicitly that the packet is being sampled on
2128 ingress to or egress from the switch. IPFIX reports sent by
2129 Open vSwitch before version 2.6 did not include a direction.
2130 From 2.6 until 2.7, IPFIX reports inferred a direction from
2131 sampling_port: if it was the packet’s output port, then the
2132 direction was reported as egress, otherwise as ingress. Open
2133 vSwitch 2.7 introduced these options, which allow the in‐
2134 ferred direction to be overridden. This is particularly use‐
2135 ful when the ingress (or egress) port is not a tunnel.
2136 Refer to ovs-vswitchd.conf.db(5) for more details on configuring sample
2138 collector sets.
2139 Conformance
2141 This action is an OpenFlow extension added in Open vSwitch 2.4.
2142
2144 Every version of OpenFlow includes actions. OpenFlow 1.1 introduced
2145 the higher-level, related concept of instructions. In OpenFlow 1.1 and
2146 later, actions within a flow are always encapsulated within an instruc‐
2147 tion. Each flow has at most one instruction of each kind, which are
2148 executed in the following fixed order defined in the OpenFlow specifi‐
2149 cation:
2150 1. Meter
2152 2. Apply-Actions
2154 3. Clear-Actions
2156 4. Write-Actions
2158 5. Write-Metadata
2160 6. Stat-Trigger (not supported by Open vSwitch)
2162 7. Goto-Table
2164 The most important instruction is Apply-Actions. This instruction en‐
2166 capsulates any number of actions, which the instruction executes. Open
2167 vSwitch does not explicitly represent Apply-Actions. Instead, any ac‐
2168 tion by itself is implicitly part of an Apply-Actions instructions.
2169 Open vSwitch syntax requires other instructions, if present, to be in
2171 the order listed above. Otherwise it will flag an error.
2172 The meter action and instruction
2174 Syntax:
2175 meter:meter_id
2176 Apply meter meter_id. If a meter band rate is exceeded, the packet may
2179 be dropped, or modified, depending on the meter band type.
2180 Conformance
2182 OpenFlow 1.3 introduced the meter instruction. OpenFlow 1.5
2183 changes meter from an instruction to an action.
2184 OpenFlow 1.5 allows implementations to restrict meter to be the
2186 first action in an action list and to exclude meter from action
2187 sets, for better compatibility with OpenFlow 1.3 and 1.4. Open
2188 vSwitch restricts the meter action both ways.
2189 Open vSwitch 2.0 introduced OpenFlow protocol support for me‐
2191 ters, but it did not include a datapath implementation. Open
2192 vSwitch 2.7 added meter support to the userspace datapath. Open
2193 vSwitch 2.10 added meter support to the kernel datapath. Open
2194 vSwitch 2.12 added support for meter as an action in OpenFlow
2195 1.5.
2196 The clear_actions instruction
2198 Syntax:
2199 clear_actions
2200 Clears the action set. See Action Sets, above, for more information.
2203 Conformance
2205 OpenFlow 1.1 introduced clear_actions. Open vSwitch 2.1 added
2206 support for clear_actions.
2207 The write_actions instruction
2209 Syntax:
2210 write_actions(action...)
2211 Adds each action to the action set. The action set is carried between
2214 flow tables and then executed at the end of the pipeline. Only certain
2215 actions may be written to the action set. See Action Sets, above, for
2216 more information.
2217 Conformance
2219 OpenFlow 1.1 introduced write_actions. Open vSwitch 2.1 added
2220 support for write_actions.
2221 The write_metadata instruction
2223 Syntax:
2224 write_metadata:value[/mask]
2225 Updates the flow’s metadata field. If mask is omitted, metadata is set
2228 exactly to value; if mask is specified, then a 1-bit in mask indicates
2229 that the corresponding bit in metadata will be replaced with the corre‐
2230 sponding bit from value. Both value and mask are 64-bit values that
2231 are decimal by default; use a 0x prefix to specify them in hexadecimal.
2232 The metadata field can also be matched in the flow table and updated
2234 with actions such as set_field and move.
2235 Conformance
2237 OpenFlow 1.1 introduced write_metadata. Open vSwitch 2.1 added
2238 support for write_metadata.
2239 The goto_table instruction
2241 Syntax:
2242 goto_table:table
2243 Jumps to table as the next table in the process pipeline. The table
2246 may be a number between 0 and 254 or a table name.
2247 It is an error if table is less than or equal to the table of the flow
2249 that contains it; that is, goto_table must move forward in the OpenFlow
2250 pipeline. Since goto_table must be the last instruction in a flow, it
2251 never leads to recursion. The resubmit extension action is more flexi‐
2252 ble.
2253 Conformance
2255 OpenFlow 1.1 introduced goto_table. Open vSwitch 2.1 added sup‐
2256 port for goto_table.
2257
2259 The Open vSwitch Development Community
2260
2262 2016-2022, The Open vSwitch Development Community
22632.17 Jul 22, 2022 OVS-ACTIONS(7)