1OVS-ACTIONS(7)                   Open vSwitch                   OVS-ACTIONS(7)
2
3
4

NAME

6       ovs-actions  -  OpenFlow actions and instructions with Open vSwitch ex‐
7       tensions
8

INTRODUCTION

10       This document aims to comprehensively document all of the OpenFlow  ac‐
11       tions  and  instructions,  both standard and non-standard, supported by
12       Open vSwitch, regardless of origin.  The document includes  information
13       of  interest  to Open vSwitch users, such as the semantics of each sup‐
14       ported action and the syntax used by Open vSwitch tools, and to  devel‐
15       opers  seeking  to  build controllers and switches compatible with Open
16       vSwitch, such as the wire format for each supported message.
17
18   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
27       OpenFlow groups actions in two ways: as an action  list  or  an  action
28       set, described below.
29
30   Action Lists
31       An action list, a concept present in every version of OpenFlow, is sim‐
32       ply an ordered sequence of actions.  The  OpenFlow  specifications  re‐
33       quire  a  switch  to execute actions within an action list in the order
34       specified, and to refuse to execute an action list entirely if it  can‐
35       not  implement  the  actions in that order [OpenFlow 1.0, section 3.3],
36       with one exception: when an action list outputs multiple  packets,  the
37       switch  may  output  the packets in an order different from that speci‐
38       fied.  Usually, this exception is not important, especially in the com‐
39       mon case when the packets are output to different ports.
40
41   Action Sets
42       OpenFlow 1.1 introduced the concept of an action set.  An action set is
43       also a sequence of actions, but the switch  reorders  the  actions  and
44       drops  duplicates according to rules specified in the OpenFlow specifi‐
45       cations.  Because of these semantics, some  standard  OpenFlow  actions
46       cannot  usefully  be included in an action set.  For some, but not all,
47       Open vSwitch extension actions, Open vSwitch defines its own action set
48       semantics and ordering.
49
50       The  OpenFlow pipeline has an action set associated with it as a packet
51       is processed.  After pipeline processing  is  otherwise  complete,  the
52       switch executes the actions in the action set.
53
54       Open  vSwitch  applies actions in an action set in the following order:
55       Except as noted otherwise below, the action set only executes at most a
56       single  action  of  each type, and when more than one action of a given
57       type is present, the one added to the set later  replaces  the  earlier
58       action:
59
60          1.  strip_vlan
61
62          2.  pop_mpls
63
64          3.  decap
65
66          4.  encap
67
68          5.  push_mpls
69
70          6.  push_vlan
71
72          7.  dec_ttl
73
74          8.  dec_mpls_ttl
75
76          9.  dec_nsh_ttl
77
78          10. All  of the following actions are executed in the order added to
79              the action set, with cumulative effect.  That is, when  multiple
80              actions  modify the same part of a field, the later modification
81              takes effect, and when they modify different parts  of  a  field
82              (or different fields), then both modifications are applied:
83
84load
85
86move
87
88mod_dl_dst
89
90mod_dl_src
91
92mod_nw_dst
93
94mod_nw_src
95
96mod_nw_tos
97
98mod_nw_ecn
99
100mod_nw_ttl
101
102mod_tp_dst
103
104mod_tp_src
105
106mod_vlan_pcp
107
108mod_vlan_vid
109
110set_field
111
112set_tunnel
113
114set_tunnel64
115
116          11. set_queue
117
118          12. group,  output,  resubmit, ct_clear, or ct.  If more than one of
119              these actions is present, then the one listed earliest above  is
120              executed  and the others are ignored, regardless of the order in
121              which they were added to the action set.  (If none of these  ac‐
122              tions is present, the action set has no real effect, because the
123              modified packet is not sent anywhere and thus the  modifications
124              are not visible.)
125
126       An action set may only contain the actions listed above.
127
128   Error Handling
129       Packet processing can encounter a variety of errors:
130
131       Bridge not found
132              Open vSwitch supports an extension to the standard OpenFlow con‐
133              troller action called a  continuation,  which  allows  the  con‐
134              troller to interrupt and later resume the processing of a packet
135              through the switch pipeline.  This  error  occurs  when  such  a
136              packet’s  processing cannot be resumed, e.g.  because the bridge
137              processing it has been destroyed.  Open vSwitch reports this er‐
138              ror to the controller as Open vSwitch extension error NXR_STALE.
139
140              This error prevents packet processing entirely.
141
142       Recursion too deep
143              While  processing  a  given packet, Open vSwitch limits the flow
144              table recursion depth to 64, to ensure  that  packet  processing
145              uses  a  finite  amount  of  time and space.  Actions that count
146              against the recursion limit include resubmit from a given  Open‐
147              Flow table to the same or an earlier table, group, and output to
148              patch ports.
149
150              A resubmit from one table to a later one  (or,  equivalently,  a
151              goto_table  instruction)  does not count against the depth limit
152              because resubmits to strictly  monotonically  increasing  tables
153              will  eventually  terminate.   OpenFlow tables are most commonly
154              traversed in numerically increasing order,  so  this  limit  has
155              little effect on conventionally designed OpenFlow pipelines.
156
157              This  error terminates packet processing.  Any previous side ef‐
158              fects (e.g. output actions) are retained.
159
160              Usually this error indicates a loop or other bug in the OpenFlow
161              flow  tables.  To assist debugging, when this error occurs, Open
162              vSwitch 2.10 and later logs a trace of the packet execution,  as
163              if  by  ovs-appctl ofproto/trace, rate-limited to one per minute
164              to reduce the log volume.
165
166       Too many resubmits
167              Open vSwitch limits the total number of resubmit actions that  a
168              given packet can execute to 4,096.  For this purpose, goto_table
169              instructions and output to the table port are treated  like  re‐
170              submit.   This  limits  the  amount  of time to process a single
171              packet.
172
173              Unlike the limit on recursion  depth,  the  limit  on  resubmits
174              counts all resubmits, regardless of direction.
175
176              This  error has the same effect, including logging, as exceeding
177              the recursion depth limit.
178
179       Stack too deep
180              Open vSwitch limits the amount of data that the push action  can
181              put onto the stack at one time to 64 kB of data.
182
183              This  error terminates packet processing.  Any previous side ef‐
184              fects (e.g. output actions) are retained.
185
186       No recirculation context / Recirculation conflict
187              These errors indicate internal errors inside  Open  vSwitch  and
188              should  generally  not  occur.  If you notice recurring log mes‐
189              sages about these errors, please report a bug.
190
191       Too many MPLS labels
192              Open vSwitch can process packets with any number of MPLS labels,
193              but  its  ability  to  push and pop MPLS labels is limited, cur‐
194              rently to 3 labels.  Attempting to push more than the  supported
195              number  of  labels onto a packet, or to pop any number of labels
196              from a packet with more than the supported number,  raises  this
197              error.
198
199              This  error terminates packet processing, retaining any previous
200              side effects (e.g. output  actions).   When  this  error  arises
201              within  the execution of a group bucket, it only terminates that
202              bucket’s execution, not packet processing overall.
203
204       Invalid tunnel metadata
205              Open vSwitch raises this error when it processes a Geneve packet
206              that has TLV options with an invalid form, e.g. where the length
207              in a TLV would extend past the end of the options.
208
209              This error prevents packet processing entirely.
210
211       Unsupported packet type
212              When a encap action encapsulates a packet, Open  vSwitch  raises
213              this error if it does not support the combination of the new en‐
214              capsulation with the  current  packet.   encap(ethernet)  raises
215              this  error  if  the current packet is not an L3 packet, and en‐
216              cap(nsh) raises this error if the current packet is  not  Ether‐
217              net, IPv4, IPv6, or NSH.
218
219              The  decap  action  is supported only for packet types ethernet,
220              NSH and MPLS.  Openvswitch raises this error  for  other  packet
221              types.   When a decap action decapsulates a packet, Open vSwitch
222              raises this error if it does  not  support  the  type  of  inner
223              packet.  decap of an Ethernet header raises this error if a VLAN
224              header is present, decap of a NSH packet raises  this  error  if
225              the NSH inner packet is not Ethernet, IPv4, IPv6, or NSH.
226
227              This  error terminates packet processing, retaining any previous
228              side effects (e.g. output  actions).   When  this  error  arises
229              within  the execution of a group bucket, it only terminates that
230              bucket’s execution, not packet processing overall.
231
232   Inconsistencies
233       OpenFlow 1.0 allows any action to be part of any  flow,  regardless  of
234       the  flow’s  match.   Some  combinations  do  not  make  sense, e.g. an
235       set_nw_tos action in a flow that matches only ARP packets or strip_vlan
236       in  a  flow that matches packets without VLAN tags.  Other combinations
237       have varying results depending on the kind of packet that the flow pro‐
238       cesses,  e.g.  a  set_nw_src  action  in  a flow that does not match on
239       Ethertype will be treated as a  no-op  when  it  processes  a  non-IPv4
240       packet.   Nevertheless  OVS allows all of the above in conformance with
241       OpenFlow 1.0, that is, the following will succeed:
242
243          $ ovs-ofctl -O OpenFlow10 add-flow br0 arp,actions=mod_nw_tos:12
244          $ ovs-ofctl -O OpenFlow10 add-flow br0 dl_vlan=0xffff,actions=strip_vlan
245          $ ovs-ofctl -O OpenFlow10 add-flow br0 actions=mod_nw_src:1.2.3.4
246
247       Open vSwitch calls these kinds of combinations inconsistencies  between
248       match  and actions.  OpenFlow 1.1 and later forbid inconsistencies, and
249       disallow the examples described above by preventing such flows from be‐
250       ing added.  All of the above, for example, will fail with an error mes‐
251       sage if one replaces OpenFlow10 by OpenFlow11.
252
253       OpenFlow 1.1 and later cannot detect and disallow all  inconsistencies.
254       For example, the write_actions instruction arbitrarily delays execution
255       of the actions inside it, which can even  be  canceled  with  clear_ac‐
256       tions,  so  that there is no way to ensure that its actions are consis‐
257       tent with the packet at the time  they  execute.   Thus,  actions  with
258       write_actions  and  some other contexts are exempt from consistency re‐
259       quirements.
260
261       When OVS executes an action inconsistent with the packet, it treats  it
262       as a no-op.
263
264   Inter-Version Compatibility
265       Open  vSwitch  supports  multiple OpenFlow versions simultaneously on a
266       single switch.  When actions are added with one  OpenFlow  version  and
267       then  retrieved  with  another, Open vSwitch does its best to translate
268       between them.
269
270       Inter-version compatibility issues can still arise when different  con‐
271       nections  use  different  OpenFlow versions.  Backward compatibility is
272       the most obvious case.  Suppose, for example, that an OpenFlow 1.1 ses‐
273       sion adds a flow with a push_vlan action, for which there is no equiva‐
274       lent in OpenFlow 1.0.  If an OpenFlow 1.0 session retrieves this  flow,
275       Open vSwitch must somehow represent the action.
276
277       Forward compatibility can also be an issue, because later OpenFlow ver‐
278       sions sometimes remove functionality.  The best example is the  enqueue
279       action from OpenFlow 1.0, which OpenFlow 1.1 removed.
280
281       In  practice,  Open vSwitch uses a variety of strategies for inter-ver‐
282       sion compatibility:
283
284       • Most standard OpenFlow actions, such  as  output  actions,  translate
285         without compatibility issues.
286
287       • Open  vSwitch  supports  its extension actions in every OpenFlow ver‐
288         sion, so they do not pose inter-version compatibility problems.
289
290       • Open vSwitch sometimes adds extension actions to ensure  backward  or
291         forward  compatibility.  For example, for backward compatibility with
292         the group action added in OpenFlow  1.1,  Open  vSwitch  includes  an
293         OpenFlow 1.0 extension group action.
294
295       Perfect  inter-version  compatibility  is not possible, so best results
296       require OpenFlow connections to use a consistent version.  One may  en‐
297       force use of a particular version by setting the protocols column for a
298       bridge, e.g. to force br0 to use only OpenFlow 1.3:
299
300          ovs-vsctl set bridge br0 protocols=OpenFlow13
301
302   Field Specifications
303       Many Open vSwitch actions refer to fields.  In such cases,  fields  may
304       usually  be  referred to by their common names, such as eth_dst for the
305       Ethernet destination field, or by their full OXM or NXM names, such  as
306       NXM_OF_ETH_DST or OXM_OF_ETH_DST.  Before Open vSwitch 2.7, only OXM or
307       NXM field names were accepted.
308
309       Many actions that act on fields can also act  on  subfields,  that  is,
310       parts of fields, written as field[start..end], where start is the first
311       bit and end is the last bit to use in field, e.g. vlan_tci[13..15]  for
312       the  VLAN PCP.  A single-bit subfield may also be written as field[off‐
313       set], e.g. vlan_tci[13] for the least-significant bit of the VLAN  PCP.
314       Empty  brackets  may  be  used to explicitly designate an entire field,
315       e.g.  vlan_tci[] for the entire 16-bit VLAN TCI  header.   Before  Open
316       vSwitch 2.7, brackets were required in field specifications.
317
318       See ovs-fields(7) for a list of fields and their names.
319
320   Port Specifications
321       Many  Open vSwitch actions refer to OpenFlow ports.  In such cases, the
322       port may be specified as a numeric  port  number  in  the  range  0  to
323       65,535,  although Open vSwitch only assigns port numbers in the range 1
324       through 62,279 to ports.  OpenFlow 1.1 and later use 32-bit  port  num‐
325       bers,  but  Open vSwitch never assigns a port number that requires more
326       than 16 bits.
327
328       In most contexts, the name of a port may also be used.  (The most obvi‐
329       ous  context  where a port name may not be used is in an ovs-ofctl com‐
330       mand along with the --no-names option.)  When a  port’s  name  contains
331       punctuation  or  could be ambiguous with other actions, the name may be
332       enclosed in double quotes, with JSON-like string escapes supported (see
333       [RFC 8259]).
334
335       Open  vSwitch  also supports the following standard OpenFlow port names
336       (even in contexts where port names are not otherwise  supported).   The
337       corresponding  OpenFlow  1.0 and 1.1+ port numbers are listed alongside
338       them but should not be used in flow syntax:
339
340in_port (65528 or 0xfff8; 0xfffffff8)
341
342table (65529 or 0xfff9; 0xfffffff9)
343
344normal (65530 or 0xfffa; 0xfffffffa)
345
346flood (65531 or 0xfffb; 0xfffffffb)
347
348all (65532 or 0xfffc; 0xfffffffc)
349
350controller (65533 or 0xfffd; 0xfffffffd)
351
352local (65534 or 0xfffe; 0xfffffffe)
353
354any or none (65535 or 0xffff; 0xffffffff)
355
356unset (not in OpenFlow 1.0; 0xfffffff7)
357

