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 Theoutputaction
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 Thecontrolleraction
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 Theenqueueaction
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 Thebundleandbundle_loadactions
612 Syntax:
613 bundle(fields, basis, algorithm, ofport, members:port...)
614 bundle_load(fields, basis, algorithm, ofport, dst, mem‐
615 bers:port...)
616 These actions choose a port (a ``member’’) from a comma-separated Open‐
618 Flow port list. After selecting the port, bundle outputs to it, whereas
619 bundle_load writes its port number to dst, which must be a 16-bit or
620 wider field or subfield in the syntax described under ``Field Specifi‐
621 cations’’ 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 members.
655 hrw (Highest Random Weight)
657 Computes the following, considering only the live ports
658 in members:
659 for i in [1,n_members]:
661 weights[i] = hash(flow, i)
662 member = { 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 members.
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 members 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,members: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 Thegroupaction
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. The following
712 alternative bucket designs do work:
713 · Recursively invoke the rest of the pipeline with resub‐
715 mit.
716 · Use resubmit into a table that uses push to put the value
718 on the stack for the caller to pop off. This works
719 because group preserves only packet data and metadata,
720 not the stack.
721 (This design requires indirection through resubmit
723 because actions sets may not contain push or pop
724 actions.)
725 An exit action within a group bucket terminates only execution of that
727 bucket, not other buckets or the overall pipeline.
728 Conformance:
730 OpenFlow 1.1 introduced group. Open vSwitch 2.6 and later also supports
732 group as an extension to OpenFlow 1.0.
733
735 Thestrip_vlanandpopactions
736 Syntax:
737 strip_vlan
738 pop_vlan
739 Removes the outermost VLAN tag, if any, from the packet.
741 The two names for this action are synonyms with no semantic difference.
743 The OpenFlow 1.0 specification uses the name strip_vlan and later ver‐
744 sions use pop_vlan, but OVS accepts either name regardless of version.
745 In OpenFlow 1.1 and later, consistency rules allow strip_vlan only in a
747 flow that matches only packets with a VLAN tag (or following an action
748 that pushes a VLAN tag, such as push_vlan). See ``Inconsistencies’’,
749 above, for more information.
750 Conformance:
752 All versions of OpenFlow and Open vSwitch support this action.
754 Thepush_vlanaction
756 Syntax:
757 push_vlan:ethertype
758 Pushes a new outermost VLAN onto the packet. Uses TPID ethertype, which
760 must be 0x8100 for an 802.1Q C-tag or 0x88a8 for a 802.1ad S-tag.
761 Conformance:
763 OpenFlow 1.1 and later supports this action. Open vSwitch 2.8 added
765 support for multiple VLAN tags (with a limit of 2) and 802.1ad S-tags.
766 Thepush_mplsaction
768 Syntax:
769 push_mpls:ethertype
770 Pushes a new outermost MPLS label stack entry (LSE) onto the packet and
772 changes the packet’s Ethertype to ethertype, which must be either
773 B0x8847 or 0x8848.
774 If the packet did not already contain any MPLS labels, initializes the
776 new LSE as:
777 Label 2, if the packet contains IPv6, 0 otherwise.
779 TC The low 3 bits of the packet’s DSCP value, or 0 if the
781 packet is not IP.
782 TTL Copied from the IP TTL, or 64 if the packet is not IP.
784 If the packet did already contain an MPLS label, initializes the new
786 outermost label as a copy of the existing outermost label.
787 OVS currently supports at most 3 MPLS labels.
789 This action applies only to Ethernet packets.
791 Conformance:
793 Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later
795 support push_mpls. Open vSwitch implements push_mpls as an extension to
796 OpenFlow 1.0.
797 Thepop_mplsaction
799 Syntax:
800 pop_mpls:ethertype
801 Strips the outermost MPLS label stack entry and changes the packet’s
803 Ethertype to ethertype.
804 This action applies only to Ethernet packets with at least one MPLS
806 label. If there is more than one MPLS label, then ethertype should be
807 an MPLS Ethertype (B0x8847 or 0x8848).
808 Conformance:
810 Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later
812 support pop_mpls. Open vSwitch implements pop_mpls as an extension to
813 OpenFlow 1.0.
814 Theencapaction
816 Syntax:
817 encap(nsh([md_type=md_type], [tlv(class,type,value)]...))
818 encap(ethernet)
819 The encap action encapsulates a packet with a specified header. It has
821 variants for different kinds of encapsulation.
822 The encap(nsh(...)) variant encapsulates an Ethernet frame with NSH.
824 The md_type may be 1 or 2 for metadata type 1 or 2, defaulting to 1.
825 For metadata type 2, TLVs may be specified with class as a 16-bit hexa‐
826 decimal integer beginning with 0x, type as an 8-bit decimal integer,
827 and value a sequence of pairs of hex digits beginning with 0x. For
828 example:
829 encap(nsh(md_type=1))
831 Encapsulates the packet with an NSH header with metadata
832 type 1.
833 encap(nsh(md_type=2,tlv(0x1000,10,0x12345678)))
835 Encapsulates the packet with an NSH header, NSH metadata
836 type 2, and an NSH TLV with class 0x1000, type 10, and
837 the 4-byte value 0x12345678.
838 The encap(ethernet) variant encapsulate a bare L3 packet in an Ethernet
840 frame. The Ethernet type is initialized to the L3 packet’s type, e.g.
841 0x0800 if the L3 packet is IPv4. The Ethernet source and destination
842 are initially zeroed.
843 Conformance:
845 This action is an Open vSwitch extension to OpenFlow 1.3 and later,
847 introduced in Open vSwitch 2.8.
848 Thedecapaction
850 Syntax:
851 decap
852 Removes an outermost encapsulation from the packet:
854 · If the packet is an Ethernet packet, removes the Ethernet
856 header, which changes the packet into a bare L3 packet.
857 If the packet has VLAN tags, raises an unsupported packet
858 type error (see ``Error Handling’’, above).
859 · Otherwise, if the packet is an NSH packet, removes the
861 NSH header, revealing the inner packet. Open vSwitch sup‐
862 ports Ethernet, IPv4, IPv6, and NSH inner packet types.
863 Other types raise unsupported packet type errors.
864 · Otherwise, raises an unsupported packet type error.
866 Conformance:
868 This action is an Open vSwitch extension to OpenFlow 1.3 and later,
870 introduced in Open vSwitch 2.8.
871
873 These actions modify packet data and metadata fields.
874 Theset_fieldandloadactions
876 Syntax:
877 set_field:value[/mask]->dst
878 load:value->dst
879 These actions loads a literal value into a field or part of a field.
881 The set_field action takes value in the customary syntax for field dst,
882 e.g. 00:11:22:33:44:55 for an Ethernet address, and dst as the field’s
883 name. The optional mask allows part of a field to be set.
884 The load action takes value as an integer value (in decimal or prefixed
886 by 0x for hexadecimal) and dst as a field or subfield in the syntax
887 described under ``Field Specifications’’ above.
888 The following all set the Ethernet source address to 00:11:22:33:44:55:
890 · set_field:00:11:22:33:44:55->eth_src
892 · load:0x001122334455->eth_src
894 · load:0x001122334455->OXM_OF_ETH_SRC[]
896 The following all set the multicast bit in the Ethernet destination
898 address:
899 · set_field:01:00:00:00:00:00/01:00:00:00:00:00->eth_dst
901 · load:1->eth_dst[40]
903 Open vSwitch prohibits a set_field or load action whose dst is not
905 guaranteed to be part of the packet; for example, set_field of nw_dst
906 is only allowed in a flow that matches on Ethernet type 0x800. In some
907 cases, such as in an action set, Open vSwitch can’t statically check
908 that dst is part of the packet, and in that case if it is not then Open
909 vSwitch treats the action as a no-op.
910 Conformance:
912 Open vSwitch 1.1 introduced NXAST_REG_LOAD as a extension to OpenFlow
914 1.0 and used load to express it. Later, OpenFlow 1.2 introduced a stan‐
915 dard OFPAT_SET_FIELD action that was restricted to loading entire
916 fields, so Open vSwitch added the form set_field with this restriction.
917 OpenFlow 1.5 extended OFPAT_SET_FIELD to the point that it became a
918 superset of NXAST_REG_LOAD. Open vSwitch translates either syntax as
919 necessary for the OpenFlow version in use: in OpenFlow 1.0 and 1.1,
920 NXAST_REG_LOAD; in OpenFlow 1.2, 1.3, and 1.4, NXAST_REG_LOAD for load
921 or for loading a subfield, OFPAT_SET_FIELD otherwise; and OpenFlow 1.5
922 and later, OFPAT_SET_FIELD.
923 Themoveaction
925 Syntax:
926 move:src->dst
927 Copies the named bits from field or subfield src to field or subfield
929 dst. src and dst should fields or subfields in the syntax described
930 under ``Field Specifications’’ above. The two fields or subfields must
931 have the same width.
932 Examples:
934 · move:reg0[0..5]->reg1[26..31] copies the six bits num‐
936 bered 0 through 5 in register 0 into bits 26 through 31
937 of register 1.
938 · move:reg0[0..15]->vlan_tci copies the least significant
940 16 bits of register 0 into the VLAN TCI field.
941 Conformance:
943 In OpenFlow 1.0 through 1.4, move ordinarily uses an Open vSwitch
945 extension to OpenFlow. In OpenFlow 1.5, move uses the OpenFlow 1.5
946 standard OFPAT_COPY_FIELD action. The ONF has also made
947 OFPAT_COPY_FIELD available as an extension to OpenFlow 1.3. Open
948 vSwitch 2.4 and later understands this extension and uses it if a con‐
949 troller uses it, but for backward compatibility with older versions of
950 Open vSwitch, ovs-ofctl does not use it.
951 Themod_dl_srcandmod_dl_dstactions
953 Syntax:
954 mod_dl_src:mac
955 mod_dl_dst:mac
956 Sets the Ethernet source or destination address, respectively, to mac,
958 which should be expressed in the form xx:xx:xx:xx:xx:xx.
959 For L3-only packets, that is, those that lack an Ethernet header, this
961 action has no effect.
962 Conformance:
964 OpenFlow 1.0 and 1.1 have specialized actions for these purposes. Open‐
966 Flow 1.2 and later do not, so Open vSwitch translates them to appropri‐
967 ate OFPAT_SET_FIELD actions for those versions,
968 Themod_nw_srcandmod_nw_dstactions
970 Syntax:
971 mod_nw_src:ip
972 mod_nw_dst:ip
973 Sets the IPv4 source or destination address, respectively, to ip, which
975 should be expressed in the form w.x.y.z.
976 In OpenFlow 1.1 and later, consistency rules allow these actions only
978 in a flow that matches only packets that contain an IPv4 header (or
979 following an action that adds an IPv4 header, e.g. pop_mpls:0x0800).
980 See ``Inconsistencies’’, above, for more information.
981 Conformance:
983 OpenFlow 1.0 and 1.1 have specialized actions for these purposes. Open‐
985 Flow 1.2 and later do not, so Open vSwitch translates them to appropri‐
986 ate OFPAT_SET_FIELD actions for those versions,
987 Themod_nw_tosandmod_nw_ecnactions
989 Syntax:
990 mod_nw_tos:tos
991 mod_nw_ecn:ecn
992 The mod_nw_tos action sets the DSCP bits in the IPv4 ToS/DSCP or IPv6
994 traffic class field to tos, which must be a multiple of 4 between 0 and
995 255. This action does not modify the two least significant bits of the
996 ToS field (the ECN bits).
997 The mod_nw_ecn action sets the ECN bits in the IPv4 ToS or IPv6 traffic
999 class field to ecn, which must be a value between 0 and 3, inclusive.
1000 This action does not modify the six most significant bits of the field
1001 (the DSCP bits).
1002 In OpenFlow 1.1 and later, consistency rules allow these actions only
1004 in a flow that matches only packets that contain an IPv4 or IPv6 header
1005 (or following an action that adds such a header). See ``Inconsisten‐
1006 cies’’, above, for more information.
1007 Conformance:
1009 OpenFlow 1.0 has a mod_nw_tos action but not mod_nw_ecn. Open vSwitch
1011 implements the latter in OpenFlow 1.0 as an extension using
1012 NXAST_REG_LOAD. OpenFlow 1.1 has specialized actions for these pur‐
1013 poses. OpenFlow 1.2 and later do not, so Open vSwitch translates them
1014 to appropriate OFPAT_SET_FIELD actions for those versions,
1015 Themod_tp_srcandmod_tp_dstactions
1017 Syntax:
1018 mod_tp_src:port
1019 mod_tp_dst:port
1020 Sets the TCP or UDP or SCTP source or destination port, respectively,
1022 to port. Both IPv4 and IPv6 are supported.
1023 In OpenFlow 1.1 and later, consistency rules allow these actions only
1025 in a flow that matches only packets that contain a TCP or UDP or SCTP
1026 header. See ``Inconsistencies’’, above, for more information.
1027 Conformance:
1029 OpenFlow 1.0 and 1.1 have specialized actions for these purposes. Open‐
1031 Flow 1.2 and later do not, so Open vSwitch translates them to appropri‐
1032 ate OFPAT_SET_FIELD actions for those versions,
1033 Thedec_ttlaction
1035 Syntax:
1036 dec_ttl
1037 dec_ttl(id1, [id2]...)
1038 Decrement TTL of IPv4 packet or hop limit of IPv6 packet. If the TTL or
1040 hop limit is initially 0 or 1, no decrement occurs, as packets reaching
1041 TTL zero must be rejected. Instead, Open vSwitch sends a ``packet-in’’
1042 message with reason code OFPR_INVALID_TTL to each connected controller
1043 that has enabled receiving such messages, and stops processing the cur‐
1044 rent set of actions. (However, if the current set of actions was
1045 reached through resubmit, the remaining actions in outer levels resume
1046 processing.)
1047 As an Open vSwitch extension to OpenFlow, this action supports the
1049 ability to specify a list of controller IDs. Open vSwitch will only
1050 send the message to controllers with the given ID or IDs. Specifying no
1051 list is equivalent to specifying a single controller ID of zero.
1052 Sets the TCP or UDP or SCTP source or destination port, respectively,
1054 to port. Both IPv4 and IPv6 are supported.
1055 In OpenFlow 1.1 and later, consistency rules allow these actions only
1057 in a flow that matches only packets that contain an IPv4 or IPv6
1058 header. See ``Inconsistencies’’, above, for more information.
1059 Conformance:
1061 All versions of OpenFlow and Open vSwitch support this action.
1063 Theset_mpls_label,set_mpls_tc, andset_mpls_ttlactions
1065 Syntax:
1066 set_mpls_label:label
1067 set_mpls_tc:tc
1068 set_mpls_ttl:ttl
1069 The set_mpls_label action sets the label of the packet’s outer MPLS
1071 label stack entry. label should be a 20-bit value that is decimal by
1072 default; use a 0x prefix to specify the value in hexadecimal.
1073 The set_mpls_tc action sets the traffic class of the packet’s outer
1075 MPLS label stack entry. tc should be in the range 0 to 7, inclusive.
1076 The set_mpls_ttl action sets the TTL of the packet’s outer MPLS label
1078 stack entry. ttl should be in the range 0 to 255 inclusive.
1079 In OpenFlow 1.1 and later, consistency rules allow these actions only
1081 in a flow that matches only packets that contain an MPLS label (or fol‐
1082 lowing an action that adds an MPLS label, e.g. push_mpls:0x8847). See
1083 ``Inconsistencies’’, above, for more information.
1084 Conformance:
1086 OpenFlow 1.0 does not support MPLS, but Open vSwitch implements these
1088 actions as extensions. OpenFlow 1.1 has specialized actions for these
1089 purposes. OpenFlow 1.2 and later do not, so Open vSwitch translates
1090 them to appropriate OFPAT_SET_FIELD actions for those versions,
1091 Thedec_mpls_ttlanddec_nsh_ttlactions
1093 Syntax:
1094 dec_mpls_ttl
1095 dec_nsh_ttl
1096 These actions decrement the TTL of the packet’s outer MPLS label stack
1098 entry or its NSH header, respectively. If the TTL is initially 0 or 1,
1099 no decrement occurs. Instead, Open vSwitch sends a ``packet-in’’ mes‐
1100 sage with reason code BOFPR_INVALID_TTL to OpenFlow controllers with ID
1101 0, if it has enabled receiving them. Processing the current set of
1102 actions then stops. (However, if the current set of actions was reached
1103 through resubmit, remaining actions in outer levels resume processing.)
1104 In OpenFlow 1.1 and later, consistency rules allow this actions only in
1106 a flow that matches only packets that contain an MPLS label or an NSH
1107 header, respectively. See ``Inconsistencies’’, above, for more informa‐
1108 tion.
1109 Conformance:
1111 Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later
1113 support dec_mpls_ttl. Open vSwitch implements dec_mpls_ttl as an exten‐
1114 sion to OpenFlow 1.0.
1115 Open vSwitch 2.8 introduced support for NSH, although the NSH draft
1117 changed after release so that only Open vSwitch 2.9 and later conform
1118 to the final protocol specification. The dec_nsh_ttl action and NSH
1119 support in general is an Open vSwitch extension not supported by any
1120 version of OpenFlow.
1121 Thecheck_pkt_largeraction
1123 Syntax:
1124 check_pkt_larger(pkt_len)->dst
1125 Checks if the packet is larger than the specified length in pkt_len. If
1127 so, stores 1 in dst, which should be a 1-bit field; if not, stores 0.
1128 The packet length to check against the argument pkt_len includes the L2
1130 header and L2 payload of the packet, but not the VLAN tag (if present).
1131 Examples:
1133 · check_pkt_larger(1500)->reg0[0]
1135 · check_pkt_larger(8000)->reg9[10]
1137 This action was added in Open vSwitch 2.11.90.
1139 Thedelete_fieldaction
1141 Syntax:
1142 delete_field:field
1143 The delete_field action deletes a field in the syntax described under
1145 ``Field Specifications’’ above. Currently, only the tun_metadta fields
1146 are supported.
1147 This action was added in Open vSwitch 2.13.90.
1149
1151 Theset_tunnelaction
1152 Syntax:
1153 set_tunnel:id
1154 set_tunnel64:id
1155 Many kinds of tunnels support a tunnel ID, e.g. VXLAN and Geneve have a
1157 24-bit VNI, and GRE has an optional 32-bit key. This action sets the
1158 value used for tunnel ID in such tunneled packets, although whether it
1159 is used for a particular tunnel depends on the tunnel’s configuration.
1160 See the tunnel ID documentation in ovs-fields(7) for more information.
1161 Conformance:
1163 These actions are OpenFlow extensions. set_tunnel was introduced in
1165 Open vSwitch 1.0. set_tunnel64, which is needed if id is wider than 32
1166 bits, was added in Open vSwitch 1.1. Both actions always set the entire
1167 tunnel ID field.
1168 Open vSwitch supports these actions in all versions of OpenFlow, but in
1170 OpenFlow 1.2 and later it translates them to an appropriate standard‐
1171 ized OFPAT_SET_FIELD action.
1172 Theset_queueandpop_queueactions
1174 Syntax:
1175 set_queue:queue
1176 pop_queue
1177 The set_queue action sets the queue ID to be used for subsequent output
1179 actions to queue, which must be a 32-bit integer. The range of meaning‐
1180 ful values of queue, and their meanings, varies greatly from one Open‐
1181 Flow implementation to another. Even within a single implementation,
1182 there is no guarantee that all OpenFlow ports have the same queues con‐
1183 figured or that all OpenFlow ports in an implementation can be config‐
1184 ured the same way queue-wise. For more information, see the documenta‐
1185 tion for the output queue field in ovs-fields(7).
1186 The pop_queue restores the output queue to the default that was set
1188 when the packet entered the switch (generally 0).
1189 Four billion queues ought to be enough for anyone: ⟨https://
1191 mailman.stanford.edu/pipermail/openflow-spec/2009-August/000394.html⟩
1192 Conformance:
1194 OpenFlow 1.1 introduced the set_queue action. Open vSwitch also sup‐
1196 ports it as an extension in OpenFlow 1.0.
1197 The pop_queue action is an Open vSwitch extension.
1199
1201 Open vSwitch is often used to implement a firewall. The preferred way
1202 to implement a firewall is ``connection tracking,’’ that is, to keep
1203 track of the connection state of individual TCP sessions. The ct action
1204 described in this section, added in Open vSwitch 2.5, implements con‐
1205 nection tracking. For new deployments, it is the recommended way to
1206 implement firewalling with Open vSwitch.
1207 Before ct was added, Open vSwitch did not have built-in support for
1209 connection tracking. Instead, Open vSwitch supported the learn action,
1210 which allows a received packet to add a flow to an OpenFlow flow table.
1211 This could be used to implement a primitive form of connection track‐
1212 ing: packets passing through the firewall in one direction could create
1213 flows that allowed response packets back through the firewall in the
1214 other direction. The additional fin_timeout action allowed the learned
1215 flows to expire quickly after TCP session termination.
1216 Thectaction
1218 Syntax:
1219 ct(argument]...)
1220 ct(commit[, argument]...)
1221 The action has two modes of operation, distinguished by whether commit
1223 is present. The following arguments may be present in either mode:
1224 zone=value
1226 A zone is a 16-bit id that isolates connections into sep‐
1227 arate domains, allowing overlapping network addresses in
1228 different zones. If a zone is not provided, then the
1229 default is 0. The value may be specified either as a
1230 16-bit integer literal or a field or subfield in the syn‐
1231 tax described under ``Field Specifications’’ above.
1232 Without commit, this action sends the packet through the connection
1234 tracker. The connection tracker keeps track of the state of TCP connec‐
1235 tions for packets passed through it. For each packet through a connec‐
1236 tion, it checks that it satisfies TCP invariants and signals the con‐
1237 nection state to later actions using the ct_state metadata field, which
1238 is documented in ovs-fields(7).
1239 In this form, ct forks the OpenFlow pipeline:
1241 · In one fork, ct passes the packet to the connection
1243 tracker. Afterward, it reinjects the packet into the
1244 OpenFlow pipeline with the connection tracking fields
1245 initialized. The ct_state field is initialized with con‐
1246 nection state and ct_zone to the connection tracking zone
1247 specified on the zone argument. If the connection is one
1248 that is already tracked, ct_mark and ct_label to its
1249 existing mark and label, respectively; otherwise they are
1250 zeroed. In addition, ct_nw_proto, ct_nw_src, ct_nw_dst,
1251 ct_ipv6_src, ct_ipv6_dst, ct_tp_src, and ct_tp_dst are
1252 initialized appropriately for the original direction con‐
1253 nection. See the resubmit action for a way to search the
1254 flow table with the connection tracking original direc‐
1255 tion fields swapped with the packet 5-tuple fields. See
1256 ovs-fields(7) for details on the connection tracking
1257 fields.
1258 · In the other fork, the original instance of the packet
1260 continues independent processing following the ct action.
1261 The ct_state field and other connection tracking metadata
1262 are cleared.
1263 Without commit, the ct action accepts the following arguments:
1265 table=table
1267 Sets the OpenFlow table where the packet is reinjected.
1268 The table must be a number between 0 and 254 inclusive,
1269 or a table’s name. If table is not specified, then the
1270 packet is not reinjected.
1271 nat
1273 nat(type=addrs[:ports][,flag]...)
1274 Specify address and port translation for the connection
1275 being tracked. The type must be src, for source
1276 address/port translation (SNAT), or dst, for destination
1277 address/port translation (DNAT). Setting up address trans‐
1278 lation for a new connection takes effect only if the con‐
1279 nection is later committed with ct(commit...).
1280 The src and dst options take the following arguments:
1282 addrs The IP address addr or range addr1-addr2 from which
1284 the translated address should be selected. If only
1285 one address is given, then that address will always
1286 be selected, otherwise the address selection can be
1287 informed by the optional persistent flag as
1288 described below. Either IPv4 or IPv6 addresses can
1289 be provided, but both addresses must be of the same
1290 type, and the datapath behavior is undefined in case
1291 of providing IPv4 address range for an IPv6 packet,
1292 or IPv6 address range for an IPv4 packet. IPv6
1293 addresses must be bracketed with [ and ] if a port
1294 range is also given.
1295 ports The L4 port or range port1-port2 from which the
1297 translated port should be selected. When a port
1298 range is specified, fallback to ephemeral ports does
1299 not happen, else, it will. The port number selection
1300 can be informed by the optional random and hash
1301 flags described below. The userspace datapath only
1302 supports the hash behavior.
1303 The optional flags are:
1305 random The selection of the port from the given range
1307 should be done using a fresh random number. This
1308 flag is mutually exclusive with hash.
1309 hash The selection of the port from the given range
1311 should be done using a datapath specific hash of the
1312 packet’s IP addresses and the other, non-mapped port
1313 number. This flag is mutually exclusive with random.
1314 persistent
1316 The selection of the IP address from the given range
1317 should be done so that the same mapping can be pro‐
1318 vided after the system restarts.
1319 If alg is specified for the committing ct action that also
1321 includes nat with a src or dst attribute, then the datapath
1322 tries to set up the helper to be NAT-aware. This function‐
1323 ality is datapath specific and may not be supported by all
1324 datapaths.
1325 A ``bare’’ nat argument with no options will only translate
1327 the packet being processed in the way the connection has
1328 been set up with an earlier, committed ct action. A nat
1329 action with src or dst, when applied to a packet belonging
1330 to an established (rather than new) connection, will behave
1331 the same as a bare nat.
1332 Open vSwitch 2.6 introduced nat. Linux 4.6 was the earliest
1334 upstream kernel that implemented ct support for nat.
1335 With commit, the connection tracker commits the connection to the con‐
1337 nection tracking module. The commit flag should only be used from the
1338 pipeline within the first fork of ct without commit. Information about
1339 the connection is stored beyond the lifetime of the packet in the pipe‐
1340 line. Some ct_state flags are only available for committed connections.
1341 The following options are available only with commit:
1343 force A committed connection always has the directionality of
1345 the packet that caused the connection to be committed in
1346 the first place. This is the ``original direction’’ of
1347 the connection, and the opposite direction is the ``reply
1348 direction’’. If a connection is already committed, but it
1349 is in the wrong direction, force effectively terminates
1350 the existing connection and starts a new one in the cur‐
1351 rent direction. This flag has no effect if the original
1352 direction of the connection is already the same as that
1353 of the current packet.
1354 exec(action...)
1356 Perform each action within the context of connection
1357 tracking. Only actions which modify the ct_mark or
1358 ct_label fields are accepted within exec action, and
1359 these fields may only be modified with this option. For
1360 example:
1361 set_field:value[/mask]->ct_mark
1363 Store a 32-bit metadata value with the connection.
1364 Subsequent lookups for packets in this connection
1365 will populate ct_mark when the packet is sent to
1366 the connection tracker with the table specified.
1367 set_field:value[/mask]->ct_label
1369 Store a 128-bit metadata value with the connec‐
1370 tion. Subsequent lookups for packets in this con‐
1371 nection will populate ct_label when the packet is
1372 sent to the connection tracker with the table
1373 specified.
1374 alg=alg
1376 Specify application layer gateway alg to track specific
1377 connection types. If subsequent related connections are
1378 sent through the ct action, then the rel flag in the
1379 ct_state field will be set. Supported types include:
1380 ftp Look for negotiation of FTP data connections.
1382 Specify this option for FTP control connections to
1383 detect related data connections and populate the
1384 rel flag for the data connections.
1385 tftp Look for negotiation of TFTP data connections.
1387 Specify this option for TFTP control connections
1388 to detect related data connections and populate
1389 the rel flag for the data connections.
1390 Related connections inherit ct_mark from that stored with
1392 the original connection (i.e. the connection created by
1393 ct(alg=...)).
1394 With the Linux datapath, global sysctl options affect ct behavior. In
1396 particular, if net.netfilter.nf_conntrack_helper is enabled, which it
1397 is by default until Linux 4.7, then application layer gateway helpers
1398 may be executed even if alg is not specified. For security reasons, the
1399 netfilter team recommends users disable this option. For further
1400 details, please see ⟨http://www.netfilter.org/news.html#2012-04-03⟩ .
1401 The ct action may be used as a primitive to construct stateful fire‐
1403 walls by selectively committing some traffic, then matching ct_state to
1404 allow established connections while denying new connections. The fol‐
1405 lowing flows provide an example of how to implement a simple firewall
1406 that allows new connections from port 1 to port 2, and only allows
1407 established connections to send traffic from port 2 to port 1:
1408 table=0,priority=1,action=drop
1410 table=0,priority=10,arp,action=normal
1411 table=0,priority=100,ip,ct_state=-trk,action=ct(table=1)
1412 table=1,in_port=1,ip,ct_state=+trk+new,action=ct(commit),2
1413 table=1,in_port=1,ip,ct_state=+trk+est,action=2
1414 table=1,in_port=2,ip,ct_state=+trk+new,action=drop
1415 table=1,in_port=2,ip,ct_state=+trk+est,action=1
1416 If ct is executed on IPv4 (or IPv6) fragments, then the message is
1419 implicitly reassembled before sending to the connection tracker and
1420 refragmented upon output, to the original maximum received fragment
1421 size. Reassembly occurs within the context of the zone, meaning that IP
1422 fragments in different zones are not assembled together. Pipeline pro‐
1423 cessing for the initial fragments is halted. When the final fragment is
1424 received, the message is assembled and pipeline processing continues
1425 for that flow. Packet ordering is not guaranteed by IP protocols, so it
1426 is not possible to determine which IP fragment will cause message
1427 reassembly (and therefore continue pipeline processing). As such, it is
1428 strongly recommended that multiple flows should not execute ct to
1429 reassemble fragments from the same IP message.
1430 Conformance:
1432 The ct action was introduced in Open vSwitch 2.5. Some of its features
1434 were introduced later, noted individually above.
1435 Thect_clearaction
1437 Syntax:
1438 ct_clear
1439 Clears connection tracking state from the flow, zeroing ct_state,
1441 ct_zone, ct_mark, and ct_label.
1442 This action was introduced in Open vSwitch 2.6.90.
1444 Thelearnaction
1446 Syntax:
1447 learn(argument...)
1448 The learn action adds or modifies a flow in an OpenFlow table, similar
1450 to ovs-ofctl --strict mod-flows. The arguments specify the match
1451 fields, actions, and other properties of the flow to be added or modi‐
1452 fied.
1453 Match fields for the new flow are specified as follows. At least one
1455 match field should ordinarily be specified:
1456 field=value
1458 Specifies that field, in the new flow, must match the
1459 literal value, e.g. dl_type=0x800. Shorthand match syn‐
1460 tax, such as ip in place of dl_type=0x800, is not sup‐
1461 ported.
1462 field=src
1464 Specifies that field in the new flow must match src taken
1465 from the packet currently being processed. For example,
1466 udp_dst=udp_src, applied to a UDP packet with source port
1467 53, creates a flow which matches udp_dst=53. field and
1468 src must have the same width.
1469 field Shorthand for the previous form when field and src are
1471 the same. For example, udp_dst, applied to a UDP packet
1472 with destination port 53, creates a flow which matches
1473 udp_dst=53.
1474 The field and src arguments above should be fields or subfields in the
1476 syntax described under ``Field Specifications’’ above.
1477 Match field specifications must honor prerequisites for both the flow
1479 with the learn and the new flow that it creates. Consider the following
1480 complete flow, in the syntax accepted by ovs-ofctl. If the flow’s match
1481 on udp were omitted, then the flow would not satisfy the prerequisites
1482 for the learn action’s use of udp_src. If dl_type=0x800 or nw_proto
1483 were omitted from learn, then the new flow would not satisfy the pre‐
1484 requisite for its match on udp_dst. For more information on prerequi‐
1485 sites, please refer to ovs-fields(7):
1486 udp, actions=learn(dl_type=0x800, nw_proto=17, udp_dst=udp_src)
1488 Actions for the new flow are specified as follows. At least one action
1491 should ordinarily be specified:
1492 load:value->dst
1494 Adds a load action to the new flow that loads the literal
1495 value into dst. The syntax is the same as the load action
1496 explained in the ``Header Modification’’ section.
1497 load:src->dst
1499 Adds a load action to the new flow that loads src, a
1500 field or subfield from the packet being processed, into
1501 dst.
1502 output:field
1504 Adds an output action to the new flow’s actions that out‐
1505 puts to the OpenFlow port taken from field, which must be
1506 a field as described above.
1507 fin_idle_timeout=seconds
1509 fin_hard_timeout=seconds
1510 Adds a fin_timeout action with the specified arguments to
1511 the new flow. This feature was added in Open vSwitch
1512 1.5.90.
1513 The following additional arguments are optional:
1515 idle_timeout=seconds
1517 hard_timeout=seconds
1518 priority=value
1519 cookie=value
1520 send_flow_rem
1521 These arguments have the same meaning as in the usual flow
1522 syntax documented in ovs-ofctl(8).
1523 table=table
1525 The table in which the new flow should be inserted. Specify
1526 a decimal number between 0 and 254 inclusive or the name of
1527 a table. The default, if table is unspecified, is table 1
1528 (not 0).
1529 delete_learned
1531 When this flag is specified, deleting the flow that con‐
1532 tains the learn action will also delete the flows created
1533 by learn. Specifically, when the last learn action with
1534 this flag and particular table and cookie values is
1535 removed, the switch deletes all of the flows in the speci‐
1536 fied table with the specified cookie.
1537 This flag was added in Open vSwitch 2.4.
1539 limit=number
1541 If the number of flows in the new flow’s table with the
1542 same cookie exceeds number, the action will not add a new
1543 flow. By default, or with limit=0, there is no limit.
1544 This flag was added in Open vSwitch 2.8.
1546 result_dst=field[bit]
1548 If learn fails (because the number of flows exceeds limit),
1549 the action sets field[bit] to 0, otherwise it will be set
1550 to 1. field[bit] must be a single bit.
1551 This flag was added in Open vSwitch 2.8.
1553 By itself, the learn action can only put two kinds of actions into the
1555 flows that it creates: load and output actions. If learn is used in
1556 isolation, these are severe limits.
1557 However, learn is not meant to be used in isolation. It is a primitive
1559 meant to be used together with other Open vSwitch features to accom‐
1560 plish a task. Its existing features are enough to accomplish most
1561 tasks.
1562 Here is an outline of a typical pipeline structure that allows for ver‐
1564 satile behavior using learn:
1565 · Flows in table A contain a learn action, that populates
1567 flows in table L, that use a load action to populate reg‐
1568 ister R with information about what was learned.
1569 · Flows in table B contain two sequential resubmit actions:
1571 one to table L and another one to table B+1.
1572 · Flows in table B+1 match on register R and act differ‐
1574 ently depending on what the flows in table L loaded into
1575 it.
1576 This approach can be used to implement many learn-based features. For
1578 example:
1579 · Resubmit to a table selected based on learned informa‐
1581 tion, e.g. see ⟨https://mail.openvswitch.org/pipermail/
1582 ovs-discuss/2016-June/021694.html⟩ .
1583 · MAC learning in the middle of a pipeline, as described in
1585 the ``Open vSwitch Advanced Features Tutorial’’ in the
1586 OVS documentation.
1587 · TCP state based firewalling, by learning outgoing connec‐
1589 tions based on SYN packets and matching them up with
1590 incoming packets. (This is usually better implemented
1591 using the ct action.)
1592 · At least some of the features described in T. A. Hoff,
1594 ``Extending Open vSwitch to Facilitate Creation of State‐
1595 ful SDN Applications’’.
1596 Conformance:
1598 The learn action is an Open vSwitch extension to OpenFlow added in Open
1600 vSwitch 1.3. Some features of learn were added in later versions, as
1601 noted individually above.
1602 Thefin_timeoutaction
1604 Syntax:
1605 fin_timeout(key=value...)
1606 This action changes the idle timeout or hard timeout, or both, of the
1608 OpenFlow flow that contains it, when the flow matches a TCP packet with
1609 the FIN or RST flag. When such a packet is observed, the action reduces
1610 the rule’s timeouts to those specified on the action. If the rule’s
1611 existing timeout is already shorter than the one that the action speci‐
1612 fies, then that timeout is unaffected.
1613 The timeouts are specified as key-value pairs:
1615 idle_timeout=seconds
1617 Causes the flow to expire after the given number of sec‐
1618 onds of inactivity.
1619 hard_timeout=seconds
1621 Causes the flow to expire after the given number of sec‐
1622 onds, regardless of activity. (seconds specifies time
1623 since the flow’s creation, not since the receipt of the
1624 FIN or RST.)
1625 This action is normally added to a learned flow by the learn action. It
1627 is unlikely to be useful otherwise.
1628 Conformance:
1630 This Open vSwitch extension action was added in Open vSwitch 1.5.90.
1632
1634 Theresubmitaction
1635 Syntax:
1636 resubmit:port
1637 resubmit([port],[table][,ct])
1638 Searches an OpenFlow flow table for a matching flow and executes the
1640 actions found, if any, before continuing to the following action in the
1641 current flow entry. Arguments can customize the search:
1642 · If port is given as an OpenFlow port number or name, then
1644 it specifies a value to use for the input port metadata
1645 field as part of the search, in place of the input port
1646 currently in the flow. Specifying in_port as port is
1647 equivalent to omitting it.
1648 · If table is given as an integer between 0 and 254 or a
1650 table name, it specifies the OpenFlow table to search. If
1651 it is not specified, the table from the current flow is
1652 used.
1653 · If ct is specified, then the search is done with packet
1655 5-tuple fields swapped with the corresponding conntrack
1656 original direction tuple fields. See the documentation
1657 for ct above, for more information about connection
1658 tracking, or ovs-fields(7) for details about the connec‐
1659 tion tracking fields.
1660 This flag requires a valid connection tracking state as a
1662 match prerequisite in the flow where this action is
1663 placed. Examples of valid connection tracking state
1664 matches include ct_state=+new, ct_state=+est,
1665 ct_state=+rel, and ct_state=+trk-inv.
1666 The changes, if any, to the input port and connection tracking fields
1668 are just for searching the flow table. The changes are not visible to
1669 actions or to later flow table lookups.
1670 The most common use of resubmit is to visit another flow table without
1672 port or ct, like this: resubmit(,table).
1673 Recursive resubmit actions are permitted.
1675 Conformance:
1677 The resubmit action is an Open vSwitch extension. However, the goto_ta‐
1679 ble instruction in OpenFlow 1.1 and later can be viewed as a kind of
1680 restricted resubmit.
1681 Open vSwitch 1.2.90 added table. Open vSwitch 2.7 added ct.
1683 Open vSwitch imposes a limit on resubmit recursion that varies among
1685 version:
1686 · Open vSwitch 1.0.1 and earlier did not support recursion.
1688 · Open vSwitch 1.0.2 and 1.0.3 limited recursion to 8 lev‐
1690 els.
1691 · Open vSwitch 1.1 and 1.2 limited recursion to 16 levels.
1693 · Open vSwitch 1.2 through 1.8 limited recursion to 32 lev‐
1695 els.
1696 · Open vSwitch 1.9 through 2.0 limited recursion to 64 lev‐
1698 els.
1699 · Open vSwitch 2.1 through 2.5 limited recursion to 64 lev‐
1701 els and impose a total limit of 4,096 resubmits per flow
1702 translation (earlier versions did not impose any total
1703 limit).
1704 · Open vSwitch 2.6 and later imposes the same limits as
1706 2.5, with one exception: resubmit from table x to any ta‐
1707 ble y > x does not count against the recursion depth
1708 limit.
1709 Thecloneaction
1711 Syntax:
1712 clone(action...)
1713 Executes each nested action, saving much of the packet and pipeline
1715 state beforehand and then restoring it afterward. The state that is
1716 saved and restored includes all flow data and metadata (including, for
1717 example, in_port and ct_state), the stack accessed by push and pop
1718 actions, and the OpenFlow action set.
1719 This action was added in Open vSwitch 2.6.90.
1721 Thepushandpopactions
1723 Syntax:
1724 push:src
1725 pop:dst
1726 The push action pushes src on a general-purpose stack. The pop action
1728 pops an entry off the stack into dst. src and dst should be fields or
1729 subfields in the syntax described under ``Field Specifications’’ above.
1730 Controllers can use the stack for saving and restoring data or metadata
1732 around resubmit actions, for swapping or rearranging data and metadata,
1733 or for other purposes. Any data or metadata field, or part of one, may
1734 be pushed, and any modifiable field or subfield may be popped.
1735 The number of bits pushed in a stack entry do not have to match the
1737 number of bits later popped from that entry. If more bits are popped
1738 from an entry than were pushed, then the entry is conceptually left-
1739 padded with 0-bits as needed. If fewer bits are popped than pushed,
1740 then bits are conceptually trimmed from the left side of the entry.
1741 The stack’s size is limited. The limit is intended to be high enough
1743 that ``normal’’ use will not pose problems. Stack overflow or underflow
1744 is an error that stops action execution (see ``Stack too deep’’ under
1745 ``Error Handling’’, above).
1746 Examples:
1748 · push:reg2[0..5] or push:NXM_NX_REG2[0..5] pushes on the
1750 stack the 6 bits in register 2 bits 0 through 5.
1751 · pop:reg2[0..5] or pop:NXM_NX_REG2[0..5] pops the value
1753 from top of the stack and copy bits 0 through 5 of that
1754 value into bits 0 through 5 of register 2.
1755 Conformance:
1757 Open vSwitch 1.2 introduced push and pop as OpenFlow extension actions.
1759 Theexitaction
1761 Syntax:
1762 exit
1763 This action causes Open vSwitch to immediately halt execution of fur‐
1765 ther actions. Actions which have already been executed are unaffected.
1766 Any further actions, including those which may be in other tables, or
1767 different levels of the resubmit call stack, are ignored. However, an
1768 exit action within a group bucket terminates only execution of that
1769 bucket, not other buckets or the overall pipeline. Actions in the
1770 action set are still executed (specify clear_actions before exit to
1771 discard them).
1772 Themultipathaction
1774 Syntax:
1775 multipath(fields, basis, algorithm, n_links, arg, dst)
1776 Hashes fields using basis as a universal hash parameter, then the
1778 applies multipath link selection algorithm (with parameter arg) to
1779 choose one of n_links output links numbered 0 through n_links minus 1,
1780 and stores the link into dst, which must be a field or subfield in the
1781 syntax described under ``Field Specifications’’ above.
1782 The bundle or bundle_load actions are usually easier to use than multi‐
1784 path.
1785 fields must be one of the following:
1787 eth_src
1789 Hashes Ethernet source address only.
1790 symmetric_l4
1792 Hashes Ethernet source, destination, and type, VLAN ID,
1793 IPv4/IPv6 source, destination, and protocol, and TCP or
1794 SCTP (but not UDP) ports. The hash is computed so that
1795 pairs of corresponding flows in each direction hash to
1796 the same value, in environments where L2 paths are the
1797 same in each direction. UDP ports are not included in the
1798 hash to support protocols such as VXLAN that use asymmet‐
1799 ric ports in each direction.
1800 symmetric_l3l4
1802 Hashes IPv4/IPv6 source, destination, and protocol, and
1803 TCP or SCTP (but not UDP) ports. Like symmetric_l4, this
1804 is a symmetric hash, but by excluding L2 headers it is
1805 more effective in environments with asymmetric L2 paths
1806 (e.g. paths involving VRRP IP addresses on a router). Not
1807 an effective hash function for protocols other than IPv4
1808 and IPv6, which hash to a constant zero.
1809 symmetric_l3l4+udp
1811 Like symmetric_l3l4+udp, but UDP ports are included in
1812 the hash. This is a more effective hash when asymmetric
1813 UDP protocols such as VXLAN are not a consideration.
1814 symmetric_l3
1816 Hashes network source address and network destination
1817 address.
1818 nw_src Hashes network source address only.
1820 nw_dst Hashes network destination address only.
1822 The algorithm used to compute the final result link must be one of the
1824 following:
1825 modulo_n
1827 Computes link = hash(flow) % n_links.
1828 This algorithm redistributes all traffic when n_links
1830 changes. It has O(1) performance.
1831 Use 65535 for max_link to get a raw hash value.
1833 This algorithm is specified by RFC 2992.
1835 hash_threshold
1837 Computes link = hash(flow) / (MAX_HASH / n_links).
1838 Redistributes between one-quarter and one-half of traffic
1840 when n_links changes. It has O(1) performance.
1841 This algorithm is specified by RFC 2992.
1843 hrw (Highest Random Weight)
1845 Computes the following:
1846 for i in [0,n_links]:
1848 weights[i] = hash(flow, i)
1849 link = { i such that weights[i] >= weights[j] for all j != i }
1850 Redistributes 1/n_links of traffic when n_links changes.
1853 It has O(n_links) performance. If n_links is greater than
1854 a threshold (currently 64, but subject to change), Open
1855 vSwitch will substitute another algorithm automatically.
1856 This algorithm is specified by RFC 2992.
1858 iter_hash (Iterative Hash)
1860 Computes the following:
1861 i = 0
1863 repeat:
1864 i = i + 1
1865 link = hash(flow, i) % arg
1866 while link > max_link
1867 Redistributes 1/n_links of traffic when n_links changes.
1870 O(1) performance when arg/max_link is bounded by a con‐
1871 stant.
1872 Redistributes all traffic when arg changes.
1874 arg must be greater than max_link and for best perfor‐
1876 mance should be no more than approximately max_link * 2.
1877 If arg is outside the acceptable range, Open vSwitch will
1878 automatically substitute the least power of 2 greater
1879 than max_link.
1880 This algorithm is specific to Open vSwitch.
1882 Only the iter_hash algorithm uses arg.
1884 It is an error if max_link is greater than or equal to 2**n_bits.
1886 Conformance:
1888 This is an OpenFlow extension added in Open vSwitch 1.1.
1890
1892 Theconjunctionaction
1893 Syntax:
1894 conjunction(id, k/n)
1895 This action allows for sophisticated ``conjunctive match’’ flows. Refer
1897 to ``Conjunctive Match Fields’’ in ovs-fields(7) for details.
1898 A flow that has one or more conjunction actions may not have any other
1900 actions except for note actions.
1901 Conformance:
1903 Open vSwitch 2.4 introduced the conjunction action and conj_id field.
1905 They are Open vSwitch extensions to OpenFlow.
1906 Thenoteaction
1908 Syntax:
1909 note:[hh]...
1910 This action does nothing at all. OpenFlow controllers may use it to
1912 annotate flows with more data than can fit in a flow cookie.
1913 The action may include any number of bytes represented as hex digits
1915 hh. Periods may separate pairs of hex digits, for readability. The note
1916 action’s format doesn’t include an exact length for its payload, so the
1917 provided bytes will be padded on the right by enough bytes with value 0
1918 to make the total number 6 more than a multiple of 8.
1919 Conformance:
1921 This action is an extension to OpenFlow introduced in Open vSwitch 1.1.
1923 Thesampleaction
1925 Syntax:
1926 sample(argument...)
1927 Samples packets and sends one sample for every sampled packet.
1929 The following argument forms are accepted:
1931 probability=packets
1933 The number of sampled packets out of 65535. Must be
1934 greater or equal to 1.
1935 collector_set_id=id
1937 The unsigned 32-bit integer identifier of the set of sam‐
1938 ple collectors to send sampled packets to. Defaults to 0.
1939 obs_domain_id=id
1941 When sending samples to IPFIX collectors, the unsigned
1942 32-bit integer Observation Domain ID sent in every IPFIX
1943 flow record. Defaults to 0.
1944 obs_point_id=id
1946 When sending samples to IPFIX collectors, the unsigned
1947 32-bit integer Observation Point ID sent in every IPFIX
1948 flow record. Defaults to 0.
1949 sampling_port=port
1951 Sample packets on port, which should be the ingress or
1952 egress port. This option, which was added in Open vSwitch
1953 2.5.90, allows the IPFIX implementation to export egress
1954 tunnel information.
1955 ingress
1957 egress
1958 Specifies explicitly that the packet is being sampled on
1959 ingress to or egress from the switch. IPFIX reports sent by
1960 Open vSwitch before version 2.5.90 did not include a direc‐
1961 tion. From 2.5.90 until 2.6.90, IPFIX reports inferred a
1962 direction from sampling_port: if it was the packet’s output
1963 port, then the direction was reported as egress, otherwise
1964 as ingress. Open vSwitch 2.6.90 introduced these options,
1965 which allow the inferred direction to be overridden. This
1966 is particularly useful when the ingress (or egress) port is
1967 not a tunnel.
1968 Refer to ovs-vswitchd.conf.db(5) for more details on configuring sample
1970 collector sets.
1971 Conformance:
1973 This action is an OpenFlow extension added in Open vSwitch 2.4.
1975
1977 Every version of OpenFlow includes actions. OpenFlow 1.1 introduced the
1978 higher-level, related concept of instructions. In OpenFlow 1.1 and
1979 later, actions within a flow are always encapsulated within an instruc‐
1980 tion. Each flow has at most one instruction of each kind, which are
1981 executed in the following fixed order defined in the OpenFlow specifi‐
1982 cation:
1983 1. Meter
1985 2. Apply-Actions
1987 3. Clear-Actions
1989 4. Write-Actions
1991 5. Write-Metadata
1993 6. Stat-Trigger (not supported by Open vSwitch)
1995 7. Goto-Table
1997 The most important instruction is Apply-Actions. This instruction
1999 encapsulates any number of actions, which the instruction executes.
2000 Open vSwitch does not explicitly represent Apply-Actions. Instead, any
2001 action by itself is implicitly part of an Apply-Actions instructions.
2002 Open vSwitch syntax requires other instructions, if present, to be in
2004 the order listed above. Otherwise it will flag an error.
2005 Themeteraction and instruction
2007 Syntax:
2008 meter:meter_id
2009 Apply meter meter_id. If a meter band rate is exceeded, the packet may
2011 be dropped, or modified, depending on the meter band type.
2012 Conformance:
2014 OpenFlow 1.3 introduced the meter instruction. OpenFlow 1.5 changes
2016 meter from an instruction to an action.
2017 OpenFlow 1.5 allows implementations to restrict meter to be the first
2019 action in an action list and to exclude meter from action sets, for
2020 better compatibility with OpenFlow 1.3 and 1.4. Open vSwitch restricts
2021 the meter action both ways.
2022 Open vSwitch 2.0 introduced OpenFlow protocol support for meters, but
2024 it did not include a datapath implementation. Open vSwitch 2.7 added
2025 meter support to the userspace datapath. Open vSwitch 2.10 added meter
2026 support to the kernel datapath. Open vSwitch 2.12 added support for
2027 meter as an action in OpenFlow 1.5.
2028 Theclear_actionsinstruction
2030 Syntax:
2031 clear_actions
2032 Clears the action set. See ``Action Sets’’, above, for more informa‐
2034 tion.
2035 Conformance:
2037 OpenFlow 1.1 introduced clear_actions. Open vSwitch 2.1 added support
2039 for clear_actions.
2040 Thewrite_actionsinstruction
2042 Syntax:
2043 write_actions(action...)
2044 Adds each action to the action set. The action set is carried between
2046 flow tables and then executed at the end of the pipeline. Only certain
2047 actions may be written to the action set. See ``Action Sets’’, above,
2048 for more information.
2049 Conformance:
2051 OpenFlow 1.1 introduced write_actions. Open vSwitch 2.1 added support
2053 for write_actions.
2054 Thewrite_metadatainstruction
2056 Syntax:
2057 write_metadata:value[/mask]
2058 Updates the flow’s metadata field. If mask is omitted, metadata is set
2060 exactly to value; if mask is specified, then a 1-bit in mask indicates
2061 that the corresponding bit in metadata will be replaced with the corre‐
2062 sponding bit from value. Both value and mask are 64-bit values that are
2063 decimal by default; use a 0x prefix to specify them in hexadecimal.
2064 The metadata field can also be matched in the flow table and updated
2066 with actions such as set_field and move.
2067 Conformance:
2069 OpenFlow 1.1 introduced write_metadata. Open vSwitch 2.1 added support
2071 for write_metadata.
2072 Thegoto_tableinstruction
2074 Syntax:
2075 goto_table:table
2076 Jumps to table as the next table in the process pipeline. The table may
2078 be a number between 0 and 254 or a table name.
2079 It is an error if table is less than or equal to the table of the flow
2081 that contains it; that is, goto_table must move forward in the OpenFlow
2082 pipeline. Since goto_table must be the last instruction in a flow, it
2083 never leads to recursion. The resubmit extension action is more flexi‐
2084 ble.
2085 Conformance:
2087 OpenFlow 1.1 introduced goto_table. Open vSwitch 2.1 added support for
2089 goto_table.
2090Open vSwitch 2.15.0 ovs-actions(7)