1ovs-actions(7) Open vSwitch Manual ovs-actions(7)
2
6 ovs-actions - OpenFlow actions and instructions with Open vSwitch
7 extensions
8
10 This document aims to comprehensively document all of the OpenFlow
11 actions 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‐
33 ply an ordered sequence of actions. The OpenFlow specifications require
34 a switch to execute actions within an action list in the order speci‐
35 fied, and to refuse to execute an action list entirely if it cannot
36 implement the actions in that order [OpenFlow 1.0, section 3.3], with
37 one exception: when an action list outputs multiple packets, the switch
38 may output the packets in an order different from that specified. Usu‐
39 ally, this exception is not important, especially in the common case
40 when the packets are output to different ports.
41 Action Sets
43 OpenFlow 1.1 introduced the concept of an action set. An action set is
45 also a sequence of actions, but the switch reorders the actions and
46 drops duplicates according to rules specified in the OpenFlow specifi‐
47 cations. Because of these semantics, some standard OpenFlow actions
48 cannot usefully be included in an action set. For some, but not all,
49 Open vSwitch extension actions, Open vSwitch defines its own action set
50 semantics and ordering.
51 The OpenFlow pipeline has an action set associated with it as a packet
53 is processed. After pipeline processing is otherwise complete, the
54 switch executes the actions in the action set.
55 Open vSwitch applies actions in an action set in the following order:
57 Except as noted otherwise below, the action set only executes at most a
58 single action of each type, and when more than one action of a given
59 type is present, the one added to the set later replaces the earlier
60 action:
61 1. strip_vlan
63 2. pop_mpls
65 3. decap
67 4. encap
69 5. push_mpls
71 6. push_vlan
73 7. dec_ttl
75 8. dec_mpls_ttl
77 9. dec_nsh_ttl
79 10. All of the following actions are executed in the order added
81 to the action set, with cumulative effect. That is, when
82 multiple actions modify the same part of a field, the later
83 modification takes effect, and when they modify different
84 parts of a field (or different fields), then both modifica‐
85 tions are applied:
86 · load
88 · move
90 · mod_dl_dst
92 · mod_dl_src
94 · mod_nw_dst
96 · mod_nw_src
98 · mod_nw_tos
100 · mod_nw_ecn
102 · mod_nw_ttl
104 · mod_tp_dst
106 · mod_tp_src
108 · mod_vlan_pcp
110 · mod_vlan_vid
112 · set_field
114 · set_tunnel
116 · set_tunnel64
118 11. set_queue
120 12. group, output, resubmit, ct_clear, or ct. If more than one
122 of these actions is present, then the one listed earliest
123 above is executed and the others are ignored, regardless of
124 the order in which they were added to the action set. (If
125 none of these actions is present, the action set has no real
126 effect, because the modified packet is not sent anywhere and
127 thus the modifications are not visible.)
128 An action set may only contain the actions listed above.
130 Error Handling
132 Packet processing can encounter a variety of errors:
133 Bridge not found
135 Open vSwitch supports an extension to the standard Open‐
136 Flow controller action called a ``continuation,’’ which
137 allows the controller to interrupt and later resume the
138 processing of a packet through the switch pipeline. This
139 error occurs when such a packet’s processing cannot be
140 resumed, e.g. because the bridge processing it has been
141 destroyed. Open vSwitch reports this error to the con‐
142 troller as Open vSwitch extension error NXR_STALE.
143 This error prevents packet processing entirely.
145 Recursion too deep
147 While processing a given packet, Open vSwitch limits the
148 flow table recursion depth to 64, to ensure that packet
149 processing uses a finite amount of time and space.
150 Actions that count against the recursion limit include
151 resubmit from a given OpenFlow table to the same or an
152 earlier table, group, and output to patch ports.
153 A resubmit from one table to a later one (or, equiva‐
155 lently. a goto_table instruction) does not count against
156 the depth limit because resubmits to strictly monotoni‐
157 cally increasing tables will eventually terminate. Open‐
158 Flow tables are most commonly traversed in numerically
159 increasing order, so this limit has little effect on con‐
160 ventionally designed OpenFlow pipelines.
161 This error terminates packet processing. Any previous
163 side effects (e.g. output actions) are retained.
164 Usually this error indicates a loop or other bug in the
166 OpenFlow flow tables. To assist debugging, when this
167 error occurs, Open vSwitch 2.10 and later logs a trace of
168 the packet execution, as if by ovs-appctl ofproto/trace,
169 rate-limited to one per minute to reduce the log volume.
170 Too many resubmits
172 Open vSwitch limits the total number of resubmit actions
173 that a given packet can execute to 4,096. For this pur‐
174 pose, goto_table instructions and output to the table
175 port are treated like resubmit. This limits the amount of
176 time to process a single packet.
177 Unlike the limit on recursion depth, the limit on resub‐
179 mits counts all resubmits, regardless of direction.
180 This error has the same effect, including logging, as
182 exceeding the recursion depth limit.
183 Stack too deep
185 Open vSwitch limits the amount of data that the push
186 action can put onto the stack at one time to 64 kB of
187 data.
188 This error terminates packet processing. Any previous
190 side effects (e.g. output actions) are retained.
191 No recirculation context
193 Recirculation conflict
194 These errors indicate internal errors inside Open vSwitch
195 and should generally not occur. If you notice recurring log
196 messages about these errors, please report a bug.
197 Too many MPLS labels
199 Open vSwitch can process packets with any number of MPLS
200 labels, but its ability to push and pop MPLS labels is lim‐
201 ited, currently to 3 labels. Attempting to push more than
202 the supported number of labels onto a packet, or to pop any
203 number of labels from a packet with more than the supported
204 number, raises this error.
205 This error terminates packet processing, retaining any pre‐
207 vious side effects (e.g. output actions). When this error
208 arises within the execution of a group bucket, it only ter‐
209 minates that bucket’s execution, not packet processing
210 overall.
211 Invalid tunnel metadata
213 Open vSwitch raises this error when it processes a Geneve
214 packet that has TLV options with an invalid form, e.g.
215 where the length in a TLV would extend past the end of the
216 options.
217 This error prevents packet processing entirely.
219 Unsupported packet type
221 When a encap action encapsulates a packet, Open vSwitch
222 raises this error if it does not support the combination of
223 the new encapsulation with the current packet. encap(ether‐
224 net) raises this error if the current packet is not an L3
225 packet, and encap(nsh) raises this error if the current
226 packet is not Ethernet, IPv4, IPv6, or NSH.
227 When a decap action decapsulates a packet, Open vSwitch
229 raises this error if it does not support the type of inner
230 packet. decap of an Ethernet header raises this error if a
231 VLAN header is present, decap of a NSH packet raises this
232 error if the NSH inner packet is not Ethernet, IPv4, IPv6,
233 or NSH, and decap of other types of packets is unsupported
234 and also raises this error.
235 This error terminates packet processing, retaining any pre‐
237 vious side effects (e.g. output actions). When this error
238 arises within the execution of a group bucket, it only ter‐
239 minates that bucket’s execution, not packet processing
240 overall.
241 Inconsistencies
243 OpenFlow 1.0 allows any action to be part of any flow, regardless of
244 the flow’s match. Some combinations do not make sense, e.g. an
245 set_nw_tos action in a flow that matches only ARP packets or strip_vlan
246 in a flow that matches packets without VLAN tags. Other combinations
247 have varying results depending on the kind of packet that the flow pro‐
248 cesses, e.g. a set_nw_src action in a flow that does not match on
249 Ethertype will be treated as a no-op when it processes a non-IPv4
250 packet. Nevertheless OVS allows all of the above in conformance with
251 OpenFlow 1.0, that is, the following will succeed:
252 $ ovs-ofctl -O OpenFlow10 add-flow br0 arp,actions=mod_nw_tos:12
254 $ ovs-ofctl -O OpenFlow10 add-flow br0 dl_vlan=0xffff,actions=strip_vlan
255 $ ovs-ofctl -O OpenFlow10 add-flow br0 actions=mod_nw_src:1.2.3.4
256 Open vSwitch calls these kinds of combinations inconsistencies between
259 match and actions. OpenFlow 1.1 and later forbid inconsistencies, and
260 disallow the examples described above by preventing such flows from
261 being added. All of the above, for example, will fail with an error
262 message if one replaces OpenFlow10 by OpenFlow11.
263 OpenFlow 1.1 and later cannot detect and disallow all inconsistencies.
265 For example, the write_actions instruction arbitrarily delays execution
266 of the actions inside it, which can even be canceled with
267 clear_actions, so that there is no way to ensure that its actions are
268 consistent with the packet at the time they execute. Thus, actions with
269 write_actions and some other contexts are exempt from consistency
270 requirements.
271 When OVS executes an action inconsistent with the packet, it treats it
273 as a no-op.
274 Inter-Version Compatibility
276 Open vSwitch supports multiple OpenFlow versions simultaneously on a
277 single switch. When actions are added with one OpenFlow version and
278 then retrieved with another, Open vSwitch does its best to translate
279 between them.
280 Inter-version compatibility issues can still arise when different con‐
282 nections use different OpenFlow versions. Backward compatibility is the
283 most obvious case. Suppose, for example, that an OpenFlow 1.1 session
284 adds a flow with a push_vlan action, for which there is no equivalent
285 in OpenFlow 1.0. If an OpenFlow 1.0 session retrieves this flow, Open
286 vSwitch must somehow represent the action.
287 Forward compatibility can also be an issue, because later OpenFlow ver‐
289 sions sometimes remove functionality. The best example is the enqueue
290 action from OpenFlow 1.0, which OpenFlow 1.1 removed.
291 In practice, Open vSwitch uses a variety of strategies for inter-ver‐
293 sion compatibility:
294 · Most standard OpenFlow actions, such as output actions,
296 translate without compatibility issues.
297 · Open vSwitch supports its extension actions in every
299 OpenFlow version, so they do not pose inter-version com‐
300 patibility problems.
301 · Open vSwitch sometimes adds extension actions to ensure
303 backward or forward compatibility. For example, for back‐
304 ward compatibility with the group action added in Open‐
305 Flow 1.1, Open vSwitch includes an OpenFlow 1.0 extension
306 group action.
307 Perfect inter-version compatibility is not possible, so best results
309 require OpenFlow connections to use a consistent version. One may
310 enforce use of a particular version by setting the protocols column for
311 a bridge, e.g. to force br0 to use only OpenFlow 1.3:
312 ovs-vsctl set bridge br0 protocols=OpenFlow13
314 Field Specifications
317 Many Open vSwitch actions refer to fields. In such cases, fields may
318 usually be referred to by their common names, such as eth_dst for the
319 Ethernet destination field, or by their full OXM or NXM names, such as
320 NXM_OF_ETH_DST or OXM_OF_ETH_DST. Before Open vSwitch 2.7, only OXM or
321 NXM field names were accepted.
322 Many actions that act on fields can also act on subfields, that is,
324 parts of fields, written as field[start..end], where start is the first
325 bit and end is the last bit to use in field, e.g. vlan_tci[13..15] for
326 the VLAN PCP. A single-bit subfield may also be written as field[off‐
327 set], e.g. vlan_tci[13] for the least-significant bit of the VLAN PCP.
328 Empty brackets may be used to explicitly designate an entire field,
329 e.g. vlan_tci[] for the entire 16-bit VLAN TCI header. Before Open
330 vSwitch 2.7, brackets were required in field specifications.
331 See ovs-fields(7) for a list of fields and their names.
333 Port Specifications
335 Many Open vSwitch actions refer to OpenFlow ports. In such cases, the
336 port may be specified as a numeric port number in the range 0 to
337 65,535, although Open vSwitch only assigns port numbers in the range 1
338 through 62,279 to ports. OpenFlow 1.1 and later use 32-bit port num‐
339 bers, but Open vSwitch never assigns a port number that requires more
340 than 16 bits.
341 In most contexts, the name of a port may also be used. (The most obvi‐
343 ous context where a port name may not be used is in an ovs-ofctl com‐
344 mand along with the --no-names option.) When a port’s name contains
345 punctuation or could be ambiguous with other actions, the name may be
346 enclosed in double quotes, with JSON-like string escapes supported (see
347 [RFC 8259]).
348 Open vSwitch also supports the following standard OpenFlow port names
350 (even in contexts where port names are not otherwise supported). The
351 corresponding OpenFlow 1.0 and 1.1+ port numbers are listed alongside
352 them but should not be used in flow syntax:
353 · in_port (65528 or 0xfff8; 0xfffffff8)
355 · table (65529 or 0xfff9; 0xfffffff9)
357 · normal (65530 or 0xfffa; 0xfffffffa)
359 · flood (65531 or 0xfffb; 0xfffffffb)
361 · all (65532 or 0xfffc; 0xfffffffc)
363 · controller (65533 or 0xfffd; 0xfffffffd)
365 · local (65534 or 0xfffe; 0xfffffffe)
367 · any or none (65535 or 0xffff; 0xffffffff)
369 · unset (not in OpenFlow 1.0; 0xfffffff7)
371
373 These actions send a packet to a physical port or a controller. A
374 packet that never encounters an output action on its trip through the
375 Open vSwitch pipeline is effectively dropped. Because actions are exe‐
376 cuted in order, a packet modification action that is not eventually
377 followed by an output action will not have an externally visible
378 effect.
379 The output action
381 Syntax:
382 port
383 output:port
384 output:field
385 output(port=port, max_len=nbytes)
386 Outputs the packet to an OpenFlow port most commonly specified as port.
388 Alternatively, the output port may be read from field, a field or sub‐
389 field in the syntax described under ``Field Specifications’’ above.
390 Either way, if the port is the packet’s input port, the packet is not
391 output.
392 The port may be one of the following standard OpenFlow ports:
394 local Outputs the packet on the ``local port’’ that corresponds
396 to the network device that has the same name as the
397 bridge, unless the packet was received on the local port.
398 OpenFlow switch implementations are not required to have
399 a local port, but Open vSwitch bridges always do.
400 in_port
402 Outputs the packet on the port on which it was received.
403 This is the only standard way to output the packet to the
404 input port (but see ``Output to the Input port’’, below).
405 The port may also be one of the following additional OpenFlow ports,
407 unless max_len is specified:
408 normal Subjects the packet to the device’s normal L2/L3 process‐
410 ing. This action is not implemented by all OpenFlow
411 switches, and each switch implements it differently.
412 flood Outputs the packet on all switch physical ports, except
414 the port on which it was received and any ports on which
415 flooding is disabled. Flooding can be disabled automati‐
416 cally on a port by Open vSwitch when IEEE 802.1D spanning
417 tree (STP) or rapid spanning tree (RSTP) is enabled, or
418 by a controller using an OpenFlow OFPT_MOD_PORT request
419 to set the port’s OFPPC_NO_FLOOD flag (ovs-ofctl mod-port
420 provides a command-line interface to set this flag).
421 all Outputs the packet on all switch physical ports except
423 the port on which it was received.
424 controller
426 Sends the packet and its metadata to an OpenFlow con‐
427 troller or controllers encapsulated in an OpenFlow
428 ``packet-in’’ message. The separate controller action,
429 described below, provides more options for output to a
430 controller.
431 Open vSwitch rejects output to other standard OpenFlow ports, including
433 none, unset, and port numbers reserved for future use as standard
434 ports, with the error OFPBAC_BAD_OUT_PORT.
435 With max_len, the packet is truncated to at most nbytes bytes before
437 being output. In this case, the output port may not be a patch port.
438 Truncation is just for the single output action, so that later actions
439 in the OpenFlow pipeline work with the complete packet. The truncation
440 feature is meant for use in monitoring applications, e.g. for mirroring
441 packets to a collector.
442 When an output action specifies the number of a port that does not cur‐
444 rently exist (and is not in the range for standard ports), the OpenFlow
445 specification allows but does not require OVS to reject the action. All
446 versions of Open vSwitch treat such an action as a no-op. If a port
447 with the number is created later, then the action will be honored at
448 that point. (OpenFlow requires OVS to reject output to a port number
449 that will never be valid, with OFPBAC_BAD_OUT_PORT, but this situation
450 does not arise when OVS is a software switch, since the user can add or
451 renumber ports at any time.)
452 A controller can suppress output to a port by setting its OFPPC_NO_FOR‐
454 WARD flag using an OpenFlow OFPT_MOD_PORT request (ovs-ofctl mod-port
455 provides a command-line interface to set this flag). When output is
456 disabled, output actions (and other actions that output to the port)
457 are allowed but have no effect.
458 Open vSwitch allows output to a port that does not exist, although
460 OpenFlow allows switches to reject such actions.
461 Output to the Input Port
463 OpenFlow requires a switch to ignore attempts to send a packet out its
465 ingress port in the most straightforward way. For example, output:234
466 has no effect if the packet has ingress port 234. The rationale is that
467 dropping these packets makes it harder to loop the network. Sometimes
468 this behavior can even be convenient, e.g. it is often the desired
469 behavior in a flow that forwards a packet to several ports (``floods’’
470 the packet).
471 Sometimes one really needs to send a packet out its ingress port
473 (``hairpin’’). In this case, use in_port to explicitly output the
474 packet to its input port, e.g.:
475 $ ovs-ofctl add-flow br0 in_port=2,actions=in_port
477 This also works in some circumstances where the flow doesn’t match on
480 the input port. For example, if you know that your switch has five
481 ports numbered 2 through 6, then the following will send every received
482 packet out every port, even its ingress port:
483 $ ovs-ofctl add-flow br0 actions=2,3,4,5,6,in_port
485 or, equivalently:
488 $ ovs-ofctl add-flow br0 actions=all,in_port
490 Sometimes, in complicated flow tables with multiple levels of resubmit
493 actions, a flow needs to output to a particular port that may or may
494 not be the ingress port. It’s difficult to take advantage of output to
495 in_port in this situation. To help, Open vSwitch provides, as an Open‐
496 Flow extension, the ability to modify the in_port field. Whatever value
497 is currently in the in_port field is both the port to which output will
498 be dropped and the destination for in_port. This means that the follow‐
499 ing adds flows that reliably output to port 2 or to ports 2 through 6,
500 respectively:
501 $ ovs-ofctl add-flow br0 "in_port=2,actions=load:0->in_port,2"
503 $ ovs-ofctl add-flow br0 "actions=load:0->in_port,2,3,4,5,6"
504 If in_port is important for matching or other reasons, one may save and
507 restore it on the stack:
508 $ ovs-ofctl add-flow br0 actions="push:in_port,\
510 load:0->in_port,\
511 2,3,4,5,6,\
512 pop:in_port"
513 Conformance:
516 All versions of OpenFlow and Open vSwitch support output to a literal
518 port. Output to a register is an OpenFlow extension introduced in Open
519 vSwitch 1.3. Output with truncation is an OpenFlow extension introduced
520 in Open vSwitch 2.6.
521 The controller action
523 Syntax:
524 controller
525 controller:max_len
526 controller(key[=value], ...)
527 Sends the packet and its metadata to an OpenFlow controller or con‐
529 trollers encapsulated in an OpenFlow ``packet-in’’ message. The sup‐
530 ported options are:
531 max_len=max_len
533 Limit to max_len the number of bytes of the packet to
534 send in the ``packet-in.’’ A max_len of 0 prevents any of
535 the packet from being sent (thus, only metadata is
536 included). By default, the entire packet is sent, equiva‐
537 lent to a max_len of 65535.
538 reason=reason
540 Specify reason as the reason for sending the message in
541 the ``packet-in.’’ The supported reasons are no_match,
542 action, invalid_ttl, action_set, group, and packet_out.
543 The default reason is action.
544 id=controller_id
546 Specify controller_id, a 16-bit integer, as the connec‐
547 tion ID of the OpenFlow controller or controllers to
548 which the ``packet-in’’ message should be sent. The
549 default is zero. Zero is also the default connection ID
550 for each controller connection, and a given controller
551 connection will only have a nonzero connection ID if its
552 controller uses the NXT_SET_CONTROLLER_ID Open vSwitch
553 extension to OpenFlow.
554 userdata=hh...
556 Supplies the bytes represented as hex digits hh as addi‐
557 tional data to the controller in the ``packet-in’’ mes‐
558 sage. Pairs of hex digits may be separated by periods for
559 readability.
560 pause Causes the switch to freeze the packet’s trip through
562 Open vSwitch flow tables and serializes that state into
563 the packet-in message as a ``continuation,’’ an addi‐
564 tional property in the NXT_PACKET_IN2 message. The con‐
565 troller can later send the continuation back to the
566 switch in an NXT_RESUME message, which will restart the
567 packet’s traversal from the point where it was inter‐
568 rupted. This permits an OpenFlow controller to interpose
569 on a packet midway through processing in Open vSwitch.
570 Conformance:
572 All versions of OpenFlow and Open vSwitch support controller action and
574 its max_len option. The userdata and pause options require the Open
575 vSwitch NXAST_CONTROLLER2 extension action added in Open vSwitch 2.6.
576 In the absence of these options, the reason (other than reason=action)
577 and controller_id (option than controller_id=0) options require the
578 Open vSwitch NXAST_CONTROLLER extension action added in Open vSwitch
579 1.6.
580 The enqueue action
582 Syntax:
583 enqueue(port,queue)
584 enqueue:port:queue
585 Enqueues the packet on the specified queue within port port.
587 port must be an OpenFlow port number or name as described under ``Port
589 Specifications’’ above. port may be in_port or local but the other
590 standard OpenFlow ports are not allowed.
591 queue must be a a number between 0 and 4294967294 (0xfffffffe), inclu‐
593 sive. The number of actually supported queues depends on the switch.
594 Some OpenFlow implementations do not support queuing at all. In Open
595 vSwitch, the supported queues vary depending on the operating system,
596 datapath, and hardware in use. Use the QoS and Queue tables in the Open
597 vSwitch database to configure queuing on individual OpenFlow ports (see
598 ovs-vswitchd.conf.db(5) for more information).
599 Conformance:
601 Only OpenFlow 1.0 supports enqueue. OpenFlow 1.1 added the set_queue
603 action to use in its place along with output.
604 Open vSwitch translates enqueue to a sequence of three actions in Open‐
606 Flow 1.1 or later: set_queue:queue, output:port, pop_queue. This is
607 equivalent in behavior as long as the flow table does not otherwise use
608 set_queue, but it relies on the pop_queue Open vSwitch extension
609 action.
610 The bundle and bundle_load actions
612 Syntax:
613 bundle(fields, basis, algorithm, ofport, slaves:port...)
614 bundle_load(fields, basis, algorithm, ofport, dst,
615 slaves:port...)
616 These actions choose a port (``slave’’) from a comma-separated OpenFlow
618 port list. After selecting the port, bundle outputs to it, whereas bun‐
619 dle_load writes its port number to dst, which must be a 16-bit or wider
620 field or subfield in the syntax described under ``Field Specifica‐
621 tions’’ above.
622 These actions hash a set of fields using basis as a universal hash
624 parameter, then apply the bundle link selection algorithm to choose a
625 port.
626 fields must be one of the following. For the options with ``symmetric’’
628 in the name, reversing source and destination addresses yields the same
629 hash:
630 eth_src
632 Ethernet source address.
633 nw_src IPv4 or IPv6 source address.
635 nw_dst IPv4 or IPv6 destination address.
637 symmetric_l4
639 Ethernet source and destination, Ethernet type, VLAN ID
640 or IDs (if any), IPv4 or IPv6 source and destination, IP
641 protocol, TCP or SCTP (but not UDP) source and destina‐
642 tion.
643 symmetric_l3l4
645 IPv4 or IPv6 source and destination, IP protocol, TCP or
646 SCTP (but not UDP) source and destination.
647 symmetric_l3l4+udp
649 Like symmetric_l3l4 but include UDP ports.
650 algorithm must be one of the following:
652 active_backup
654 Chooses the first live port listed in slaves.
655 hrw (Highest Random Weight)
657 Computes the following, considering only the live ports
658 in slaves:
659 for i in [1,n_slaves]:
661 weights[i] = hash(flow, i)
662 slave = { i such that weights[i] >= weights[j] for all j != i }
663 This algorithm is specified by RFC 2992.
666 The algorithms take port liveness into account when selecting slaves.
668 The definition of whether a port is live is subject to change. It cur‐
669 rently takes into account carrier status and link monitoring protocols
670 such as BFD and CFM. If none of the slaves is live, bundle does not
671 output the packet and bundle_load stores OFPP_NONE (65535) in the out‐
672 put field.
673 Example: bundle(eth_src,0,hrw,ofport,slaves:4,8) uses an Ethernet
675 source hash with basis 0, to select between OpenFlow ports 4 and 8
676 using the Highest Random Weight algorithm.
677 Conformance:
679 Open vSwitch 1.2 introduced the bundle and bundle_load OpenFlow exten‐
681 sion actions.
682 The group action
684 Syntax:
685 group:group
686 Outputs the packet to the OpenFlow group group, which must be a number
688 in the range 0 to 4294967040 (0xffffff00). The group must exist or Open
689 vSwitch will refuse to add the flow. When a group is deleted, Open
690 vSwitch also deletes all of the flows that output to it.
691 Groups contain action sets, whose semantics are described above in the
693 section ``Action Sets’’. The semantics of action sets can be surprising
694 to users who expect action list semantics, since action sets reorder
695 and sometimes ignore actions.
696 A group action usually executes the action set or sets in one or more
698 group buckets. Open vSwitch saves the packet and metadata before it
699 executes each bucket, and then restores it afterward. Thus, when a
700 group executes more than one bucket, this means that each bucket exe‐
701 cutes on the same packet and metadata. Moreover, regardless of the num‐
702 ber of buckets executed, the packet and metadata are the same before
703 and after executing the group.
704 Sometimes saving and restoring the packet and metadata can be undesir‐
706 able. In these situations, workarounds are possible. For example, con‐
707 sider a pipeline design in which a select group bucket is to communi‐
708 cate to a later stage of processing a value based on which bucket was
709 selected. An obvious design would be for the bucket to communicate the
710 value via set_field on a register. This does not work because registers
711 are part of the metadata that group saves and restores. A design that
712 would work would be for the bucket to recursively invoke the rest of
713 the pipeline with resubmit rather than to attempt to return it. Another
714 possibility is for the bucket to use push to put the value on the stack
715 for the caller to pop off, since group preserves only packet data and
716 metadata, not the stack.
717 An exit action within a group bucket terminates only execution of that
719 bucket, not other buckets or the overall pipeline.
720 Conformance:
722 OpenFlow 1.1 introduced group. Open vSwitch 2.6 and later also supports
724 group as an extension to OpenFlow 1.0.
725
727 The strip_vlan and pop actions
728 Syntax:
729 strip_vlan
730 pop_vlan
731 Removes the outermost VLAN tag, if any, from the packet.
733 The two names for this action are synonyms with no semantic difference.
735 The OpenFlow 1.0 specification uses the name strip_vlan and later ver‐
736 sions use pop_vlan, but OVS accepts either name regardless of version.
737 In OpenFlow 1.1 and later, consistency rules allow strip_vlan only in a
739 flow that matches only packets with a VLAN tag (or following an action
740 that pushes a VLAN tag, such as push_vlan). See ``Inconsistencies’’,
741 above, for more information.
742 Conformance:
744 All versions of OpenFlow and Open vSwitch support this action.
746 The push_vlan action
748 Syntax:
749 push_vlan:ethertype
750 Pushes a new outermost VLAN onto the packet. Uses TPID ethertype, which
752 must be 0x8100 for an 802.1Q C-tag or 0x88a8 for a 802.1ad S-tag.
753 Conformance:
755 OpenFlow 1.1 and later supports this action. Open vSwitch 2.8 added
757 support for multiple VLAN tags (with a limit of 2) and 802.1ad S-tags.
758 The push_mpls action
760 Syntax:
761 push_mpls:ethertype
762 Pushes a new outermost MPLS label stack entry (LSE) onto the packet and
764 changes the packet’s Ethertype to ethertype, which must be either
765 B0x8847 or 0x8848.
766 If the packet did not already contain any MPLS labels, initializes the
768 new LSE as:
769 Label 2, if the packet contains IPv6, 0 otherwise.
771 TC The low 3 bits of the packet’s DSCP value, or 0 if the
773 packet is not IP.
774 TTL Copied from the IP TTL, or 64 if the packet is not IP.
776 If the packet did already contain an MPLS label, initializes the new
778 outermost label as a copy of the existing outermost label.
779 OVS currently supports at most 3 MPLS labels.
781 This action applies only to Ethernet packets.
783 Conformance:
785 Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later
787 support push_mpls. Open vSwitch implements push_mpls as an extension to
788 OpenFlow 1.0.
789 The pop_mpls action
791 Syntax:
792 pop_mpls:ethertype
793 Strips the outermost MPLS label stack entry and changes the packet’s
795 Ethertype to ethertype.
796 This action applies only to Ethernet packets with at least one MPLS
798 label. If there is more than one MPLS label, then ethertype should be
799 an MPLS Ethertype (B0x8847 or 0x8848).
800 Conformance:
802 Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later
804 support pop_mpls. Open vSwitch implements pop_mpls as an extension to
805 OpenFlow 1.0.
806 The encap action
808 Syntax:
809 encap(nsh([md_type=md_type], [tlv(class,type,value)]...))
810 encap(ethernet)
811 The encap action encapsulates a packet with a specified header. It has
813 variants for different kinds of encapsulation.
814 The encap(nsh(...)) variant encapsulates an Ethernet frame with NSH.
816 The md_type may be 1 or 2 for metadata type 1 or 2, defaulting to 1.
817 For metadata type 2, TLVs may be specified with class as a 16-bit hexa‐
818 decimal integer beginning with 0x, type as an 8-bit decimal integer,
819 and value a sequence of pairs of hex digits beginning with 0x. For
820 example:
821 encap(nsh(md_type=1))
823 Encapsulates the packet with an NSH header with metadata
824 type 1.
825 encap(nsh(md_type=2,tlv(0x1000,10,0x12345678)))
827 Encapsulates the packet with an NSH header, NSH metadata
828 type 2, and an NSH TLV with class 0x1000, type 10, and
829 the 4-byte value 0x12345678.
830 The encap(ethernet) variant encapsulate a bare L3 packet in an Ethernet
832 frame. The Ethernet type is initialized to the L3 packet’s type, e.g.
833 0x0800 if the L3 packet is IPv4. The Ethernet source and destination
834 are initially zeroed.
835 Conformance:
837 This action is an Open vSwitch extension to OpenFlow 1.3 and later,
839 introduced in Open vSwitch 2.8.
840 The decap action
842 Syntax:
843 decap
844 Removes an outermost encapsulation from the packet:
846 · If the packet is an Ethernet packet, removes the Ethernet
848 header, which changes the packet into a bare L3 packet.
849 If the packet has VLAN tags, raises an unsupported packet
850 type error (see ``Error Handling’’, above).
851 · Otherwise, if the packet is an NSH packet, removes the
853 NSH header, revealing the inner packet. Open vSwitch sup‐
854 ports Ethernet, IPv4, IPv6, and NSH inner packet types.
855 Other types raise unsupported packet type errors.
856 · Otherwise, raises an unsupported packet type error.
858 Conformance:
860 This action is an Open vSwitch extension to OpenFlow 1.3 and later,
862 introduced in Open vSwitch 2.8.
864 These actions modify packet data and metadata fields.
865 The set_field and load actions
867 Syntax:
868 set_field:value[/mask]->dst
869 load:value->dst
870 These actions loads a literal value into a field or part of a field.
872 The set_field action takes value in the customary syntax for field dst,
873 e.g. 00:11:22:33:44:55 for an Ethernet address, and dst as the field’s
874 name. The optional mask allows part of a field to be set.
875 The load action takes value as an integer value (in decimal or prefixed
877 by 0x for hexadecimal) and dst as a field or subfield in the syntax
878 described under ``Field Specifications’’ above.
879 The following all set the Ethernet source address to 00:11:22:33:44:55:
881 · set_field:00:11:22:33:44:55->eth_src
883 · load:0x001122334455->eth_src
885 · load:0x001122334455->OXM_OF_ETH_SRC[]
887 The following all set the multicast bit in the Ethernet destination
889 address:
890 · set_field:01:00:00:00:00:00/01:00:00:00:00:00->eth_dst
892 · load:1->eth_dst[40]
894 Open vSwitch prohibits a set_field or load action whose dst is not
896 guaranteed to be part of the packet; for example, set_field of nw_dst
897 is only allowed in a flow that matches on Ethernet type 0x800. In some
898 cases, such as in an action set, Open vSwitch can’t statically check
899 that dst is part of the packet, and in that case if it is not then Open
900 vSwitch treats the action as a no-op.
901 Conformance:
903 Open vSwitch 1.1 introduced NXAST_REG_LOAD as a extension to OpenFlow
905 1.0 and used load to express it. Later, OpenFlow 1.2 introduced a stan‐
906 dard OFPAT_SET_FIELD action that was restricted to loading entire
907 fields, so Open vSwitch added the form set_field with this restriction.
908 OpenFlow 1.5 extended OFPAT_SET_FIELD to the point that it became a
909 superset of NXAST_REG_LOAD. Open vSwitch translates either syntax as
910 necessary for the OpenFlow version in use: in OpenFlow 1.0 and 1.1,
911 NXAST_REG_LOAD; in OpenFlow 1.2, 1.3, and 1.4, NXAST_REG_LOAD for load
912 or for loading a subfield, OFPAT_SET_FIELD otherwise; and OpenFlow 1.5
913 and later, OFPAT_SET_FIELD.
914 The move action
916 Syntax:
917 move:src->dst
918 Copies the named bits from field or subfield src to field or subfield
920 dst. src and dst should fields or subfields in the syntax described
921 under ``Field Specifications’’ above. The two fields or subfields must
922 have the same width.
923 Examples:
925 · move:reg0[0..5]->reg1[26..31] copies the six bits num‐
927 bered 0 through 5 in register 0 into bits 26 through 31
928 of register 1.
929 · move:reg0[0..15]->vlan_tci copies the least significant
931 16 bits of register 0 into the VLAN TCI field.
932 Conformance:
934 In OpenFlow 1.0 through 1.4, move ordinarily uses an Open vSwitch
936 extension to OpenFlow. In OpenFlow 1.5, move uses the OpenFlow 1.5
937 standard OFPAT_COPY_FIELD action. The ONF has also made
938 OFPAT_COPY_FIELD available as an extension to OpenFlow 1.3. Open
939 vSwitch 2.4 and later understands this extension and uses it if a con‐
940 troller uses it, but for backward compatibility with older versions of
941 Open vSwitch, ovs-ofctl does not use it.
942 The mod_dl_src and mod_dl_dst actions
944 Syntax:
945 mod_dl_src:mac
946 mod_dl_dst:mac
947 Sets the Ethernet source or destination address, respectively, to mac,
949 which should be expressed in the form xx:xx:xx:xx:xx:xx.
950 For L3-only packets, that is, those that lack an Ethernet header, this
952 action has no effect.
953 Conformance:
955 OpenFlow 1.0 and 1.1 have specialized actions for these purposes. Open‐
957 Flow 1.2 and later do not, so Open vSwitch translates them to appropri‐
958 ate OFPAT_SET_FIELD actions for those versions,
959 The mod_nw_src and mod_nw_dst actions
961 Syntax:
962 mod_nw_src:ip
963 mod_nw_dst:ip
964 Sets the IPv4 source or destination address, respectively, to ip, which
966 should be expressed in the form w.x.y.z.
967 In OpenFlow 1.1 and later, consistency rules allow these actions only
969 in a flow that matches only packets that contain an IPv4 header (or
970 following an action that adds an IPv4 header, e.g. pop_mpls:0x0800).
971 See ``Inconsistencies’’, above, for more information.
972 Conformance:
974 OpenFlow 1.0 and 1.1 have specialized actions for these purposes. Open‐
976 Flow 1.2 and later do not, so Open vSwitch translates them to appropri‐
977 ate OFPAT_SET_FIELD actions for those versions,
978 The mod_nw_tos and mod_nw_ecn actions
980 Syntax:
981 mod_nw_tos:tos
982 mod_nw_ecn:ecn
983 The mod_nw_tos action sets the DSCP bits in the IPv4 ToS/DSCP or IPv6
985 traffic class field to tos, which must be a multiple of 4 between 0 and
986 255. This action does not modify the two least significant bits of the
987 ToS field (the ECN bits).
988 The mod_nw_ecn action sets the ECN bits in the IPv4 ToS or IPv6 traffic
990 class field to ecn, which must be a value between 0 and 3, inclusive.
991 This action does not modify the six most significant bits of the field
992 (the DSCP bits).
993 In OpenFlow 1.1 and later, consistency rules allow these actions only
995 in a flow that matches only packets that contain an IPv4 or IPv6 header
996 (or following an action that adds such a header). See ``Inconsisten‐
997 cies’’, above, for more information.
998 Conformance:
1000 OpenFlow 1.0 has a mod_nw_tos action but not mod_nw_ecn. Open vSwitch
1002 implements the latter in OpenFlow 1.0 as an extension using
1003 NXAST_REG_LOAD. OpenFlow 1.1 has specialized actions for these pur‐
1004 poses. OpenFlow 1.2 and later do not, so Open vSwitch translates them
1005 to appropriate OFPAT_SET_FIELD actions for those versions,
1006 The mod_tp_src and mod_tp_dst actions
1008 Syntax:
1009 mod_tp_src:port
1010 mod_tp_dst:port
1011 Sets the TCP or UDP or SCTP source or destination port, respectively,
1013 to port. Both IPv4 and IPv6 are supported.
1014 In OpenFlow 1.1 and later, consistency rules allow these actions only
1016 in a flow that matches only packets that contain a TCP or UDP or SCTP
1017 header. See ``Inconsistencies’’, above, for more information.
1018 Conformance:
1020 OpenFlow 1.0 and 1.1 have specialized actions for these purposes. Open‐
1022 Flow 1.2 and later do not, so Open vSwitch translates them to appropri‐
1023 ate OFPAT_SET_FIELD actions for those versions,
1024 The dec_ttl action
1026 Syntax:
1027 dec_ttl
1028 dec_ttl(id1, [id2]...)
1029 Decrement TTL of IPv4 packet or hop limit of IPv6 packet. If the TTL or
1031 hop limit is initially 0 or 1, no decrement occurs, as packets reaching
1032 TTL zero must be rejected. Instead, Open vSwitch sends a ``packet-in’’
1033 message with reason code OFPR_INVALID_TTL to each connected controller
1034 that has enabled receiving such messages, and stops processing the cur‐
1035 rent set of actions. (However, if the current set of actions was
1036 reached through resubmit, the remaining actions in outer levels resume
1037 processing.)
1038 As an Open vSwitch extension to OpenFlow, this action supports the
1040 ability to specify a list of controller IDs. Open vSwitch will only
1041 send the message to controllers with the given ID or IDs. Specifying no
1042 list is equivalent to specifying a single controller ID of zero.
1043 Sets the TCP or UDP or SCTP source or destination port, respectively,
1045 to port. Both IPv4 and IPv6 are supported.
1046 In OpenFlow 1.1 and later, consistency rules allow these actions only
1048 in a flow that matches only packets that contain an IPv4 or IPv6
1049 header. See ``Inconsistencies’’, above, for more information.
1050 Conformance:
1052 All versions of OpenFlow and Open vSwitch support this action.
1054 The set_mpls_label, set_mpls_tc, and set_mpls_ttl actions
1056 Syntax:
1057 set_mpls_label:label
1058 set_mpls_tc:tc
1059 set_mpls_ttl:ttl
1060 The set_mpls_label action sets the label of the packet’s outer MPLS
1062 label stack entry. label should be a 20-bit value that is decimal by
1063 default; use a 0x prefix to specify the value in hexadecimal.
1064 The set_mpls_tc action sets the traffic class of the packet’s outer
1066 MPLS label stack entry. tc should be in the range 0 to 7, inclusive.
1067 The set_mpls_ttl action sets the TTL of the packet’s outer MPLS label
1069 stack entry. ttl should be in the range 0 to 255 inclusive.
1070 In OpenFlow 1.1 and later, consistency rules allow these actions only
1072 in a flow that matches only packets that contain an MPLS label (or fol‐
1073 lowing an action that adds an MPLS label, e.g. push_mpls:0x8847). See
1074 ``Inconsistencies’’, above, for more information.
1075 Conformance:
1077 OpenFlow 1.0 does not support MPLS, but Open vSwitch implements these
1079 actions as extensions. OpenFlow 1.1 has specialized actions for these
1080 purposes. OpenFlow 1.2 and later do not, so Open vSwitch translates
1081 them to appropriate OFPAT_SET_FIELD actions for those versions,
1082 The dec_mpls_ttl and dec_nsh_ttl actions
1084 Syntax:
1085 dec_mpls_ttl
1086 dec_nsh_ttl
1087 These actions decrement the TTL of the packet’s outer MPLS label stack
1089 entry or its NSH header, respectively. If the TTL is initially 0 or 1,
1090 no decrement occurs. Instead, Open vSwitch sends a ``packet-in’’ mes‐
1091 sage with reason code BOFPR_INVALID_TTL to OpenFlow controllers with ID
1092 0, if it has enabled receiving them. Processing the current set of
1093 actions then stops. (However, if the current set of actions was reached
1094 through resubmit, remaining actions in outer levels resume processing.)
1095 In OpenFlow 1.1 and later, consistency rules allow this actions only in
1097 a flow that matches only packets that contain an MPLS label or an NSH
1098 header, respectively. See ``Inconsistencies’’, above, for more informa‐
1099 tion.
1100 Conformance:
1102 Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later
1104 support dec_mpls_ttl. Open vSwitch implements dec_mpls_ttl as an exten‐
1105 sion to OpenFlow 1.0.
1106 Open vSwitch 2.8 introduced support for NSH, although the NSH draft
1108 changed after release so that only Open vSwitch 2.9 and later conform
1109 to the final protocol specification. The dec_nsh_ttl action and NSH
1110 support in general is an Open vSwitch extension not supported by any
1111 version of OpenFlow.
1112 The check_pkt_larger action
1114 Syntax:
1115 check_pkt_larger(pkt_len)->dst
1116 Checks if the packet is larger than the specified length in pkt_len. If
1118 so, stores 1 in dst, which should be a 1-bit field; if not, stores 0.
1119 The packet length to check againt the argument pkt_len includes the L2
1121 header and L2 payload of the packet, but not the VLAN tag (if present).
1122 Examples:
1124 · check_pkt_larger(1500)->reg0[0]
1126 · check_pkt_larger(8000)->reg9[10]
1128 This action was added in Open vSwitch 2.11.90.
1130
1132 The set_tunnel action
1133 Syntax:
1134 set_tunnel:id
1135 set_tunnel64:id
1136 Many kinds of tunnels support a tunnel ID, e.g. VXLAN and Geneve have a
1138 24-bit VNI, and GRE has an optional 32-bit key. This action sets the
1139 value used for tunnel ID in such tunneled packets, although whether it
1140 is used for a particular tunnel depends on the tunnel’s configuration.
1141 See the tunnel ID documentation in ovs-fields(7) for more information.
1142 Conformance:
1144 These actions are OpenFlow extensions. set_tunnel was introduced in
1146 Open vSwitch 1.0. set_tunnel64, which is needed if id is wider than 32
1147 bits, was added in Open vSwitch 1.1. Both actions always set the entire
1148 tunnel ID field.
1149 Open vSwitch supports these actions in all versions of OpenFlow, but in
1151 OpenFlow 1.2 and later it translates them to an appropriate standard‐
1152 ized OFPAT_SET_FIELD action.
1153 The set_queue and pop_queue actions
1155 Syntax:
1156 set_queue:queue
1157 pop_queue
1158 The set_queue action sets the queue ID to be used for subsequent output
1160 actions to queue, which must be a 32-bit integer. The range of meaning‐
1161 ful values of queue, and their meanings, varies greatly from one Open‐
1162 Flow implementation to another. Even within a single implementation,
1163 there is no guarantee that all OpenFlow ports have the same queues con‐
1164 figured or that all OpenFlow ports in an implementation can be config‐
1165 ured the same way queue-wise. For more information, see the documenta‐
1166 tion for the output queue field in ovs-fields(7).
1167 The pop_queue restores the output queue to the default that was set
1169 when the packet entered the switch (generally 0).
1170 Four billion queues ought to be enough for anyone: ⟨https://
1172 mailman.stanford.edu/pipermail/openflow-spec/2009-August/000394.html⟩
1173 Conformance:
1175 OpenFlow 1.1 introduced the set_queue action. Open vSwitch also sup‐
1177 ports it as an extension in OpenFlow 1.0.
1178 The pop_queue action is an Open vSwitch extension.
1180
1182 Open vSwitch is often used to implement a firewall. The preferred way
1183 to implement a firewall is ``connection tracking,’’ that is, to keep
1184 track of the connection state of individual TCP sessions. The ct action
1185 described in this section, added in Open vSwitch 2.5, implements con‐
1186 nection tracking. For new deployments, it is the recommended way to
1187 implement firewalling with Open vSwitch.
1188 Before ct was added, Open vSwitch did not have built-in support for
1190 connection tracking. Instead, Open vSwitch supported the learn action,
1191 which allows a received packet to add a flow to an OpenFlow flow table.
1192 This could be used to implement a primitive form of connection track‐
1193 ing: packets passing through the firewall in one direction could create
1194 flows that allowed response packets back through the firewall in the
1195 other direction. The additional fin_timeout action allowed the learned
1196 flows to expire quickly after TCP session termination.
1197 The ct action
1199 Syntax:
1200 ct(argument]...)
1201 ct(commit[, argument]...)
1202 The action has two modes of operation, distinguished by whether commit
1204 is present. The following arguments may be present in either mode:
1205 zone=value
1207 A zone is a 16-bit id that isolates connections into sep‐
1208 arate domains, allowing overlapping network addresses in
1209 different zones. If a zone is not provided, then the
1210 default is 0. The value may be specified either as a
1211 16-bit integer literal or a field or subfield in the syn‐
1212 tax described under ``Field Specifications’’ above.
1213 Without commit, this action sends the packet through the connection
1215 tracker. The connection tracker keeps track of the state of TCP connec‐
1216 tions for packets passed through it. For each packet through a connec‐
1217 tion, it checks that it satisfies TCP invariants and signals the con‐
1218 nection state to later actions using the ct_state metadata field, which
1219 is documented in ovs-fields(7).
1220 In this form, ct forks the OpenFlow pipeline:
1222 · In one fork, ct passes the packet to the connection
1224 tracker. Afterward, it reinjects the packet into the
1225 OpenFlow pipeline with the connection tracking fields
1226 initialized. The ct_state field is initialized with con‐
1227 nection state and ct_zone to the connection tracking zone
1228 specified on the zone argument. If the connection is one
1229 that is already tracked, ct_mark and ct_label to its
1230 existing mark and label, respectively; otherwise they are
1231 zeroed. In addition, ct_nw_proto, ct_nw_src, ct_nw_dst,
1232 ct_ipv6_src, ct_ipv6_dst, ct_tp_src, and ct_tp_dst are
1233 initialized appropriately for the original direction con‐
1234 nection. See the resubmit action for a way to search the
1235 flow table with the connection tracking original direc‐
1236 tion fields swapped with the packet 5-tuple fields. See
1237 ovs-fields(7) for details on the connection tracking
1238 fields.
1239 · In the other fork, the original instance of the packet
1241 continues independent processing following the ct action.
1242 The ct_state field and other connection tracking metadata
1243 are cleared.
1244 Without commit, the ct action accepts the following arguments:
1246 table=table
1248 Sets the OpenFlow table where the packet is reinjected.
1249 The table must be a number between 0 and 254 inclusive,
1250 or a table’s name. If table is not specified, then the
1251 packet is not reinjected.
1252 nat
1254 nat(type=addrs[:ports][,flag]...)
1255 Specify address and port translation for the connection
1256 being tracked. The type must be src, for source
1257 address/port translation (SNAT), or dst, for destination
1258 address/port translation (DNAT). Setting up address trans‐
1259 lation for a new connection takes effect only if the con‐
1260 nection is later committed with ct(commit...).
1261 The src and dst options take the following arguments:
1263 addrs The IP address addr or range addr1-addr2 from which
1265 the translated address should be selected. If only
1266 one address is given, then that address will always
1267 be selected, otherwise the address selection can be
1268 informed by the optional persistent flag as
1269 described below. Either IPv4 or IPv6 addresses can
1270 be provided, but both addresses must be of the same
1271 type, and the datapath behavior is undefined in case
1272 of providing IPv4 address range for an IPv6 packet,
1273 or IPv6 address range for an IPv4 packet. IPv6
1274 addresses must be bracketed with [ and ] if a port
1275 range is also given.
1276 ports The L4 port or range port1-port2 from which the
1278 translated port should be selected. When a port
1279 range is specified, fallback to ephemeral ports does
1280 not happen, else, it will. The port number selection
1281 can be informed by the optional random and hash
1282 flags described below. The userspace datapath only
1283 supports the hash behavior.
1284 The optional flags are:
1286 random The selection of the port from the given range
1288 should be done using a fresh random number. This
1289 flag is mutually exclusive with hash.
1290 hash The selection of the port from the given range
1292 should be done using a datapath specific hash of the
1293 packet’s IP addresses and the other, non-mapped port
1294 number. This flag is mutually exclusive with random.
1295 persistent
1297 The selection of the IP address from the given range
1298 should be done so that the same mapping can be pro‐
1299 vided after the system restarts.
1300 If alg is specified for the committing ct action that also
1302 includes nat with a src or dst attribute, then the datapath
1303 tries to set up the helper to be NAT-aware. This function‐
1304 ality is datapath specific and may not be supported by all
1305 datapaths.
1306 A ``bare’’ nat argument with no options will only translate
1308 the packet being processed in the way the connection has
1309 been set up with an earlier, committed ct action. A nat
1310 action with src or dst, when applied to a packet belonging
1311 to an established (rather than new) connection, will behave
1312 the same as a bare nat.
1313 Open vSwitch 2.6 introduced nat. Linux 4.6 was the earliest
1315 upstream kernel that implemented ct support for nat.
1316 With commit, the connection tracker commits the connection to the con‐
1318 nection tracking module. The commit flag should only be used from the
1319 pipeline within the first fork of ct without commit. Information about
1320 the connection is stored beyond the lifetime of the packet in the pipe‐
1321 line. Some ct_state flags are only available for committed connections.
1322 The following options are available only with commit:
1324 force A committed connection always has the directionality of
1326 the packet that caused the connection to be committed in
1327 the first place. This is the ``original direction’’ of
1328 the connection, and the opposite direction is the ``reply
1329 direction’’. If a connection is already committed, but it
1330 is in the wrong direction, force effectively terminates
1331 the existing connection and starts a new one in the cur‐
1332 rent direction. This flag has no effect if the original
1333 direction of the connection is already the same as that
1334 of the current packet.
1335 exec(action...)
1337 Perform each action within the context of connection
1338 tracking. Only actions which modify the ct_mark or
1339 ct_label fields are accepted within exec action, and
1340 these fields may only be modified with this option. For
1341 example:
1342 set_field:value[/mask]->ct_mark
1344 Store a 32-bit metadata value with the connection.
1345 Subsequent lookups for packets in this connection
1346 will populate ct_mark when the packet is sent to
1347 the connection tracker with the table specified.
1348 set_field:value[/mask]->ct_label
1350 Store a 128-bit metadata value with the connec‐
1351 tion. Subsequent lookups for packets in this con‐
1352 nection will populate ct_label when the packet is
1353 sent to the connection tracker with the table
1354 specified.
1355 alg=alg
1357 Specify application layer gateway alg to track specific
1358 connection types. If subsequent related connections are
1359 sent through the ct action, then the rel flag in the
1360 ct_state field will be set. Supported types include:
1361 ftp Look for negotiation of FTP data connections.
1363 Specify this option for FTP control connections to
1364 detect related data connections and populate the
1365 rel flag for the data connections.
1366 tftp Look for negotiation of TFTP data connections.
1368 Specify this option for TFTP control connections
1369 to detect related data connections and populate
1370 the rel flag for the data connections.
1371 Related connections inherit ct_mark from that stored with
1373 the original connection (i.e. the connection created by
1374 ct(alg=...)).
1375 With the Linux datapath, global sysctl options affect ct behavior. In
1377 particular, if net.netfilter.nf_conntrack_helper is enabled, which it
1378 is by default until Linux 4.7, then application layer gateway helpers
1379 may be executed even if alg is not specified. For security reasons, the
1380 netfilter team recommends users disable this option. For further
1381 details, please see ⟨http://www.netfilter.org/news.html#2012-04-03⟩ .
1382 The ct action may be used as a primitive to construct stateful fire‐
1384 walls by selectively committing some traffic, then matching ct_state to
1385 allow established connections while denying new connections. The fol‐
1386 lowing flows provide an example of how to implement a simple firewall
1387 that allows new connections from port 1 to port 2, and only allows
1388 established connections to send traffic from port 2 to port 1:
1389 table=0,priority=1,action=drop
1391 table=0,priority=10,arp,action=normal
1392 table=0,priority=100,ip,ct_state=-trk,action=ct(table=1)
1393 table=1,in_port=1,ip,ct_state=+trk+new,action=ct(commit),2
1394 table=1,in_port=1,ip,ct_state=+trk+est,action=2
1395 table=1,in_port=2,ip,ct_state=+trk+new,action=drop
1396 table=1,in_port=2,ip,ct_state=+trk+est,action=1
1397 If ct is executed on IPv4 (or IPv6) fragments, then the message is
1400 implicitly reassembled before sending to the connection tracker and
1401 refragmented upon output, to the original maximum received fragment
1402 size. Reassembly occurs within the context of the zone, meaning that IP
1403 fragments in different zones are not assembled together. Pipeline pro‐
1404 cessing for the initial fragments is halted. When the final fragment is
1405 received, the message is assembled and pipeline processing continues
1406 for that flow. Packet ordering is not guaranteed by IP protocols, so it
1407 is not possible to determine which IP fragment will cause message
1408 reassembly (and therefore continue pipeline processing). As such, it is
1409 strongly recommended that multiple flows should not execute ct to
1410 reassemble fragments from the same IP message.
1411 Conformance:
1413 The ct action was introduced in Open vSwitch 2.5. Some of its features
1415 were introduced later, noted individually above.
1416 The ct_clear action
1418 Syntax:
1419 ct_clear
1420 Clears connection tracking state from the flow, zeroing ct_state,
1422 ct_zone, ct_mark, and ct_label.
1423 This action was introduced in Open vSwitch 2.6.90.
1425 The learn action
1427 Syntax:
1428 learn(argument...)
1429 The learn action adds or modifies a flow in an OpenFlow table, similar
1431 to ovs-ofctl --strict mod-flows. The arguments specify the match
1432 fields, actions, and other properties of the flow to be added or modi‐
1433 fied.
1434 Match fields for the new flow are specified as follows. At least one
1436 match field should ordinarily be specified:
1437 field=value
1439 Specifies that field, in the new flow, must match the
1440 literal value, e.g. dl_type=0x800. Shorthand match syn‐
1441 tax, such as ip in place of dl_type=0x800, is not sup‐
1442 ported.
1443 field=src
1445 Specifies that field in the new flow must match src taken
1446 from the packet currently being processed. For example,
1447 udp_dst=udp_src, applied to a UDP packet with source port
1448 53, creates a flow which matches udp_dst=53. field and
1449 src must have the same width.
1450 field Shorthand for the previous form when field and src are
1452 the same. For example, udp_dst, applied to a UDP packet
1453 with destination port 53, creates a flow which matches
1454 udp_dst=53.
1455 The field and src arguments above should be fields or subfields in the
1457 syntax described under ``Field Specifications’’ above.
1458 Match field specifications must honor prerequisites for both the flow
1460 with the learn and the new flow that it creates. Consider the following
1461 complete flow, in the syntax accepted by ovs-ofctl. If the flow’s match
1462 on udp were omitted, then the flow would not satisfy the prerequisites
1463 for the learn action’s use of udp_src. If dl_type=0x800 or nw_proto
1464 were omitted from learn, then the new flow would not satisfy the pre‐
1465 requisite for its match on udp_dst. For more information on prerequi‐
1466 sites, please refer to ovs-fields(7):
1467 udp, actions=learn(dl_type=0x800, nw_proto=17, udp_dst=udp_src)
1469 Actions for the new flow are specified as follows. At least one action
1472 should ordinarily be specified:
1473 load:value->dst
1475 Adds a load action to the new flow that loads the literal
1476 value into dst. The syntax is the same as the load action
1477 explained in the ``Header Modification’’ section.
1478 load:src->dst
1480 Adds a load action to the new flow that loads src, a
1481 field or subfield from the packet being processed, into
1482 dst.
1483 output:field
1485 Adds an output action to the new flow’s actions that out‐
1486 puts to the OpenFlow port taken from field, which must be
1487 a field as described above.
1488 fin_idle_timeout=seconds
1490 fin_hard_timeout=seconds
1491 Adds a fin_timeout action with the specified arguments to
1492 the new flow. This feature was added in Open vSwitch
1493 1.5.90.
1494 The following additional arguments are optional:
1496 idle_timeout=seconds
1498 hard_timeout=seconds
1499 priority=value
1500 cookie=value
1501 send_flow_rem
1502 These arguments have the same meaning as in the usual flow
1503 syntax documented in ovs-ofctl(8).
1504 table=table
1506 The table in which the new flow should be inserted. Specify
1507 a decimal number between 0 and 254 inclusive or the name of
1508 a table. The default, if table is unspecified, is table 1
1509 (not 0).
1510 delete_learned
1512 When this flag is specified, deleting the flow that con‐
1513 tains the learn action will also delete the flows created
1514 by learn. Specifically, when the last learn action with
1515 this flag and particular table and cookie values is
1516 removed, the switch deletes all of the flows in the speci‐
1517 fied table with the specified cookie.
1518 This flag was added in Open vSwitch 2.4.
1520 limit=number
1522 If the number of flows in the new flow’s table with the
1523 same cookie exceeds number, the action will not add a new
1524 flow. By default, or with limit=0, there is no limit.
1525 This flag was added in Open vSwitch 2.8.
1527 result_dst=field[bit]
1529 If learn fails (because the number of flows exceeds limit),
1530 the action sets field[bit] to 0, otherwise it will be set
1531 to 1. field[bit] must be a single bit.
1532 This flag was added in Open vSwitch 2.8.
1534 By itself, the learn action can only put two kinds of actions into the
1536 flows that it creates: load and output actions. If learn is used in
1537 isolation, these are severe limits.
1538 However, learn is not meant to be used in isolation. It is a primitive
1540 meant to be used together with other Open vSwitch features to accom‐
1541 plish a task. Its existing features are enough to accomplish most
1542 tasks.
1543 Here is an outline of a typical pipeline structure that allows for ver‐
1545 satile behavior using learn:
1546 · Flows in table A contain a learn action, that populates
1548 flows in table L, that use a load action to populate reg‐
1549 ister R with information about what was learned.
1550 · Flows in table B contain two sequential resubmit actions:
1552 one to table L and another one to table B+1.
1553 · Flows in table B+1 match on register R and act differ‐
1555 ently depending on what the flows in table L loaded into
1556 it.
1557 This approach can be used to implement many learn-based features. For
1559 example:
1560 · Resubmit to a table selected based on learned informa‐
1562 tion, e.g. see ⟨https://mail.openvswitch.org/pipermail/
1563 ovs-discuss/2016-June/021694.html⟩ .
1564 · MAC learning in the middle of a pipeline, as described in
1566 the ``Open vSwitch Advanced Features Tutorial’’ in the
1567 OVS documentation.
1568 · TCP state based firewalling, by learning outgoing connec‐
1570 tions based on SYN packets and matching them up with
1571 incoming packets. (This is usually better implemented
1572 using the ct action.)
1573 · At least some of the features described in T. A. Hoff,
1575 ``Extending Open vSwitch to Facilitate Creation of State‐
1576 ful SDN Applications’’.
1577 Conformance:
1579 The learn action is an Open vSwitch extension to OpenFlow added in Open
1581 vSwitch 1.3. Some features of learn were added in later versions, as
1582 noted individually above.
1583 The fin_timeout action
1585 Syntax:
1586 fin_timeout(key=value...)
1587 This action changes the idle timeout or hard timeout, or both, of the
1589 OpenFlow flow that contains it, when the flow matches a TCP packet with
1590 the FIN or RST flag. When such a packet is observed, the action reduces
1591 the rule’s timeouts to those specified on the action. If the rule’s
1592 existing timeout is already shorter than the one that the action speci‐
1593 fies, then that timeout is unaffected.
1594 The timeouts are specified as key-value pairs:
1596 idle_timeout=seconds
1598 Causes the flow to expire after the given number of sec‐
1599 onds of inactivity.
1600 hard_timeout=seconds
1602 Causes the flow to expire after the given number of sec‐
1603 onds, regardless of activity. (seconds specifies time
1604 since the flow’s creation, not since the receipt of the
1605 FIN or RST.)
1606 This action is normally added to a learned flow by the learn action. It
1608 is unlikely to be useful otherwise.
1609 Conformance:
1611 This Open vSwitch extension action was added in Open vSwitch 1.5.90.
1613
1615 The resubmit action
1616 Syntax:
1617 resubmit:port
1618 resubmit([port],[table][,ct])
1619 Searches an OpenFlow flow table for a matching flow and executes the
1621 actions found, if any, before continuing to the following action in the
1622 current flow entry. Arguments can customize the search:
1623 · If port is given as an OpenFlow port number or name, then
1625 it specifies a value to use for the input port metadata
1626 field as part of the search, in place of the input port
1627 currently in the flow. Specifying in_port as port is
1628 equivalent to omitting it.
1629 · If table is given as an integer between 0 and 254 or a
1631 table name, it specifies the OpenFlow table to search. If
1632 it is not specified, the table from the current flow is
1633 used.
1634 · If ct is specified, then the search is done with packet
1636 5-tuple fields swapped with the corresponding conntrack
1637 original direction tuple fields. See the documentation
1638 for ct above, for more information about connection
1639 tracking, or ovs-fields(7) for details about the connec‐
1640 tion tracking fields.
1641 This flag requires a valid connection tracking state as a
1643 match prerequisite in the flow where this action is
1644 placed. Examples of valid connection tracking state
1645 matches include ct_state=+new, ct_state=+est,
1646 ct_state=+rel, and ct_state=+trk-inv.
1647 The changes, if any, to the input port and connection tracking fields
1649 are just for searching the flow table. The changes are not visible to
1650 actions or to later flow table lookups.
1651 The most common use of resubmit is to visit another flow table without
1653 port or ct, like this: resubmit(,table).
1654 Recursive resubmit actions are permitted.
1656 Conformance:
1658 The resubmit action is an Open vSwitch extension. However, the goto_ta‐
1660 ble instruction in OpenFlow 1.1 and later can be viewed as a kind of
1661 restricted resubmit.
1662 Open vSwitch 1.2.90 added table. Open vSwitch 2.7 added ct.
1664 Open vSwitch imposes a limit on resubmit recursion that varies among
1666 version:
1667 · Open vSwitch 1.0.1 and earlier did not support recursion.
1669 · Open vSwitch 1.0.2 and 1.0.3 limited recursion to 8 lev‐
1671 els.
1672 · Open vSwitch 1.1 and 1.2 limited recursion to 16 levels.
1674 · Open vSwitch 1.2 through 1.8 limited recursion to 32 lev‐
1676 els.
1677 · Open vSwitch 1.9 through 2.0 limited recursion to 64 lev‐
1679 els.
1680 · Open vSwitch 2.1 through 2.5 limited recursion to 64 lev‐
1682 els and impose a total limit of 4,096 resubmits per flow
1683 translation (earlier versions did not impose any total
1684 limit).
1685 · Open vSwitch 2.6 and later imposes the same limits as
1687 2.5, with one exception: resubmit from table x to any ta‐
1688 ble y > x does not count against the recursion depth
1689 limit.
1690 The clone action
1692 Syntax:
1693 clone(action...)
1694 Executes each nested action, saving much of the packet and pipeline
1696 state beforehand and then restoring it afterward. The state that is
1697 saved and restored includes all flow data and metadata (including, for
1698 example, in_port and ct_state), the stack accessed by push and pop
1699 actions, and the OpenFlow action set.
1700 This action was added in Open vSwitch 2.6.90.
1702 The push and pop actions
1704 Syntax:
1705 push:src
1706 pop:dst
1707 The push action pushes src on a general-purpose stack. The pop action
1709 pops an entry off the stack into dst. src and dst should be fields or
1710 subfields in the syntax described under ``Field Specifications’’ above.
1711 Controllers can use the stack for saving and restoring data or metadata
1713 around resubmit actions, for swapping or rearranging data and metadata,
1714 or for other purposes. Any data or metadata field, or part of one, may
1715 be pushed, and any modifiable field or subfield may be popped.
1716 The number of bits pushed in a stack entry do not have to match the
1718 number of bits later popped from that entry. If more bits are popped
1719 from an entry than were pushed, then the entry is conceptually left-
1720 padded with 0-bits as needed. If fewer bits are popped than pushed,
1721 then bits are conceptually trimmed from the left side of the entry.
1722 The stack’s size is limited. The limit is intended to be high enough
1724 that ``normal’’ use will not pose problems. Stack overflow or underflow
1725 is an error that stops action execution (see ``Stack too deep’’ under
1726 ``Error Handling’’, above).
1727 Examples:
1729 · push:reg2[0..5] or push:NXM_NX_REG2[0..5] pushes on the
1731 stack the 6 bits in register 2 bits 0 through 5.
1732 · pop:reg2[0..5] or pop:NXM_NX_REG2[0..5] pops the value
1734 from top of the stack and copy bits 0 through 5 of that
1735 value into bits 0 through 5 of register 2.
1736 Conformance:
1738 Open vSwitch 1.2 introduced push and pop as OpenFlow extension actions.
1740 The exit action
1742 Syntax:
1743 exit
1744 This action causes Open vSwitch to immediately halt execution of fur‐
1746 ther actions. Actions which have already been executed are unaffected.
1747 Any further actions, including those which may be in other tables, or
1748 different levels of the resubmit call stack, are ignored. However, an
1749 exit action within a group bucket terminates only execution of that
1750 bucket, not other buckets or the overall pipeline. Actions in the
1751 action set are still executed (specify clear_actions before exit to
1752 discard them).
1753 The multipath action
1755 Syntax:
1756 multipath(fields, basis, algorithm, n_links, arg, dst)
1757 Hashes fields using basis as a universal hash parameter, then the
1759 applies multipath link selection algorithm (with parameter arg) to
1760 choose one of n_links output links numbered 0 through n_links minus 1,
1761 and stores the link into dst, which must be a field or subfield in the
1762 syntax described under ``Field Specifications’’ above.
1763 The bundle or bundle_load actions are usually easier to use than multi‐
1765 path.
1766 fields must be one of the following:
1768 eth_src
1770 Hashes Ethernet source address only.
1771 symmetric_l4
1773 Hashes Ethernet source, destination, and type, VLAN ID,
1774 IPv4/IPv6 source, destination, and protocol, and TCP or
1775 SCTP (but not UDP) ports. The hash is computed so that
1776 pairs of corresponding flows in each direction hash to
1777 the same value, in environments where L2 paths are the
1778 same in each direction. UDP ports are not included in the
1779 hash to support protocols such as VXLAN that use asymmet‐
1780 ric ports in each direction.
1781 symmetric_l3l4
1783 Hashes IPv4/IPv6 source, destination, and protocol, and
1784 TCP or SCTP (but not UDP) ports. Like symmetric_l4, this
1785 is a symmetric hash, but by excluding L2 headers it is
1786 more effective in environments with asymmetric L2 paths
1787 (e.g. paths involving VRRP IP addresses on a router). Not
1788 an effective hash function for protocols other than IPv4
1789 and IPv6, which hash to a constant zero.
1790 symmetric_l3l4+udp
1792 Like symmetric_l3l4+udp, but UDP ports are included in
1793 the hash. This is a more effective hash when asymmetric
1794 UDP protocols such as VXLAN are not a consideration.
1795 symmetric_l3
1797 Hashes network source address and network destination
1798 address.
1799 nw_src Hashes network source address only.
1801 nw_dst Hashes network destination address only.
1803 The algorithm used to compute the final result link must be one of the
1805 following:
1806 modulo_n
1808 Computes link = hash(flow) % n_links.
1809 This algorithm redistributes all traffic when n_links
1811 changes. It has O(1) performance.
1812 Use 65535 for max_link to get a raw hash value.
1814 This algorithm is specified by RFC 2992.
1816 hash_threshold
1818 Computes link = hash(flow) / (MAX_HASH / n_links).
1819 Redistributes between one-quarter and one-half of traffic
1821 when n_links changes. It has O(1) performance.
1822 This algorithm is specified by RFC 2992.
1824 hrw (Highest Random Weight)
1826 Computes the following:
1827 for i in [0,n_links]:
1829 weights[i] = hash(flow, i)
1830 link = { i such that weights[i] >= weights[j] for all j != i }
1831 Redistributes 1/n_links of traffic when n_links changes.
1834 It has O(n_links) performance. If n_links is greater than
1835 a threshold (currently 64, but subject to change), Open
1836 vSwitch will substitute another algorithm automatically.
1837 This algorithm is specified by RFC 2992.
1839 iter_hash (Iterative Hash)
1841 Computes the following:
1842 i = 0
1844 repeat:
1845 i = i + 1
1846 link = hash(flow, i) % arg
1847 while link > max_link
1848 Redistributes 1/n_links of traffic when n_links changes.
1851 O(1) performance when arg/max_link is bounded by a con‐
1852 stant.
1853 Redistributes all traffic when arg changes.
1855 arg must be greater than max_link and for best perfor‐
1857 mance should be no more than approximately max_link * 2.
1858 If arg is outside the acceptable range, Open vSwitch will
1859 automatically substitute the least power of 2 greater
1860 than max_link.
1861 This algorithm is specific to Open vSwitch.
1863 Only the iter_hash algorithm uses arg.
1865 It is an error if max_link is greater than or equal to 2**n_bits.
1867 Conformance:
1869 This is an OpenFlow extension added in Open vSwitch 1.1.
1871
1873 The conjunction action
1874 Syntax:
1875 conjunction(id, k/n)
1876 This action allows for sophisticated ``conjunctive match’’ flows. Refer
1878 to ``Conjunctive Match Fields’’ in ovs-fields(7) for details.
1879 A flow that has one or more conjunction actions may not have any other
1881 actions except for note actions.
1882 Conformance:
1884 Open vSwitch 2.4 introduced the conjunction action and conj_id field.
1886 They are Open vSwitch extensions to OpenFlow.
1887 The note action
1889 Syntax:
1890 note:[hh]...
1891 This action does nothing at all. OpenFlow controllers may use it to
1893 annotate flows with more data than can fit in a flow cookie.
1894 The action may include any number of bytes represented as hex digits
1896 hh. Periods may separate pairs of hex digits, for readability. The note
1897 action’s format doesn’t include an exact length for its payload, so the
1898 provided bytes will be padded on the right by enough bytes with value 0
1899 to make the total number 6 more than a multiple of 8.
1900 Conformance:
1902 This action is an extension to OpenFlow introduced in Open vSwitch 1.1.
1904 The sample action
1906 Syntax:
1907 sample(argument...)
1908 Samples packets and sends one sample for every sampled packet.
1910 The following argument forms are accepted:
1912 probability=packets
1914 The number of sampled packets out of 65535. Must be
1915 greater or equal to 1.
1916 collector_set_id=id
1918 The unsigned 32-bit integer identifier of the set of sam‐
1919 ple collectors to send sampled packets to. Defaults to 0.
1920 obs_domain_id=id
1922 When sending samples to IPFIX collectors, the unsigned
1923 32-bit integer Observation Domain ID sent in every IPFIX
1924 flow record. Defaults to 0.
1925 obs_point_id=id
1927 When sending samples to IPFIX collectors, the unsigned
1928 32-bit integer Observation Point ID sent in every IPFIX
1929 flow record. Defaults to 0.
1930 sampling_port=port
1932 Sample packets on port, which should be the ingress or
1933 egress port. This option, which was added in Open vSwitch
1934 2.5.90, allows the IPFIX implementation to export egress
1935 tunnel information.
1936 ingress
1938 egress
1939 Specifies explicitly that the packet is being sampled on
1940 ingress to or egress from the switch. IPFIX reports sent by
1941 Open vSwitch before version 2.5.90 did not include a direc‐
1942 tion. From 2.5.90 until 2.6.90, IPFIX reports inferred a
1943 direction from sampling_port: if it was the packet’s output
1944 port, then the direction was reported as egress, otherwise
1945 as ingress. Open vSwitch 2.6.90 introduced these options,
1946 which allow the inferred direction to be overridden. This
1947 is particularly useful when the ingress (or egress) port is
1948 not a tunnel.
1949 Refer to ovs-vswitchd.conf.db(5) for more details on configuring sample
1951 collector sets.
1952 Conformance:
1954 This action is an OpenFlow extension added in Open vSwitch 2.4.
1956
1958 Every version of OpenFlow includes actions. OpenFlow 1.1 introduced the
1959 higher-level, related concept of instructions. In OpenFlow 1.1 and
1960 later, actions within a flow are always encapsulated within an instruc‐
1961 tion. Each flow has at most one instruction of each kind, which are
1962 executed in the following fixed order defined in the OpenFlow specifi‐
1963 cation:
1964 1. Meter
1966 2. Apply-Actions
1968 3. Clear-Actions
1970 4. Write-Actions
1972 5. Write-Metadata
1974 6. Stat-Trigger (not supported by Open vSwitch)
1976 7. Goto-Table
1978 The most important instruction is Apply-Actions. This instruction
1980 encapsulates any number of actions, which the instruction executes.
1981 Open vSwitch does not explicitly represent Apply-Actions. Instead, any
1982 action by itself is implicitly part of an Apply-Actions instructions.
1983 Open vSwitch syntax requires other instructions, if present, to be in
1985 the order listed above. Otherwise it will flag an error.
1986 The meter action and instruction
1988 Syntax:
1989 meter:meter_id
1990 Apply meter meter_id. If a meter band rate is exceeded, the packet may
1992 be dropped, or modified, depending on the meter band type.
1993 Conformance:
1995 OpenFlow 1.3 introduced the meter instruction. OpenFlow 1.5 changes
1997 meter from an instruction to an action.
1998 OpenFlow 1.5 allows implementations to restrict meter to be the first
2000 action in an action list and to exclude meter from action sets, for
2001 better compatibility with OpenFlow 1.3 and 1.4. Open vSwitch restricts
2002 the meter action both ways.
2003 Open vSwitch 2.0 introduced OpenFlow protocol support for meters, but
2005 it did not include a datapath implementation. Open vSwitch 2.7 added
2006 meter support to the userspace datapath. Open vSwitch 2.10 added meter
2007 support to the kernel datapath. Open vSwitch 2.12 added support for
2008 meter as an action in OpenFlow 1.5.
2009 The clear_actions instruction
2011 Syntax:
2012 clear_actions
2013 Clears the action set. See ``Action Sets’’, above, for more informa‐
2015 tion.
2016 Conformance:
2018 OpenFlow 1.1 introduced clear_actions. Open vSwitch 2.1 added support
2020 for clear_actions.
2021 The write_actions instruction
2023 Syntax:
2024 write_actions(action...)
2025 Adds each action to the action set. The action set is carried between
2027 flow tables and then executed at the end of the pipeline. Only certain
2028 actions may be written to the action set. See ``Action Sets’’, above,
2029 for more information.
2030 Conformance:
2032 OpenFlow 1.1 introduced write_actions. Open vSwitch 2.1 added support
2034 for write_actions.
2035 The write_metadata instruction
2037 Syntax:
2038 write_metadata:value[/mask]
2039 Updates the flow’s metadata field. If mask is omitted, metadata is set
2041 exactly to value; if mask is specified, then a 1-bit in mask indicates
2042 that the corresponding bit in metadata will be replaced with the corre‐
2043 sponding bit from value. Both value and mask are 64-bit values that are
2044 decimal by default; use a 0x prefix to specify them in hexadecimal.
2045 The metadata field can also be matched in the flow table and updated
2047 with actions such as set_field and move.
2048 Conformance:
2050 OpenFlow 1.1 introduced write_metadata. Open vSwitch 2.1 added support
2052 for write_metadata.
2053 The goto_table instruction
2055 Syntax:
2056 goto_table:table
2057 Jumps to table as the next table in the process pipeline. The table may
2059 be a number between 0 and 254 or a table name.
2060 It is an error if table is less than or equal to the table of the flow
2062 that contains it; that is, goto_table must move forward in the OpenFlow
2063 pipeline. Since goto_table must be the last instruction in a flow, it
2064 never leads to recursion. The resubmit extension action is more flexi‐
2065 ble.
2066 Conformance:
2068 OpenFlow 1.1 introduced goto_table. Open vSwitch 2.1 added support for
2070 goto_table.
2071Open vSwitch 2.12.0 ovs-actions(7)