OUTPUT ACTIONS

359       These actions send a packet to a physical  port  or  a  controller.   A
360       packet  that  never encounters an output action on its trip through the
361       Open vSwitch pipeline is effectively dropped.  Because actions are exe‐
362       cuted  in  order,  a  packet modification action that is not eventually
363       followed by an output action will not have an  externally  visible  ef‐
364       fect.
365
366   The output action
367       Syntax:
368              port
369              output:port
370              output:field
371              output(port=port, max_len=nbytes)
372
373
374       Outputs the packet to an OpenFlow port most commonly specified as port.
375       Alternatively, the output port may be read from field, a field or  sub‐
376       field in the syntax described under Field Specifications above.  Either
377       way, if the port is the packet’s input port, the packet is not output.
378
379       The port may be one of the following standard OpenFlow ports:
380
381          local  Outputs the packet on the local port that corresponds to  the
382                 network  device  that has the same name as the bridge, unless
383                 the packet was received on the local port.   OpenFlow  switch
384                 implementations  are  not  required to have a local port, but
385                 Open vSwitch bridges always do.
386
387          in_port
388                 Outputs the packet on the port  on  which  it  was  received.
389                 This is the only standard way to output the packet to the in‐
390                 put port (but see Output to the Input port, below).
391
392       The port may also be one of the following  additional  OpenFlow  ports,
393       unless max_len is specified:
394
395          normal Subjects  the packet to the device’s normal L2/L3 processing.
396                 This action is not implemented by all OpenFlow switches,  and
397                 each  switch  implements it differently.  The section The OVS
398                 Normal Pipeline below documents the OVS implementation.
399
400          flood  Outputs the packet on all switch physical ports,  except  the
401                 port on which it was received and any ports on which flooding
402                 is disabled.  Flooding can be  disabled  automatically  on  a
403                 port  by Open vSwitch when IEEE 802.1D spanning tree (STP) or
404                 rapid spanning tree (RSTP) is enabled, or by a controller us‐
405                 ing  an  OpenFlow OFPT_MOD_PORT request to set the port’s OF‐
406                 PPC_NO_FLOOD flag (ovs-ofctl mod-port provides a command-line
407                 interface to set this flag).
408
409          all    Outputs  the  packet  on all switch physical ports except the
410                 port on which it was received.
411
412          controller
413                 Sends the packet and its metadata to an  OpenFlow  controller
414                 or controllers encapsulated in an OpenFlow packet-in message.
415                 The separate controller  action,  described  below,  provides
416                 more options for output to a controller.
417
418       Open vSwitch rejects output to other standard OpenFlow ports, including
419       none, unset, and port numbers  reserved  for  future  use  as  standard
420       ports, with the error OFPBAC_BAD_OUT_PORT.
421
422       With  max_len,  the  packet is truncated to at most nbytes bytes before
423       being output.  In this case, the output port may not be a  patch  port.
424       Truncation  is just for the single output action, so that later actions
425       in the OpenFlow pipeline work with the complete packet.  The truncation
426       feature is meant for use in monitoring applications, e.g. for mirroring
427       packets to a collector.
428
429       When an output action specifies the number of a port that does not cur‐
430       rently exist (and is not in the range for standard ports), the OpenFlow
431       specification allows but does not require OVS  to  reject  the  action.
432       All  versions  of  Open  vSwitch treat such an action as a no-op.  If a
433       port with the number is created later, then the action will be  honored
434       at  that point.  (OpenFlow requires OVS to reject output to a port num‐
435       ber that will never be valid, with OFPBAC_BAD_OUT_PORT, but this situa‐
436       tion  does  not arise when OVS is a software switch, since the user can
437       add or renumber ports at any time.)
438
439       A controller can suppress output to a port by setting its OFPPC_NO_FOR‐
440       WARD  flag  using an OpenFlow OFPT_MOD_PORT request (ovs-ofctl mod-port
441       provides a command-line interface to set this flag).   When  output  is
442       disabled,  output  actions  (and other actions that output to the port)
443       are allowed but have no effect.
444
445       Open vSwitch allows output to a port  that  does  not  exist,  although
446       OpenFlow allows switches to reject such actions.
447
448       Conformance
449              All  versions  of  OpenFlow and Open vSwitch support output to a
450              literal port.  Output to a register is an OpenFlow extension in‐
451              troduced  in  Open  vSwitch  1.3.   Output with truncation is an
452              OpenFlow extension introduced in Open vSwitch 2.6.
453
454   Output to the Input Port
455       OpenFlow requires a switch to ignore attempts to send a packet out  its
456       ingress  port in the most straightforward way.  For example, output:234
457       has no effect if the packet has ingress port  234.   The  rationale  is
458       that dropping these packets makes it harder to loop the network.  Some‐
459       times this behavior can even be convenient, e.g. it is  often  the  de‐
460       sired  behavior  in  a  flow  that  forwards  a packet to several ports
461       (floods the packet).
462
463       Sometimes one really needs to send a packet out its ingress port (hair‐
464       pin).  In this case, use in_port to explicitly output the packet to its
465       input port, e.g.:
466
467          $ ovs-ofctl add-flow br0 in_port=2,actions=in_port
468
469       This also works in some circumstances where the flow doesn’t  match  on
470       the  input  port.   For  example, if you know that your switch has five
471       ports numbered 2 through 6, then the following will send every received
472       packet out every port, even its ingress port:
473
474          $ ovs-ofctl add-flow br0 actions=2,3,4,5,6,in_port
475
476       or, equivalently:
477
478          $ ovs-ofctl add-flow br0 actions=all,in_port
479
480       Sometimes,  in complicated flow tables with multiple levels of resubmit
481       actions, a flow needs to output to a particular port that  may  or  may
482       not be the ingress port.  It’s difficult to take advantage of output to
483       in_port in this situation.  To help, Open vSwitch provides, as an Open‐
484       Flow  extension,  the  ability  to  modify the in_port field.  Whatever
485       value is currently in the in_port field is both the port to which  out‐
486       put  will  be dropped and the destination for in_port.  This means that
487       the following adds flows that reliably output to port 2 or to  ports  2
488       through 6, respectively:
489
490          $ ovs-ofctl add-flow br0 "in_port=2,actions=load:0->in_port,2"
491          $ ovs-ofctl add-flow br0 "actions=load:0->in_port,2,3,4,5,6"
492
493       If in_port is important for matching or other reasons, one may save and
494       restore it on the stack:
495
496          $ ovs-ofctl add-flow br0 \
497                actions="push:in_port,load:0->in_port,2,3,4,5,6,pop:in_port"
498
499   The OVS Normal Pipeline
500       This section documents how Open vSwitch implements output to the normal
501       port.   The  OpenFlow  specification places no requirements on how this
502       port works, so all of this documentation is specific to Open vSwitch.
503
504       Open   vSwitch   uses   the   Open_vSwitch   database,   detailed    in
505       ovs-vswitchd.conf.db(5),  to  determine the details of the normal pipe‐
506       line.
507
508       The normal pipeline executes the  following  ingress  stages  for  each
509       packet.  Each stage either accepts the packet, in which case the packet
510       goes on to the next stage, or drops the packet,  which  terminates  the
511       pipeline.   The  result of the ingress stages is a set of output ports,
512       which is the empty set if some ingress stage drops the packet:
513
514       1.  Input port lookup: Looks up the OpenFlow in_port field’s  value  to
515           the corresponding Port and Interface record in the database.
516
517           The  in_port  is normally the OpenFlow port that the packet was re‐
518           ceived on.  If set_field or another actions  changes  the  in_port,
519           the updated value is honored.  Accept the packet if the lookup suc‐
520           ceeds, which it normally will.  If the lookup  fails,  for  example
521           because in_port was changed to an unknown value, drop the packet.
522
523       2.  Drop  malformed  packet:  If the packet is malformed enough that it
524           contains only part of an 802.1Q header, then drop the  packet  with
525           an error.
526
527       3.  Drop  packets  sent to a port reserved for mirroring: If the packet
528           was received on a port that is configured as the output port for  a
529           mirror (that is, it is the output_port in some Mirror record), then
530           drop the packet.
531
532       4.  VLAN input processing: This stage determines what VLAN  the  packet
533           is  in.   It also verifies that this VLAN is valid for the port; if
534           not, drop the packet.  How the VLAN is determined  and  which  ones
535           are  valid  vary  based  on  the vlan-mode in the input port’s Port
536           record:
537
538              trunk  The packet is in the VLAN specified in its 802.1Q header,
539                     or  in  VLAN  0 if there is no 802.1Q header.  The trunks
540                     column in the Port record lists the valid VLANs; if it is
541                     empty, all VLANs are valid.
542
543              access The  packet is in the VLAN specified in the tag column of
544                     its Port record.  The packet  must  not  have  an  802.1Q
545                     header  with  a  nonzero  VLAN  ID;  if it does, drop the
546                     packet.
547
548              native-tagged / native-untagged
549                     Same as trunk except that the VLAN of a packet without an
550                     802.1Q  header  is  not  necessarily zero; instead, it is
551                     taken from the tag column.
552
553              dot1q-tunnel
554                     The packet is in the VLAN specified in the tag column  of
555                     its  Port  record,  which is a QinQ service VLAN with the
556                     Ethertype   specified   by    the    Port’s    other_con‐
557                     fig:qinq-ethtype.   If  the  packet has an 802.1Q header,
558                     then it specifies the customer VLAN.  The  cvlans  column
559                     specifies  the  valid customer VLANs; if it is empty, all
560                     customer VLANs are valid.
561
562       5.  Drop reserved multicast addresses: If the packet is addressed to  a
563           reserved  Ethernet multicast address and the Bridge record does not
564           have other_config:forward-bpdu set to true, drop the packet.
565
566       6.  LACP bond admissibility: This step applies only if the  input  port
567           is  a  member  of  a bond (a Port with more than one Interface) and
568           that bond is configured to use LACP. Otherwise, skip  to  the  next
569           step.
570
571           The behavior here depends on the state of LACP negotiation:
572
573              • If  LACP  has been negotiated with the peer, accept the packet
574                if the bond member is enabled  (i.e.  carrier  is  up  and  it
575                hasn’t  been  administratively disabled).  Otherwise, drop the
576                packet.
577
578              • If LACP negotiation  is  incomplete,  then  drop  the  packet.
579                There  is  one exception: if fallback to active-backup mode is
580                enabled, continue with the next step, pretending that the  ac‐
581                tive-backup balancing mode is in use.
582
583       7.  Non-LACP bond admissibility: This step applies if the input port is
584           a member of a bond without LACP configured, or if a LACP bond falls
585           back  to  active-backup as described in the previous step.  If nei‐
586           ther of these applies, skip to the next step.
587
588           If the packet is an Ethernet multicast or broadcast,  and  not  re‐
589           ceived on the bond’s active member, drop the packet.
590
591           The remaining behavior depends on the bond’s balancing mode:
592
593              L4 (aka TCP balancing)
594                     Drop  the  packet  (this balancing mode is only supported
595                     with LACP).
596
597              Active-backup
598                     Accept the packet only if it was received on  the  active
599                     member.
600
601              SLB (Source Load Balancing)
602                     Drop  the  packet  if  the  bridge  has  not  learned the
603                     packet’s source address (in its VLAN) on  the  port  that
604                     received it.  Otherwise, accept the packet unless it is a
605                     gratuitous ARP.  Otherwise, accept the packet if the  MAC
606                     entry  we  found  is  ARP-locked.   Otherwise,  drop  the
607                     packet.  (See the SLB Bonding section in the OVS  bonding
608                     document for more information and a rationale.)
609
610       8.  Learn source MAC: If the source Ethernet address is not a multicast
611           address, then insert a mapping from packet’s  source  Ethernet  ad‐
612           dress  and  VLAN to the input port in the bridge’s MAC learning ta‐
613           ble.  (This is skipped if  the  packet’s  VLAN  is  listed  in  the
614           switch’s Bridge record in the flood_vlans column, since there is no
615           use for MAC learning when all packets are flooded.)
616
617           When learning happens on a non-bond port, if the packet is a gratu‐
618           itous ARP, the entry is marked as ARP-locked.  The lock expires af‐
619           ter 5 seconds.  (See the SLB Bonding section  in  the  OVS  bonding
620           document for more information and a rationale.)
621
622       9.  IP  multicast path: If multicast snooping is enabled on the bridge,
623           and the packet is an Ethernet multicast but not an Ethernet  broad‐
624           cast,  and the packet is an IP packet, then the packet takes a spe‐
625           cial processing path.  This path is not yet documented here.
626
627       10. Output port set: Search the MAC learning table for the port  corre‐
628           sponding  to  the  packet’s  Ethernet destination and VLAN.  If the
629           search finds an entry, the output port  set  is  just  the  learned
630           port.   Otherwise (including the case where the packet is an Ether‐
631           net multicast or in flood_vlans), the output port set is all of the
632           ports  in  the  bridge that belong to the packet’s VLAN, except for
633           any ports that were disabled for flooding via OpenFlow or that  are
634           configured in a Mirror record as a mirror destination port.
635
636       The following egress stages execute once for each element in the set of
637       output ports.  They execute (conceptually) in parallel, so that a deci‐
638       sion or action taken for a given output port has no effect on those for
639       another one:
640
641       1. Drop loopback: If the output port is the same  as  the  input  port,
642          drop the packet.
643
644       2. VLAN  output  processing: This stage adjusts the packet to represent
645          the VLAN in the correct way  for  the  output  port.   Its  behavior
646          varies based on the vlan-mode in the output port’s Port record:
647
648             trunk / native-tagged / native-untagged
649                    If  the  packet  is in VLAN 0 (for native-untagged, if the
650                    packet is in the native VLAN)  drops  any  802.1Q  header.
651                    Otherwise,  ensures  that there is an 802.1Q header desig‐
652                    nating the VLAN.
653
654             access Remove any 802.1Q header that was present.
655
656             dot1q-tunnel
657                    Ensures that the packet has an outer  802.1Q  header  with
658                    the  QinQ  Ethertype and the specified configured tag, and
659                    an inner 802.1Q header with the packet’s VLAN.
660
661       3. VLAN priority tag processing: If VLAN  output  processing  discarded
662          the  802.1Q  headers,  but priority tags are enabled with other_con‐
663          fig:priority-tags in the output port’s Port record,  then  a  prior‐
664          ity-only  tag  is  added (perhaps only if the priority would be non‐
665          zero, depending on the configuration).
666
667       4. Bond member choice: If the output port is a bond, the code chooses a
668          particular member.  This step is skipped for non-bonded ports.
669
670          If  the  bond is configured to use LACP, but LACP negotiation is in‐
671          complete, then normally the packet is  dropped.   The  exception  is
672          that  if fallback to active-backup mode is enabled, the egress pipe‐
673          line continues choosing a bond member as if active-backup  mode  was
674          in use.
675
676          For  active-backup  mode,  the  output  member is the active member.
677          Other modes hash appropriate header fields and use the hash value to
678          choose one of the enabled members.
679
680       5. Output: The pipeline sends the packet to the output port.
681
682   The controller action
683       Syntax:
684              controller
685              controller:max_len
686              controller(key[=value], ...)
687
688
689       Sends  the  packet  and  its metadata to an OpenFlow controller or con‐
690       trollers encapsulated in an OpenFlow packet-in message.  The  supported
691       options are:
692
693          max_len=max_len
694                 Limit to max_len the number of bytes of the packet to send in
695                 the packet-in.  A max_len of 0 prevents  any  of  the  packet
696                 from  being  sent  (thus, only metadata is included).  By de‐
697                 fault, the entire packet is sent, equivalent to a max_len  of
698                 65535.
699
700          reason=reason
701                 Specify  reason  as the reason for sending the message in the
702                 packet-in.  The supported reasons are no_match,  action,  in‐
703                 valid_ttl,  action_set,  group,  and packet_out.  The default
704                 reason is action.
705
706          id=controller_id
707                 Specify controller_id, a 16-bit integer, as the connection ID
708                 of  the  OpenFlow  controller  or  controllers  to  which the
709                 packet-in message should be sent.  The default is zero.  Zero
710                 is also the default connection ID for each controller connec‐
711                 tion, and a given controller connection will only have a non‐
712                 zero  connection  ID  if its controller uses the NXT_SET_CON‐
713                 TROLLER_ID Open vSwitch extension to OpenFlow.
714
715          userdata=hh...
716                 Supplies the bytes represented as hex digits hh as additional
717                 data  to  the  controller in the packet-in message.  Pairs of
718                 hex digits may be separated by periods for readability.
719
720          pause  Causes the switch to freeze the packet’s  trip  through  Open
721                 vSwitch  flow  tables  and  serializes  that  state  into the
722                 packet-in message as a continuation, an  additional  property
723                 in the NXT_PACKET_IN2 message.  The controller can later send
724                 the continuation back to the switch in an NXT_RESUME message,
725                 which  will  restart  the  packet’s  traversal from the point
726                 where it was interrupted.   This  permits  an  OpenFlow  con‐
727                 troller to interpose on a packet midway through processing in
728                 Open vSwitch.
729
730       Conformance
731              All versions of OpenFlow and Open vSwitch support controller ac‐
732              tion and its max_len option.  The userdata and pause options re‐
733              quire the Open vSwitch NXAST_CONTROLLER2 extension action  added
734              in Open vSwitch 2.6. In the absence of these options, the reason
735              (other than reason=action) and controller_id (option  than  con‐
736              troller_id=0)  options require the Open vSwitch NXAST_CONTROLLER
737              extension action added in Open vSwitch 1.6.
738
739   The enqueue action
740       Syntax:
741              enqueue(port,queue)
742              enqueue:port:queue
743
744
745       Enqueues the packet on the specified queue within port port.
746
747       port must be an OpenFlow port number or name as  described  under  Port
748       Specifications above.  port may be in_port or local but the other stan‐
749       dard OpenFlow ports are not allowed.
750
751       queue must be a number between 0 and  4294967294  (0xfffffffe),  inclu‐
752       sive.   The  number of actually supported queues depends on the switch.
753       Some OpenFlow implementations do not support queuing at all.   In  Open
754       vSwitch,  the  supported queues vary depending on the operating system,
755       datapath, and hardware in use.  Use the QoS and  Queue  tables  in  the
756       Open vSwitch database to configure queuing on individual OpenFlow ports
757       (see ovs-vswitchd.conf.db(5) for more information).
758
759       Conformance
760              Only OpenFlow 1.0 supports  enqueue.   OpenFlow  1.1  added  the
761              set_queue action to use in its place along with output.
762
763              Open  vSwitch  translates enqueue to a sequence of three actions
764              in OpenFlow 1.1 or later: set_queue:queue,output:port,pop_queue.
765              This  is  equivalent  in behavior as long as the flow table does
766              not otherwise use set_queue, but it relies on the pop_queue Open
767              vSwitch extension action.
768
769   The bundle and bundle_load actions
770       Syntax:
771              bundle(fields,basis,algorithm,ofport,members:port...)
772              bundle_load(fields,basis,algorithm,ofport,dst,members:port...)
773
774
775       These  actions choose a port (a member) from a comma-separated OpenFlow
776       port list.  After selecting the port, bundle  outputs  to  it,  whereas
777       bundle_load  writes  its  port number to dst, which must be a 16-bit or
778       wider field or subfield in the syntax described under Field  Specifica‐
779       tions above.
780
781       These  actions hash a set of fields using basis as a universal hash pa‐
782       rameter, then apply the bundle link selection  algorithm  to  choose  a
783       port.
784
785       fields must be one of the following.  For the options with symmetric in
786       the name, reversing source and destination addresses  yields  the  same
787       hash:
788
789          eth_src
790                 Ethernet source address.
791
792          nw_src IPv4 or IPv6 source address.
793
794          nw_dst IPv4 or IPv6 destination address.
795
796          symmetric_l4
797                 Ethernet  source  and  destination, Ethernet type, VLAN ID or
798                 IDs (if any), IPv4 or IPv6 source and destination, IP  proto‐
799                 col, TCP or SCTP (but not UDP) source and destination.
800
801          symmetric_l3l4
802                 IPv4 or IPv6 source and destination, IP protocol, TCP or SCTP
803                 (but not UDP) source and destination.
804
805          symmetric_l3l4+udp
806                 Like symmetric_l3l4 but include UDP ports.
807
808       algorithm must be one of the following:
809
810          active_backup
811                 Chooses the first live port listed in members.
812
813          hrw (Highest Random Weight)
814                 Computes the following, considering only the  live  ports  in
815                 members:
816
817                     for i in [1, n_members]:
818                         weights[i] = hash(flow, i)
819                     member = { i such that weights[i] >= weights[j] for all j != i }
820
821                 This algorithm is specified by RFC 2992.
822
823       The  algorithms take port liveness into account when selecting members.
824       The definition of whether a port is live is subject to change.  It cur‐
825       rently  takes into account carrier status and link monitoring protocols
826       such as BFD and CFM.  If none of the members is live, bundle  does  not
827       output  the packet and bundle_load stores OFPP_NONE (65535) in the out‐
828       put field.
829
830       Example:  bundle(eth_src,0,hrw,ofport,members:4,8)  uses  an   Ethernet
831       source  hash with basis 0, to select between OpenFlow ports 4 and 8 us‐
832       ing the Highest Random Weight algorithm.
833
834       Conformance
835              Open vSwitch 1.2 introduced the bundle and bundle_load  OpenFlow
836              extension actions.
837
838   The group action
839       Syntax:
840              group:group
841
842
843       Outputs  the packet to the OpenFlow group group, which must be a number
844       in the range 0 to 4294967040 (0xffffff00).  The  group  must  exist  or
845       Open  vSwitch  will  refuse  to add the flow.  When a group is deleted,
846       Open vSwitch also deletes all of the flows that output to it.
847
848       Groups contain action sets, whose semantics are described above in  the
849       section Action Sets.  The semantics of action sets can be surprising to
850       users who expect action list semantics, since action sets  reorder  and
851       sometimes ignore actions.
852
853       A  group  action usually executes the action set or sets in one or more
854       group buckets.  Open vSwitch saves the packet and  metadata  before  it
855       executes  each  bucket,  and  then restores it afterward.  Thus, when a
856       group executes more than one bucket, this means that each  bucket  exe‐
857       cutes  on  the  same  packet and metadata.  Moreover, regardless of the
858       number of buckets executed, the packet and metadata are the same before
859       and after executing the group.
860
861       Sometimes  saving and restoring the packet and metadata can be undesir‐
862       able.  In these situations, workarounds  are  possible.   For  example,
863       consider  a pipeline design in which a select group bucket is to commu‐
864       nicate to a later stage of processing a value based on which bucket was
865       selected.  An obvious design would be for the bucket to communicate the
866       value via set_field on a register.  This does not work  because  regis‐
867       ters  are part of the metadata that group saves and restores.  The fol‐
868       lowing alternative bucket designs do work:
869
870          • Recursively invoke the rest of the pipeline with resubmit.
871
872          • Use resubmit into a table that uses push to put the value  on  the
873            stack  for  the  caller to pop off.  This works because group pre‐
874            serves only packet data and metadata, not the stack.
875
876            (This design requires indirection through resubmit because actions
877            sets may not contain push or pop actions.)
878
879       An  exit action within a group bucket terminates only execution of that
880       bucket, not other buckets or the overall pipeline.
881
882       Conformance
883              OpenFlow 1.1 introduced group.  Open vSwitch 2.6 and later  also
884              supports group as an extension to OpenFlow 1.0.
885

ENCAPSULATION AND DECAPSULATION ACTIONS

887   The strip_vlan and pop actions
888       Syntax:
889              strip_vlan
890              pop_vlan
891
892
893       Removes the outermost VLAN tag, if any, from the packet.
894
895       The two names for this action are synonyms with no semantic difference.
896       The OpenFlow 1.0 specification uses the name strip_vlan and later  ver‐
897       sions use pop_vlan, but OVS accepts either name regardless of version.
898
899       In OpenFlow 1.1 and later, consistency rules allow strip_vlan only in a
900       flow that matches only packets with a VLAN tag (or following an  action
901       that  pushes  a  VLAN  tag,  such  as push_vlan).  See Inconsistencies,
902       above, for more information.
903
904       Conformance
905              All versions of OpenFlow and Open vSwitch support this action.
906
907   The push_vlan action
908       Syntax:
909              push_vlan:ethertype
910
911
912       Pushes a new outermost VLAN onto  the  packet.   Uses  TPID  ethertype,
913       which must be 0x8100 for an 802.1Q C-tag or 0x88a8 for a 802.1ad S-tag.
914
915       Conformance
916              OpenFlow  1.1  and later supports this action.  Open vSwitch 2.8
917              added support for multiple VLAN tags (with a  limit  of  2)  and
918              802.1ad S-tags.
919
920   The push_mpls action
921       Syntax:
922              push_mpls:ethertype
923
924
925       Pushes a new outermost MPLS label stack entry (LSE) onto the packet and
926       changes the packet’s Ethertype  to  ethertype,  which  must  be  either
927       B0x8847  or 0x8848.  If the packet did not already contain any MPLS la‐
928       bels, initializes the new LSE as:
929
930          Label  2, if the packet contains IPv6, 0 otherwise.
931
932          TC     The low 3 bits of the packet’s DSCP value, or 0 if the packet
933                 is not IP.
934
935          TTL    Copied from the IP TTL, or 64 if the packet is not IP.
936
937       If  the  packet  did already contain an MPLS label, initializes the new
938       outermost label as a copy of the existing outermost label.
939
940       OVS currently supports at most 3 MPLS labels.
941
942       This action applies only to Ethernet packets.
943
944       Conformance
945              Open vSwitch 1.11 introduced support for MPLS.  OpenFlow 1.1 and
946              later  support  push_mpls.  Open vSwitch implements push_mpls as
947              an extension to OpenFlow 1.0.
948
949   The pop_mpls action
950       Syntax:
951              pop_mpls:ethertype
952
953
954       Strips the outermost MPLS label stack entry and  changes  the  packet’s
955       Ethertype  to  ethertype.  This action applies only to Ethernet packets
956       with at least one MPLS label.  If there is more than  one  MPLS  label,
957       then ethertype should be an MPLS Ethertype (B0x8847 or 0x8848).
958
959       Conformance
960              Open vSwitch 1.11 introduced support for MPLS.  OpenFlow 1.1 and
961              later support pop_mpls.  Open vSwitch implements pop_mpls as  an
962              extension to OpenFlow 1.0.
963
964   The encap action
965       Syntax:
966              encap(nsh([md_type=md_type], [tlv(class,type,value)]...))
967              encap(ethernet)
968              encap(mpls)
969              encap(mpls_mc)
970
971
972       The encap action encapsulates a packet with a specified header.  It has
973       variants for different kinds of encapsulation.
974
975       The encap(nsh(...)) variant encapsulates an Ethernet  frame  with  NSH.
976       The  md_type  may  be 1 or 2 for metadata type 1 or 2, defaulting to 1.
977       For metadata type 2, TLVs may be specified with class as a 16-bit hexa‐
978       decimal  integer  beginning  with 0x, type as an 8-bit decimal integer,
979       and value a sequence of pairs of hex digits beginning with 0x.  For ex‐
980       ample:
981
982          encap(nsh(md_type=1))
983                 Encapsulates the packet with an NSH header with metadata type
984                 1.
985
986          encap(nsh(md_type=2,tlv(0x1000,10,0x12345678)))
987                 Encapsulates the packet with an NSH header, NSH metadata type
988                 2,  and an NSH TLV with class 0x1000, type 10, and the 4-byte
989                 value 0x12345678.
990
991       The encap(ethernet) variant encapsulate a bare L3 packet in an Ethernet
992       frame.   The Ethernet type is initialized to the L3 packet’s type, e.g.
993       0x0800 if the L3 packet is IPv4.  The Ethernet source  and  destination
994       are initially zeroed.
995
996       The  encap(mpls) variant adds a MPLS header at the start of the packet.
997       When encap(ethernet) is applied after this  action,  the  ethertype  of
998       ethernet header will be populated with MPLS unicast ethertype (0x8847).
999
1000       The  encap(mpls_mc)  variant  adds  a  MPLS  header at the start of the
1001       packet.  When encap(ethernet) is applied after this action, the  ether‐
1002       type of ethernet header will be populated with MPLS multicast ethertype
1003       (0x8848).
1004
1005       Conformance
1006              This action is an Open vSwitch extension  to  OpenFlow  1.3  and
1007              later, introduced in Open vSwitch 2.8.
1008
1009              The MPLS support for this action is added in Open vSwitch 2.17.
1010
1011   The decap action
1012       Syntax:
1013              decap
1014              decap(packet_type(ns=namespace,type=type))
1015
1016
1017       Removes an outermost encapsulation from the packet:
1018
1019          • If  the packet is an Ethernet packet, removes the Ethernet header,
1020            which changes the packet into a bare L3 packet.  If the packet has
1021            VLAN tags, raises an unsupported packet type error (see Error Han‐
1022            dling, above).
1023
1024          • Otherwise, if the packet is an NSH packet, removes the NSH header,
1025            revealing the inner packet.  Open vSwitch supports Ethernet, IPv4,
1026            IPv6, and NSH inner packet types.  Other types  raise  unsupported
1027            packet type errors.
1028
1029          • Otherwise, if the packet is encapsulated inside a MPLS header, re‐
1030            moves the MPLS header and classifies the inner packet as mentioned
1031            in  the  packet type argument of the decap.  The packet_type field
1032            specifies the type of the packet in the format specified in  Open‐
1033            Flow  1.5  chapter  7.2.3.11  Packet  Type Match Field.  The inner
1034            packet will be incorrectly classified, if the inner packet is dif‐
1035            ferent from mentioned in the packet_type field.
1036
1037          • Otherwise, raises an unsupported packet type error.
1038
1039       Conformance
1040              This  action  is  an  Open vSwitch extension to OpenFlow 1.3 and
1041              later, introduced in Open vSwitch 2.8.
1042
1043              The MPLS support for this action is added in Open vSwitch 2.17.
1044

FIELD MODIFICATION ACTIONS

1046       These actions modify packet data and metadata fields.
1047
1048   The set_field and load actions
1049       Syntax:
1050              set_field:value[/mask]->dst
1051              load:value->dst
1052
1053
1054       These actions loads a literal value into a field or part  of  a  field.
1055       The set_field action takes value in the customary syntax for field dst,
1056       e.g. 00:11:22:33:44:55 for an Ethernet address, and dst as the  field’s
1057       name.  The optional mask allows part of a field to be set.
1058
1059       The load action takes value as an integer value (in decimal or prefixed
1060       by 0x for hexadecimal) and dst as a field or subfield in the syntax de‐
1061       scribed under Field Specifications above.
1062
1063       The following all set the Ethernet source address to 00:11:22:33:44:55:
1064
1065set_field:00:11:22:33:44:55->eth_src
1066
1067load:0x001122334455->eth_src
1068
1069load:0x001122334455->OXM_OF_ETH_SRC[]
1070
1071       The following all set the multicast bit in the Ethernet destination ad‐
1072       dress:
1073
1074set_field:01:00:00:00:00:00/01:00:00:00:00:00->eth_dst
1075
1076load:1->eth_dst[40]
1077
1078       Open vSwitch prohibits a set_field or load  action  whose  dst  is  not
1079       guaranteed  to  be part of the packet; for example, set_field of nw_dst
1080       is only allowed in a flow that matches on Ethernet type 0x800.  In some
1081       cases,  such  as  in an action set, Open vSwitch can’t statically check
1082       that dst is part of the packet, and in that case if it is not then Open
1083       vSwitch treats the action as a no-op.
1084
1085       Conformance
1086              Open  vSwitch  1.1  introduced  NXAST_REG_LOAD as a extension to
1087              OpenFlow 1.0 and used load to express it.  Later,  OpenFlow  1.2
1088              introduced a standard OFPAT_SET_FIELD action that was restricted
1089              to loading  entire  fields,  so  Open  vSwitch  added  the  form
1090              set_field  with  this  restriction.   OpenFlow  1.5 extended OF‐
1091              PAT_SET_FIELD to the point that it  became  a  superset  of  NX‐
1092              AST_REG_LOAD.   Open  vSwitch translates either syntax as neces‐
1093              sary for the OpenFlow version in use: in OpenFlow 1.0  and  1.1,
1094              NXAST_REG_LOAD;  in  OpenFlow  1.2, 1.3, and 1.4, NXAST_REG_LOAD
1095              for load or for loading a subfield,  OFPAT_SET_FIELD  otherwise;
1096              and OpenFlow 1.5 and later, OFPAT_SET_FIELD.
1097
1098   The move action
1099       Syntax:
1100              move:src->dst
1101
1102
1103       Copies  the  named bits from field or subfield src to field or subfield
1104       dst.  src and dst should fields or subfields in  the  syntax  described
1105       under  Field  Specifications  above.   The two fields or subfields must
1106       have the same width.
1107
1108       Examples:
1109
1110move:reg0[0..5]->reg1[26..31]  copies  the  six  bits  numbered  0
1111            through 5 in register 0 into bits 26 through 31 of register 1.
1112
1113move:reg0[0..15]->vlan_tci copies the least significant 16 bits of
1114            register 0 into the VLAN TCI field.
1115
1116       Conformance
1117              In OpenFlow 1.0  through  1.4,  move  ordinarily  uses  an  Open
1118              vSwitch  extension  to OpenFlow.  In OpenFlow 1.5, move uses the
1119              OpenFlow 1.5 standard OFPAT_COPY_FIELD action.  The ONF has also
1120              made OFPAT_COPY_FIELD available as an extension to OpenFlow 1.3.
1121              Open vSwitch 2.4 and later understands this extension  and  uses
1122              it  if a controller uses it, but for backward compatibility with
1123              older versions of Open vSwitch, ovs-ofctl does not use it.
1124
1125   The mod_dl_src and mod_dl_dst actions
1126       Syntax:
1127              mod_dl_src:mac
1128              mod_dl_dst:mac
1129
1130
1131       Sets the Ethernet source or destination address, respectively, to  mac,
1132       which should be expressed in the form xx:xx:xx:xx:xx:xx.
1133
1134       For  L3-only packets, that is, those that lack an Ethernet header, this
1135       action has no effect.
1136
1137       Conformance
1138              OpenFlow 1.0 and 1.1 have specialized  actions  for  these  pur‐
1139              poses.   OpenFlow  1.2  and later do not, so Open vSwitch trans‐
1140              lates them to appropriate OFPAT_SET_FIELD actions for those ver‐
1141              sions,
1142
1143   The mod_nw_src and mod_nw_dst actions
1144       Syntax:
1145              mod_nw_src:ip
1146              mod_nw_dst:ip
1147
1148
1149       Sets the IPv4 source or destination address, respectively, to ip, which
1150       should be expressed in the form w.x.y.z.
1151
1152       In OpenFlow 1.1 and later, consistency rules allow these  actions  only
1153       in  a  flow  that  matches only packets that contain an IPv4 header (or
1154       following an action that adds an IPv4  header,  e.g.  pop_mpls:0x0800).
1155       See Inconsistencies, above, for more information.
1156
1157       Conformance
1158              OpenFlow  1.0  and  1.1  have specialized actions for these pur‐
1159              poses.  OpenFlow 1.2 and later do not, so  Open  vSwitch  trans‐
1160              lates them to appropriate OFPAT_SET_FIELD actions for those ver‐
1161              sions,
1162
1163   The mod_nw_tos and mod_nw_ecn actions
1164       Syntax:
1165              mod_nw_tos:tos
1166              mod_nw_ecn:ecn
1167
1168
1169       The mod_nw_tos action sets the DSCP bits in the IPv4 ToS/DSCP  or  IPv6
1170       traffic class field to tos, which must be a multiple of 4 between 0 and
1171       255.  This action does not modify the two least significant bits of the
1172       ToS field (the ECN bits).
1173
1174       The mod_nw_ecn action sets the ECN bits in the IPv4 ToS or IPv6 traffic
1175       class field to ecn, which must be a value between 0 and  3,  inclusive.
1176       This  action does not modify the six most significant bits of the field
1177       (the DSCP bits).
1178
1179       In OpenFlow 1.1 and later, consistency rules allow these  actions  only
1180       in a flow that matches only packets that contain an IPv4 or IPv6 header
1181       (or following an action that adds such a header).  See Inconsistencies,
1182       above, for more information.
1183
1184       Conformance
1185              OpenFlow  1.0  has a mod_nw_tos action but not mod_nw_ecn.  Open
1186              vSwitch implements the latter in OpenFlow 1.0  as  an  extension
1187              using  NXAST_REG_LOAD.  OpenFlow 1.1 has specialized actions for
1188              these purposes.  OpenFlow 1.2 and later do not, so Open  vSwitch
1189              translates them to appropriate OFPAT_SET_FIELD actions for those
1190              versions.
1191
1192   The mod_tp_src and mod_tp_dst actions
1193       Syntax:
1194              mod_tp_src:port
1195              mod_tp_dst:port
1196
1197
1198       Sets the TCP or UDP or SCTP source or destination  port,  respectively,
1199       to port.  Both IPv4 and IPv6 are supported.
1200
1201       In  OpenFlow  1.1 and later, consistency rules allow these actions only
1202       in a flow that matches only packets that contain a TCP or UDP  or  SCTP
1203       header.  See Inconsistencies, above, for more information.
1204
1205       Conformance
1206              OpenFlow  1.0  and  1.1  have specialized actions for these pur‐
1207              poses.  OpenFlow 1.2 and later do not, so  Open  vSwitch  trans‐
1208              lates them to appropriate OFPAT_SET_FIELD actions for those ver‐
1209              sions,
1210
1211   The dec_ttl action
1212       Syntax:
1213              dec_ttl
1214              dec_ttl(id1[,id2[, ...]])
1215
1216
1217       Decrement TTL of IPv4 packet or hop limit of IPv6 packet.  If  the  TTL
1218       or  hop  limit  is  initially  0  or 1, no decrement occurs, as packets
1219       reaching TTL zero must be rejected.   Instead,  Open  vSwitch  sends  a
1220       packet-in  message  with reason code OFPR_INVALID_TTL to each connected
1221       controller that has enabled receiving such messages, and stops process‐
1222       ing  the  current  set of actions.  (However, if the current set of ac‐
1223       tions was reached through resubmit, the remaining actions in outer lev‐
1224       els resume processing.)
1225
1226       As  an  Open  vSwitch  extension  to OpenFlow, this action supports the
1227       ability to specify a list of controller IDs.  Open  vSwitch  will  only
1228       send  the  message to controllers with the given ID or IDs.  Specifying
1229       no list is equivalent to specifying a single controller ID of zero.
1230
1231       In OpenFlow 1.1 and later, consistency rules allow these  actions  only
1232       in  a  flow  that  matches  only  packets  that contain an IPv4 or IPv6
1233       header.  See Inconsistencies, above, for more information.
1234
1235       Conformance
1236              All versions of OpenFlow and Open vSwitch support this action.
1237
1238   The set_mpls_label, set_mpls_tc, and set_mpls_ttl actions
1239       Syntax:
1240              set_mpls_label:label
1241              set_mpls_tc:tc
1242              set_mpls_ttl:ttl
1243
1244
1245       The set_mpls_label action sets the label of the packet’s outer MPLS la‐
1246       bel stack entry.  label should be a 20-bit value that is decimal by de‐
1247       fault; use a 0x prefix to specify the value in hexadecimal.
1248
1249       The set_mpls_tc action sets the traffic class  of  the  packet’s  outer
1250       MPLS label stack entry.  tc should be in the range 0 to 7, inclusive.
1251
1252       The  set_mpls_ttl  action sets the TTL of the packet’s outer MPLS label
1253       stack entry.  ttl should be in the range 0 to 255 inclusive.  In  Open‐
1254       Flow  1.1  and  later,  consistency rules allow these actions only in a
1255       flow that matches only packets that contain an MPLS label (or following
1256       an  action  that  adds  an  MPLS  label,  e.g.  push_mpls:0x8847).  See
1257       Inconsistencies, above, for more information.
1258
1259       Conformance
1260              OpenFlow 1.0 does not support MPLS, but Open vSwitch  implements
1261              these  actions  as extensions.  OpenFlow 1.1 has specialized ac‐
1262              tions for these purposes.  OpenFlow 1.2 and  later  do  not,  so
1263              Open  vSwitch translates them to appropriate OFPAT_SET_FIELD ac‐
1264              tions for those versions,
1265
1266   The dec_mpls_ttl and dec_nsh_ttl actions
1267       Syntax:
1268              dec_mpls_ttl
1269              dec_nsh_ttl
1270
1271
1272       These actions decrement the TTL of the packet’s outer MPLS label  stack
1273       entry or its NSH header, respectively.  If the TTL is initially 0 or 1,
1274       no decrement occurs.  Instead, Open vSwitch sends a  packet-in  message
1275       with  reason  code BOFPR_INVALID_TTL to OpenFlow controllers with ID 0,
1276       if it has enabled receiving them.  Processing the current  set  of  ac‐
1277       tions  then stops.  (However, if the current set of actions was reached
1278       through resubmit, remaining actions in outer levels resume processing.)
1279
1280       In OpenFlow 1.1 and later, consistency rules allow this actions only in
1281       a  flow  that matches only packets that contain an MPLS label or an NSH
1282       header, respectively.  See Inconsistencies, above,  for  more  informa‐
1283       tion.
1284
1285       Conformance
1286              Open vSwitch 1.11 introduced support for MPLS.  OpenFlow 1.1 and
1287              later   support   dec_mpls_ttl.    Open    vSwitch    implements
1288              dec_mpls_ttl as an extension to OpenFlow 1.0.
1289
1290              Open  vSwitch  2.8  introduced support for NSH, although the NSH
1291              draft changed after release so that only Open  vSwitch  2.9  and
1292              later   conform   to  the  final  protocol  specification.   The
1293              dec_nsh_ttl action and NSH support in general is an Open vSwitch
1294              extension not supported by any version of OpenFlow.
1295
1296   The check_pkt_larger action
1297       Syntax:
1298              check_pkt_larger(pkt_len)->dst
1299
1300
1301       Checks  if  the  packet is larger than the specified length in pkt_len.
1302       If so, stores 1 in dst, which should be a 1-bit field; if  not,  stores
1303       0.
1304
1305       The packet length to check against the argument pkt_len includes the L2
1306       header and L2 payload of the packet, but not the VLAN tag (if present).
1307
1308       Examples:
1309
1310          • check_pkt_larger(1500)->reg0[0]
1311
1312          • check_pkt_larger(8000)->reg9[10]
1313
1314       This action was added in Open vSwitch 2.12.
1315
1316   The delete_field action
1317       Syntax:
1318              delete_field:field
1319
1320
1321       The delete_field action deletes a field in the syntax  described  under
1322       Field Specifications above.  Currently, only the tun_metadta fields are
1323       supported.
1324
1325       This action was added in Open vSwitch 2.14.
1326

METADATA ACTIONS

1328   The set_tunnel action
1329       Syntax:
1330              set_tunnel:id
1331              set_tunnel64:id
1332
1333
1334       Many kinds of tunnels support a tunnel ID, e.g. VXLAN and Geneve have a
1335       24-bit  VNI,  and GRE has an optional 32-bit key.  This action sets the
1336       value used for tunnel ID in such tunneled packets, although whether  it
1337       is  used for a particular tunnel depends on the tunnel’s configuration.
1338       See the tunnel ID documentation in ovs-fields(7) for more information.
1339
1340       Conformance
1341              These actions are OpenFlow extensions.   set_tunnel  was  intro‐
1342              duced  in Open vSwitch 1.0.  set_tunnel64, which is needed if id
1343              is wider than 32 bits, was added in Open vSwitch 1.1.  Both  ac‐
1344              tions  always set the entire tunnel ID field.  Open vSwitch sup‐
1345              ports these actions in all versions of OpenFlow, but in OpenFlow
1346              1.2  and later it translates them to an appropriate standardized
1347              OFPAT_SET_FIELD action.
1348
1349   The set_queue and pop_queue actions
1350       Syntax:
1351              set_queue:queue
1352              pop_queue
1353
1354
1355       The set_queue action sets the queue ID to be used for subsequent output
1356       actions  to  queue, which must be a 32-bit integer.  The range of mean‐
1357       ingful values of queue, and their meanings,  varies  greatly  from  one
1358       OpenFlow  implementation  to another.  Even within a single implementa‐
1359       tion, there is no guarantee that  all  OpenFlow  ports  have  the  same
1360       queues  configured  or that all OpenFlow ports in an implementation can
1361       be configured the same way queue-wise.  For more information,  see  the
1362       documentation for the output queue field in ovs-fields(7).
1363
1364       The  pop_queue  restores  the  output queue to the default that was set
1365       when the packet entered the switch (generally 0).
1366
1367       Four   billion   queues   ought    to    be    enough    for    anyone:
1368       https://mailman.stanford.edu/pipermail/openflow-spec/2009-August/000394.html
1369
1370       Conformance
1371              OpenFlow 1.1 introduced the set_queue action.  Open vSwitch also
1372              supports it as an extension in OpenFlow 1.0.
1373
1374              The pop_queue action is an Open vSwitch extension.
1375

FIREWALLING ACTIONS

1377       Open  vSwitch is often used to implement a firewall.  The preferred way
1378       to implement a firewall is connection tracking, that is, to keep  track
1379       of  the connection state of individual TCP sessions.  The ct action de‐
1380       scribed in this section, added in Open vSwitch 2.5, implements  connec‐
1381       tion  tracking.   For new deployments, it is the recommended way to im‐
1382       plement firewalling with Open vSwitch.
1383
1384       Before ct was added, Open vSwitch did not  have  built-in  support  for
1385       connection tracking.  Instead, Open vSwitch supported the learn action,
1386       which allows a received packet to add a flow to an OpenFlow flow table.
1387       This  could  be used to implement a primitive form of connection track‐
1388       ing: packets passing through the firewall in one direction could create
1389       flows  that  allowed  response packets back through the firewall in the
1390       other direction.  The additional fin_timeout action allowed the learned
1391       flows to expire quickly after TCP session termination.
1392
1393   The ct action
1394       Syntax:
1395              ct([argument]...)
1396              ct(commit[,argument]...)
1397
1398
1399       The  action has two modes of operation, distinguished by whether commit
1400       is present.  The following arguments may be present in either mode:
1401
1402          zone=value
1403                 A zone is a 16-bit id that isolates connections into separate
1404                 domains,  allowing overlapping network addresses in different
1405                 zones.  If a zone is not provided, then the default is 0. The
1406                 value  may be specified either as a 16-bit integer literal or
1407                 a field or subfield in the syntax described under Field Spec‐
1408                 ifications above.
1409
1410       Without  commit,  this  action  sends the packet through the connection
1411       tracker.  The connection tracker keeps track of the state of  TCP  con‐
1412       nections for packets passed through it.  For each packet through a con‐
1413       nection, it checks that it satisfies TCP  invariants  and  signals  the
1414       connection  state  to  later actions using the ct_state metadata field,
1415       which is documented in ovs-fields(7).
1416
1417       In this form, ct forks the OpenFlow pipeline:
1418
1419          • In one fork, ct passes the packet to the connection tracker.   Af‐
1420            terward,  it  reinjects the packet into the OpenFlow pipeline with
1421            the connection tracking fields initialized.  The ct_state field is
1422            initialized  with  connection  state and ct_zone to the connection
1423            tracking zone specified on the zone argument.  If  the  connection
1424            is one that is already tracked, ct_mark and ct_label to its exist‐
1425            ing mark and label, respectively; otherwise they are  zeroed.   In
1426            addition,    ct_nw_proto,   ct_nw_src,   ct_nw_dst,   ct_ipv6_src,
1427            ct_ipv6_dst, ct_tp_src, and ct_tp_dst  are  initialized  appropri‐
1428            ately for the original direction connection.  See the resubmit ac‐
1429            tion for a way to search the flow table with the connection track‐
1430            ing  original  direction  fields  swapped  with the packet 5-tuple
1431            fields.  See ovs-fields(7) for details on the connection  tracking
1432            fields.
1433
1434          • In  the  other fork, the original instance of the packet continues
1435            independent processing following  the  ct  action.   The  ct_state
1436            field and other connection tracking metadata are cleared.
1437
1438       Without commit, the ct action accepts the following arguments:
1439
1440          table=table
1441                 Sets  the OpenFlow table where the packet is reinjected.  The
1442                 table must be a number between 0 and 254 inclusive, or a  ta‐
1443                 ble’s  name.   If  table is not specified, then the packet is
1444                 not reinjected.
1445
1446          nat
1447
1448          nat(type=addrs[:ports][,flag]...)
1449                 Specify address and port translation for the connection being
1450                 tracked.   The  type  must  be  src,  for source address/port
1451                 translation (SNAT),  or  dst,  for  destination  address/port
1452                 translation (DNAT).  Setting up address translation for a new
1453                 connection takes effect only if the connection is later  com‐
1454                 mitted with ct(commit ...).
1455
1456                 The src and dst options take the following arguments:
1457
1458                     addrs  The  IP  address  addr  or  range addr1-addr2 from
1459                            which the translated address should  be  selected.
1460                            If  only  one  address is given, then that address
1461                            will always be selected, otherwise the address se‐
1462                            lection can be informed by the optional persistent
1463                            flag as described below.  Either IPv4 or IPv6  ad‐
1464                            dresses  can  be provided, but both addresses must
1465                            be of the same type, and the datapath behavior  is
1466                            undefined  in case of providing IPv4 address range
1467                            for an IPv6 packet, or IPv6 address range  for  an
1468                            IPv4  packet.   IPv6  addresses  must be bracketed
1469                            with [ and ] if a port range is also given.
1470
1471                     ports  The L4 port or range port1-port2  from  which  the
1472                            translated  port  should  be selected. When a port
1473                            range is specified, fallback  to  ephemeral  ports
1474                            does  not  happen, else, it will.  The port number
1475                            selection can be informed by the  optional  random
1476                            and  hash  flags  described  below.  The userspace
1477                            datapath only supports the hash behavior.
1478
1479                 The optional flags are:
1480
1481                     random The selection of the port  from  the  given  range
1482                            should  be done using a fresh random number.  This
1483                            flag is mutually exclusive with hash.
1484
1485                     hash   The selection of the port  from  the  given  range
1486                            should  be  done using a datapath specific hash of
1487                            the  packet’s  IP   addresses   and   the   other,
1488                            non-mapped port number.  This flag is mutually ex‐
1489                            clusive with random.
1490
1491                     persistent
1492                            The selection of the IP  address  from  the  given
1493                            range  should be done so that the same mapping can
1494                            be provided after the system restarts.
1495
1496                 If alg is specified for the committing ct  action  that  also
1497                 includes  nat  with a src or dst attribute, then the datapath
1498                 tries to set up the helper to be NAT-aware.  This functional‐
1499                 ity  is  datapath  specific  and  may not be supported by all
1500                 datapaths.
1501
1502                 A bare nat argument with no options will only  translate  the
1503                 packet being processed in the way the connection has been set
1504                 up with an earlier, committed ct action.  A nat  action  with
1505                 src  or  dst, when applied to a packet belonging to an estab‐
1506                 lished (rather than new) connection, will behave the same  as
1507                 a bare nat.
1508
1509                 For  SNAT, there is a special case when the src IP address is
1510                 configured as all 0’s, i.e., nat(src=0.0.0.0). In this  case,
1511                 when  a  source port collision is detected during the commit,
1512                 the source port will be translated to an ephemeral  port.  If
1513                 there is no collision, no SNAT is performed.
1514
1515                 Open  vSwitch 2.6 introduced nat.  Linux 4.6 was the earliest
1516                 upstream kernel that implemented ct support for nat.
1517
1518       With commit, the connection tracker commits the connection to the  con‐
1519       nection  tracking module.  The commit flag should only be used from the
1520       pipeline within the first fork of ct without commit.  Information about
1521       the connection is stored beyond the lifetime of the packet in the pipe‐
1522       line.  Some ct_state flags are only  available  for  committed  connec‐
1523       tions.
1524
1525       The following options are available only with commit:
1526
1527          force  A  committed  connection always has the directionality of the
1528                 packet that caused the connection  to  be  committed  in  the
1529                 first  place.   This is the original direction of the connec‐
1530                 tion, and the opposite direction is the reply direction.   If
1531                 a connection is already committed, but it is in the wrong di‐
1532                 rection, force effectively terminates the existing connection
1533                 and starts a new one in the current direction.  This flag has
1534                 no effect if the original direction of the connection is  al‐
1535                 ready the same as that of the current packet.
1536
1537          exec(action...)
1538                 Perform  each  action within the context of connection track‐
1539                 ing.  Only actions  which  modify  the  ct_mark  or  ct_label
1540                 fields  are accepted within exec action, and these fields may
1541                 only be modified with this option. For example:
1542
1543                 set_field:value[/mask]->ct_mark
1544                        Store a 32-bit metadata  value  with  the  connection.
1545                        Subsequent lookups for packets in this connection will
1546                        populate ct_mark when the packet is sent to  the  con‐
1547                        nection tracker with the table specified.
1548
1549                 set_field:value[/mask]->ct_label
1550                        Store  a  128-bit  metadata value with the connection.
1551                        Subsequent lookups for packets in this connection will
1552                        populate  ct_label when the packet is sent to the con‐
1553                        nection tracker with the table specified.
1554
1555          alg=alg
1556                 Specify application layer gateway alg to track specific  con‐
1557                 nection  types.   If  subsequent related connections are sent
1558                 through the ct action, then the  rel  flag  in  the  ct_state
1559                 field will be set.  Supported types include:
1560
1561                 ftp    Look for negotiation of FTP data connections.  Specify
1562                        this option for FTP control connections to detect  re‐
1563                        lated  data  connections and populate the rel flag for
1564                        the data connections.
1565
1566                 tftp   Look for negotiation of TFTP data connections.   Spec‐
1567                        ify this option for TFTP control connections to detect
1568                        related data connections and populate the rel flag for
1569                        the data connections.
1570
1571                 Related connections inherit ct_mark from that stored with the
1572                 original  connection  (i.e.   the   connection   created   by
1573                 ct(alg=...).
1574
1575       With  the Linux datapath, global sysctl options affect ct behavior.  In
1576       particular, if net.netfilter.nf_conntrack_helper is enabled,  which  it
1577       is  by  default until Linux 4.7, then application layer gateway helpers
1578       may be executed even if alg is not specified.   For  security  reasons,
1579       the  netfilter  team recommends users disable this option.  For further
1580       details, please see http://www.netfilter.org/news.html#2012-04-03 .
1581
1582       The ct action may be used as a primitive to  construct  stateful  fire‐
1583       walls by selectively committing some traffic, then matching ct_state to
1584       allow established connections while denying new connections.  The  fol‐
1585       lowing  flows  provide an example of how to implement a simple firewall
1586       that allows new connections from port 1 to port 2, and only allows  es‐
1587       tablished connections to send traffic from port 2 to port 1:
1588
1589          table=0,priority=1,action=drop
1590          table=0,priority=10,arp,action=normal
1591          table=0,priority=100,ip,ct_state=-trk,action=ct(table=1)
1592          table=1,in_port=1,ip,ct_state=+trk+new,action=ct(commit),2
1593          table=1,in_port=1,ip,ct_state=+trk+est,action=2
1594          table=1,in_port=2,ip,ct_state=+trk+new,action=drop
1595          table=1,in_port=2,ip,ct_state=+trk+est,action=1
1596
1597       If  ct is executed on IPv4 (or IPv6) fragments, then the message is im‐
1598       plicitly reassembled before sending to the connection tracker  and  re‐
1599       fragmented upon output, to the original maximum received fragment size.
1600       Reassembly occurs within the context of the zone, meaning that IP frag‐
1601       ments in different zones are not assembled together.  Pipeline process‐
1602       ing for the initial fragments is halted.  When the  final  fragment  is
1603       received,  the  message  is assembled and pipeline processing continues
1604       for that flow.  Packet ordering is not guaranteed by IP  protocols,  so
1605       it  is  not  possible to determine which IP fragment will cause message
1606       reassembly (and therefore continue pipeline processing). As such, it is
1607       strongly  recommended  that multiple flows should not execute ct to re‐
1608       assemble fragments from the same IP message.
1609
1610       Conformance
1611              The ct action was introduced in Open vSwitch 2.5.  Some  of  its
1612              features were introduced later, noted individually above.
1613
1614   The ct_clear action
1615       Syntax:
1616              ct_clear
1617
1618
1619       Clears  connection  tracking  state  from  the  flow, zeroing ct_state,
1620       ct_zone, ct_mark, and ct_label.
1621
1622       This action was introduced in Open vSwitch 2.7.
1623
1624   The learn action
1625       Syntax:
1626              learn(argument...)
1627
1628
1629       The learn action adds or modifies a flow in an OpenFlow table,  similar
1630       to  ovs-ofctl  --strict  mod-flows.   The  arguments  specify the match
1631       fields, actions, and other properties of the flow to be added or  modi‐
1632       fied.
1633
1634       Match  fields  for the new flow are specified as follows.  At least one
1635       match field should ordinarily be specified:
1636
1637          field=value
1638                 Specifies that field, in the new flow, must match the literal
1639                 value,  e.g.  dl_type=0x800.  Shorthand match syntax, such as
1640                 ip in place of dl_type=0x800, is not supported.
1641
1642          field=src
1643                 Specifies that field in the new flow  must  match  src  taken
1644                 from  the  packet  currently  being  processed.  For example,
1645                 udp_dst=udp_src, applied to a UDP packet with source port 53,
1646                 creates  a flow which matches udp_dst=53.  field and src must
1647                 have the same width.
1648
1649          field  Shorthand for the previous form when field and  src  are  the
1650                 same.   For  example,  udp_dst,  applied to a UDP packet with
1651                 destination port 53, creates a flow which matches udp_dst=53.
1652
1653       The field and src arguments above should be fields or subfields in  the
1654       syntax described under Field Specifications above.
1655
1656       Match  field  specifications must honor prerequisites for both the flow
1657       with the learn and the new flow that it creates.  Consider the  follow‐
1658       ing  complete flow, in the syntax accepted by ovs-ofctl.  If the flow’s
1659       match on udp were omitted, then the flow would not satisfy the  prereq‐
1660       uisites  for  the  learn  action’s use of udp_src.  If dl_type=0x800 or
1661       nw_proto were omitted from learn, then the new flow would  not  satisfy
1662       the  prerequisite  for  its  match on udp_dst.  For more information on
1663       prerequisites, please refer to ovs-fields(7):
1664
1665          udp, actions=learn(dl_type=0x800, nw_proto=17, udp_dst=udp_src)
1666
1667       Actions for the new flow are specified as follows.  At least one action
1668       should ordinarily be specified:
1669
1670          load:value->dst
1671                 Adds  a  load  action  to the new flow that loads the literal
1672                 value into dst.  The syntax is the same as  the  load  action
1673                 explained in the Field Modification Actions section.
1674
1675          load:src->dst
1676                 Adds a load action to the new flow that loads src, a field or
1677                 subfield from the packet being processed, into dst.
1678
1679          output:field
1680                 Adds an output action to the new flow’s actions that  outputs
1681                 to  the OpenFlow port taken from field, which must be a field
1682                 as described above.
1683
1684          fin_idle_timeout=seconds / fin_hard_timeout=seconds
1685                 Adds a fin_timeout action with the specified arguments to the
1686                 new flow.  This feature was added in Open vSwitch 1.6.
1687
1688       The following additional arguments are optional:
1689          idle_timeout=seconds
1690
1691          hard_timeout=seconds
1692
1693          priority=value
1694
1695          cookie=value
1696
1697          send_flow_rem
1698                 These  arguments  have  the same meaning as in the usual flow
1699                 syntax documented in ovs-ofctl(8).
1700
1701          table=table
1702                 The table in which the new flow should be inserted.   Specify
1703                 a decimal number between 0 and 254 inclusive or the name of a
1704                 table.  The default, if table is unspecified, is table 1 (not
1705                 0).
1706
1707          delete_learned
1708                 When  this flag is specified, deleting the flow that contains
1709                 the learn action will also delete the flows created by learn.
1710                 Specifically,  when  the last learn action with this flag and
1711                 particular table and cookie values  is  removed,  the  switch
1712                 deletes  all  of  the  flows  in the specified table with the
1713                 specified cookie.
1714
1715                 This flag was added in Open vSwitch 2.4.
1716
1717          limit=number
1718                 If the number of flows in the new flow’s table with the  same
1719                 cookie  exceeds  number,  the action will not add a new flow.
1720                 By default, or with limit=0, there is no limit.
1721
1722                 This flag was added in Open vSwitch 2.8.
1723
1724          result_dst=field[bit]
1725                 If learn fails (because the number of flows  exceeds  limit),
1726                 the  action sets field[bit] to 0, otherwise it will be set to
1727                 1.  field[bit] must be a single bit.
1728
1729                 This flag was added in Open vSwitch 2.8.
1730
1731       By itself, the learn action can only put two kinds of actions into  the
1732       flows  that  it  creates: load and output actions.  If learn is used in
1733       isolation, these are severe limits.
1734
1735       However, learn is not meant to be used in isolation.  It is a primitive
1736       meant  to  be  used together with other Open vSwitch features to accom‐
1737       plish a task.  Its existing features  are  enough  to  accomplish  most
1738       tasks.
1739
1740       Here is an outline of a typical pipeline structure that allows for ver‐
1741       satile behavior using learn:
1742
1743          • Flows in table A contain a learn action, that populates  flows  in
1744            table L, that use a load action to populate register R with infor‐
1745            mation about what was learned.
1746
1747          • Flows in table B contain two sequential resubmit actions:  one  to
1748            table L and another one to table B + 1.
1749
1750          • Flows  in  table B + 1 match on register R and act differently de‐
1751            pending on what the flows in table L loaded into it.
1752
1753       This approach can be used to implement many learn-based features.   For
1754       example:
1755
1756          • Resubmit  to  a  table selected based on learned information, e.g.
1757            see
1758            https://mail.openvswitch.org/pipermail/ovs-discuss/2016-June/021694.html
1759            .
1760
1761          • MAC learning in the middle of a pipeline, as described in the Open
1762            vSwitch Advanced Features Tutorial in the OVS documentation.
1763
1764          • TCP  state  based  firewalling,  by  learning outgoing connections
1765            based on SYN packets and matching them up with  incoming  packets.
1766            (This is usually better implemented using the ct action.)
1767
1768          • At  least  some of the features described in T. A. Hoff, Extending
1769            Open vSwitch to Facilitate Creation of Stateful SDN Applications.
1770
1771       Conformance
1772              The learn action is an Open vSwitch extension to OpenFlow  added
1773              in Open vSwitch 1.3.  Some features of learn were added in later
1774              versions, as noted individually above.
1775
1776   The fin_timeout action
1777       Syntax:
1778              fin_timeout(key=value...)
1779
1780
1781       This action changes the idle timeout or hard timeout, or both,  of  the
1782       OpenFlow flow that contains it, when the flow matches a TCP packet with
1783       the FIN or RST flag.  When such a packet is observed,  the  action  re‐
1784       duces  the  rule’s  timeouts  to those specified on the action.  If the
1785       rule’s existing timeout is already shorter than the one that the action
1786       specifies, then that timeout is unaffected.
1787
1788       The timeouts are specified as key-value pairs:
1789
1790          idle_timeout=seconds
1791                 Causes  the  flow to expire after the given number of seconds
1792                 of inactivity.
1793
1794          hard_timeout=seconds
1795                 Causes the flow to expire after the given number of  seconds,
1796                 regardless  of  activity.   (seconds specifies time since the
1797                 flow’s creation, not since the receipt of the FIN or RST.)
1798
1799       This action is normally added to a learned flow by  the  learn  action.
1800       It is unlikely to be useful otherwise.
1801
1802       Conformance
1803              This  Open  vSwitch  extension  action was added in Open vSwitch
1804              1.6.
1805

PROGRAMMING AND CONTROL FLOW ACTIONS

1807   The resubmit action
1808       Syntax:
1809              resubmit:port
1810              resubmit([port],[table][,ct])``
1811
1812
1813       Searches an OpenFlow flow table for a matching flow  and  executes  the
1814       actions found, if any, before continuing to the following action in the
1815       current flow entry.  Arguments can customize the search:
1816
1817          • If port is given as an OpenFlow port number or name, then it spec‐
1818            ifies  a value to use for the input port metadata field as part of
1819            the search, in place of the input  port  currently  in  the  flow.
1820            Specifying in_port as port is equivalent to omitting it.
1821
1822          • If table is given as an integer between 0 and 254 or a table name,
1823            it specifies the OpenFlow table to search.  If it  is  not  speci‐
1824            fied, the table from the current flow is used.
1825
1826          • If  ct  is  specified, then the search is done with packet 5-tuple
1827            fields swapped with the corresponding conntrack original direction
1828            tuple fields.  See the documentation for ct above, for more infor‐
1829            mation about connection tracking,  or  ovs-fields(7)  for  details
1830            about the connection tracking fields.
1831
1832            This  flag  requires  a valid connection tracking state as a match
1833            prerequisite in the flow where this action is placed.  Examples of
1834            valid  connection  tracking  state  matches include ct_state=+new,
1835            ct_state=+est, ct_state=+rel, and ct_state=+trk-inv.
1836
1837       The changes, if any, to the input port and connection  tracking  fields
1838       are  just for searching the flow table.  The changes are not visible to
1839       actions or to later flow table lookups.
1840
1841       The most common use of resubmit is to visit another flow table  without
1842       port or ct, like this: resubmit(,table).
1843
1844       Recursive resubmit actions are permitted.
1845
1846       Conformance
1847              The  resubmit action is an Open vSwitch extension.  However, the
1848              goto_table instruction in OpenFlow 1.1 and later can  be  viewed
1849              as a kind of restricted resubmit.
1850
1851              Open vSwitch 1.3 added table.  Open vSwitch 2.7 added ct.
1852
1853              Open  vSwitch  imposes a limit on resubmit recursion that varies
1854              among version:
1855
1856                 • Open vSwitch 1.0.1 and earlier did not support recursion.
1857
1858                 • Open vSwitch 1.0.2 and 1.0.3 limited recursion to 8 levels.
1859
1860                 • Open vSwitch 1.1 and 1.2 limited recursion to 16 levels.
1861
1862                 • Open vSwitch 1.2 through 1.8 limited recursion to  32  lev‐
1863                   els.
1864
1865                 • Open  vSwitch  1.9 through 2.0 limited recursion to 64 lev‐
1866                   els.
1867
1868                 • Open vSwitch 2.1 through 2.5 limited recursion to 64 levels
1869                   and impose a total limit of 4,096 resubmits per flow trans‐
1870                   lation (earlier versions did not impose any total limit).
1871
1872                 • Open vSwitch 2.6 and later imposes the same limits as  2.5,
1873                   with  one exception: resubmit from table x to any table y >
1874                   x does not count against the recursion depth limit.
1875
1876   The clone action
1877       Syntax:
1878              clone(action...)
1879
1880
1881       Executes each nested action, saving much of  the  packet  and  pipeline
1882       state  beforehand  and  then restoring it afterward.  The state that is
1883       saved and restored includes all flow data and metadata (including,  for
1884       example,  in_port and ct_state), the stack accessed by push and pop ac‐
1885       tions, and the OpenFlow action set.
1886
1887       This action was added in Open vSwitch 2.7.
1888
1889   The push and pop actions
1890       Syntax:
1891              push:src
1892              pop:dst
1893
1894
1895       The push action pushes src on a general-purpose stack.  The pop  action
1896       pops  an entry off the stack into dst.  src and dst should be fields or
1897       subfields in the syntax described under Field Specifications above.
1898
1899       Controllers can use the stack for saving and restoring data or metadata
1900       around resubmit actions, for swapping or rearranging data and metadata,
1901       or for other purposes.  Any data or metadata field, or part of one, may
1902       be pushed, and any modifiable field or subfield may be popped.
1903
1904       The  number  of  bits  pushed in a stack entry do not have to match the
1905       number of bits later popped from that entry.  If more bits  are  popped
1906       from  an  entry  than  were  pushed,  then  the  entry  is conceptually
1907       left-padded with 0-bits as needed.   If  fewer  bits  are  popped  than
1908       pushed,  then  bits  are conceptually trimmed from the left side of the
1909       entry.
1910
1911       The stack’s size is limited.  The limit is intended to be  high  enough
1912       that normal use will not pose problems.  Stack overflow or underflow is
1913       an error that stops action execution (see Stack too  deep  under  Error
1914       Handling, above).
1915
1916       Examples:
1917
1918push:reg2[0..5]  or push:NXM_NX_REG2[0..5] pushes on the stack the
1919            6 bits in register 2 bits 0 through 5.
1920
1921pop:reg2[0..5] or pop:NXM_NX_REG2[0..5] pops the value from top of
1922            the  stack  and  copy  bits  0 through 5 of that value into bits 0
1923            through 5 of register 2.
1924
1925       Conformance
1926              Open vSwitch 1.2 introduced push and pop as  OpenFlow  extension
1927              actions.
1928
1929   The exit action
1930       Syntax:
1931              exit
1932
1933
1934       This  action  causes Open vSwitch to immediately halt execution of fur‐
1935       ther actions.  Actions which have already been executed are unaffected.
1936       Any  further  actions, including those which may be in other tables, or
1937       different levels of the resubmit call stack, are ignored.  However,  an
1938       exit  action  within  a  group bucket terminates only execution of that
1939       bucket, not other buckets or the overall pipeline.  Actions in the  ac‐
1940       tion  set are still executed (specify clear_actions before exit to dis‐
1941       card them).
1942
1943   The multipath action
1944       Syntax:
1945              multipath(fields,basis,algorithm,n_links,arg,dst)
1946
1947
1948       Hashes fields using basis as a universal hash parameter, then  the  ap‐
1949       plies multipath link selection algorithm (with parameter arg) to choose
1950       one of n_links output links numbered 0 through  n_links  minus  1,  and
1951       stores the link into dst, which must be a field or subfield in the syn‐
1952       tax described under Field Specifications above.
1953
1954       The bundle or bundle_load actions are usually easier to use than multi‐
1955       path.
1956
1957       fields must be one of the following:
1958
1959          eth_src
1960                 Hashes Ethernet source address only.
1961
1962          symmetric_l4
1963                 Hashes  Ethernet  source,  destination,  and  type,  VLAN ID,
1964                 IPv4/IPv6 source, destination, and protocol, and TCP or  SCTP
1965                 (but  not  UDP) ports.  The hash is computed so that pairs of
1966                 corresponding flows in each direction hash to the same value,
1967                 in  environments  where  L2 paths are the same in each direc‐
1968                 tion.  UDP ports are not included in the hash to support pro‐
1969                 tocols such as VXLAN that use asymmetric ports in each direc‐
1970                 tion.
1971
1972          symmetric_l3l4
1973                 Hashes IPv4/IPv6 source, destination, and protocol,  and  TCP
1974                 or  SCTP  (but  not UDP) ports.  Like symmetric_l4, this is a
1975                 symmetric hash, but by excluding L2 headers it is more effec‐
1976                 tive in environments with asymmetric L2 paths (e.g. paths in‐
1977                 volving VRRP IP addresses on a  router).   Not  an  effective
1978                 hash  function  for protocols other than IPv4 and IPv6, which
1979                 hash to a constant zero.
1980
1981          symmetric_l3l4+udp
1982                 Like symmetric_l3l4+udp, but UDP ports are  included  in  the
1983                 hash.  This is a more effective hash when asymmetric UDP pro‐
1984                 tocols such as VXLAN are not a consideration.
1985
1986          symmetric_l3
1987                 Hashes network source address  and  network  destination  ad‐
1988                 dress.
1989
1990          nw_src Hashes network source address only.
1991
1992          nw_dst Hashes network destination address only.
1993
1994       The  algorithm used to compute the final result link must be one of the
1995       following:
1996
1997          modulo_n
1998                 Computes link = hash(flow) % n_links.
1999
2000                 This  algorithm  redistributes  all  traffic   when   n_links
2001                 changes.  It has O(1) performance.
2002
2003                 Use 65535 for max_link to get a raw hash value.
2004
2005                 This algorithm is specified by RFC 2992.
2006
2007          hash_threshold
2008                 Computes link = hash(flow) / (MAX_HASH / n_links).
2009
2010                 Redistributes  between  one-quarter  and  one-half of traffic
2011                 when n_links changes.  It has O(1) performance.
2012
2013                 This algorithm is specified by RFC 2992.
2014
2015          hrw (Highest Random Weight)
2016                 Computes the following:
2017
2018                     for i in [0, n_links]:
2019                         weights[i] = hash(flow, i)
2020                     link = { i such that weights[i] >= weights[j] for all j != i }
2021
2022                 Redistributes 1 / n_links of traffic  when  n_links  changes.
2023                 It  has O(n_links) performance.  If n_links is greater than a
2024                 threshold (currently 64, but subject to change), Open vSwitch
2025                 will substitute another algorithm automatically.
2026
2027                 This algorithm is specified by RFC 2992.
2028
2029          iter_hash (Iterative Hash)
2030                 Computes the following:
2031
2032                     i = 0
2033                     repeat:
2034                         i = i + 1
2035                         link = hash(flow, i) % arg
2036                     while link > max_link
2037
2038                 Redistributes  1  /  n_links of traffic when n_links changes.
2039                 O(1) performance when arg / max_link is  bounded  by  a  con‐
2040                 stant.
2041
2042                 Redistributes all traffic when arg changes.
2043
2044                 arg  must  be  greater than max_link and for best performance
2045                 should be no more than approximately max_link * 2.  If arg is
2046                 outside the acceptable range, Open vSwitch will automatically
2047                 substitute the least power of 2 greater than max_link.
2048
2049                 This algorithm is specific to Open vSwitch.
2050
2051       Only the iter_hash algorithm uses arg.
2052
2053       It is an error if max_link is greater than or equal to 2**n_bits.
2054
2055       Conformance
2056              This is an OpenFlow extension added in Open vSwitch 1.1.
2057

OTHER ACTIONS

2059   The conjunction action
2060       Syntax:
2061              conjunction(id, k/n)
2062
2063
2064       This action allows for sophisticated conjunctive match flows.  Refer to
2065       Conjunctive Match Fields in ovs-fields(7) for details.
2066
2067       A  flow that has one or more conjunction actions may not have any other
2068       actions except for note actions.
2069
2070       Conformance
2071              Open vSwitch 2.4 introduced the conjunction action  and  conj_id
2072              field.  They are Open vSwitch extensions to OpenFlow.
2073
2074   The note action
2075       Syntax:
2076              note:[hh]...
2077
2078
2079       This  action  does  nothing at all.  OpenFlow controllers may use it to
2080       annotate flows with more data than can fit in a flow cookie.
2081
2082       The action may include any number of bytes represented  as  hex  digits
2083       hh.   Periods  may  separate pairs of hex digits, for readability.  The
2084       note action’s format doesn’t include an exact length for  its  payload,
2085       so  the provided bytes will be padded on the right by enough bytes with
2086       value 0 to make the total number 6 more than a multiple of 8.
2087
2088       Conformance
2089              This action is an  extension  to  OpenFlow  introduced  in  Open
2090              vSwitch 1.1.
2091
2092   The sample action
2093       Syntax:
2094              sample(argument...)
2095
2096
2097       Samples packets and sends one sample for every sampled packet.
2098
2099       The following argument forms are accepted:
2100
2101          probability=packets
2102                 The  number of sampled packets out of 65535.  Must be greater
2103                 or equal to 1.
2104
2105          collector_set_id=id
2106                 The unsigned 32-bit integer identifier of the set  of  sample
2107                 collectors to send sampled packets to.  Defaults to 0.
2108
2109          obs_domain_id=id
2110                 When sending samples to IPFIX collectors, the unsigned 32-bit
2111                 integer Observation  Domain  ID  sent  in  every  IPFIX  flow
2112                 record.  Defaults to 0.
2113
2114          obs_point_id=id
2115                 When sending samples to IPFIX collectors, the unsigned 32-bit
2116                 integer Observation Point ID sent in every IPFIX flow record.
2117                 Defaults to 0.
2118
2119          sampling_port=port
2120                 Sample packets on port, which should be the ingress or egress
2121                 port.  This option, which was added in Open vSwitch 2.6,  al‐
2122                 lows  the IPFIX implementation to export egress tunnel infor‐
2123                 mation.
2124
2125          ingress
2126
2127          egress Specifies explicitly that the  packet  is  being  sampled  on
2128                 ingress  to or egress from the switch.  IPFIX reports sent by
2129                 Open vSwitch before version 2.6 did not include a  direction.
2130                 From  2.6  until 2.7, IPFIX reports inferred a direction from
2131                 sampling_port: if it was the packet’s output port,  then  the
2132                 direction was reported as egress, otherwise as ingress.  Open
2133                 vSwitch 2.7 introduced these options,  which  allow  the  in‐
2134                 ferred direction to be overridden.  This is particularly use‐
2135                 ful when the ingress (or egress) port is not a tunnel.
2136
2137       Refer to ovs-vswitchd.conf.db(5) for more details on configuring sample
2138       collector sets.
2139
2140       Conformance
2141              This action is an OpenFlow extension added in Open vSwitch 2.4.
2142

INSTRUCTIONS

2144       Every  version  of  OpenFlow includes actions.  OpenFlow 1.1 introduced
2145       the higher-level, related concept of instructions.  In OpenFlow 1.1 and
2146       later, actions within a flow are always encapsulated within an instruc‐
2147       tion.  Each flow has at most one instruction of each  kind,  which  are
2148       executed  in the following fixed order defined in the OpenFlow specifi‐
2149       cation:
2150
2151          1. Meter
2152
2153          2. Apply-Actions
2154
2155          3. Clear-Actions
2156
2157          4. Write-Actions
2158
2159          5. Write-Metadata
2160
2161          6. Stat-Trigger (not supported by Open vSwitch)
2162
2163          7. Goto-Table
2164
2165       The most important instruction is Apply-Actions.  This instruction  en‐
2166       capsulates any number of actions, which the instruction executes.  Open
2167       vSwitch does not explicitly represent Apply-Actions.  Instead, any  ac‐
2168       tion by itself is implicitly part of an Apply-Actions instructions.
2169
2170       Open  vSwitch  syntax requires other instructions, if present, to be in
2171       the order listed above.  Otherwise it will flag an error.
2172
2173   The meter action and instruction
2174       Syntax:
2175              meter:meter_id
2176
2177
2178       Apply meter meter_id.  If a meter band rate is exceeded, the packet may
2179       be dropped, or modified, depending on the meter band type.
2180
2181       Conformance
2182              OpenFlow  1.3  introduced  the  meter instruction.  OpenFlow 1.5
2183              changes meter from an instruction to an action.
2184
2185              OpenFlow 1.5 allows implementations to restrict meter to be  the
2186              first  action in an action list and to exclude meter from action
2187              sets, for better compatibility with OpenFlow 1.3 and 1.4.   Open
2188              vSwitch restricts the meter action both ways.
2189
2190              Open  vSwitch  2.0  introduced OpenFlow protocol support for me‐
2191              ters, but it did not include a  datapath  implementation.   Open
2192              vSwitch 2.7 added meter support to the userspace datapath.  Open
2193              vSwitch 2.10 added meter support to the kernel  datapath.   Open
2194              vSwitch  2.12  added  support for meter as an action in OpenFlow
2195              1.5.
2196
2197   The clear_actions instruction
2198       Syntax:
2199              clear_actions
2200
2201
2202       Clears the action set.  See Action Sets, above, for more information.
2203
2204       Conformance
2205              OpenFlow 1.1 introduced clear_actions.  Open vSwitch  2.1  added
2206              support for clear_actions.
2207
2208   The write_actions instruction
2209       Syntax:
2210              write_actions(action...)
2211
2212
2213       Adds  each action to the action set.  The action set is carried between
2214       flow tables and then executed at the end of the pipeline.  Only certain
2215       actions  may be written to the action set.  See Action Sets, above, for
2216       more information.
2217
2218       Conformance
2219              OpenFlow 1.1 introduced write_actions.  Open vSwitch  2.1  added
2220              support for write_actions.
2221
2222   The write_metadata instruction
2223       Syntax:
2224              write_metadata:value[/mask]
2225
2226
2227       Updates the flow’s metadata field.  If mask is omitted, metadata is set
2228       exactly to value; if mask is specified, then a 1-bit in mask  indicates
2229       that the corresponding bit in metadata will be replaced with the corre‐
2230       sponding bit from value.  Both value and mask are  64-bit  values  that
2231       are decimal by default; use a 0x prefix to specify them in hexadecimal.
2232
2233       The  metadata  field  can also be matched in the flow table and updated
2234       with actions such as set_field and move.
2235
2236       Conformance
2237              OpenFlow 1.1 introduced write_metadata.  Open vSwitch 2.1  added
2238              support for write_metadata.
2239
2240   The goto_table instruction
2241       Syntax:
2242              goto_table:table
2243
2244
2245       Jumps  to  table  as the next table in the process pipeline.  The table
2246       may be a number between 0 and 254 or a table name.
2247
2248       It is an error if table is less than or equal to the table of the  flow
2249       that contains it; that is, goto_table must move forward in the OpenFlow
2250       pipeline.  Since goto_table must be the last instruction in a flow,  it
2251       never leads to recursion.  The resubmit extension action is more flexi‐
2252       ble.
2253
2254       Conformance
2255              OpenFlow 1.1 introduced goto_table.  Open vSwitch 2.1 added sup‐
2256              port for goto_table.
2257

AUTHOR

2259       The Open vSwitch Development Community
2260
2262       2016-2022, The Open vSwitch Development Community
2263
2264
2265
2266
22672.17                             Jul 22, 2022                   OVS-ACTIONS(7)
Impressum