[ovs-dev,3/3] ovs-actions: New document describing OVS actions in detail.

Message ID	20181109053955.28951-3-blp@ovn.org
State	Accepted
Headers	show Return-Path: <ovs-dev-bounces@openvswitch.org> sender: blp@ovn.org) by relay6-d.mail.gandi.net (Postfix) with ESMTPSA id D5E8CC0009; Fri, 9 Nov 2018 05:40:03 +0000 (UTC) From: Ben Pfaff <blp@ovn.org> To: dev@openvswitch.org Date: Thu, 8 Nov 2018 21:39:55 -0800 Message-Id: <20181109053955.28951-3-blp@ovn.org> In-Reply-To: <20181109053955.28951-1-blp@ovn.org> References: <20181109053955.28951-1-blp@ovn.org> MIME-Version: 1.0 Cc: Ben Pfaff <blp@ovn.org> Subject: [ovs-dev] [PATCH 3/3] ovs-actions: New document describing OVS actions in detail. Precedence: list Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: base64 Sender: ovs-dev-bounces@openvswitch.org Errors-To: ovs-dev-bounces@openvswitch.org
Series	[ovs-dev,1/3] nroff: Increase width for .IP used for ordered lists. \| expand [ovs-dev,1/3] nroff: Increase width for .IP used for ordered lists. [ovs-dev,2/3] nroff: Fix fonts for h2, h3, h4. [ovs-dev,3/3] ovs-actions: New document describing OVS actions in detail.

diff --git a/Documentation/faq/issues.rst b/Documentation/faq/issues.rst index 8a30dad37da0..79164e55ad31 100644 --- a/Documentation/faq/issues.rst +++ b/Documentation/faq/issues.rst @@ -196,7 +196,7 @@ Q: Open vSwitch does not seem to obey my packet filter rules. For simple filtering rules, it might be possible to achieve similar results by installing appropriate OpenFlow flows instead. The OVS conntrack - feature (see the "ct" action in ovs-ofctl(8)) can implement a stateful + feature (see the "ct" action in ovs-actions(7)) can implement a stateful firewall. If the use of a particular packet filter setup is essential, Open vSwitch diff --git a/Documentation/faq/openflow.rst b/Documentation/faq/openflow.rst index 7cd6161ddefb..f722f9e78b38 100644 --- a/Documentation/faq/openflow.rst +++ b/Documentation/faq/openflow.rst @@ -516,44 +516,6 @@ but the packets are getting dropped instead. Why? See also the preceding question. -Q: The "learn" action can't learn the action I want, can you improve it? - - A: By itself, the "learn" action can only put two kinds of actions into the - flows that it creates: "load" and "output" actions. If "learn" is used in - isolation, these are severe limits. - - However, "learn" is not meant to be used in isolation. It is a primitive - meant to be used together with other Open vSwitch features to accomplish a - task. Its existing features are enough to accomplish most tasks. - - Here is an outline of a typical pipeline structure that allows for - versatile behavior using "learn": - - - Flows in table A contain a "learn" action, that populates flows in table - L, that use a "load" action to populate register R with information about - what was learned. - - - Flows in table B contain two sequential resubmit actions: one to table L - and another one to table B+1. - - - Flows in table B+1 match on register R and act differently depending on - what the flows in table L loaded into it. - - This approach can be used to implement many "learn"-based features. For - example: - - - Resubmit to a table selected based on learned information, e.g. see: - https://mail.openvswitch.org/pipermail/ovs-discuss/2016-June/021694.html - - - MAC learning in the middle of a pipeline, as described in - :doc:`/tutorials/ovs-advanced` - - - TCP state based firewalling, by learning outgoing connections based on - SYN packets and matching them up with incoming packets. - - - At least some of the features described in T. A. Hoff, "Extending Open - vSwitch to Facilitate Creation of Stateful SDN Applications". - Q: When using the "ct" action with FTP connections, it doesn't seem to matter if I set the "alg=ftp" parameter in the action. Is this required? diff --git a/Documentation/ref/index.rst b/Documentation/ref/index.rst index 29183af623f0..0a80a5f41277 100644 --- a/Documentation/ref/index.rst +++ b/Documentation/ref/index.rst @@ -50,6 +50,10 @@ The remainder are still in roff format can be found below: .. list-table:: + * - ovs-actions(7) + - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovs-actions.7.pdf>`__ + - `(html) <http://www.openvswitch.org/support/dist-docs/ovs-actions.7.html>`__ + - `(plain text) <http://www.openvswitch.org/support/dist-docs/ovs-actions.7.txt>`__ * - ovn-architecture(7) - `(pdf) <http://www.openvswitch.org/support/dist-docs/ovn-architecture.7.pdf>`__ - `(html) <http://www.openvswitch.org/support/dist-docs/ovn-architecture.7.html>`__ diff --git a/build-aux/extract-ofp-actions b/build-aux/extract-ofp-actions index bd7131f1a9cb..64de0f31f4a0 100755 --- a/build-aux/extract-ofp-actions +++ b/build-aux/extract-ofp-actions @@ -1,8 +1,11 @@ #! /usr/bin/python +import getopt import sys import os.path import re +import xml.dom.minidom +import build.nroff OFP_ACTION_ALIGN = 8 @@ -69,14 +72,21 @@ def usage(): argv0 = os.path.basename(sys.argv[0]) print('''\ %(argv0)s, for extracting OpenFlow action data -usage: %(argv0)s OFP_ACTIONS.C [--prototypes | --definitions] +usage: %(argv0)s [prototypes | definitions] OFP-ACTIONS.c +usage: %(argv0)s ovs-actions OVS-ACTIONS.XML -This program reads ofp-actions.c to obtain information about OpenFlow -actions. With --prototypes, it outputs on stdout a set of prototypes to -#include early in ofp-actions.c. With --definitions, it outputs on stdout -a set of definitions to #include late in ofp-actions.c +Commands: -OFP_ACTIONS.C should point to lib/ofp-actions.c.\ + prototypes OFP-ACTIONS.C + Reads ofp-actions.c and prints a set of prototypes to #include early in + ofp-actions.c. + + definitions OFP-ACTIONS.C + Reads ofp-actions.c and prints a set of definitions to #include late in + ofp-actions.c. + + ovs-actions OVS-ACTIONS.XML + Reads ovs-actions.xml and prints documentation in troff format.\ ''' % {"argv0": argv0}) sys.exit(0) @@ -377,19 +387,176 @@ static enum ofperr ofpact_decode(const struct ofp_action_header *, uint64_t arg, const struct vl_mff_map *vl_mff_map, uint64_t *tlv_bitmap, struct ofpbuf *out); """) + +## ------------------------ ## +## Documentation Generation ## +## ------------------------ ## + +def action_to_xml(action_node, body): + syntax = 0 + for node in action_node.childNodes: + if node.nodeType == node.ELEMENT_NODE and node.tagName == 'syntax': + if body[-1].strip() == '.PP': + del body[-1] + if syntax: + body += ['.IQ\n'] + else: + body += ['.IP "\\fBSyntax:\\fR"\n'] + body += [build.nroff.inline_xml_to_nroff(x, r'\fR') + for x in node.childNodes] + ['\n'] + syntax += 1 + elif (node.nodeType == node.ELEMENT_NODE + and node.tagName == 'conformance'): + body += ['.IP "\\fBConformance:\\fR"\n'] + body += [build.nroff.block_xml_to_nroff(node.childNodes)] + else: + body += [build.nroff.block_xml_to_nroff([node])] + +def group_xml_to_nroff(group_node): + title = group_node.attributes['title'].nodeValue + + body = [] + for node in group_node.childNodes: + if node.nodeType == node.ELEMENT_NODE and node.tagName == 'action': + action_to_xml(node, body) + else: + body += [build.nroff.block_xml_to_nroff([node])] + + content = [ + '.bp\n', + '.SH \"%s\"\n' % build.nroff.text_to_nroff(title.upper())] + content += body + return ''.join(content) + +def make_ovs_actions(ovs_actions_xml): + document = xml.dom.minidom.parse(ovs_actions_xml) + doc = document.documentElement + + global version + if version == None: + version = "UNKNOWN" + + print('''\ +'\\" tp +.\\" -*- mode: troff; coding: utf-8 -*- +.TH "ovs\-actions" 7 "%s" "Open vSwitch" "Open vSwitch Manual" +.fp 5 L CR \\" Make fixed-width font available as \\fL. +.de ST +. PP +. RS -0.15in +. I "\\\\$1" +. RE +.. + +.de SU +. PP +. I "\\\\$1" +.. + +.de IQ +. br +. ns +. IP "\\\\$1" +.. + +.de TQ +. br +. ns +. TP "\\\\$1" +.. +.de URL +\\\\$2 \\(laURL: \\\\$1 \\(ra\\\\$3 +.. +.if \\n[.g] .mso www.tmac +.SH NAME +ovs\-actions \- OpenFlow actions and instructions with Open vSwitch extensions +. +.PP +''' % version) + + s = '' + for node in doc.childNodes: + if node.nodeType == node.ELEMENT_NODE and node.tagName == "group": + s += group_xml_to_nroff(node) + elif node.nodeType == node.TEXT_NODE: + assert node.data.isspace() + elif node.nodeType == node.COMMENT_NODE: + pass + else: + s += build.nroff.block_xml_to_nroff([node]) + + if n_errors: + sys.exit(1) + + output = [] + for oline in s.split("\n"): + oline = oline.strip() + + # Life is easier with nroff if we don't try to feed it Unicode. + # Fortunately, we only use a few characters outside the ASCII range. + oline = oline.replace(u'\u2208', r'\[mo]') + oline = oline.replace(u'\u2260', r'\[!=]') + oline = oline.replace(u'\u2264', r'\[<=]') + oline = oline.replace(u'\u2265', r'\[>=]') + oline = oline.replace(u'\u00d7', r'\[mu]') + if len(oline): + output += [oline] + + # nroff tends to ignore .bp requests if they come after .PP requests, + # so remove .PPs that precede .bp. + for i in range(len(output)): + if output[i] == '.bp': + j = i - 1 + while j >= 0 and output[j] == '.PP': + output[j] = None + j -= 1 + for i in range(len(output)): + if output[i] is not None: + print(output[i]) + + +## ------------ ## +## Main Program ## +## ------------ ## if __name__ == '__main__': - if '--help' in sys.argv: - usage() - elif len(sys.argv) != 3: - sys.stderr.write("exactly two arguments required; " - "use --help for help\n") + argv0 = sys.argv[0] + try: + options, args = getopt.gnu_getopt(sys.argv[1:], 'h', + ['help', 'ovs-version=']) + except getopt.GetoptError as geo: + sys.stderr.write("%s: %s\n" % (argv0, geo.msg)) sys.exit(1) - elif sys.argv[2] == '--prototypes': - extract_ofp_actions(sys.argv[1], False) - elif sys.argv[2] == '--definitions': - extract_ofp_actions(sys.argv[1], True) - else: - sys.stderr.write("invalid arguments; use --help for help\n") + + global version + version = None + for key, value in options: + if key in ['-h', '--help']: + usage() + elif key == '--ovs-version': + version = value + else: + sys.exit(0) + + if not args: + sys.stderr.write("%s: missing command argument " + "(use --help for help)\n" % argv0) + sys.exit(1) + + commands = {"prototypes": (lambda fn: extract_ofp_actions(fn, False), 1), + "definitions": (lambda fn: extract_ofp_actions(fn, True), 1), + "ovs-actions": (make_ovs_actions, 1)} + + if not args[0] in commands: + sys.stderr.write("%s: unknown command \"%s\" " + "(use --help for help)\n" % (argv0, args[0])) + sys.exit(1) + + func, n_args = commands[args[0]] + if len(args) - 1 != n_args: + sys.stderr.write("%s: \"%s\" requires %d arguments but %d " + "provided\n" + % (argv0, args[0], n_args, len(args) - 1)) sys.exit(1) + func(*args[1:]) diff --git a/lib/automake.mk b/lib/automake.mk index 63e9d72ac18a..b1ff495ff1f3 100644 --- a/lib/automake.mk +++ b/lib/automake.mk @@ -557,9 +557,9 @@ CLEANFILES += lib/meta-flow.inc lib/nx-match.inc EXTRA_DIST += build-aux/extract-ofp-fields lib/ofp-actions.inc1: $(srcdir)/build-aux/extract-ofp-actions lib/ofp-actions.c - $(AM_V_GEN)$(run_python) $^ --prototypes > $@.tmp && mv $@.tmp $@ + $(AM_V_GEN)$(run_python) $< prototypes $(srcdir)/lib/ofp-actions.c > $@.tmp && mv $@.tmp $@ lib/ofp-actions.inc2: $(srcdir)/build-aux/extract-ofp-actions lib/ofp-actions.c - $(AM_V_GEN)$(run_python) $^ --definitions > $@.tmp && mv $@.tmp $@ + $(AM_V_GEN)$(run_python) $< definitions $(srcdir)/lib/ofp-actions.c > $@.tmp && mv $@.tmp $@ lib/ofp-actions.lo: lib/ofp-actions.inc1 lib/ofp-actions.inc2 CLEANFILES += lib/ofp-actions.inc1 lib/ofp-actions.inc2 EXTRA_DIST += build-aux/extract-ofp-actions @@ -601,3 +601,12 @@ lib/ovs-fields.7: $(srcdir)/build-aux/extract-ofp-fields include/openvswitch/met $(srcdir)/lib/meta-flow.xml > $@.tmp $(AM_V_at)mv $@.tmp $@ EXTRA_DIST += lib/meta-flow.xml + +man_MANS += lib/ovs-actions.7 +CLEANFILES += lib/ovs-actions.7 +lib/ovs-actions.7: $(srcdir)/build-aux/extract-ofp-actions lib/ovs-actions.xml + $(AM_V_GEN)PYTHONIOENCODING=utf8 $(run_python) $< \ + --ovs-version=$(VERSION) ovs-actions \ + $(srcdir)/lib/ovs-actions.xml > $@.tmp + $(AM_V_at)mv $@.tmp $@ +EXTRA_DIST += lib/ovs-actions.xml diff --git a/lib/learn.c b/lib/learn.c index c4d5b3e0c449..642ce18252d6 100644 --- a/lib/learn.c +++ b/lib/learn.c @@ -461,7 +461,7 @@ learn_parse__(char *orig, char *arg, const struct ofputil_port_map *port_map, } /* Parses 'arg' as a set of arguments to the "learn" action and appends a - * matching OFPACT_LEARN action to 'ofpacts'. ovs-ofctl(8) describes the + * matching OFPACT_LEARN action to 'ofpacts'. ovs-actions(7) describes the * format parsed. * * Returns NULL if successful, otherwise a malloc()'d string describing the @@ -483,7 +483,7 @@ learn_parse(char *arg, const struct ofputil_port_map *port_map, return error; } -/* Appends a description of 'learn' to 's', in the format that ovs-ofctl(8) +/* Appends a description of 'learn' to 's', in the format that ovs-actions(7) * describes. */ void learn_format(const struct ofpact_learn *learn, diff --git a/lib/multipath.c b/lib/multipath.c index e6ba4c60adf2..43a3d8f30466 100644 --- a/lib/multipath.c +++ b/lib/multipath.c @@ -136,7 +136,7 @@ multipath_algorithm(uint32_t hash, enum nx_mp_algorithm algorithm, } /* Parses 's_' as a set of arguments to the "multipath" action and initializes - * 'mp' accordingly. ovs-ofctl(8) describes the format parsed. + * 'mp' accordingly. ovs-actions(7) describes the format parsed. * * Returns NULL if successful, otherwise a malloc()'d string describing the * error. The caller is responsible for freeing the returned string.*/ @@ -214,7 +214,7 @@ multipath_parse__(struct ofpact_multipath *mp, const char *s_, char *s) } /* Parses 's_' as a set of arguments to the "multipath" action and initializes - * 'mp' accordingly. ovs-ofctl(8) describes the format parsed. + * 'mp' accordingly. ovs-actions(7) describes the format parsed. * * Returns NULL if successful, otherwise a malloc()'d string describing the * error. The caller is responsible for freeing the returned string. */ @@ -227,7 +227,7 @@ multipath_parse(struct ofpact_multipath *mp, const char *s_) return error; } -/* Appends a description of 'mp' to 's', in the format that ovs-ofctl(8) +/* Appends a description of 'mp' to 's', in the format that ovs-actions(7) * describes. */ void multipath_format(const struct ofpact_multipath *mp, struct ds *s) diff --git a/lib/nx-match.c b/lib/nx-match.c index 8f98032195af..fd3eac0c0e0e 100644 --- a/lib/nx-match.c +++ b/lib/nx-match.c @@ -1745,7 +1745,7 @@ oxm_match_from_string(const char *s, struct ofpbuf *b) return match_len; } -/* Parses 's' as a "move" action, in the form described in ovs-ofctl(8), into +/* Parses 's' as a "move" action, in the form described in ovs-actions(7), into * '*move'. * * Returns NULL if successful, otherwise a malloc()'d string describing the @@ -1825,7 +1825,7 @@ nxm_reg_load(const struct mf_subfield *dst, uint64_t src_data, /* nxm_parse_stack_action, works for both push() and pop(). */ /* Parses 's' as a "push" or "pop" action, in the form described in - * ovs-ofctl(8), into '*stack_action'. + * ovs-actions(7), into '*stack_action'. * * Returns NULL if successful, otherwise a malloc()'d string describing the * error. The caller is responsible for freeing the returned string. */ diff --git a/lib/ovs-actions.xml b/lib/ovs-actions.xml new file mode 100644 index 000000000000..f285d2607ff4 --- /dev/null +++ b/lib/ovs-actions.xml @@ -0,0 +1,2843 @@ +<?xml version="1.0" encoding="utf-8"?> +<actions> + <h1>Introduction</h1> + + <p> + This document aims to comprehensively document all of the OpenFlow actions + and instructions, both standard and non-standard, supported by Open + vSwitch, regardless of origin. The document includes information of + interest to Open vSwitch users, such as the semantics of each supported + action and the syntax used by Open vSwitch tools, and to developers seeking + to build controllers and switches compatible with Open vSwitch, such as the + wire format for each supported message. + </p> + + <h2>Actions</h2> + + <p> + In this document, we define an <dfn>action</dfn> as an OpenFlow action, + which is a kind of command that specifies what to do with a packet. + Actions are used in OpenFlow flows to describe what to do when the flow + matches a packet, and in a few other places in OpenFlow. Each version of + the OpenFlow specification defines standard actions, and beyond that many + OpenFlow switches, including Open vSwitch, implement extensions to the + standard. + </p> + + <p> + OpenFlow groups actions in two ways: as an <dfn>action list</dfn> or an + <dfn>action set</dfn>, described below. + </p> + + <h3>Action Lists</h3> + + <p> + An <dfn>action list</dfn>, a concept present in every version of OpenFlow, + is simply an ordered sequence of actions. The OpenFlow specifications + require a switch to execute actions within an action list in the order + specified, and to refuse to execute an action list entirely if it cannot + implement the actions in that order [OpenFlow 1.0, section 3.3], with one + exception: when an action list outputs multiple packets, the switch may + output the packets in an order different from that specified. Usually, + this exception is not important, especially in the common case when the + packets are output to different ports. + </p> + + <h3>Action Sets</h3> + + <p> + OpenFlow 1.1 introduced the concept of an <dfn>action set</dfn>. An action + set is also a sequence of actions, but the switch reorders the actions and + drops duplicates according to rules specified in the OpenFlow + specifications. Because of these semantics, some standard OpenFlow actions + cannot usefully be included in an action set. For some, but not all, Open + vSwitch extension actions, Open vSwitch defines its own action set + semantics and ordering. + </p> + + <p> + The OpenFlow pipeline has an action set associated with it as a packet is + processed. After pipeline processing is otherwise complete, the switch + executes the actions in the action set. + </p> + + <p> + Open vSwitch applies actions in an action set in the following order: + Except as noted otherwise below, the action set only executes at most a + single action of each type, and when more than one action of a given type + is present, the one added to the set later replaces the earlier action: + </p> + + <ol> + <li><code>strip_vlan</code></li> + <li><code>pop_mpls</code></li> + <li><code>decap</code></li> + <li><code>encap</code></li> + <li><code>push_mpls</code></li> + <li><code>push_vlan</code></li> + <li><code>dec_ttl</code></li> + <li><code>dec_mpls_ttl</code></li> + <li><code>dec_nsh_ttl</code></li> + <li> + <p> + All of the following actions are executed in the order added to the + action set, with cumulative effect. That is, when multiple actions + modify the same part of a field, the later modification takes effect, + and when they modify different parts of a field (or different fields), + then both modifications are applied: + </p> + + <ul> + <li><code>load</code></li> + <li><code>move</code></li> + <li><code>mod_dl_dst</code></li> + <li><code>mod_dl_src</code></li> + <li><code>mod_nw_dst</code></li> + <li><code>mod_nw_src</code></li> + <li><code>mod_nw_tos</code></li> + <li><code>mod_nw_ecn</code></li> + <li><code>mod_nw_ttl</code></li> + <li><code>mod_tp_dst</code></li> + <li><code>mod_tp_src</code></li> + <li><code>mod_vlan_pcp</code></li> + <li><code>mod_vlan_vid</code></li> + <li><code>set_field</code></li> + <li><code>set_tunnel</code></li> + <li><code>set_tunnel64</code></li> + </ul> + </li> + <li><code>set_queue</code></li> + <li> + <code>group</code>, <code>output</code>, <code>resubmit</code>, + <code>ct_clear</code>, or <code>ct</code>. If more than one of these + actions is present, then the one listed earliest above is executed and + the others are ignored, regardless of the order in which they were added + to the action set. (If none of these actions is present, the action set + has no real effect, because the modified packet is not sent anywhere and + thus the modifications are not visible.) + </li> + </ol> + + <p> + An action set may only contain the actions listed above. + </p> + + <h2>Error Handling</h2> + + <p> + Packet processing can encounter a variety of errors: + </p> + + <dl> + <dt>Bridge not found</dt> + <dd> + <p> + Open vSwitch supports an extension to the standard OpenFlow + <code>controller</code> action called a ``continuation,'' which allows + the controller to interrupt and later resume the processing of a packet + through the switch pipeline. This error occurs when such a packet's + processing cannot be resumed, e.g. because the bridge processing it has + been destroyed. Open vSwitch reports this error to the controller as + Open vSwitch extension error <code>NXR_STALE</code>. + </p> + + <p> + This error prevents packet processing entirely. + </p> + </dd> + + <dt>Recursion too deep</dt> + <dd> + <p> + While processing a given packet, Open vSwitch limits the flow table + recursion depth to 64, to ensure that packet processing uses a finite + amount of time and space. Actions that count against the recursion + limit include <code>resubmit</code> from a given OpenFlow table to the + same or an earlier table, <code>group</code>, and <code>output</code> + to patch ports. + </p> + + <p> + A <code>resubmit</code> from one table to a later one (or, + equivalently. a <code>goto_table</code> instruction) does not count + against the depth limit because resubmits to strictly monotonically + increasing tables will eventually terminate. OpenFlow tables are most + commonly traversed in numerically increasing order, so this limit has + little effect on conventionally designed OpenFlow pipelines. + </p> + + <p> + This error terminates packet processing. Any previous side effects + (e.g. output actions) are retained. + </p> + + <p> + Usually this error indicates a loop or other bug in the OpenFlow flow + tables. To assist debugging, when this error occurs, Open vSwitch 2.10 + and later logs a trace of the packet execution, as if by + <code>ovs-appctl ofproto/trace</code>, rate-limited to one per minute + to reduce the log volume. + </p> + </dd> + + <dt>Too many resubmits</dt> + <dd> + <p> + Open vSwitch limits the total number of <code>resubmit</code> actions + that a given packet can execute to 4,096. For this purpose, + <code>goto_table</code> instructions and output to the + <code>table</code> port are treated like <code>resubmit</code>. This + limits the amount of time to process a single packet. + </p> + + <p> + Unlike the limit on recursion depth, the limit on resubmits counts all + resubmits, regardless of direction. + </p> + + <p> + This error has the same effect, including logging, as exceeding the + recursion depth limit. + </p> + </dd> + + <dt>Stack too deep</dt> + <dd> + <p> + Open vSwitch limits the amount of data that the <code>push</code> + action can put onto the stack at one time to 64 kB of data. + </p> + + <p> + This error terminates packet processing. Any previous side effects + (e.g. output actions) are retained. + </p> + </dd> + + <dt>No recirculation context</dt> + <dt>Recirculation conflict</dt> + <dd> + These errors indicate internal errors inside Open vSwitch and should + generally not occur. If you notice recurring log messages about these + errors, please report a bug. + </dd> + + <dt>Too many MPLS labels</dt> + <dd> + <p> + Open vSwitch can process packets with any number of MPLS labels, but + its ability to push and pop MPLS labels is limited, currently to 3 + labels. Attempting to push more than the supported number of labels + onto a packet, or to pop any number of labels from a packet with more + than the supported number, raises this error. + </p> + + <p> + This error terminates packet processing, retaining any previous side + effects (e.g. output actions). When this error arises within the + execution of a group bucket, it only terminates that bucket's + execution, not packet processing overall. + </p> + </dd> + + <dt>Invalid tunnel metadata</dt> + <dd> + <p> + Open vSwitch raises this error when it processes a Geneve packet that + has TLV options with an invalid form, e.g. where the length in a TLV + would extend past the end of the options. + </p> + + <p> + This error prevents packet processing entirely. + </p> + </dd> + + <dt>Unsupported packet type</dt> + <dd> + <p> + When a <code>encap</code> action encapsulates a packet, Open vSwitch + raises this error if it does not support the combination of the new + encapsulation with the current packet. <code>encap(ethernet)</code> + raises this error if the current packet is not an L3 packet, and + <code>encap(nsh)</code> raises this error if the current packet is not + Ethernet, IPv4, IPv6, or NSH. + </p> + + <p> + When a <code>decap</code> action decapsulates a packet, Open vSwitch + raises this error if it does not support the type of inner packet. + <code>decap</code> of an Ethernet header raises this error if a VLAN + header is present, <code>decap</code> of a NSH packet raises this error + if the NSH inner packet is not Ethernet, IPv4, IPv6, or NSH, and + <code>decap</code> of other types of packets is unsupported and also + raises this error. + </p> + + <p> + This error terminates packet processing, retaining any previous side + effects (e.g. output actions). When this error arises within the + execution of a group bucket, it only terminates that bucket's + execution, not packet processing overall. + </p> + </dd> + </dl> + + <h2>Inconsistencies</h2> + + <p> + OpenFlow 1.0 allows any action to be part of any flow, regardless of the + flow's match. Some combinations do not make sense, e.g. an + <code>set_nw_tos</code> action in a flow that matches only ARP packets or + <code>strip_vlan</code> in a flow that matches packets without VLAN tags. + Other combinations have varying results depending on the kind of packet + that the flow processes, e.g. a <code>set_nw_src</code> action in a flow + that does not match on Ethertype will be treated as a no-op when it + processes a non-IPv4 packet. Nevertheless OVS allows all of the above in + conformance with OpenFlow 1.0, that is, the following will succeed: + </p> + + <pre> +$ ovs-ofctl -O OpenFlow10 add-flow br0 arp,actions=mod_nw_tos:12 +$ ovs-ofctl -O OpenFlow10 add-flow br0 dl_vlan=0xffff,actions=strip_vlan +$ ovs-ofctl -O OpenFlow10 add-flow br0 actions=mod_nw_src:1.2.3.4 + </pre> + + <p> + Open vSwitch calls these kinds of combinations <dfn>inconsistencies</dfn> + between match and actions. OpenFlow 1.1 and later forbid inconsistencies, + and disallow the examples described above by preventing such flows from + being added. All of the above, for example, will fail with an error + message if one replaces <code>OpenFlow10</code> by <code>OpenFlow11</code>. + </p> + + <p> + OpenFlow 1.1 and later cannot detect and disallow all inconsistencies. For + example, the <code>write_actions</code> instruction arbitrarily delays + execution of the actions inside it, which can even be canceled with + <code>clear_actions</code>, so that there is no way to ensure that its + actions are consistent with the packet at the time they execute. Thus, + actions with <code>write_actions</code> and some other contexts are exempt + from consistency requirements. + </p> + + <p> + When OVS executes an action inconsistent with the packet, it treats it as a + no-op. + </p> + + <h2>Inter-Version Compatibility</h2> + + <p> + Open vSwitch supports multiple OpenFlow versions simultaneously on a single + switch. When actions are added with one OpenFlow version and then + retrieved with another, Open vSwitch does its best to translate between + them. + </p> + + <p> + Inter-version compatibility issues can still arise when different + connections use different OpenFlow versions. Backward compatibility is the + most obvious case. Suppose, for example, that an OpenFlow 1.1 session adds + a flow with a <code>push_vlan</code> action, for which there is no + equivalent in OpenFlow 1.0. If an OpenFlow 1.0 session retrieves this + flow, Open vSwitch must somehow represent the action. + </p> + + <p> + Forward compatibility can also be an issue, because later OpenFlow versions + sometimes remove functionality. The best example is the + <code>enqueue</code> action from OpenFlow 1.0, which OpenFlow 1.1 removed. + </p> + + <p> + In practice, Open vSwitch uses a variety of strategies for inter-version + compatibility: + </p> + + <ul> + <li> + Most standard OpenFlow actions, such as <code>output</code> actions, + translate without compatibility issues. + </li> + + <li> + Open vSwitch supports its extension actions in every OpenFlow version, so + they do not pose inter-version compatibility problems. + </li> + + <li> + Open vSwitch sometimes adds extension actions to ensure backward or + forward compatibility. For example, for backward compatibility with the + <code>group</code> action added in OpenFlow 1.1, Open vSwitch includes + an OpenFlow 1.0 extension <code>group</code> action. + </li> + </ul> + + <p> + Perfect inter-version compatibility is not possible, so best results + require OpenFlow connections to use a consistent version. One may enforce + use of a particular version by setting the <code>protocols</code> column + for a bridge, e.g. to force <code>br0</code> to use only OpenFlow 1.3: + </p> + + <pre> + ovs-vsctl set bridge br0 protocols=OpenFlow13 + </pre> + + <h2>Field Specifications</h2> + + <p> + Many Open vSwitch actions refer to fields. In such cases, fields may + usually be referred to by their common names, such as <code>eth_dst</code> + for the Ethernet destination field, or by their full OXM or NXM names, such + as <code>NXM_OF_ETH_DST</code> or <code>OXM_OF_ETH_DST</code>. Before Open + vSwitch 2.7, only OXM or NXM field names were accepted. + </p> + + <p> + Many actions that act on fields can also act on <dfn>subfields</dfn>, that + is, parts of fields, written as + <code><var>field</var>[<var>start</var>..<var>end</var>]</code>, where + <var>start</var> is the first bit and <var>end</var> is the last bit to use + in <var>field</var>, e.g. <code>vlan_tci[13..15]</code> for the VLAN PCP. + A single-bit subfield may also be written as + <code><var>field</var>[<var>offset</var>]</code>, + e.g. <code>vlan_tci[13]</code> for the least-significant bit of the VLAN + PCP. Empty brackets may be used to explicitly designate an entire field, + e.g. <code>vlan_tci[]</code> for the entire 16-bit VLAN TCI header. Before + Open vSwitch 2.7, brackets were required in field specifications. + </p> + + <p> + See <code>ovs-fields</code>(7) for a list of fields and their names. + </p> + + <h2>Port Specifications</h2> + + <p> + Many Open vSwitch actions refer to OpenFlow ports. In such cases, the port + may be specified as a numeric port number in the range 0 to 65,535, + although Open vSwitch only assigns port numbers in the range 1 through + 62,279 to ports. OpenFlow 1.1 and later use 32-bit port numbers, but Open + vSwitch never assigns a port number that requires more than 16 bits. + </p> + + <p> + In most contexts, the name of a port may also be used. (The most obvious + context where a port name may not be used is in an <code>ovs-ofctl</code> + command along with the <code>--no-names</code> option.) When a port's name + contains punctuation or could be ambiguous with other actions, the name may + be enclosed in double quotes, with JSON-like string escapes supported (see + [RFC 8259]). + </p> + + <p> + Open vSwitch also supports the following standard OpenFlow port names (even + in contexts where port names are not otherwise supported). The + corresponding OpenFlow 1.0 and 1.1+ port numbers are listed alongside them + but should not be used in flow syntax: + </p> + + <ul> + <li><code>in_port</code> (65528 or 0xfff8; 0xfffffff8)</li> + <li><code>table</code> (65529 or 0xfff9; 0xfffffff9)</li> + <li><code>normal</code> (65530 or 0xfffa; 0xfffffffa)</li> + <li><code>flood</code> (65531 or 0xfffb; 0xfffffffb)</li> + <li><code>all</code> (65532 or 0xfffc; 0xfffffffc)</li> + <li><code>controller</code> (65533 or 0xfffd; 0xfffffffd)</li> + <li><code>local</code> (65534 or 0xfffe; 0xfffffffe)</li> + <li><code>any</code> or <code>none</code> (65535 or 0xffff; 0xffffffff)</li> + <li><code>unset</code> (not in OpenFlow 1.0; 0xfffffff7)</li> + </ul> + +  + + <group title="Output Actions"> + <p> + These actions send a packet to a physical port or a controller. A packet + that never encounters an output action on its trip through the Open + vSwitch pipeline is effectively dropped. Because actions are executed in + order, a packet modification action that is not eventually followed by an + output action will not have an externally visible effect. + </p> + + <action name="OUTPUT, OUTPUT_REG, OUTPUT_TRUNC"> + <h2>The <code>output</code> action</h2> + <syntax><var>port</var></syntax> + <syntax><code>output:</code><var>port</var></syntax> + <syntax><code>output:<var>field</var></code></syntax> + <syntax><code>output(port=<var>port</var>, max_len=<var>nbytes</var>)</code></syntax> + + <p> + Outputs the packet to an OpenFlow port most commonly specified as + <var>port</var>. Alternatively, the output port may be read from + <var>field</var>, a field or subfield in the syntax described under + ``Field Specifications'' above. Either way, if the port is the + packet's input port, the packet is not output. + </p> + + <p> + The port may be one of the following standard OpenFlow ports: + </p> + + <dl> + <dt><code>local</code></dt> + <dd> + Outputs the packet on the ``local port'' that corresponds to the + network device that has the same name as the bridge, unless the + packet was received on the local port. OpenFlow switch + implementations are not required to have a local port, but Open + vSwitch bridges always do. + </dd> + + <dt><code>in_port</code></dt> + <dd> + Outputs the packet on the port on which it was received. This is the + only standard way to output the packet to the input port (but see + ``Output to the Input port'', below). + </dd> + </dl> + + <p> + The port may also be one of the following additional OpenFlow ports, + unless <code>max_len</code> is specified: + </p> + + <dl> + <dt><code>normal</code></dt> + <dd> + Subjects the packet to the device's normal L2/L3 processing. This + action is not implemented by all OpenFlow switches, and each switch + implements it differently. + </dd> + + <dt><code>flood</code></dt> + <dd> + Outputs the packet on all switch physical ports, except the port on + which it was received and any ports on which flooding is disabled. + Flooding can be disabled automatically on a port by Open vSwitch when + IEEE 802.1D spanning tree (STP) or rapid spanning tree (RSTP) is + enabled, or by a controller using an OpenFlow + <code>OFPT_MOD_PORT</code> request to set the port's + <code>OFPPC_NO_FLOOD</code> flag (<code>ovs-ofctl mod-port</code> + provides a command-line interface to set this flag). + </dd> + + <dt><code>all</code></dt> + <dd> + Outputs the packet on all switch physical ports except the port on + which it was received. + </dd> + + <dt><code>controller</code></dt> + <dd> + Sends and its metadata the packet to an OpenFlow controller or + controllers encapsulated in an OpenFlow ``packet-in'' message. The + separate <code>controller</code> action, described below, provides + more options for output to a controller. + </dd> + </dl> + + <p> + Open vSwitch rejects output to other standard OpenFlow ports, including + <code>none</code>, <code>unset</code>, and port numbers reserved for + future use as standard ports, with the error + <code>OFPBAC_BAD_OUT_PORT</code>. + </p> + + <p> + With <var>max_len</var>, the packet is truncated to at most + <var>nbytes</var> bytes before being output. In this case, the output + port may not be a patch port. Truncation is just for the single output + action, so that later actions in the OpenFlow pipeline work with the + complete packet. The truncation feature is meant for use in monitoring + applications, e.g. for mirroring packets to a collector. + </p> + + <p> + When an <code>output</code> action specifies the number of a port that + does not currently exist (and is not in the range for standard ports), + the OpenFlow specification allows but does not require OVS to reject + the action. All versions of Open vSwitch treat such an action as a + no-op. If a port with the number is created later, then the action + will be honored at that point. (OpenFlow requires OVS to reject output + to a port number that will never be valid, with + <code>OFPBAC_BAD_OUT_PORT</code>, but this situation does not arise + when OVS is a software switch, since the user can add or renumber ports + at any time.) + </p> + + <p> + A controller can suppress output to a port by setting its + <code>OFPPC_NO_FORWARD</code> flag using an OpenFlow + <code>OFPT_MOD_PORT</code> request (<code>ovs-ofctl mod-port</code> + provides a command-line interface to set this flag). When output is + disabled, <code>output</code> actions (and other actions that output to + the port) are allowed but have no effect. + </p> + + <p> + Open vSwitch allows output to a port that does not exist, although + OpenFlow allows switches to reject such actions. + </p> + +  +  + + <h3>Output to the Input Port</h3> + + <p> + OpenFlow requires a switch to ignore attempts to send a packet out its + ingress port in the most straightforward way. For example, + <code>output:234</code> has no effect if the packet has ingress port + 234. The rationale is that dropping these packets makes it harder to + loop the network. Sometimes this behavior can even be convenient, + e.g. it is often the desired behavior in a flow that forwards a packet + to several ports (``floods'' the packet). + </p> + + <p> + Sometimes one really needs to send a packet out its ingress port + (``hairpin''). In this case, use <code>in_port</code> to explicitly + output the packet to its input port, e.g.: + </p> + + <pre> + $ ovs-ofctl add-flow br0 in_port=2,actions=in_port + </pre> + + <p> + This also works in some circumstances where the flow doesn't match on + the input port. For example, if you know that your switch has five + ports numbered 2 through 6, then the following will send every received + packet out every port, even its ingress port: + </p> + + <pre> + $ ovs-ofctl add-flow br0 actions=2,3,4,5,6,in_port + </pre> + + <p> + or, equivalently: + </p> + + <pre> + $ ovs-ofctl add-flow br0 actions=all,in_port + </pre> + + <p> + Sometimes, in complicated flow tables with multiple levels of + <code>resubmit</code> actions, a flow needs to output to a particular + port that may or may not be the ingress port. It's difficult to take + advantage of output to <code>in_port</code> in this situation. To + help, Open vSwitch provides, as an OpenFlow extension, the ability to + modify the <code>in_port</code> field. Whatever value is currently in + the <code>in_port</code> field is both the port to which output will be + dropped and the destination for <code>in_port</code>. This means that + the following adds flows that reliably output to port 2 or to ports 2 + through 6, respectively: + </p> + + <pre> + $ ovs-ofctl add-flow br0 "in_port=2,actions=load:0->in_port,2" + $ ovs-ofctl add-flow br0 "actions=load:0->in_port,2,3,4,5,6" + </pre> + + <p> + If <code>in_port</code> is important for matching or other reasons, one + may save and restore it on the stack: + </p> + + <pre> + $ ovs-ofctl add-flow br0 actions="push:in_port,\ + load:0->in_port,\ + 2,3,4,5,6,\ + pop:in_port" + </pre> + + <conformance> + All versions of OpenFlow and Open vSwitch support <code>output</code> + to a literal <var>port</var>. Output to a register is an OpenFlow + extension introduced in Open vSwitch 1.3. Output with truncation is an + OpenFlow extension introduced in Open vSwitch 2.6. + </conformance> + </action> + + <action name="CONTROLLER"> + <h2>The <code>controller</code> action</h2> + <syntax><code>controller</code></syntax> + <syntax><code>controller:</code><var>max_len</var></syntax> + <syntax><code>controller(</code><var>key</var>[<code>=</code><var>value</var>]<code>,</code> ...<code>)</code></syntax> + + <p> + Sends the packet and its metadata to an OpenFlow controller or + controllers encapsulated in an OpenFlow ``packet-in'' message. The + supported options are: + </p> + + <dl> + <dt><code>max_len=</code><var>max_len</var></dt> + <dd> + <p> + Limit to <var>max_len</var> the number of bytes of the packet to + send in the ``packet-in.'' A <var>max_len</var> of 0 prevents any + of the packet from being sent (thus, only metadata is included). + By default, the entire packet is sent, equivalent to a + <var>max_len</var> of 65535. + </p> + </dd> + + <dt><code>reason=</code><var>reason</var></dt> + <dd> + Specify <var>reason</var> as the reason for sending the message in + the ``packet-in.'' The supported reasons are <code>no_match</code>, + <code>action</code>, <code>invalid_ttl</code>, + <code>action_set</code>, <code>group</code>, and + <code>packet_out</code>. The default reason is <code>action</code>. + </dd> + + <dt><code>id=</code><var>controller_id</var></dt> + <dd> + Specify <var>controller-id</var>, a 16-bit integer, as the connection + ID of the OpenFlow controller or controllers to which the + ``packet-in'' message should be sent. The default is zero. Zero is + also the default connection ID for each controller connection, and a + given controller connection will only have a nonzero connection ID if + its controller uses the <code>NXT_SET_CONTROLLER_ID</code> Open + vSwitch extension to OpenFlow. + </dd> + + <dt><code>userdata=</code><var>hh</var>...</dt> + <dd> + Supplies the bytes represented as hex digits <var>hh</var> as + additional data to the controller in the ``packet-in'' message. + Pairs of hex digits may be separated by periods for readability. + </dd> + + <dt><code>pause</code></dt> + <dd> + Causes the switch to freeze the packet's trip through Open vSwitch + flow tables and serializes that state into the packet-in message as a + ``continuation,'' an additional property in the + <code>NXT_PACKET_IN2</code> message. The controller can later send + the continuation back to the switch in an <code>NXT_RESUME</code> + message, which will restart the packet's traversal from the point + where it was interrupted. This permits an OpenFlow controller to + interpose on a packet midway through processing in Open vSwitch. + </dd> + </dl> + + <conformance> + All versions of OpenFlow and Open vSwitch support + <code>controller</code> action and its <code>max_len</code> option. + The <code>userdata</code> and <code>pause</code> options require the + Open vSwitch <code>NXAST_CONTROLLER2</code> extension action added in + Open vSwitch 2.6. In the absence of these options, the + <var>reason</var> (other than <code>reason=action</code>) and + <var>controller_id</var> (option than <code>controller_id=0</code>) + options require the Open vSwitch <code>NXAST_CONTROLLER</code> + extension action added in Open vSwitch 1.6. + </conformance> + </action> + + <action name="ENQUEUE"> + <h2>The <code>enqueue</code> action</h2> + <syntax><code>enqueue(</code><var>port</var><code>,</code><var>queue</var><code>)</code></syntax> + <syntax><code>enqueue:</code><var>port</var><code>:</code><var>queue</var></syntax> + + <p> + Enqueues the packet on the specified <var>queue</var> within port + <var>port</var>. + </p> + + <p> + <var>port</var> must be an OpenFlow port number or name as described + under ``Port Specifications'' above. <var>port</var> may be + <code>in_port</code> or <code>local</code> but the other standard + OpenFlow ports are not allowed. + </p> + + <p> + <var>queue</var> must be a a number between 0 and 4294967294 + (0xfffffffe), inclusive. The number of actually supported queues + depends on the switch. Some OpenFlow implementations do not support + queuing at all. In Open vSwitch, the supported queues vary depending + on the operating system, datapath, and hardware in use. Use the + <code>QoS</code> and <code>Queue</code> tables in the Open vSwitch + database to configure queuing on individual OpenFlow ports (see + <code>ovs-vswitchd.conf.db</code>(5) for more information). + </p> + + <conformance> + <p> + Only OpenFlow 1.0 supports <code>enqueue</code>. OpenFlow 1.1 added + the <code>set_queue</code> action to use in its place along with + <code>output</code>. + </p> + + <p> + Open vSwitch translates <code>enqueue</code> to a sequence of three + actions in OpenFlow 1.1 or later: <code>set_queue:<var>queue</var>, + output:<var>port</var>, pop_queue</code>. This is equivalent in + behavior as long as the flow table does not otherwise use + <code>set_queue</code>, but it relies on the <code>pop_queue</code> + Open vSwitch extension action. + </p> + </conformance> + </action> + + <action name="BUNDLE,BUNDLE_LOAD"> + <h2>The <code>bundle</code> and <code>bundle_load</code> actions</h2> + <syntax><code>bundle(</code><var>fields</var><code>, </code><var>basis</var><code>, </code><var>algorithm</var><code>, </code>ofport<code>, slaves:</code><var>port</var>...<code>)</code></syntax> + <syntax><code>bundle_load(</code><var>fields</var><code>, </code><var>basis</var><code>, </code><var>algorithm</var><code>, </code>ofport<code>, </code><var>dst</var><code>, slaves:</code><var>port</var>...<code>)</code></syntax> + + <p> + These actions choose a port (``slave'') from a comma-separated OpenFlow + <var>port</var> list. After selecting the port, <code>bundle</code> + outputs to it, whereas <code>bundle_load</code> writes its port number + to <var>dst</var>, which must be a field or subfield in the syntax + described under ``Field Specifications'' above. + </p> + + <p> + These actions hash a set of <var>fields</var> using <var>basis</var> as + a universal hash parameter, then apply the bundle link selection + <var>algorithm</var> to choose a <var>port</var>. + </p> + + <p> + <var>fields</var> must be one of the following. For the options with + ``symmetric'' in the name, reversing source and destination addresses + yields the same hash: + </p> + + <dl> + <dt><code>eth_src</code></dt> + <dd> + Ethernet source address. + </dd> + + <dt><code>nw_src</code></dt> + <dd> + IPv4 or IPv6 source address. + </dd> + + <dt><code>nw_dst</code></dt> + <dd> + IPv4 or IPv6 destination address. + </dd> + + <dt><code>symmetric_l4</code></dt> + <dd> + Ethernet source and destination, Ethernet type, VLAN ID or IDs (if + any), IPv4 or IPv6 source and destination, IP protocol, TCP or SCTP + (but not UDP) source and destination. + </dd> + + <dt><code>symmetric_l3l4</code></dt> + <dd> + IPv4 or IPv6 source and destination, IP protocol, TCP or SCTP (but + not UDP) source and destination. + </dd> + + <dt><code>symmetric_l3l4+udp</code></dt> + <dd> + Like <code>symmetric_l3l4</code> but include UDP ports. + </dd> + </dl> + + <conformance> + Open vSwitch 1.2 introduced the <code>bundle</code> and + <code>bundle_load</code> OpenFlow extension actions. + </conformance> + </action> + + <action name="GROUP"> + <h2>The <code>group</code> action</h2> + <syntax><code>group:</code><var>group</var></syntax> + <p> + Outputs the packet to the OpenFlow group <var>group</var>, which must + be a number in the range 0 to 4294967040 (0xffffff00). The group must + exist or Open vSwitch will refuse to add the flow. When a group is + deleted, Open vSwitch also deletes all of the flows that output to it. + </p> + + <p> + Groups contain action sets, whose semantics are described above in the + section ``Action Sets''. The semantics of action sets can be + surprising to users who expect action list semantics, since action sets + reorder and sometimes ignore actions. + </p> + + <p> + A <code>group</code> action usually executes the action set or sets in + one or more group buckets. Open vSwitch saves the packet and metadata + before it executes each bucket, and then restores it afterward. Thus, + when a group executes more than one bucket, this means that each bucket + executes on the same packet and metadata. Moreover, regardless of the + number of buckets executed, the packet and metadata are the same before + and after executing the group. + </p> + + <p> + Sometimes saving and restoring the packet and metadata can be + undesirable. In these situations, workarounds are possible. For + example, consider a pipeline design in which a <code>select</code> + group bucket is to communicate to a later stage of processing a value + based on which bucket was selected. An obvious design would be for the + bucket to communicate the value via <code>set_field</code> on a + register. This does not work because registers are part of the + metadata that <code>group</code> saves and restores. A design that + would work would be for the bucket to recursively invoke the rest of + the pipeline with <code>resubmit</code> rather than to attempt to + return it. Another possibility is for the bucket to use + <code>push</code> to put the value on the stack for the caller to + <code>pop</code> off, since <code>group</code> preserves only packet + data and metadata, not the stack. + </p> + + <p> + An <code>exit</code> action within a group bucket terminates only + execution of that bucket, not other buckets or the overall pipeline. + </p> + + <conformance> + OpenFlow 1.1 introduced <code>group</code>. Open vSwitch 2.6 and later + also supports <code>group</code> as an extension to OpenFlow 1.0. + </conformance> + </action> + + </group> + + <group title="Encapsulation and Decapsulation Actions"> + <action name="STRIP_VLAN"> + <h2>The <code>strip_vlan</code> and <code>pop</code> actions</h2> + <syntax><code>strip_vlan</code></syntax> + <syntax><code>pop_vlan</code></syntax> + + <p> + Removes the outermost VLAN tag, if any, from the packet. + </p> + + <p> + The two names for this action are synonyms with no semantic difference. + The OpenFlow 1.0 specification uses the name <code>strip_vlan</code> + and later versions use <code>pop_vlan</code>, but OVS accepts either + name regardless of version. + </p> + + <p> + In OpenFlow 1.1 and later, consistency rules allow + <code>strip_vlan</code> only in a flow that matches only packets with a + VLAN tag (or following an action that pushes a VLAN tag, such as + <code>push_vlan</code>). See ``Inconsistencies'', above, for more + information. + </p> + + <conformance> + All versions of OpenFlow and Open vSwitch support this action. + </conformance> + </action> + + <action name="PUSH_VLAN"> + <h2>The <code>push_vlan</code> action</h2> + <syntax><code>push_vlan:</code><var>ethertype</var></syntax> + + <p> + Pushes a new outermost VLAN onto the packet. Uses TPID + <var>ethertype</var>, which must be <code>0x8100</code> for an 802.1Q + C-tag or <code>0x88a8</code> for a 802.1ad S-tag. + </p> + + <conformance> + OpenFlow 1.1 and later supports this action. Open vSwitch 2.8 added + support for multiple VLAN tags (with a limit of 2) and 802.1ad S-tags. + </conformance> + </action> + + <action name="PUSH_MPLS"> + <h2>The <code>push_mpls</code> action</h2> + <syntax><code>push_mpls:<var>ethertype</var></code></syntax> + + <p> + Pushes a new outermost MPLS label stack entry (LSE) onto the packet and + changes the packet's Ethertype to <var>ethertype</var>, which must be + either <code>B0x8847</code> or <code>0x8848</code>. + </p> + + <p> + If the packet did not already contain any MPLS labels, initializes the + new LSE as: + </p> + + <dl> + <dt>Label</dt> + <dd> + 2, if the packet contains IPv6, 0 otherwise. + </dd> + <dt>TC</dt> + <dd> + The low 3 bits of the packet's DSCP value, or 0 if the packet is not + IP. + </dd> + <dt>TTL</dt> + <dd> + Copied from the IP TTL, or 64 if the packet is not IP. + </dd> + </dl> + + <p> + If the packet did already contain an MPLS label, initializes the new + outermost label as a copy of the existing outermost label. + </p> + + <p> + OVS currently supports at most 3 MPLS labels. + </p> + + <p> + This action applies only to Ethernet packets. + </p> + + <conformance> + Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later + support <code>push_mpls</code>. Open vSwitch implements + <code>push_mpls</code> as an extension to OpenFlow 1.0. + </conformance> + </action> + + <action name="POP_MPLS"> + <h2>The <code>pop_mpls</code> action</h2> + <syntax><code>pop_mpls:<var>ethertype</var></code></syntax> + + <p> + Strips the outermost MPLS label stack entry and changes the packet's + Ethertype to <var>ethertype</var>. + </p> + + <p> + This action applies only to Ethernet packets with at least one MPLS + label. If there is more than one MPLS label, then <var>ethertype</var> + should be an MPLS Ethertype (<code>B0x8847</code> or + <code>0x8848</code>). + </p> + + <conformance> + Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later + support <code>pop_mpls</code>. Open vSwitch implements + <code>pop_mpls</code> as an extension to OpenFlow 1.0. + </conformance> + </action> + + <action name="ENCAP"> + <h2>The <code>encap</code> action</h2> + <syntax><code>encap(nsh(</code>[<code>md_type=<var>md_type</var></code>]<code>, </code>[<code>tlv(<var>class</var>,<var>type</var>,<var>value</var>)</code>]...<code>))</code></syntax> + <syntax><code>encap(ethernet)</code></syntax> + + <p> + The <code>encap</code> action encapsulates a packet with a specified + header. It has variants for different kinds of encapsulation. + </p> + + <p> + The <code>encap(nsh(</code>...<code>))</code> variant encapsulates an + Ethernet frame with NSH. The <var>md_type</var> may be <code>1</code> + or <code>2</code> for metadata type 1 or 2, defaulting to 1. For + metadata type 2, TLVs may be specified with <var>class</var> as a + 16-bit hexadecimal integer beginning with <code>0x</code>, + <var>type</var> as an 8-bit decimal integer, and <var>value</var> a + sequence of pairs of hex digits beginning with <code>0x</code>. For + example: + </p> + + <dl> + <dt><code>encap(nsh(md_type=1))</code></dt> + <dd> + Encapsulates the packet with an NSH header with metadata type 1. + </dd> + + <dt><code>encap(nsh(md_type=2,tlv(0x1000,10,0x12345678)))</code></dt> + <dd> + Encapsulates the packet with an NSH header, NSH metadata type 2, and + an NSH TLV with class 0x1000, type 10, and the 4-byte value + 0x12345678. + </dd> + </dl> + + <p> + The <code>encap(ethernet)</code> variant encapsulate a bare L3 packet + in an Ethernet frame. The Ethernet type is initialized to the L3 + packet's type, e.g. 0x0800 if the L3 packet is IPv4. The Ethernet + source and destination are initially zeroed. + </p> + + <conformance> + This action is an Open vSwitch extension to OpenFlow 1.3 and later, + introduced in Open vSwitch 2.8. + </conformance> + </action> + + <action name="DECAP"> + <h2>The <code>decap</code> action</h2> + <syntax><code>decap</code></syntax> + + <p> + Removes an outermost encapsulation from the packet: + </p> + + <ul> + <li> + If the packet is an Ethernet packet, removes the Ethernet header, + which changes the packet into a bare L3 packet. If the packet has + VLAN tags, raises an unsupported packet type error (see ``Error + Handling'', above). + </li> + + <li> + Otherwise, if the packet is an NSH packet, removes the NSH header, + revealing the inner packet. Open vSwitch supports Ethernet, IPv4, + IPv6, and NSH inner packet types. Other types raise unsupported + packet type errors. + </li> + + <li> + Otherwise, raises an unsupported packet type error. + </li> + </ul> + + <conformance> + This action is an Open vSwitch extension to OpenFlow 1.3 and later, + introduced in Open vSwitch 2.8. + </conformance> + </action> + </group> + + <group title="Field Modification Actions"> + <p> + These actions modify packet data and metadata fields. + </p> + + <action name="SET_FIELD"> + <h2>The <code>set_field</code> and <code>load</code> actions</h2> + <syntax><code>set_field:</code><var>value</var>[<code>/</code><var>mask</var>]<code>-></code><var>dst</var></syntax> + <syntax><code>load:</code><var>value</var><code>-></code><var>dst</var><code></code></syntax> + + <p> + These actions loads a literal value into a field or part of a field. + The <code>set_field</code> action takes <var>value</var> in the + customary syntax for field <var>dst</var>, + e.g. <code>00:11:22:33:44:55</code> for an Ethernet address, and + <var>dst</var> as the field's name. The optional <var>mask</var> + allows part of a field to be set. + </p> + + <p> + The <code>load</code> action takes <var>value</var> as an integer value + (in decimal or prefixed by <code>0x</code> for hexadecimal) and + <var>dst</var> as a field or subfield in the syntax described under + ``Field Specifications'' above. + </p> + + <p> + The following all set the Ethernet source address to 00:11:22:33:44:55: + </p> + + <ul> + <li><code>set_field:00:11:22:33:44:55->eth_src</code></li> + <li><code>load:0x001122334455->eth_src</code></li> + <li><code>load:0x001122334455->OXM_OF_ETH_SRC[]</code></li> + </ul> + + <p> + The following all set the multicast bit in the Ethernet destination + address: + </p> + + <ul> + <li><code>set_field:01:00:00:00:00:00/01:00:00:00:00:00->eth_dst</code></li> + <li><code>load:1->eth_dst[40]</code></li> + </ul> + + <p> + Open vSwitch prohibits a <code>set_field</code> or <code>load</code> + action whose <var>dst</var> is not guaranteed to be part of the packet; + for example, <code>set_field</code> of <code>nw_dst</code> is only + allowed in a flow that matches on Ethernet type 0x800. In some cases, + such as in an action set, Open vSwitch can't statically check that + <var>dst</var> is part of the packet, and in that case if it is not + then Open vSwitch treats the action as a no-op. + </p> + + <conformance> + Open vSwitch 1.1 introduced <code>NXAST_REG_LOAD</code> as a extension + to OpenFlow 1.0 and used <code>load</code> to express it. Later, + OpenFlow 1.2 introduced a standard <code>OFPAT_SET_FIELD</code> action + that was restricted to loading entire fields, so Open vSwitch added the + form <code>set_field</code> with this restriction. OpenFlow 1.5 + extended <code>OFPAT_SET_FIELD</code> to the point that it became a + superset of <code>NXAST_REG_LOAD</code>. Open vSwitch translates + either syntax as necessary for the OpenFlow version in use: in OpenFlow + 1.0 and 1.1, <code>NXAST_REG_LOAD</code>; in OpenFlow 1.2, 1.3, and + 1.4, <code>NXAST_REG_LOAD</code> for <code>load</code> or for loading a + subfield, <code>OFPAT_SET_FIELD</code> otherwise; and OpenFlow 1.5 and + later, <code>OFPAT_SET_FIELD</code>. + </conformance> + </action> + + <action name="REG_MOVE"> + <h2>The <code>move</code> action</h2> + <syntax><code>move:<var>src</var>-><var>dst</var></code></syntax> + + <p> + Copies the named bits from field or subfield <var>src</var> to field or + subfield <var>dst</var>. <var>src</var> and <var>dst</var> should + fields or subfields in the syntax described under ``Field + Specifications'' above. The two fields or subfields must have the same + width. + </p> + + <p> + Examples: + </p> + + <ul> + <li> + <code>move:reg0[0..5]->reg1[26..31]</code> copies the six bits + numbered 0 through 5 in register 0 into bits 26 through 31 of + register 1. + </li> + <li> + <code>move:reg0[0..15]->vlan_tci</code> copies the least + significant 16 bits of register 0 into the VLAN TCI field. + </li> + </ul> + + <conformance> + In OpenFlow 1.0 through 1.4, <code>move</code> ordinarily uses an Open + vSwitch extension to OpenFlow. In OpenFlow 1.5, <code>move</code> uses + the OpenFlow 1.5 standard <code>OFPAT_COPY_FIELD</code> action. The + ONF has also made <code>OFPAT_COPY_FIELD</code> available as an + extension to OpenFlow 1.3. Open vSwitch 2.4 and later understands this + extension and uses it if a controller uses it, but for backward + compatibility with older versions of Open vSwitch, + <code>ovs-ofctl</code> does not use it. + </conformance> + </action> + + <action name="SET_ETH_SRC, SET_ETH_DST"> + <h2>The <code>mod_dl_src</code> and <code>mod_dl_dst</code> actions</h2> + <syntax><code>mod_dl_src:</code><var>mac</var></syntax> + <syntax><code>mod_dl_dst:</code><var>mac</var></syntax> + + <p> + Sets the Ethernet source or destination address, respectively, to + <var>mac</var>, which should be expressed in the form + <code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code>. + </p> + + <p> + For L3-only packets, that is, those that lack an Ethernet header, this + action has no effect. + </p> + + <conformance> + OpenFlow 1.0 and 1.1 have specialized actions for these purposes. + OpenFlow 1.2 and later do not, so Open vSwitch translates them to + appropriate <code>OFPAT_SET_FIELD</code> actions for those versions, + </conformance> + </action> + + <action name="SET_IP_SRC, SET_IP_DST"> + <h2>The <code>mod_nw_src</code> and <code>mod_nw_dst</code> actions</h2> + <syntax><code>mod_nw_src:</code><var>ip</var></syntax> + <syntax><code>mod_nw_dst:</code><var>ip</var></syntax> + + <p> + Sets the IPv4 source or destination address, respectively, to + <var>ip</var>, which should be expressed in the form + <code><var>w</var>.<var>x</var>.<var>y</var>.<var>z</var></code>. + </p> + + <p> + In OpenFlow 1.1 and later, consistency rules allow these actions only + in a flow that matches only packets that contain an IPv4 header (or + following an action that adds an IPv4 header, + e.g. <code>pop_mpls:0x0800</code>). See ``Inconsistencies'', above, + for more information. + </p> + + <conformance> + OpenFlow 1.0 and 1.1 have specialized actions for these purposes. + OpenFlow 1.2 and later do not, so Open vSwitch translates them to + appropriate <code>OFPAT_SET_FIELD</code> actions for those versions, + </conformance> + </action> + + <action name="SET_IP_DSCP, SET_IP_ECN"> + <h2>The <code>mod_nw_tos</code> and <code>mod_nw_ecn</code> actions</h2> + <syntax><code>mod_nw_tos:</code><var>tos</var></syntax> + <syntax><code>mod_nw_ecn:</code><var>ecn</var></syntax> + + <p> + The <code>mod_nw_tos</code> action sets the DSCP bits in the IPv4 + ToS/DSCP or IPv6 traffic class field to <var>tos</var>, which must be a + multiple of 4 between 0 and 255. This action does not modify the two + least significant bits of the ToS field (the ECN bits). + </p> + + <p> + The <code>mod_nw_ecn</code> action sets the ECN bits in the IPv4 ToS or + IPv6 traffic class field to <code>ecn</code>, which must be a value + between 0 and 3, inclusive. This action does not modify the six most + significant bits of the field (the DSCP bits). + </p> + + <p> + In OpenFlow 1.1 and later, consistency rules allow these actions only + in a flow that matches only packets that contain an IPv4 or IPv6 header + (or following an action that adds such a header). See + ``Inconsistencies'', above, for more information. + </p> + + <conformance> + OpenFlow 1.0 has a <code>mod_nw_tos</code> action but not + <code>mod_nw_ecn</code>. Open vSwitch implements the latter in + OpenFlow 1.0 as an extension using <code>NXAST_REG_LOAD</code>. + OpenFlow 1.1 has specialized actions for these purposes. OpenFlow 1.2 + and later do not, so Open vSwitch translates them to appropriate + <code>OFPAT_SET_FIELD</code> actions for those versions, + </conformance> + </action> + + <action name="SET_L4_SRC_PORT, SET_L4_DST_PORT"> + <h2>The <code>mod_tp_src</code> and <code>mod_tp_dst</code> actions</h2> + <syntax><code>mod_tp_src:</code><var>port</var></syntax> + <syntax><code>mod_tp_dst:</code><var>port</var></syntax> + + <p> + Sets the TCP or UDP or SCTP source or destination port, respectively, + to <var>port</var>. Both IPv4 and IPv6 are supported. + </p> + + <p> + In OpenFlow 1.1 and later, consistency rules allow these actions only + in a flow that matches only packets that contain a TCP or UDP or SCTP + header. See ``Inconsistencies'', above, for more information. + </p> + + <conformance> + OpenFlow 1.0 and 1.1 have specialized actions for these purposes. + OpenFlow 1.2 and later do not, so Open vSwitch translates them to + appropriate <code>OFPAT_SET_FIELD</code> actions for those versions, + </conformance> + </action> + + <action name="DEC_TTL"> + <h2>The <code>dec_ttl</code> action</h2> + <syntax><code>dec_ttl</code></syntax> + <syntax><code>dec_ttl(<var>id1</var>, </code>[<code><var>id2</var></code>]...<code>)</code></syntax> + + <p> + Decrement TTL of IPv4 packet or hop limit of IPv6 packet. If the TTL + or hop limit is initially 0 or 1, no decrement occurs, as packets + reaching TTL zero must be rejected. Instead, Open vSwitch sends a + ``packet-in'' message with reason code <code>OFPR_INVALID_TTL</code> to + each connected controller that has enabled receiving such messages, and + stops processing the current set of actions. (However, if the current + set of actions was reached through <code>resubmit</code>, the remaining + actions in outer levels resume processing.) + </p> + + <p> + As an Open vSwitch extension to OpenFlow, this action supports the + ability to specify a list of controller IDs. Open vSwitch will only + send the message to controllers with the given ID or IDs. Specifying + no list is equivalent to specifying a single controller ID of zero. + </p> + + <p> + Sets the TCP or UDP or SCTP source or destination port, respectively, + to <var>port</var>. Both IPv4 and IPv6 are supported. + </p> + + <p> + In OpenFlow 1.1 and later, consistency rules allow these actions only + in a flow that matches only packets that contain an IPv4 or IPv6 + header. See ``Inconsistencies'', above, for more information. + </p> + + <conformance> + All versions of OpenFlow and Open vSwitch support this action. + </conformance> + </action> + + <action name="SET_MPLS_LABEL, SET_MPLS_TC, SET_MPLS_TTL"> + <h2>The <code>set_mpls_label</code>, <code>set_mpls_tc</code>, and <code>set_mpls_ttl</code> actions</h2> + <syntax><code>set_mpls_label:</code><var>label</var></syntax> + <syntax><code>set_mpls_tc:</code><var>tc</var></syntax> + <syntax><code>set_mpls_ttl:</code><var>ttl</var></syntax> + + <p> + The <code>set_mpls_label</code> action sets the label of the packet's + outer MPLS label stack entry. <var>label</var> should be a 20-bit + value that is decimal by default; use a <code>0x</code> prefix to + specify the value in hexadecimal. + </p> + + <p> + The <code>set_mpls_tc</code> action sets the traffic class of the + packet's outer MPLS label stack entry. <var>tc</var> should be in the + range 0 to 7, inclusive. + </p> + + <p> + The <code>set_mpls_ttl</code> action sets the TTL of the packet's outer + MPLS label stack entry. <var>ttl</var> should be in the range 0 to 255 + inclusive. + </p> + + <p> + In OpenFlow 1.1 and later, consistency rules allow these actions only + in a flow that matches only packets that contain an MPLS label (or + following an action that adds an MPLS label, + e.g. <code>push_mpls:0x8847</code>). See ``Inconsistencies'', above, + for more information. + </p> + + <conformance> + OpenFlow 1.0 does not support MPLS, but Open vSwitch implements these + actions as extensions. OpenFlow 1.1 has specialized actions for these + purposes. OpenFlow 1.2 and later do not, so Open vSwitch translates + them to appropriate <code>OFPAT_SET_FIELD</code> actions for those + versions, + </conformance> + </action> + + <action name="DEC_MPLS_TTL, DEC_NSH_TTL"> + <h2>The <code>dec_mpls_ttl</code> and <code>dec_nsh_ttl</code> actions</h2> + <syntax><code>dec_mpls_ttl</code></syntax> + <syntax><code>dec_nsh_ttl</code></syntax> + + <p> + These actions decrement the TTL of the packet's outer MPLS label stack + entry or its NSH header, respectively. If the TTL is initially 0 or 1, + no decrement occurs. Instead, Open vSwitch sends a ``packet-in'' + message with reason code <code>BOFPR_INVALID_TTL</code> to OpenFlow + controllers with ID 0, if it has enabled receiving them. Processing + the current set of actions then stops. (However, if the current set of + actions was reached through <code>resubmit</code>, remaining actions in + outer levels resume processing.) + </p> + + <p> + In OpenFlow 1.1 and later, consistency rules allow this actions only in + a flow that matches only packets that contain an MPLS label or an NSH + header, respectively. See ``Inconsistencies'', above, for more + information. + </p> + + <conformance> + <p> + Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and + later support <code>dec_mpls_ttl</code>. Open vSwitch implements + <code>dec_mpls_ttl</code> as an extension to OpenFlow 1.0. + </p> + + <p> + Open vSwitch 2.8 introduced support for NSH, although the NSH draft + changed after release so that only Open vSwitch 2.9 and later conform + to the final protocol specification. The <code>dec_nsh_ttl</code> + action and NSH support in general is an Open vSwitch extension not + supported by any version of OpenFlow. + </p> + </conformance> + </action> + </group> + + <group title="Metadata Actions"> + <action name="SET_TUNNEL"> + <h2>The <code>set_tunnel</code> action</h2> + <syntax><code>set_tunnel:</code><var>id</var></syntax> + <syntax><code>set_tunnel64:</code><var>id</var></syntax> + + <p> + Many kinds of tunnels support a tunnel ID, e.g. VXLAN and Geneve have a + 24-bit VNI, and GRE has an optional 32-bit key. This action sets the + value used for tunnel ID in such tunneled packets, although whether it + is used for a particular tunnel depends on the tunnel's configuration. + See the tunnel ID documentation in <code>ovs-fields</code>(7) for more + information. + </p> + + <conformance> + <p> + These actions are OpenFlow extensions. <code>set_tunnel</code> was + introduced in Open vSwitch 1.0. <code>set_tunnel64</code>, which is + needed if <var>id</var> is wider than 32 bits, was added in Open + vSwitch 1.1. Both actions always set the entire tunnel ID field. + </p> + + <p> + Open vSwitch supports these actions in all versions of OpenFlow, but + in OpenFlow 1.2 and later it translates them to an appropriate + standardized <code>OFPAT_SET_FIELD</code> action. + </p> + </conformance> + </action> + + <action name="SET_QUEUE, POP_QUEUE"> + <h2>The <code>set_queue</code> and <code>pop_queue</code> actions</h2> + <syntax><code>set_queue:</code><var>queue</var></syntax> + <syntax><code>pop_queue</code></syntax> + + <p> + The <code>set_queue</code> action sets the queue ID to be used for + subsequent output actions to <var>queue</var>, which must be a 32-bit + integer. The range of meaningful values of <var>queue</var>, and their + meanings, varies greatly from one OpenFlow implementation to another. + Even within a single implementation, there is no guarantee that all + OpenFlow ports have the same queues configured or that all OpenFlow + ports in an implementation can be configured the same way queue-wise. + For more information, see the documentation for the output queue field + in <code>ovs-fields</code>(7). + </p> + + <p> + The <code>pop_queue</code> restores the output queue to the default + that was set when the packet entered the switch (generally 0). + </p> + + <p> + Four billion queues ought to be enough for anyone: <url + href="https://mailman.stanford.edu/pipermail/openflow-spec/2009-August/000394.html"/> + </p> + + <conformance> + <p> + OpenFlow 1.1 introduced the <code>set_queue</code> action. Open + vSwitch also supports it as an extension in OpenFlow 1.0. + </p> + + <p> + The <code>pop_queue</code> action is an Open vSwitch extension. + </p> + </conformance> + </action> + </group> + + <group title="Firewalling Actions"> + <p> + Open vSwitch is often used to implement a firewall. The preferred way to + implement a firewall is ``connection tracking,'' that is, to keep track + of the connection state of individual TCP sessions. The <code>ct</code> + action described in this section, added in Open vSwitch 2.5, implements + connection tracking. For new deployments, it is the recommended way to + implement firewalling with Open vSwitch. + </p> + + <p> + Before <code>ct</code> was added, Open vSwitch did not have built-in + support for connection tracking. Instead, Open vSwitch supported the + <code>learn</code> action, which allows a received packet to add a flow + to an OpenFlow flow table. This could be used to implement a primitive + form of connection tracking: packets passing through the firewall in one + direction could create flows that allowed response packets back through + the firewall in the other direction. The additional + <code>fin_timeout</code> action allowed the learned flows to expire + quickly after TCP session termination. + </p> + + <action name="CT"> + <h2>The <code>ct</code> action</h2> + <syntax><code>ct(<var>argument</var></code>]...<code>)</code></syntax> + <syntax><code>ct(commit</code>[<code>, <var>argument</var></code>]...<code>)</code></syntax> + + <p> + The action has two modes of operation, distinguished by whether + <code>commit</code> is present. The following arguments may be present + in either mode: + </p> + + <dl> + <dt><code>zone=<var>value</var></code></dt> + <dd> + A zone is a 16-bit id that isolates connections into separate + domains, allowing overlapping network addresses in different zones. + If a zone is not provided, then the default is 0. The + <var>value</var> may be specified either as a 16-bit integer literal + or a field or subfield in the syntax described under ``Field + Specifications'' above. + </dd> + </dl> + + <p> + Without <code>commit</code>, this action sends the packet through the + connection tracker. The connection tracker keeps track of the state of + TCP connections for packets passed through it. For each packet through + a connection, it checks that it satisfies TCP invariants and signals + the connection state to later actions using the <code>ct_state</code> + metadata field, which is documented in <code>ovs-fields</code>(7). + </p> + + <p> + In this form, <code>ct</code> forks the OpenFlow pipeline: + </p> + + <ul> + <li> + In one fork, <code>ct</code> passes the packet to the connection + tracker. Afterward, it reinjects the packet into the OpenFlow + pipeline with the connection tracking fields initialized. The + <code>ct_state</code> field is initialized with connection state and + <code>ct_zone</code> to the connection tracking zone specified on the + <code>zone</code> argument. If the connection is one that is already + tracked, <code>ct_mark</code> and <code>ct_label</code> to its + existing mark and label, respectively; otherwise they are zeroed. In + addition, <code>ct_nw_proto</code>, <code>ct_nw_src</code>, + <code>ct_nw_dst</code>, <code>ct_ipv6_src</code>, + <code>ct_ipv6_dst</code>, <code>ct_tp_src</code>, and + <code>ct_tp_dst</code> are initialized appropriately for the original + direction connection. See the <code>resubmit</code> action for a way + to search the flow table with the connection tracking original + direction fields swapped with the packet 5-tuple fields. See + <code>ovs-fields</code>(7) for details on the connection tracking + fields. + </li> + + <li> + In the other fork, the original instance of the packet continues + independent processing following the <code>ct</code> action. The + <code>ct_state</code> field and other connection tracking metadata + are cleared. + </li> + </ul> + + <p> + Without <code>commit</code>, the <code>ct</code> action accepts the + following arguments: + </p> + + <dl> + <dt><code>table=<var>table</var></code></dt> + <dd> + Sets the OpenFlow table where the packet is reinjected. The + <var>table</var> must be a number between 0 and 254 inclusive, or a + table's name. If <var>table</var> is not specified, then the packet + is not reinjected. + </dd> + + <dt><code>nat</code></dt> + <dt><code>nat(<var>type</var>=<var>addrs</var></code>[<code>:<var>ports</var></code>][<code>,<var>flag</var></code>]...<code>)</code></dt> + <dd> + <p> + Specify address and port translation for the connection being + tracked. The <var>type</var> must be <code>src</code>, for source + address/port translation (SNAT), or <code>dst</code>, for destination + address/port translation (DNAT). Setting up address translation for + a new connection takes effect only if the connection is later + committed with <code>ct(commit</code>...<code>)</code>. + </p> + + <p> + The <code>src</code> and <code>dst</code> options take the following + arguments: + </p> + + <dl> + <dt><var>addrs</var></dt> + <dd> + The IP address <var>addr</var> or range + <code><var>addr1</var>-<var>addr2</var></code> from which the + translated address should be selected. If only one address is + given, then that address will always be selected, otherwise the + address selection can be informed by the optional persistent flag + as described below. Either IPv4 or IPv6 addresses can be provided, + but both addresses must be of the same type, and the datapath + behavior is undefined in case of providing IPv4 address range for + an IPv6 packet, or IPv6 address range for an IPv4 packet. IPv6 + addresses must be bracketed with <code>[</code> and <code>]</code> + if a port range is also given. + </dd> + + <dt><var>ports</var></dt> + <dd> + The L4 <var>port</var> or range + <code><var>port1</var>-<var>port2</var></code> from which the + translated port should be selected. In case of a mapping conflict + the datapath may choose any other non-conflicting port number + instead, even when no port range is specified. The port number + selection can be informed by the optional <code>random</code> and + <code>hash</code> flags described below. + </dd> + </dl> + + <p> + The optional flags are: + </p> + + <dl> + <dt><code>random</code></dt> + <dd> + The selection of the port from the given range should be done using + a fresh random number. This flag is mutually exclusive with + <code>hash</code>. + </dd> + + <dt><code>hash</code></dt> + <dd> + The selection of the port from the given range should be done using + a datapath specific hash of the packet's IP addresses and the + other, non-mapped port number. This flag is mutually exclusive + with <code>random</code>. + </dd> + + <dt><code>persistent</code></dt> + <dd> + The selection of the IP address from the given range should be done + so that the same mapping can be provided after the system restarts. + </dd> + </dl> + + <p> + If <code>alg</code> is specified for the committing <code>ct</code> + action that also includes <code>nat</code> with a <code>src</code> or + <code>dst</code> attribute, then the datapath tries to set up the + helper to be NAT-aware. This functionality is datapath specific and + may not be supported by all datapaths. + </p> + + <p> + A ``bare'' <code>nat</code> argument with no options will only + translate the packet being processed in the way the connection has been + set up with an earlier, committed <code>ct</code> action. A + <code>nat</code> action with <code>src</code> or <code>dst</code>, when + applied to a packet belonging to an established (rather than new) + connection, will behave the same as a bare <code>nat</code>. + </p> + + <p> + Open vSwitch 2.6 introduced <code>nat</code>. Linux 4.6 was the + earliest upstream kernel that implemented <code>ct</code> support for + <code>nat</code>. + </p> + </dd> + </dl> + + <p> + With <code>commit</code>, the connection tracker commits the connection + to the connection tracking module. The <code>commit</code> flag should + only be used from the pipeline within the first fork of <code>ct</code> + without <code>commit</code>. Information about the connection is + stored beyond the lifetime of the packet in the pipeline. Some + <code>ct_state</code> flags are only available for committed + connections. + </p> + + <p> + The following options are available only with <code>commit</code>: + </p> + + <dl> + <dt><code>force</code></dt> + <dd> + A committed connection always has the directionality of the packet + that caused the connection to be committed in the first place. This + is the ``original direction'' of the connection, and the opposite + direction is the ``reply direction''. If a connection is already + committed, but it is in the wrong direction, <code>force</code> + effectively terminates the existing connection and starts a new one + in the current direction. This flag has no effect if the original + direction of the connection is already the same as that of the + current packet. + </dd> + + <dt><code>exec(<var>action</var></code>...<code>)</code></dt> + <dd> + <p> + Perform each <var>action</var> within the context of connection + tracking. Only actions which modify the <code>ct_mark</code> or + <code>ct_label</code> fields are accepted within <code>exec</code> + action, and these fields may only be modified with this option. For + example: + </p> + + <dl> + <dt><code>set_field:<var>value</var>[/<var>mask</var>]->ct_mark</code></dt> + <dd> + Store a 32-bit metadata value with the connection. Subsequent + lookups for packets in this connection will populate + <code>ct_mark</code> when the packet is sent to the connection + tracker with the table specified. + </dd> + + <dt><code>set_field:<var>value</var>[/<var>mask</var>]->ct_label</code></dt> + <dd> + Store a 128-bit metadata value with the connection. Subsequent + lookups for packets in this connection will populate + <code>ct_label</code> when the packet is sent to the connection + tracker with the table specified. + </dd> + </dl> + </dd> + + <dt><code>alg=<var>alg</var></code></dt> + <dd> + <p> + Specify application layer gateway <var>alg</var> to track specific + connection types. If subsequent related connections are sent + through the <code>ct</code> action, then the <code>rel</code> flag + in the <code>ct_state</code> field will be set. Supported types + include: + </p> + + <dl> + <dt><code>ftp</code></dt> + <dd> + Look for negotiation of FTP data connections. Specify this + option for FTP control connections to detect related data + connections and populate the <code>rel</code> flag for the data + connections. + </dd> + + <dt><code>tftp</code></dt> + <dd> + <p> + Look for negotiation of TFTP data connections. Specify this + option for TFTP control connections to detect related data + connections and populate the <code>rel</code> flag for the data + connections. + </p> + </dd> + </dl> + + <p> + Related connections inherit <code>ct_mark</code> from that stored + with the original connection (i.e. the connection created by + <code>ct(alg=</code>...<code>)</code>). + </p> + </dd> + </dl> + + <p> + With the Linux datapath, global sysctl options affect <code>ct</code> + behavior. In particular, if + <code>net.netfilter.nf_conntrack_helper</code> is enabled, which it is + by default until Linux 4.7, then application layer gateway helpers may + be executed even if <code>alg</code> is not specified. For security + reasons, the netfilter team recommends users disable this option. For + further details, please see <url + href="http://www.netfilter.org/news.html#2012-04-03"/>. + </p> + + <p> + The <code>ct</code> action may be used as a primitive to construct + stateful firewalls by selectively committing some traffic, then + matching <code>ct_state</code> to allow established connections while + denying new connections. The following flows provide an example of how + to implement a simple firewall that allows new connections from port 1 + to port 2, and only allows established connections to send traffic from + port 2 to port 1: + </p> + + <pre> +table=0,priority=1,action=drop +table=0,priority=10,arp,action=normal +table=0,priority=100,ip,ct_state=-trk,action=ct(table=1) +table=1,in_port=1,ip,ct_state=+trk+new,action=ct(commit),2 +table=1,in_port=1,ip,ct_state=+trk+est,action=2 +table=1,in_port=2,ip,ct_state=+trk+new,action=drop +table=1,in_port=2,ip,ct_state=+trk+est,action=1 + </pre> + + <p> + If <code>ct</code> is executed on IPv4 (or IPv6) fragments, then the + message is implicitly reassembled before sending to the connection + tracker and refragmented upon output, to the original maximum received + fragment size. Reassembly occurs within the context of the zone, + meaning that IP fragments in different zones are not assembled + together. Pipeline processing for the initial fragments is halted. + When the final fragment is received, the message is assembled and + pipeline processing continues for that flow. Packet ordering is not + guaranteed by IP protocols, so it is not possible to determine which IP + fragment will cause message reassembly (and therefore continue pipeline + processing). As such, it is strongly recommended that multiple flows + should not execute <code>ct</code> to reassemble fragments from the + same IP message. + </p> + + <conformance> + The <code>ct</code> action was introduced in Open vSwitch 2.5. Some of + its features were introduced later, noted individually above. + </conformance> + </action> + + <action name="CT_CLEAR"> + <h2>The <code>ct_clear</code> action</h2> + <syntax><code>ct_clear</code></syntax> + + <p> + Clears connection tracking state from the flow, zeroing + <code>ct_state</code>, <code>ct_zone</code>, <code>ct_mark</code>, and + <code>ct_label</code>. + </p> + + <p> + This action was introduced in Open vSwitch 2.6.90. + </p> + </action> + + <action name="LEARN"> + <h2>The <code>learn</code> action</h2> + <syntax><code>learn(<var>argument</var></code>...<code>)</code></syntax> + + <p> + The <code>learn</code> action adds or modifies a flow in an OpenFlow + table, similar to <code>ovs-ofctl --strict mod-flows</code>. The + arguments specify the match fields, actions, and other properties of + the flow to be added or modified. + </p> + + <p> + Match fields for the new flow are specified as follows. At least one + match field should ordinarily be specified: + </p> + + <dl> + <dt><code><var>field</var>=<var>value</var></code></dt> + <dd> + <p> + Specifies that <var>field</var>, in the new flow, must match the + literal <var>value</var>, e.g. <code>dl_type=0x800</code>. + Shorthand match syntax, such as <code>ip</code> in place of + <code>dl_type=0x800</code>, is not supported. + </p> + </dd> + + <dt><code><var>field</var>=<var>src</var></code></dt> + <dd> + <p> + Specifies that <var>field</var> in the new flow must match + <var>src</var> taken from the packet currently being processed. + For example, <code>udp_dst=udp_src</code>, applied to a UDP packet + with source port 53, creates a flow which matches + <code>udp_dst=53</code>. <var>field</var> and <var>src</var> must + have the same width. + </p> + </dd> + + <dt><code><var>field</var></code></dt> + <dd> + Shorthand for the previous form when <var>field</var> and + <var>src</var> are the same. For example, <code>udp_dst</code>, + applied to a UDP packet with destination port 53, creates a flow + which matches <code>udp_dst=53</code>. + </dd> + </dl> + + <p> + The <var>field</var> and <var>src</var> arguments above should be + fields or subfields in the syntax described under ``Field + Specifications'' above. + </p> + + <p> + Match field specifications must honor prerequisites for both the flow + with the <code>learn</code> and the new flow that it creates. Consider + the following complete flow, in the syntax accepted by + <code>ovs-ofctl</code>. If the flow's match on <code>udp</code> were + omitted, then the flow would not satisfy the prerequisites for the + <code>learn</code> action's use of <code>udp_src</code>. If + <code>dl_type=0x800</code> or <code>nw_proto</code> were omitted from + <code>learn</code>, then the new flow would not satisfy the + prerequisite for its match on <code>udp_dst</code>. For more + information on prerequisites, please refer to + <code>ovs-fields</code>(7): + </p> + + <pre> + udp, actions=learn(dl_type=0x800, nw_proto=17, udp_dst=udp_src) + </pre> + + <p> + Actions for the new flow are specified as follows. At least one action + should ordinarily be specified: + </p> + + <dl> + <dt><code>load:<var>value</var>-><var>dst</var></code></dt> + <dd> + Adds a <code>load</code> action to the new flow that loads the + literal <var>value</var> into <var>dst</var>. The syntax is the same + as the <code>load</code> action explained in the ``Header + Modification'' section. + </dd> + + <dt><code>load:<var>src</var>-><var>dst</var></code></dt> + <dd> + Adds a <code>load</code> action to the new flow that loads + <var>src</var>, a field or subfield from the packet being processed, + into <var>dst</var>. + </dd> + + <dt><code>output:<var>field</var></code></dt> + <dd> + Adds an <code>output</code> action to the new flow's actions that + outputs to the OpenFlow port taken from <var>field</var>, which must + be a field as described above. + </dd> + + <dt><code>fin_idle_timeout=<var>seconds</var></code></dt> + <dt><code>fin_hard_timeout=<var>seconds</var></code></dt> + <dd> + Adds a <code>fin_timeout</code> action with the specified arguments + to the new flow. This feature was added in Open vSwitch 1.5.90. + </dd> + </dl> + + The following additional arguments are optional: + + <dl> + <dt><code>idle_timeout=<var>seconds</var></code></dt> + <dt><code>hard_timeout=<var>seconds</var></code></dt> + <dt><code>priority=<var>value</var></code></dt> + <dt><code>cookie=<var>value</var></code></dt> + <dt><code>send_flow_rem</code></dt> + <dd> + These arguments have the same meaning as in the usual flow syntax + documented in <code>ovs-ofctl</code>(8). + </dd> + + <dt><code>table=<var>table</var></code></dt> + <dd> + The table in which the new flow should be inserted. Specify a + decimal number between 0 and 254 inclusive or the name of a table. + The default, if table is unspecified, is table 1 (not 0). + </dd> + + <dt><code>delete_learned</code></dt> + <dd> + <p> + When this flag is specified, deleting the flow that contains the + <code>learn</code> action will also delete the flows created by + <code>learn</code>. Specifically, when the last <code>learn</code> + action with this flag and particular <code>table</code> and + <code>cookie</code> values is removed, the switch deletes all of + the flows in the specified table with the specified cookie. + </p> + + <p> + This flag was added in Open vSwitch 2.4. + </p> + </dd> + + <dt><code>limit=<var>number</var></code></dt> + <dd> + <p> + If the number of flows in the new flow's table with the same cookie + exceeds <code>number</code>, the action will not add a new flow. + By default, or with <code>limit=0</code>, there is no limit. + </p> + + <p> + This flag was added in Open vSwitch 2.8. + </p> + </dd> + + <dt><code>result_dst=<var>field</var>[<var>bit</var>]</code></dt> + <dd> + <p> + If learn fails (because the number of flows exceeds + <code>limit</code>), the action sets + <code><var>field</var>[<var>bit</var>]</code> to 0, otherwise it + will be set to 1. <code>field[bit]</code> must be a single bit. + </p> + + <p> + This flag was added in Open vSwitch 2.8. + </p> + </dd> + </dl> + + <p> + By itself, the <code>learn</code> action can only put two kinds of + actions into the flows that it creates: <code>load</code> and + <code>output</code> actions. If <code>learn</code> is used in + isolation, these are severe limits. + </p> + + <p> + However, <code>learn</code> is not meant to be used in isolation. It + is a primitive meant to be used together with other Open vSwitch + features to accomplish a task. Its existing features are enough to + accomplish most tasks. + </p> + + <p> + Here is an outline of a typical pipeline structure that allows for + versatile behavior using <code>learn</code>: + </p> + + <ul> + <li> + Flows in table <var>A</var> contain a <code>learn</code> action, that + populates flows in table <var>L</var>, that use a <code>load</code> + action to populate register <var>R</var> with information about what + was learned. + </li> + + <li> + Flows in table <var>B</var> contain two sequential resubmit actions: + one to table <var>L</var> and another one to table <var>B</var>+1. + </li> + + <li> + Flows in table <var>B</var>+1 match on register <var>R</var> and act + differently depending on what the flows in table <var>L</var> loaded + into it. + </li> + </ul> + + <p> + This approach can be used to implement many <code>learn</code>-based + features. For example: + </p> + + <ul> + <li> + Resubmit to a table selected based on learned information, e.g. see + <url href="https://mail.openvswitch.org/pipermail/ovs-discuss/2016-June/021694.html"/>. + </li> + + <li> + MAC learning in the middle of a pipeline, as described in the ``Open + vSwitch Advanced Features Tutorial'' in the OVS documentation. + </li> + + <li> + TCP state based firewalling, by learning outgoing connections based + on SYN packets and matching them up with incoming packets. (This is + usually better implemented using the <code>ct</code> action.) + </li> + + <li> + At least some of the features described in T. A. Hoff, ``Extending + Open vSwitch to Facilitate Creation of Stateful SDN Applications''. + </li> + </ul> + + <conformance> + The <code>learn</code> action is an Open vSwitch extension to OpenFlow + added in Open vSwitch 1.3. Some features of <code>learn</code> were + added in later versions, as noted individually above. + </conformance> + </action> + + <action name="FIN_TIMEOUT"> + <h2>The <code>fin_timeout</code> action</h2> + <syntax><code>fin_timeout(<var>key</var>=<var>value</var></code>...<code>)</code></syntax> + + <p> + This action changes the idle timeout or hard timeout, or both, of the + OpenFlow flow that contains it, when the flow matches a TCP packet with + the FIN or RST flag. When such a packet is observed, the action + reduces the rule's timeouts to those specified on the action. If the + rule's existing timeout is already shorter than the one that the action + specifies, then that timeout is unaffected. + </p> + + <p> + The timeouts are specified as key-value pairs: + </p> + + <dl> + <dt><code>idle_timeout=</code><var>seconds</var></dt> + <dd> + Causes the flow to expire after the given number of seconds of + inactivity. + </dd> + + <dt><code>hard_timeout=</code><var>seconds</var></dt> + <dd> + Causes the flow to expire after the given number of + <var>seconds</var>, regardless of activity. (<var>seconds</var> + specifies time since the flow's creation, not since the receipt of + the FIN or RST.) + </dd> + </dl> + + <p> + This action is normally added to a learned flow by the + <code>learn</code> action. It is unlikely to be useful otherwise. + </p> + + <conformance> + This Open vSwitch extension action was added in Open vSwitch 1.5.90. + </conformance> + </action> + </group> + + <group title="Programming and Control Flow Actions"> + <action name="RESUBMIT"> + <h2>The <code>resubmit</code> action</h2> + <syntax><code>resubmit:<var>port</var></code></syntax> + <syntax><code>resubmit(</code>[<code><var>port</var></code>]<code>,</code>[<code><var>table</var></code>][<code>,ct</code>]<code>)</code></syntax> + + <p> + Searches an OpenFlow flow table for a matching flow and executes the + actions found, if any, before continuing to the following action in the + current flow entry. Arguments can customize the search: + </p> + + <ul> + <li> + If <var>port</var> is given as an OpenFlow port number or name, then + it specifies a value to use for the input port metadata field as part + of the search, in place of the input port currently in the flow. + Specifying <code>in_port</code> as <var>port</var> is equivalent to + omitting it. + </li> + + <li> + If <var>table</var> is given as an integer between 0 and 254 or a + table name, it specifies the OpenFlow table to search. If it is not + specified, the table from the current flow is used. + </li> + + <li> + <p> + If <code>ct</code> is specified, then the search is done with + packet 5-tuple fields swapped with the corresponding conntrack + original direction tuple fields. See the documentation for + <code>ct</code> above, for more information about connection + tracking, or <code>ovs-fields</code>(7) for details about the + connection tracking fields. + </p> + + <p> + This flag requires a valid connection tracking state as a match + prerequisite in the flow where this action is placed. Examples of + valid connection tracking state matches include + <code>ct_state=+new</code>, <code>ct_state=+est</code>, + <code>ct_state=+rel</code>, and <code>ct_state=+trk-inv</code>. + </p> + </li> + </ul> + + <p> + The changes, if any, to the input port and connection tracking fields + are just for searching the flow table. The changes are not visible to + actions or to later flow table lookups. + </p> + + <p> + The most common use of <code>resubmit</code> is to visit another flow + table without <var>port</var> or <code>ct</code>, like this: + <code>resubmit(,<var>table</var>)</code>. + </p> + + <p> + Recursive <code>resubmit</code> actions are permitted. + </p> + + <conformance> + <p> + The <code>resubmit</code> action is an Open vSwitch extension. + However, the <code>goto_table</code> instruction in OpenFlow 1.1 and + later can be viewed as a kind of restricted <code>resubmit</code>. + </p> + + <p> + Open vSwitch 1.2.90 added <var>table</var>. Open vSwitch 2.7 added + <code>ct</code>. + </p> + + <p> + Open vSwitch imposes a limit on <code>resubmit</code> recursion that + varies among version: + </p> + + <ul> + <li> + Open vSwitch 1.0.1 and earlier did not support recursion. + </li> + + <li> + Open vSwitch 1.0.2 and 1.0.3 limited recursion to 8 levels. + </li> + + <li> + Open vSwitch 1.1 and 1.2 limited recursion to 16 levels. + </li> + + <li> + Open vSwitch 1.2 through 1.8 limited recursion to 32 levels. + </li> + + <li> + Open vSwitch 1.9 through 2.0 limited recursion to 64 levels. + </li> + + <li> + Open vSwitch 2.1 through 2.5 limited recursion to 64 levels and + impose a total limit of 4,096 resubmits per flow translation + (earlier versions did not impose any total limit). + </li> + + <li> + Open vSwitch 2.6 and later imposes the same limits as 2.5, with one + exception: resubmit from table <var>x</var> to any table + <var>y</var> > <var>x</var> does not count against the recursion + depth limit. + </li> + </ul> + </conformance> + </action> + + <action name="CLONE"> + <h2>The <code>clone</code> action</h2> + <syntax><code>clone(<var>action</var>...)</code></syntax> + + <p> + Executes each nested <var>action</var>, saving much of the packet and + pipeline state beforehand and then restoring it afterward. The state + that is saved and restored includes all flow data and metadata + (including, for example, <code>in_port</code> and + <code>ct_state</code>), the stack accessed by <code>push</code> and + <code>pop</code> actions, and the OpenFlow action set. + </p> + + <p> + This action was added in Open vSwitch 2.6.90. + </p> + </action> + + <action name="STACK_PUSH, STACK_POP"> + <h2>The <code>push</code> and <code>pop</code> actions</h2> + <syntax><code>push:<var>src</var></code></syntax> + <syntax><code>pop:<var>dst</var></code></syntax> + <p> + The <code>push</code> action pushes <var>src</var> on a general-purpose + stack. The <code>pop</code> action pops an entry off the stack into + <var>dst</var>. <var>src</var> and <var>dst</var> should be fields or + subfields in the syntax described under ``Field Specifications'' above. + </p> + + <p> + Controllers can use the stack for saving and restoring data or metadata + around <code>resubmit</code> actions, for swapping or rearranging data + and metadata, or for other purposes. Any data or metadata field, or + part of one, may be pushed, and any modifiable field or subfield may be + popped. + </p> + + <p> + The number of bits pushed in a stack entry do not have to match the + number of bits later popped from that entry. If more bits are popped + from an entry than were pushed, then the entry is conceptually + left-padded with 0-bits as needed. If fewer bits are popped than + pushed, then bits are conceptually trimmed from the left side of the + entry. + </p> + + <p> + The stack's size is limited. The limit is intended to be high enough + that ``normal'' use will not pose problems. Stack overflow or + underflow is an error that stops action execution (see ``Stack too + deep'' under ``Error Handling'', above). + </p> + + <p> + Examples: + </p> + + <ul> + <li> + <code>push:reg2[0..5]</code> or <code>push:NXM_NX_REG2[0..5]</code> + pushes on the stack the 6 bits in register 2 bits 0 through 5. + </li> + + <li> + <code>pop:reg2[0..5]</code> or <code>pop:NXM_NX_REG2[0..5]</code> + pops the value from top of the stack and copy bits 0 through 5 of + that value into bits 0 through 5 of register 2. + </li> + </ul> + + <conformance> + Open vSwitch 1.2 introduced <code>push</code> and <code>pop</code> as + OpenFlow extension actions. + </conformance> + </action> + + <action name="EXIT"> + <h2>The <code>exit</code> action</h2> + <syntax><code>exit</code></syntax> + + <p> + This action causes Open vSwitch to immediately halt execution of + further actions. Actions which have already been executed are + unaffected. Any further actions, including those which may be in other + tables, or different levels of the <code>resubmit</code> call stack, + are ignored. However, an <code>exit</code> action within a group + bucket terminates only execution of that bucket, not other buckets or + the overall pipeline. Actions in the action set are still executed + (specify <code>clear_actions</code> before <code>exit</code> to discard + them). + </p> + </action> + + <action name="MULTIPATH"> + <h2>The <code>multipath</code> action</h2> + <syntax><code>multipath(<var>fields</var>, <var>basis</var>, <var>algorithm</var>, <var>n_links</var>, <var>arg</var>, <var>dst</var>)</code></syntax> + + <p> + Hashes <var>fields</var> using <var>basis</var> as a universal hash + parameter, then the applies multipath link selection + <var>algorithm</var> (with parameter <var>arg</var>) to choose one of + <var>n_links</var> output links numbered 0 through <var>n_links</var> + minus 1, and stores the link into <var>dst</var>, which must be a field + or subfield in the syntax described under ``Field Specifications'' + above. + </p> + + <p> + The <code>bundle</code> or <code>bundle_load</code> actions are usually + easier to use than <code>multipath</code>. + </p> + + <p> + <var>fields</var> must be one of the following: + </p> + + <dl> + <dt><code>eth_src</code></dt> + <dd> + Hashes Ethernet source address only. + </dd> + + <dt><code>symmetric_l4</code></dt> + <dd> + Hashes Ethernet source, destination, and type, VLAN ID, IPv4/IPv6 + source, destination, and proto‐ col, and TCP or SCTP (but not UDP) + ports. The hash is computed so that pairs of corresponding flows in + each direction hash to the same value, in environments where L2 paths + are the same in each direction. UDP ports are not included in the + hash to support protocols such as VXLAN that use asym‐ metric ports + in each direction. + </dd> + + <dt><code>symmetric_l3l4</code></dt> + <dd> + Hashes IPv4/IPv6 source, destination, and protocol, and TCP or SCTP + (but not UDP) ports. Like <code>symmetric_l4</code>, this is a + symmetric hash, but by excluding L2 headers it is more effective in + environments with asymmetric L2 paths (e.g. paths involving VRRP IP + addresses on a router). Not an effective hash function for protocols + other than IPv4 and IPv6, which hash to a constant zero. + </dd> + + <dt><code>symmetric_l3l4+udp</code></dt> + <dd> + Like <code>symmetric_l3l4+udp</code>, but UDP ports are included in + the hash. This is a more effective hash when asymmetric UDP + protocols such as VXLAN are not a consideration. + </dd> + + <dt><code>symmetric_l3</code></dt> + <dd> + Hashes network source address and network destination address. + </dd> + + <dt><code>nw_src</code></dt> + <dd> + Hashes network source address only. + </dd> + + <dt><code>nw_dst</code></dt> + <dd> + Hashes network destination address only. + </dd> + </dl> + + <p> + The <var>algorithm</var> used to compute the final result + <var>link</var> must be one of the following: + </p> + + <dl> + <dt><code>modulo_n</code></dt> + <dd> + <p> + Computes <var>link</var> = hash(<var>flow</var>) % <var>n_links</var>. + </p> + + <p> + This algorithm redistributes all traffic when <var>n_links</var> + changes. It has <i>O(1)</i> performance. + </p> + + <p> + Use 65535 for <var>max_link</var> to get a raw hash value. + </p> + + <p> + This algorithm is specified by RFC 2992. + </p> + </dd> + + <dt><code>hash_threshold</code></dt> + <dd> + <p> + Computes <var>link</var> = hash(<var>flow</var>) / (<code>MAX_HASH</code> / <var>n_links</var>). + </p> + + <p> + Redistributes between one-quarter and one-half of traffic when + n_links changes. It has <i>O(1)</i> performance. + </p> + + <p> + This algorithm is specified by RFC 2992. + </p> + </dd> + + <dt><code>hrw</code> (Highest Random Weight)</dt> + <dd> + <p> + Computes the following: + </p> + + <pre> +for <var>i</var> in [0,<var>n_links</var>]: + <var>weights</var>[<var>i</var>] = hash(<var>flow</var>, <var>i</var>) +<var>link</var> = { <var>i</var> such that <var>weights</var>[<var>i</var>] >= <var>weights</var>[<var>j</var>] for all <var>j</var> != <var>i</var> } + </pre> + + <p> + Redistributes 1/<var>n_links</var> of traffic when + <var>n_links</var> changes. It has <i>O(<var>n_links</var>)</i> + performance. If <var>n_links</var> is greater than a threshold + (currently 64, but subject to change), Open vSwitch will substitute + another algorithm automatically. + </p> + + <p> + This algorithm is specified by RFC 2992. + </p> + </dd> + + <dt><code>iter_hash</code> (Iterative Hash)</dt> + <dd> + <p> + Computes the following: + </p> + + <pre> +<var>i</var> = 0 +repeat: + <var>i</var> = <var>i</var> + 1 + <var>link</var> = hash(<var>flow</var>, <var>i</var>) % <var>arg</var> +while <var>link</var> > <var>max_link</var> + </pre> + + <p> + Redistributes 1/<var>n_links</var> of traffic when + <var>n_links</var> changes. O(1) performance when + <var>arg</var>/<var>max_link</var> is bounded by a constant. + </p> + + <p> + Redistributes all traffic when <var>arg</var> changes. + </p> + + <p> + <var>arg</var> must be greater than <var>max_link</var> and for + best performance should be no more than approximately + <var>max_link</var> * 2. If <var>arg</var> is outside the + acceptable range, Open vSwitch will automatically substitute the + least power of 2 greater than <var>max_link</var>. + </p> + + <p> + This algorithm is specific to Open vSwitch. + </p> + </dd> + </dl> + + <p> + Only the <code>iter_hash</code> algorithm uses <var>arg</var>. + </p> + + <p> + It is an error if <var>max_link</var> is greater than or equal to + 2**<var>n_bits</var>. + </p> + + <conformance> + This is an OpenFlow extension added in Open vSwitch 1.1. + </conformance> + </action> + </group> + + <group title="Other Actions"> + <action name="CONJUNCTION"> + <h2>The <code>conjunction</code> action</h2> + <syntax><code>conjunction(<var>id</var>, <var>k</var>/<var>n</var>)</code></syntax> + + <p> + This action allows for sophisticated ``conjunctive match'' flows. + Refer to ``Conjunctive Match Fields'' in <code>ovs-fields</code>(7) for + details. + </p> + + <p> + A flow that has one or more <code>conjunction</code> actions may not + have any other actions except for <code>note</code> actions. + </p> + + <conformance> + Open vSwitch 2.4 introduced the <code>conjunction</code> action and + <code>conj_id</code> field. They are Open vSwitch extensions to + OpenFlow. + </conformance> + </action> + + <action name="NOTE"> + <h2>The <code>note</code> action</h2> + <syntax><code>note:</code>[<var>hh</var>]...</syntax> + + <p> + This action does nothing at all. OpenFlow controllers may use it to + annotate flows with more data than can fit in a flow cookie. + </p> + + <p> + The action may include any number of bytes represented as hex digits + <var>hh</var>. Periods may separate pairs of hex digits, for + readability. The <code>note</code> action's format doesn't include an + exact length for its payload, so the provided bytes will be padded on + the right by enough bytes with value 0 to make the total number 6 more + than a multiple of 8. + </p> + + <p> + + </p> + + <conformance> + This action is an extension to OpenFlow introduced in Open vSwitch 1.1. + </conformance> + </action> + + <action name="SAMPLE"> + <h2>The <code>sample</code> action</h2> + <syntax><code>sample(<var>argument</var>...)</code></syntax> + + <p> + Samples packets and sends one sample for every sampled packet. + </p> + + <p> + The following <var>argument</var> forms are accepted: + </p> + + <dl> + <dt><code>probability=<var>packets</var></code></dt> + <dd> + The number of sampled packets out of 65535. Must be greater or equal + to 1. + </dd> + + <dt><code>collector_set_id=<var>id</var></code></dt> + <dd> + The unsigned 32-bit integer identifier of the set of sample + collectors to send sampled packets to. Defaults to 0. + </dd> + + <dt><code>obs_domain_id=<var>id</var></code></dt> + <dd> + When sending samples to IPFIX collectors, the unsigned 32-bit integer + Observation Domain ID sent in every IPFIX flow record. Defaults to + 0. + </dd> + + <dt><code>obs_point_id=<var>id</var></code></dt> + <dd> + When sending samples to IPFIX collectors, the unsigned 32-bit integer + Observation Point ID sent in every IPFIX flow record. Defaults to 0. + </dd> + + <dt><code>sampling_port=<var>port</var></code></dt> + <dd> + Sample packets on <var>port</var>, which should be the ingress or + egress port. This option, which was added in Open vSwitch 2.5.90, + allows the IPFIX implementation to export egress tunnel information. + </dd> + + <dt><code>ingress</code></dt> + <dt><code>egress</code></dt> + <dd> + Specifies explicitly that the packet is being sampled on ingress to + or egress from the switch. IPFIX reports sent by Open vSwitch before + version 2.5.90 did not include a direction. From 2.5.90 until + 2.6.90, IPFIX reports inferred a direction from + <var>sampling_port</var>: if it was the packet's output port, then + the direction was reported as egress, otherwise as ingress. Open + vSwitch 2.6.90 introduced these options, which allow the inferred + direction to be overridden. This is particularly useful when the + ingress (or egress) port is not a tunnel. + </dd> + </dl> + + <p> + Refer to <code>ovs-vswitchd.conf.db</code>(5) for more details on + configuring sample collector sets. + </p> + + <conformance> + This action is an OpenFlow extension added in Open vSwitch 2.4. + </conformance> + </action> + </group> + + <group title="Instructions"> + <p> + Every version of OpenFlow includes actions. OpenFlow 1.1 introduced the + higher-level, related concept of <dfn>instructions</dfn>. In OpenFlow + 1.1 and later, actions within a flow are always encapsulated within an + instruction. Each flow has at most one instruction of each kind, which + are executed in the following fixed order defined in the OpenFlow + specification: + </p> + + <ol> + <li><code>Meter</code></li> + <li><code>Apply-Actions</code></li> + <li><code>Clear-Actions</code></li> + <li><code>Write-Actions</code></li> + <li><code>Write-Metadata</code></li> + <li><code>Stat-Trigger</code> (not supported by Open vSwitch)</li> + <li><code>Goto-Table</code></li> + </ol> + + <p> + The most important instruction is <code>Apply-Actions</code>. This + instruction encapsulates any number of actions, which the instruction + executes. Open vSwitch does not explicitly represent + <code>Apply-Actions</code>. Instead, any action by itself is implicitly + part of an <code>Apply-Actions</code> instructions. + </p> + + <p> + Open vSwitch syntax requires other instructions, if present, to be in the + order listed above. Otherwise it will flag an error. + </p> + + <action name="METER"> + <h2>The <code>meter</code> action and instruction</h2> + <syntax><code>meter:<var>meter_id</var></code></syntax> + + <p> + Apply meter <var>meter_id</var>. If a meter band rate is exceeded, the + packet may be dropped, or modified, depending on the meter band type. + </p> + + <conformance> + <p> + OpenFlow 1.3 introduced the <code>meter</code> instruction. OpenFlow + 1.5 changes <code>meter</code> from an instruction to an action. + </p> + + <p> + Open vSwitch 2.0 introduced OpenFlow protocol support for meters, but + it did not include a datapath implementation. Open vSwitch 2.7 added + meter support to the userspace datapath. Open vSwitch 2.10 added + meter support to the kernel datapath. + </p> + </conformance> + </action> + + <action name="CLEAR_ACTIONS"> + <h2>The <code>clear_actions</code> instruction</h2> + <syntax><code>clear_actions</code></syntax> + + <p> + Clears the action set. See ``Action Sets'', above, for more + information. + </p> + + <conformance> + OpenFlow 1.1 introduced <code>clear_actions</code>. Open vSwitch 2.1 + added support for <code>clear_actions</code>. + </conformance> + </action> + + <action name="WRITE_ACTIONS"> + <h2>The <code>write_actions</code> instruction</h2> + <syntax><code>write_actions(<var>action</var></code>...<code>)</code></syntax> + + <p> + Adds each <var>action</var> to the action set. The action set is + carried between flow tables and then executed at the end of the + pipeline. Only certain actions may be written to the action set. See + ``Action Sets'', above, for more information. + </p> + + <conformance> + OpenFlow 1.1 introduced <code>write_actions</code>. Open vSwitch 2.1 + added support for <code>write_actions</code>. + </conformance> + </action> + + <action name="WRITE_METADATA"> + <h2>The <code>write_metadata</code> instruction</h2> + <syntax><code>write_metadata:<var>value</var></code>[<code>/<var>mask</var></code>]</syntax> + + <p> + Updates the flow's <code>metadata</code> field. If <var>mask</var> is + omitted, <code>metadata</code> is set exactly to <var>value</var>; if + <var>mask</var> is specified, then a 1-bit in <var>mask</var> indicates + that the corresponding bit in <code>metadata</code> will be replaced + with the corresponding bit from <var>value</var>. Both + <var>value</var> and <var>mask</var> are 64-bit values that are decimal + by default; use a <code>0x</code> prefix to specify them in + hexadecimal. + </p> + + <p> + The <code>metadata</code> field can also be matched in the flow table + and updated with actions such as <code>set_field</code> and + <code>move</code>. + </p> + + <conformance> + OpenFlow 1.1 introduced <code>write_metadata</code>. Open vSwitch 2.1 + added support for <code>write_metadata</code>. + </conformance> + </action> + + <action name="GOTO_TABLE"> + <h2>The <code>goto_table</code> instruction</h2> + <syntax><code>goto_table:<var>table</var></code></syntax> + + <p> + Jumps to <var>table</var> as the next table in the process pipeline. + The table may be a number between 0 and 254 or a table name. + </p> + + <p> + It is an error if <var>table</var> is less than or equal to the table + of the flow that contains it; that is, <code>goto_table</code> must + move forward in the OpenFlow pipeline. Since <code>goto_table</code> + must be the last instruction in a flow, it never leads to recursion. + The <code>resubmit</code> extension action is more flexible. + </p> + + <conformance> + OpenFlow 1.1 introduced <code>goto_table</code>. Open vSwitch 2.1 + added support for <code>goto_table</code>. + </conformance> + </action> + </group> +</actions> diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in index ea55008b1853..e77c09e81c89 100644 --- a/utilities/ovs-ofctl.8.in +++ b/utilities/ovs-ofctl.8.in @@ -767,1060 +767,11 @@ The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands require an additional field, which must be the final field specified: . .IP \fBactions=\fR[\fIaction\fR][\fB,\fIaction\fR...]\fR -Specifies a comma-separated list of actions to take on a packet when the -flow entry matches. If no \fIaction\fR is specified, then packets -matching the flow are dropped. The following forms of \fIaction\fR -are supported: -. -.RS -.IP \fIport\fR -.IQ \fBoutput:\fIport\fR -Outputs the packet to OpenFlow port number \fIport\fR. If \fIport\fR -is the packet's input port, the packet is not output. -. -.IP \fBoutput:\fIsrc\fB[\fIstart\fB..\fIend\fB] -Outputs the packet to the OpenFlow port number read from \fIsrc\fR, -which may be an NXM field name, as described above, or a match field name. -\fBoutput:reg0[16..31]\fR outputs to the OpenFlow port number -written in the upper half of register 0. If the port number is the -packet's input port, the packet is not output. -.IP -This form of \fBoutput\fR was added in Open vSwitch 1.3.0. This form -of \fBoutput\fR uses an OpenFlow extension that is not supported by -standard OpenFlow switches. -. -.IP \fBoutput(port=\fIport\fR\fB,max_len=\fInbytes\fR) -Outputs the packet to the OpenFlow port number read from \fIport\fR, -with maximum packet size set to \fInbytes\fR. \fIport\fR may be OpenFlow -port number, \fBlocal\fR, or \fBin_port\fR. Patch port is not supported. -Packets larger than \fInbytes\fR will be trimmed to \fInbytes\fR while -packets smaller than \fInbytes\fR remains the original size. -. -.IP \fBgroup:\fIgroup_id\fR -Outputs the packet to the OpenFlow group \fIgroup_id\fR. OpenFlow 1.1 -introduced support for groups; Open vSwitch 2.6 and later also -supports output to groups as an extension to OpenFlow 1.0. See -\fBGroup Syntax\fR for more details. -. -.IP \fBnormal\fR -Subjects the packet to the device's normal L2/L3 processing. (This -action is not implemented by all OpenFlow switches.) -. -.IP \fBflood\fR -Outputs the packet on all switch physical ports other than the port on -which it was received and any ports on which flooding is disabled -(typically, these would be ports disabled by the IEEE 802.1D spanning -tree protocol). -. -.IP \fBall\fR -Outputs the packet on all switch physical ports other than the port on -which it was received. -. -.IP \fBlocal\fR -Outputs the packet on the ``local port,'' which corresponds to the -network device that has the same name as the bridge. -. -.IP \fBin_port\fR -Outputs the packet on the port from which it was received. -. -.IP \fBcontroller(\fIkey\fB=\fIvalue\fR...\fB) -Sends the packet and its metadata to the OpenFlow controller as a ``packet in'' -message. The supported key-value pairs are: -.RS -.IP "\fBmax_len=\fInbytes\fR" -Limit to \fInbytes\fR the number of bytes of the packet to send to -the controller. By default the entire packet is sent. -.IP "\fBreason=\fIreason\fR" -Specify \fIreason\fR as the reason for sending the message in the -``packet in'' message. The supported reasons are \fBaction\fR (the -default), \fBno_match\fR, and \fBinvalid_ttl\fR. -.IP "\fBid=\fIcontroller-id\fR" -Specify \fIcontroller-id\fR, a 16-bit integer, as the connection ID of -the OpenFlow controller or controllers to which the ``packet in'' -message should be sent. The default is zero. Zero is also the -default connection ID for each controller connection, and a given -controller connection will only have a nonzero connection ID if its -controller uses the \fBNXT_SET_CONTROLLER_ID\fR Nicira extension to -OpenFlow. -.IP "\fBuserdata=\fIhh\fR...\fR" -Supplies the bytes represented as hex digits \fIhh\fR as additional -data to the controller in the packet-in message. Pairs of hex digits -may be separated by periods for readability. -.IP "\fBpause\fR" -Causes the switch to freeze the packet's trip through Open vSwitch -flow tables and serializes that state into the packet-in message as a -``continuation,'' an additional property in the \fBNXT_PACKET_IN2\fR -message. The controller can later send the continuation back to the -switch in an \fBNXT_RESUME\fR message, which will restart the packet's -traversal from the point where it was interrupted. This permits an -OpenFlow controller to interpose on a packet midway through processing -in Open vSwitch. -.IP "\fBmeter_id=\fIid\fR" -Use meter \fIid\fR to rate-limit the OpenFlow packet-in messages that -this action sends to the controller. By default, packets sent to the -controller are associated with the "controller" virtual meter, if one -was configured. -. -.RE -.IP -If any \fIreason\fR other than \fBaction\fR or any nonzero -\fIcontroller-id\fR is supplied, Open vSwitch extension -\fBNXAST_CONTROLLER\fR, supported by Open vSwitch 1.6 and later, is -used. If \fBuserdata\fR is supplied, then \fBNXAST_CONTROLLER2\fR, -supported by Open vSwitch 2.6 and later, is used. -. -.IP \fBcontroller\fR -.IQ \fBcontroller\fR[\fB:\fInbytes\fR] -Shorthand for \fBcontroller()\fR or -\fBcontroller(max_len=\fInbytes\fB)\fR, respectively. -. -.IP \fBenqueue(\fIport\fB,\fIqueue\fB)\fR -Enqueues the packet on the specified \fIqueue\fR within port -\fIport\fR, which must be an OpenFlow port number or keyword -(e.g. \fBLOCAL\fR). The number of supported queues depends on the -switch; some OpenFlow implementations do not support queuing at all. -. -.IP \fBdrop\fR -Discards the packet, so no further processing or forwarding takes place. -If a drop action is used, no other actions may be specified. -. -.IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR -Modifies the VLAN id on a packet. The VLAN tag is added or modified -as necessary to match the value specified. If the VLAN tag is added, -a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set -this). -. -.IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR -Modifies the VLAN priority on a packet. The VLAN tag is added or modified -as necessary to match the value specified. Valid values are between 0 -(lowest) and 7 (highest). If the VLAN tag is added, a vid of zero is used -(see the \fBmod_vlan_vid\fR action to set this). -. -.IP \fBstrip_vlan\fR -Strips the VLAN tag from a packet if it is present. -. -.IP \fBpush_vlan\fR:\fIethertype\fR -Push a new VLAN tag onto the packet. Ethertype is used as the Ethertype -for the tag. Only ethertype 0x8100 should be used. (0x88a8 which the spec -allows isn't supported at the moment.) -A priority of zero and the tag of zero are used for the new tag. -. -.IP \fBpush_mpls\fR:\fIethertype\fR -Changes the packet's Ethertype to \fIethertype\fR, which must be either -\fB0x8847\fR or \fB0x8848\fR, and pushes an MPLS LSE. -.IP -If the packet does not already contain any MPLS labels then an initial -label stack entry is pushed. The label stack entry's label is 2 if the -packet contains IPv6 and 0 otherwise, its default traffic control value is -the low 3 bits of the packet's DSCP value (0 if the packet is not IP), and -its TTL is copied from the IP TTL (64 if the packet is not IP). -.IP -If the packet does already contain an MPLS label, pushes a new -outermost label as a copy of the existing outermost label. -.IP -OVS currently supports at most 3 MPLS labels. -. -.IP \fBpop_mpls\fR:\fIethertype\fR -Strips the outermost MPLS label stack entry and changes the packet's -Ethertype to \fIethertype\fR. -. -.IP \fBmod_dl_src\fB:\fImac\fR -Sets the source Ethernet address to \fImac\fR. -. -.IP \fBmod_dl_dst\fB:\fImac\fR -Sets the destination Ethernet address to \fImac\fR. -. -.IP \fBmod_nw_src\fB:\fIip\fR -Sets the IPv4 source address to \fIip\fR. -. -.IP \fBmod_nw_dst\fB:\fIip\fR -Sets the IPv4 destination address to \fIip\fR. -. -.IP \fBmod_tp_src\fB:\fIport\fR -Sets the TCP or UDP or SCTP source port to \fIport\fR. -. -.IP \fBmod_tp_dst\fB:\fIport\fR -Sets the TCP or UDP or SCTP destination port to \fIport\fR. -. -.IP \fBmod_nw_tos\fB:\fItos\fR -Sets the DSCP bits in the IPv4 ToS/DSCP or IPv6 traffic class field to -\fItos\fR, which must be a multiple of 4 between 0 and 255. This action -does not modify the two least significant bits of the ToS field (the ECN bits). -. -.IP \fBmod_nw_ecn\fB:\fIecn\fR -Sets the ECN bits in the IPv4 ToS or IPv6 traffic class field to \fIecn\fR, -which must be a value between 0 and 3, inclusive. This action does not modify -the six most significant bits of the field (the DSCP bits). -.IP -Requires OpenFlow 1.1 or later. -. -.IP \fBmod_nw_ttl\fB:\fIttl\fR -Sets the IPv4 TTL or IPv6 hop limit field to \fIttl\fR, which is specified as -a decimal number between 0 and 255, inclusive. Switch behavior when setting -\fIttl\fR to zero is not well specified, though. -.IP -Requires OpenFlow 1.1 or later. -.RE -.IP -The following actions are Nicira vendor extensions that, as of this writing, are -only known to be implemented by Open vSwitch: -. -.RS -. -.IP \fBresubmit\fB:\fIport\fR -.IQ \fBresubmit\fB(\fR[\fIport\fR]\fB,\fR[\fItable\fR]\fB) -.IQ \fBresubmit\fB(\fR[\fIport\fR]\fB,\fR[\fItable\fR]\fB,ct) -Re-searches this OpenFlow flow table (or table \fItable\fR, if -specified) with the \fBin_port\fR field replaced by -\fIport\fR (if \fIport\fR is specified) and the packet 5-tuple fields -swapped with the corresponding conntrack original direction tuple -fields (if \fBct\fR is specified, see \fBct_nw_src\fR above), and -executes the actions found, if any, in addition to any other actions -in this flow entry. The \fBin_port\fR and swapped 5-tuple fields are -restored immediately after the search, before any actions are -executed. -.IP -The \fItable\fR may be expressed as a number between 0 and 254 or -(unless \fB\-\-no\-names\fR is specified) a name. -.IP -The \fBct\fR option requires a valid connection tracking state as a -match prerequisite in the flow where this action is placed. Examples -of valid connection tracking state matches include -\fBct_state=+new\fR, \fBct_state=+est\fR, \fBct_state=+rel\fR, and -\fBct_state=+trk-inv\fR. -.IP -Recursive \fBresubmit\fR actions are obeyed up to -implementation-defined limits: -.RS -.IP \(bu -Open vSwitch 1.0.1 and earlier did not support recursion. -.IP \(bu -Open vSwitch 1.0.2 and 1.0.3 limited recursion to 8 levels. -.IP \(bu -Open vSwitch 1.1 and 1.2 limited recursion to 16 levels. -.IP \(bu -Open vSwitch 1.2 through 1.8 limited recursion to 32 levels. -.IP \(bu -Open vSwitch 1.9 through 2.0 limited recursion to 64 levels. -.IP \(bu -Open vSwitch 2.1 through 2.5 limited recursion to 64 levels and impose -a total limit of 4,096 resubmits per flow translation (earlier versions -did not impose any total limit). -.IP \(bu -Open vSwitch 2.6 and later imposes the same limits as 2.5, with one -exception: \fBresubmit\fR from table \fIx\fR to any table \fIy\fR > -\fIx\fR does not count against the recursion limit. -.RE -.IP -Open vSwitch before 1.2.90 did not support \fItable\fR. Open vSwitch -before 2.7 did not support \fBct\fR. -. -.IP \fBset_tunnel\fB:\fIid\fR -.IQ \fBset_tunnel64\fB:\fIid\fR -If outputting to a port that encapsulates the packet in a tunnel and -supports an identifier (such as GRE), sets the identifier to \fIid\fR. -If the \fBset_tunnel\fR form is used and \fIid\fR fits in 32 bits, -then this uses an action extension that is supported by Open vSwitch -1.0 and later. Otherwise, if \fIid\fR is a 64-bit value, it requires -Open vSwitch 1.1 or later. -. -.IP \fBset_queue\fB:\fIqueue\fR -Sets the queue that should be used to \fIqueue\fR when packets are -output. The number of supported queues depends on the switch; some -OpenFlow implementations do not support queuing at all. -. -.IP \fBpop_queue\fR -Restores the queue to the value it was before any \fBset_queue\fR -actions were applied. -. -.IP \fBct\fR -.IQ \fBct(\fR[\fIargument\fR][\fB,\fIargument\fR...]\fB) -Send the packet through the connection tracker. Refer to the \fBct_state\fR -documentation above for possible packet and connection states. A \fBct\fR -action always sets the packet to an untracked state and clears out the -\fBct_state\fR fields for the current processing path. Those fields are -only available for the processing path pointed to by the \fBtable\fR -argument. The following arguments are supported: -.RS -.IP \fBcommit\fR -.RS -Commit the connection to the connection tracking module. Information about the -connection will be stored beyond the lifetime of the packet in the pipeline. -Some \fBct_state\fR flags are only available for committed connections. -.RE -.IP \fBforce\fR -.RS -A committed connection always has the directionality of the packet -that caused the connection to be committed in the first place. This -is the ``original direction'' of the connection, and the opposite -direction is the ``reply direction''. If a connection is already -committed, but it is in the wrong direction, \fBforce\fR flag may be -used in addition to \fBcommit\fR flag to effectively terminate the -existing connection and start a new one in the current direction. -This flag has no effect if the original direction of the connection is -already the same as that of the current packet. -.RE -.IP \fBtable=\fItable\fR -Fork pipeline processing in two. The original instance of the packet will -continue processing the current actions list as an untracked packet. An -additional instance of the packet will be sent to the connection tracker, which -will be re-injected into the OpenFlow pipeline to resume processing in table -\fInumber\fR (which may be specified as a number between 0 and 254 or, -unless \fB\-\-no\-names\fR is specified, a name), with the -\fBct_state\fR and other ct match fields set. If -\fBtable\fR is not specified, then the packet which is submitted to the -connection tracker is not re-injected into the OpenFlow pipeline. It is -strongly recommended to specify a table later than the current table to prevent -loops. -.IP \fBzone=\fIvalue\fR -.IQ \fBzone=\fIsrc\fB[\fIstart\fB..\fIend\fB]\fR -A 16-bit context id that can be used to isolate connections into separate -domains, allowing overlapping network addresses in different zones. If a zone -is not provided, then the default is to use zone zero. The \fBzone\fR may be -specified either as an immediate 16-bit \fIvalue\fR, or may be provided from an -NXM field \fIsrc\fR. The \fIstart\fR and \fIend\fR pair are inclusive, and must -specify a 16-bit range within the field. This value is copied to the -\fBct_zone\fR match field for packets which are re-injected into the pipeline -using the \fBtable\fR option. -.IP \fBexec\fB(\fR[\fIaction\fR][\fB,\fIaction\fR...]\fB)\fR -Perform actions within the context of connection tracking. This is a restricted -set of actions which are in the same format as their specifications as part -of a flow. Only actions which modify the \fBct_mark\fR or \fBct_label\fR -fields are accepted within the \fBexec\fR action, and these fields may only be -modified with this option. For example: -. -.RS -.IP \fBset_field:\fIvalue\fR[\fB/\fImask\fR]->ct_mark\fR -Store a 32-bit metadata value with the connection. Subsequent lookups -for packets in this connection will populate the \fBct_mark\fR flow -field when the packet is sent to the connection tracker with the -\fBtable\fR specified. -.IP \fBset_field:\fIvalue\fR[\fB/\fImask\fR]->ct_label\fR -Store a 128-bit metadata value with the connection. Subsequent -lookups for packets in this connection will populate the -\fBct_label\fR flow field when the packet is sent to the connection -tracker with the \fBtable\fR specified. -.RE -.IP -The \fBcommit\fR parameter must be specified to use \fBexec(...)\fR. -. -.IP \fBalg=\fIalg\fR -Specify application layer gateway \fIalg\fR to track specific connection -types. If subsequent related connections are sent through the \fBct\fR -action, then the \fBrel\fR flag in the \fBct_state\fR field will be set. -Supported types include: -.RS -.IP \fBftp\fR -Look for negotiation of FTP data connections. Specify this option for FTP -control connections to detect related data connections and populate the -\fBrel\fR flag for the data connections. -. -.IP \fBtftp\fR -Look for negotiation of TFTP data connections. Specify this option for TFTP -control connections to detect related data connections and populate the -\fBrel\fR flag for the data connections. -.RE -. -.IP -The \fBcommit\fR parameter must be specified to use \fBalg=\fIalg\fR. -. -.IP -When committing related connections, the \fBct_mark\fR for that connection is -inherited from the current \fBct_mark\fR stored with the original connection -(ie, the connection created by \fBct(alg=...)\fR). -. -.IP -Note that with the Linux datapath, global sysctl options affect the usage of -the \fBct\fR action. In particular, if \fBnet.netfilter.nf_conntrack_helper\fR -is enabled then application layer gateway helpers may be executed even if the -\fBalg\fR option is not specified. This is the default setting until Linux 4.7. -For security reasons, the netfilter team recommends users to disable this -option. See this blog post for further details: -. -http://www.netfilter.org/news.html#2012-04-03 -. -.IP \fBnat\fR[\fB(\fR(\fBsrc\fR|\fBdst\fR)\fB=\fIaddr1\fR[\fB-\fIaddr2\fR][\fB:\fIport1\fR[\fB-\fIport2\fR]][\fB,\fIflags\fR]\fB)\fR] -. -Specify address and port translation for the connection being tracked. -For new connections either \fBsrc\fR or \fBdst\fR argument must be -provided to set up either source address/port translation (SNAT) or -destination address/port translation (DNAT), respectively. Setting up -address translation for a new connection takes effect only if the -\fBcommit\fR flag is also provided for the enclosing \fBct\fR action. -A bare \fBnat\fR action will only translate the packet being processed -in the way the connection has been set up with an earlier \fBct\fR -action. Also a \fBnat\fR action with \fBsrc\fR or \fBdst\fR, when -applied to a packet belonging to an established (rather than new) -connection, will behave the same as a bare \fBnat\fR. -.IP -\fBsrc\fR and \fBdst\fR options take the following arguments: -.RS -.IP \fIaddr1\fR[\fB-\fIaddr2\fR] -The address range from which the translated address should be -selected. If only one address is given, then that address will always -be selected, otherwise the address selection can be informed by the -optional \fBpersistent\fR flag as described below. Either IPv4 or -IPv6 addresses can be provided, but both addresses must be of the same -type, and the datapath behavior is undefined in case of providing IPv4 -address range for an IPv6 packet, or IPv6 address range for an IPv4 -packet. IPv6 addresses must be bracketed with '[' and ']' if a port -range is also given. -.RE -. -.RS -.IP \fIport1\fR[\fB-\fIport2\fR] -The port range from which the translated port should be selected. If -only one port number is provided, then that should be selected. In -case of a mapping conflict the datapath may choose any other -non-conflicting port number instead, even when no port range is -specified. The port number selection can be informed by the optional -\fBrandom\fR and \fBhash\fR flags as described below. -.RE -.IP -The optional flags are: -.RS -.IP \fBrandom\fR -The selection of the port from the given range should be done using a -fresh random number. This flag is mutually exclusive with \fBhash\fR. -.RE -. -.RS -.IP \fBhash\fR -The selection of the port from the given range should be done using a -datapath specific hash of the packet's IP addresses and the other, -non-mapped port number. This flag is mutually exclusive with -\fBrandom\fR. -.RE -. -.RS -.IP \fBpersistent\fR -The selection of the IP address from the given range should be done so -that the same mapping can be provided after the system restarts. -.RE -.IP -If an \fBalg\fR is specified for the committing \fBct\fR action that -also includes \fBnat\fR with a \fBsrc\fR or \fBdst\fR attribute, -then the datapath tries to set up the helper to be NAT aware. This -functionality is datapath specific and may not be supported by all -datapaths. -.IP -\fBnat\fR was introduced in Open vSwitch 2.6. The first datapath that -implements \fBct nat\fR support is the one that ships with Linux 4.6. -.RE -.IP -The \fBct\fR action may be used as a primitive to construct stateful firewalls -by selectively committing some traffic, then matching the \fBct_state\fR to -allow established connections while denying new connections. The following -flows provide an example of how to implement a simple firewall that allows new -connections from port 1 to port 2, and only allows established connections to -send traffic from port 2 to port 1: - \fBtable=0,priority=1,action=drop - table=0,priority=10,arp,action=normal - table=0,priority=100,ip,ct_state=-trk,action=ct(table=1) - table=1,in_port=1,ip,ct_state=+trk+new,action=ct(commit),2 - table=1,in_port=1,ip,ct_state=+trk+est,action=2 - table=1,in_port=2,ip,ct_state=+trk+new,action=drop - table=1,in_port=2,ip,ct_state=+trk+est,action=1\fR -.IP -If \fBct\fR is executed on IP (or IPv6) fragments, then the message is -implicitly reassembled before sending to the connection tracker and -refragmented upon \fBoutput\fR, to the original maximum received fragment size. -Reassembly occurs within the context of the \fBzone\fR, meaning that IP -fragments in different zones are not assembled together. Pipeline processing -for the initial fragments is halted; When the final fragment is received, the -message is assembled and pipeline processing will continue for that flow. -Because packet ordering is not guaranteed by IP protocols, it is not possible -to determine which IP fragment will cause message reassembly (and therefore -continue pipeline processing). As such, it is strongly recommended that -multiple flows should not execute \fBct\fR to reassemble fragments from the -same IP message. -.IP -The \fBct\fR action was introduced in Open vSwitch 2.5. -. -.IP \fBct_clear\fR -Clears connection tracking state from the flow, zeroing -\fBct_state\fR, \fBct_zone\fR, \fBct_mark\fR, and \fBct_label\fR. -.IP -This action was introduced in Open vSwitch 2.6.90. -. -.IP \fBdec_ttl\fR -.IQ \fBdec_ttl(\fIid1\fR[\fB,\fIid2\fR]...\fB)\fR -Decrement TTL of IPv4 packet or hop limit of IPv6 packet. If the -TTL or hop limit is initially zero or decrementing would make it so, no -decrement occurs, as packets reaching TTL zero must be rejected. Instead, -a ``packet-in'' message with reason code \fBOFPR_INVALID_TTL\fR is -sent to each connected controller that has enabled receiving them, -if any. Processing the current set of actions then stops. However, -if the current set of actions was reached through ``resubmit'' then -remaining actions in outer levels resume processing. -.IP -This action also optionally supports the ability to specify a list of -valid controller ids. Each of the controllers in the list will receive -the ``packet_in'' message only if they have registered to receive the -invalid ttl packets. If controller ids are not specified, the -``packet_in'' message will be sent only to the controllers having -controller id zero which have registered for the invalid ttl packets. -. -.IP \fBset_mpls_label\fR:\fIlabel\fR -Set the label of the outer MPLS label stack entry of a packet. -\fIlabel\fR should be a 20-bit value that is decimal by default; -use a \fB0x\fR prefix to specify them in hexadecimal. -. -.IP \fBset_mpls_tc\fR:\fItc\fR -Set the traffic-class of the outer MPLS label stack entry of a packet. -\fItc\fR should be a in the range 0 to 7 inclusive. -. -.IP \fBset_mpls_ttl\fR:\fIttl\fR -Set the TTL of the outer MPLS label stack entry of a packet. -\fIttl\fR should be in the range 0 to 255 inclusive. -. -.IP \fBdec_mpls_ttl\fR -Decrement TTL of the outer MPLS label stack entry of a packet. If the TTL -is initially zero or decrementing would make it so, no decrement occurs. -Instead, a ``packet-in'' message with reason code \fBOFPR_INVALID_TTL\fR -is sent to the main controller (id zero), if it has enabled receiving them. -Processing the current set of actions then stops. However, if the current -set of actions was reached through ``resubmit'' then remaining actions in -outer levels resume processing. -. -.IP \fBdec_nsh_ttl\fR -Decrement TTL of the outer NSH header of a packet. If the TTL -is initially zero or decrementing would make it so, no decrement occurs. -Instead, a ``packet-in'' message with reason code \fBOFPR_INVALID_TTL\fR -is sent to the main controller (id zero), if it has enabled receiving them. -Processing the current set of actions then stops. However, if the current -set of actions was reached through ``resubmit'' then remaining actions in -outer levels resume processing. -. -.IP \fBnote:\fR[\fIhh\fR]... -Does nothing at all. Any number of bytes represented as hex digits -\fIhh\fR may be included. Pairs of hex digits may be separated by -periods for readability. -The \fBnote\fR action's format doesn't include an exact length for its -payload, so the provided bytes will be padded on the right by enough -bytes with value 0 to make the total number 6 more than a multiple of -8. -. -.IP "\fBmove:\fIsrc\fB[\fIstart\fB..\fIend\fB]\->\fIdst\fB[\fIstart\fB..\fIend\fB]\fR" -Copies the named bits from field \fIsrc\fR to field \fIdst\fR. -\fIsrc\fR and \fIdst\fR may be NXM field names as defined in -\fBnicira\-ext.h\fR, e.g. \fBNXM_OF_UDP_SRC\fR or \fBNXM_NX_REG0\fR, -or a match field name, e.g. \fBreg0\fR. Each -\fIstart\fR and \fIend\fR pair, which are inclusive, must specify the -same number of bits and must fit within its respective field. -Shorthands for \fB[\fIstart\fB..\fIend\fB]\fR exist: use -\fB[\fIbit\fB]\fR to specify a single bit or \fB[]\fR to specify an -entire field (in the latter case the brackets can also be left off). -.IP -Examples: \fBmove:NXM_NX_REG0[0..5]\->NXM_NX_REG1[26..31]\fR copies the -six bits numbered 0 through 5, inclusive, in register 0 into bits 26 -through 31, inclusive; -\fBmove:reg0[0..15]\->vlan_tci\fR copies the least -significant 16 bits of register 0 into the VLAN TCI field. -.IP -In OpenFlow 1.0 through 1.4, \fBmove\fR ordinarily uses an Open -vSwitch extension to OpenFlow. In OpenFlow 1.5, \fBmove\fR uses the -OpenFlow 1.5 standard \fBcopy_field\fR action. The ONF has -also made \fBcopy_field\fR available as an extension to OpenFlow 1.3. -Open vSwitch 2.4 and later understands this extension and uses it if a -controller uses it, but for backward compatibility with older versions -of Open vSwitch, \fBovs\-ofctl\fR does not use it. -. -.IP "\fBset_field:\fIvalue\fR[/\fImask\fR]\fB\->\fIdst" -.IQ "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]" -Loads a literal value into a field or part of a field. With -\fBset_field\fR, \fBvalue\fR and the optional \fBmask\fR are given in -the customary syntax for field \fIdst\fR, which is expressed as a -field name. For example, \fBset_field:00:11:22:33:44:55->eth_src\fR -sets the Ethernet source address to 00:11:22:33:44:55. With -\fBload\fR, \fIvalue\fR must be an integer value (in decimal or -prefixed by \fB0x\fR for hexadecimal) and \fIdst\fR can also be the -NXM or OXM name for the field. For example, -\fBload:0x001122334455->OXM_OF_ETH_SRC[]\fR has the same effect as the -prior \fBset_field\fR example. -.IP -The two forms exist for historical reasons. Open vSwitch 1.1 -introduced \fBNXAST_REG_LOAD\fR as a Nicira extension to OpenFlow 1.0 -and used \fBload\fR to express it. Later, OpenFlow 1.2 introduced a -standard \fBOFPAT_SET_FIELD\fR action that was restricted to loading -entire fields, so Open vSwitch added the form \fBset_field\fR with -this restriction. OpenFlow 1.5 extended \fBOFPAT_SET_FIELD\fR to the -point that it became a superset of \fBNXAST_REG_LOAD\fR. Open vSwitch -translates either syntax as necessary for the OpenFlow version in use: -in OpenFlow 1.0 and 1.1, \fBNXAST_REG_LOAD\fR; in OpenFlow 1.2, 1.3, -and 1.4, \fBNXAST_REG_LOAD\fR for \fBload\fR or for loading a -subfield, \fBOFPAT_SET_FIELD\fR otherwise; and OpenFlow 1.5 and later, -\fBOFPAT_SET_FIELD\fR. -. -.IP "\fBpush:\fIsrc\fB[\fIstart\fB..\fIend\fB]" -.IQ "\fBpop:\fIdst\fB[\fIstart\fB..\fIend\fB]" -These Open vSwitch extension actions act on bits \fIstart\fR to -\fIend\fR, inclusive, in the named field, pushing or popping the bits -on a general-purpose stack of fields or subfields. Controllers can -use this stack for saving and restoring data or metadata around -\fBresubmit\fR actions, for swapping or rearranging data and metadata, -or for other purposes. Any data or metadata field, or part of one, -may be pushed, and any modifiable field or subfield may be popped. -.IP -The number of bits pushed in a stack entry do not have to match the -number of bits later popped from that entry. If more bits are popped -from an entry than were pushed, then the entry is conceptually -left-padded with 0-bits as needed. If fewer bits are popped than -pushed, then bits are conceptually trimmed from the left side of the -entry. -.IP -The stack's size is intended to have a large enough limit that -``normal'' use will not pose problems. Stack overflow or underflow is -an error that causes action execution to stop. -.IP -Example: \fBpush:NXM_NX_REG2[0..5]\fR or \fBpush:reg2[0..5]\fR push -the value stored in register 2 bits 0 through 5, inclusive, on the -internal stack, and \fBpop:NXM_NX_REG2[0..5]\fR or -\fBpop:reg2[0..5]\fR pops the value from top of the stack and sets -register 2 bits 0 through 5, inclusive, based on bits 0 through 5 from -the value just popped. -. -.IP "\fBmultipath(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIn_links\fB, \fIarg\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR" -Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter, -then the applies multipath link selection \fIalgorithm\fR (with -parameter \fIarg\fR) to choose one of \fIn_links\fR output links -numbered 0 through \fIn_links\fR minus 1, and stores the link into -\fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as -described above. -.IP -\fIfields\fR must be one of the following: -.RS -.IP \fBeth_src\fR -Hashes Ethernet source address only. -.IP \fBsymmetric_l4\fR -Hashes Ethernet source, destination, and type, VLAN ID, IPv4/IPv6 -source, destination, and protocol, and TCP or SCTP (but not UDP) -ports. The hash is computed so that pairs of corresponding flows in -each direction hash to the same value, in environments where L2 paths -are the same in each direction. UDP ports are not included in the -hash to support protocols such as VXLAN that use asymmetric ports in -each direction. -.IP \fBsymmetric_l3l4\fR -Hashes IPv4/IPv6 source, destination, and protocol, and TCP or SCTP -(but not UDP) ports. Like \fBsymmetric_l4\fR, this is a symmetric -hash, but by excluding L2 headers it is more effective in environments -with asymmetric L2 paths (e.g. paths involving VRRP IP addresses on a -router). Not an effective hash function for protocols other than IPv4 -and IPv6, which hash to a constant zero. -.IP \fBsymmetric_l3l4+udp\fR -Like \fBsymmetric_l3l4+udp\fR, but UDP ports are included in the hash. -This is a more effective hash when asymmetric UDP protocols such as -VXLAN are not a consideration. -.IP \fBsymmetric_l3\fR -Hashes network source address and network destination address. -.IP \fBnw_src\fR -Hashes Network source address only. -.IP \fBnw_dst\fR -Hashes Network destination address only. -.RE -.IP -\fIalgorithm\fR must be one of \fBmodulo_n\fR, -\fBhash_threshold\fR, \fBhrw\fR, and \fBiter_hash\fR. Only -the \fBiter_hash\fR algorithm uses \fIarg\fR. -.IP -Refer to \fBnicira\-ext.h\fR for more details. -. -.IP "\fBbundle(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, slaves:[\fIs1\fB, \fIs2\fB, ...])\fR" -Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter, then -applies the bundle link selection \fIalgorithm\fR to choose one of the listed -slaves represented as \fIslave_type\fR. Currently the only supported -\fIslave_type\fR is \fBofport\fR. Thus, each \fIs1\fR through \fIsN\fR should -be an OpenFlow port number. Outputs to the selected slave. -.IP -Currently, \fIfields\fR must be either \fBeth_src\fR, \fBsymmetric_l4\fR, \fBsymmetric_l3l4\fR, \fBsymmetric_l3l4+udp\fR, -\fBnw_src\fR, or \fBnw_dst\fR, and \fIalgorithm\fR must be one of \fBhrw\fR and \fBactive_backup\fR. -.IP -Example: \fBbundle(eth_src,0,hrw,ofport,slaves:4,8)\fR uses an Ethernet source -hash with basis 0, to select between OpenFlow ports 4 and 8 using the Highest -Random Weight algorithm. -.IP -Refer to \fBnicira\-ext.h\fR for more details. -. -.IP "\fBbundle_load(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, \fIdst\fB[\fIstart\fB..\fIend\fB], slaves:[\fIs1\fB, \fIs2\fB, ...])\fR" -Has the same behavior as the \fBbundle\fR action, with one exception. Instead -of outputting to the selected slave, it writes its selection to -\fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as described -above. -.IP -Example: \fBbundle_load(eth_src, 0, hrw, ofport, NXM_NX_REG0[], -slaves:4, 8)\fR uses an Ethernet source hash with basis 0, to select -between OpenFlow ports 4 and 8 using the Highest Random Weight -algorithm, and writes the selection to \fBNXM_NX_REG0[]\fR. Also the -match field name can be used, for example, instead of 'NXM_NX_REG0' -the name 'reg0' can be used. When the while field is indicated the -empty brackets can also be left off. -.IP -Refer to \fBnicira\-ext.h\fR for more details. -. -.IP "\fBlearn(\fIargument\fR[\fB,\fIargument\fR]...\fB)\fR" -This action adds or modifies a flow in an OpenFlow table, similar to -\fBovs\-ofctl \-\-strict mod\-flows\fR. The arguments specify the -flow's match fields, actions, and other properties, as follows. At -least one match criterion and one action argument should ordinarily be -specified. -.RS -.IP \fBidle_timeout=\fIseconds\fR -.IQ \fBhard_timeout=\fIseconds\fR -.IQ \fBpriority=\fIvalue\fR -.IQ \fBcookie=\fIvalue\fR -.IQ \fBsend_flow_rem\fR -These arguments have the same meaning as in the usual \fBovs\-ofctl\fR -flow syntax. -. -.IP \fBfin_idle_timeout=\fIseconds\fR -.IQ \fBfin_hard_timeout=\fIseconds\fR -Adds a \fBfin_timeout\fR action with the specified arguments to the -new flow. This feature was added in Open vSwitch 1.5.90. -. -.IP \fBtable=\fItable\fR -The table in which the new flow should be inserted. Specify a decimal -number between 0 and 254 or (unless \fB\-\-no\-names\fR is specified) -a name. The default, if \fBtable\fR is unspecified, is table 1. -. -.IP \fBdelete_learned\fR -This flag enables deletion of the learned flows when the flow with the -\fBlearn\fR action is removed. Specifically, when the last -\fBlearn\fR action with this flag and particular \fBtable\fR and -\fBcookie\fR values is removed, the switch deletes all of the flows in -the specified table with the specified cookie. -. -.IP -This flag was added in Open vSwitch 2.4. -. -.IP \fBlimit=\fInumber\fR -If the number of flows in table \fBtable\fR with cookie id \fBcookie\fR exceeds -\fInumber\fR, a new flow will not be learned by this action. By default -there's no limit. limit=0 is a long-hand for no limit. -. -.IP -This flag was added in Open vSwitch 2.8. -. -.IP \fBresult_dst=\fIfield\fB[\fIbit\fB]\fR -If learning failed (because the number of flows exceeds \fBlimit\fR), -the action sets \fIfield\fB[\fIbit\fB]\fR to 0, otherwise it will be set to 1. -\fIfield\fB[\fIbit\fB]\fR must be a single bit. -. -.IP -This flag was added in Open vSwitch 2.8. -. -.IP \fIfield\fB=\fIvalue\fR -.IQ \fIfield\fB[\fIstart\fB..\fIend\fB]=\fIsrc\fB[\fIstart\fB..\fIend\fB]\fR -.IQ \fIfield\fB[\fIstart\fB..\fIend\fB]\fR -Adds a match criterion to the new flow. -.IP -The first form specifies that \fIfield\fR must match the literal -\fIvalue\fR, e.g. \fBdl_type=0x0800\fR. All of the fields and values -for \fBovs\-ofctl\fR flow syntax are available with their usual -meanings. Shorthand notation matchers (e.g. \fBip\fR in place of -\fBdl_type=0x0800\fR) are not currently implemented. -.IP -The second form specifies that \fIfield\fB[\fIstart\fB..\fIend\fB]\fR -in the new flow must match \fIsrc\fB[\fIstart\fB..\fIend\fB]\fR taken -from the flow currently being processed. -For example, \fINXM_OF_UDP_DST\fB[]\fR=\fINXM_OF_UDP_SRC\fB[]\fR on a -TCP packet for which the UDP src port is \fB53\fR, creates a flow which -matches \fINXM_OF_UDP_DST\fB[]\fR=\fB53\fR. -.IP -The third form is a shorthand for the second form. It specifies that -\fIfield\fB[\fIstart\fB..\fIend\fB]\fR in the new flow must match the same -\fIfield\fB[\fIstart\fB..\fIend\fB]\fR taken from the flow currently -being processed. -For example, \fINXM_OF_TCP_DST\fB[]\fR on a TCP packet -for which the TCP dst port is \fB80\fR, creates a flow which -matches \fINXM_OF_TCP_DST\fB[]\fR=\fB80\fR. -. -.IP \fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB] -.IQ \fBload:\fIsrc\fB[\fIstart\fB..\fIend\fB]\->\fIdst\fB[\fIstart\fB..\fIend\fB] -. -Adds a \fBload\fR action to the new flow. -.IP -The first form loads the literal \fIvalue\fR into bits \fIstart\fR -through \fIend\fR, inclusive, in field \fIdst\fR. Its syntax is the -same as the \fBload\fR action described earlier in this section. -.IP -The second form loads \fIsrc\fB[\fIstart\fB..\fIend\fB]\fR, a value -from the flow currently being processed, into bits \fIstart\fR -through \fIend\fR, inclusive, in field \fIdst\fR. -. -.IP \fBoutput:\fIfield\fB[\fIstart\fB..\fIend\fB]\fR -Add an \fBoutput\fR action to the new flow's actions, that outputs to -the OpenFlow port taken from \fIfield\fB[\fIstart\fB..\fIend\fB]\fR, -which must be an NXM field as described above. -.RE -.RE -. -.RS -. -.IP \fBclear_actions\fR -Clears all the actions in the action set immediately. -. -.IP \fBwrite_actions(\fR[\fIaction\fR][\fB,\fIaction\fR...]\fB) -Add the specific actions to the action set. The syntax of -\fIactions\fR is the same as in the \fBactions=\fR field. The action -set is carried between flow tables and then executed at the end of the -pipeline. -. -.IP -The actions in the action set are applied in the following order, as -required by the OpenFlow specification, regardless of the order in -which they were added to the action set. Except as specified -otherwise below, the action set only holds at most a single action of -each type. When more than one action of a single type is written to -the action set, the one written later replaces the earlier action: -. -.RS -.IP 1. -\fBstrip_vlan\fR -.IQ -\fBpop_mpls\fR -. -.IP 2. -\fBdecap\fR -. -.IP 3. -\fBencap\fR -. -.IP 4. -\fBpush_mpls\fR -. -.IP 5. -\fBpush_vlan\fR -. -.IP 6. -\fBdec_ttl\fR -.IQ -\fBdec_mpls_ttl\fR -.IQ -\fBdec_nsh_ttl\fR -. -.IP 7. -\fBload\fR -.IQ -\fBmove\fR -.IQ -\fBmod_dl_dst\fR -.IQ -\fBmod_dl_src\fR -.IQ -\fBmod_nw_dst\fR -.IQ -\fBmod_nw_src\fR -.IQ -\fBmod_nw_tos\fR -.IQ -\fBmod_nw_ecn\fR -.IQ -\fBmod_nw_ttl\fR -.IQ -\fBmod_tp_dst\fR -.IQ -\fBmod_tp_src\fR -.IQ -\fBmod_vlan_pcp\fR -.IQ -\fBmod_vlan_vid\fR -.IQ -\fBset_field\fR -.IQ -\fBset_tunnel\fR -.IQ -\fBset_tunnel64\fR -.IQ -The action set can contain any number of these actions, with -cumulative effect. They will be applied in the order as added. -That is, when multiple actions modify the same part of a field, -the later modification takes effect, and when they modify -different parts of a field (or different fields), then both -modifications are applied. -. -.IP 8. -\fBset_queue\fR -. -.IP 9. -\fBgroup\fR -.IQ -\fBoutput\fR -.IQ -\fBresubmit\fR -.IQ -If more than one of these actions is present, then the one listed -earliest above is executed and the others are ignored, regardless of -the order in which they were added to the action set. (If none of these -actions is present, the action set has no real effect, because the -modified packet is not sent anywhere and thus the modifications are -not visible.) -.RE -.IP -Only the actions listed above may be written to the action set. -\fBencap\fR, \fBdecap\fR and \fBdec_nsh_ttl\fR actions are nonstandard. -. -.IP \fBwrite_metadata\fB:\fIvalue\fR[/\fImask\fR] -Updates the metadata field for the flow. If \fImask\fR is omitted, the -metadata field is set exactly to \fIvalue\fR; if \fImask\fR is specified, then -a 1-bit in \fImask\fR indicates that the corresponding bit in the metadata -field will be replaced with the corresponding bit from \fIvalue\fR. Both -\fIvalue\fR and \fImask\fR are 64-bit values that are decimal by default; use -a \fB0x\fR prefix to specify them in hexadecimal. -. -.IP \fBmeter\fR:\fImeter_id\fR -Apply the \fImeter_id\fR before any other actions. If a meter band rate is -exceeded, the packet may be dropped, or modified, depending on the meter -band type. See the description of the \fBMeter Table Commands\fR, above, -for more details. -. -.IP \fBgoto_table\fR:\fItable\fR -Jumps to \fItable\Fr as the next table in the process pipeline. The -\fItable\fR may be a number between 0 and 254 or (unless -\fB\-\-no\-names\fR is specified) a name. -. -.IP "\fBfin_timeout(\fIargument\fR[\fB,\fIargument\fR]\fB)" -This action changes the idle timeout or hard timeout, or both, of this -OpenFlow rule when the rule matches a TCP packet with the FIN or RST -flag. When such a packet is observed, the action reduces the rule's -timeouts to those specified on the action. If the rule's existing -timeout is already shorter than the one that the action specifies, -then that timeout is unaffected. -.IP -\fIargument\fR takes the following forms: -.RS -.IP "\fBidle_timeout=\fIseconds\fR" -Causes the flow to expire after the given number of seconds of -inactivity. -. -.IP "\fBhard_timeout=\fIseconds\fR" -Causes the flow to expire after the given number of seconds, -regardless of activity. (\fIseconds\fR specifies time since the -flow's creation, not since the receipt of the FIN or RST.) -.RE -.IP -This action was added in Open vSwitch 1.5.90. -. -.IP "\fBsample(\fIargument\fR[\fB,\fIargument\fR]...\fB)\fR" -Samples packets and sends one sample for every sampled packet. -.IP -\fIargument\fR takes the following forms: -.RS -.IP "\fBprobability=\fIpackets\fR" -The number of sampled packets out of 65535. Must be greater or equal to 1. -.IP "\fBcollector_set_id=\fIid\fR" -The unsigned 32-bit integer identifier of the set of sample collectors -to send sampled packets to. Defaults to 0. -.IP "\fBobs_domain_id=\fIid\fR" -When sending samples to IPFIX collectors, the unsigned 32-bit integer -Observation Domain ID sent in every IPFIX flow record. Defaults to 0. -.IP "\fBobs_point_id=\fIid\fR" -When sending samples to IPFIX collectors, the unsigned 32-bit integer -Observation Point ID sent in every IPFIX flow record. Defaults to 0. -.IP "\fBsampling_port=\fIport\fR" -Sample packets on \fIport\fR, which should be the ingress or egress -port. This option, which was added in Open vSwitch 2.5.90, allows the -IPFIX implementation to export egress tunnel information. -.IP "\fBingress\fR" -.IQ "\fBegress\fR" -Specifies explicitly that the packet is being sampled on ingress to or -egress from the switch. IPFIX reports sent by Open vSwitch before -version 2.5.90 did not include a direction. From 2.5.90 until 2.6.90, -IPFIX reports inferred a direction from \fBsampling_port\fR: if it was -the packet's output port, then the direction was reported as egress, -otherwise as ingress. Open vSwitch 2.6.90 introduced these options, -which allow the inferred direction to be overridden. This is -particularly useful when the ingress (or egress) port is not a tunnel. -.RE -.IP -Refer to \fBovs\-vswitchd.conf.db\fR(5) for more details on -configuring sample collector sets. -.IP -This action was added in Open vSwitch 1.10.90. -. -.IP "\fBexit\fR" -This action causes Open vSwitch to immediately halt execution of -further actions. Those actions which have already been executed are -unaffected. Any further actions, including those which may be in -other tables, or different levels of the \fBresubmit\fR call stack, -are ignored. Actions in the action set is still executed (specify -\fBclear_actions\fR before \fBexit\fR to discard them). -. -.IP "\fBconjunction(\fIid\fB, \fIk\fB/\fIn\fR\fB)\fR" -This action allows for sophisticated ``conjunctive match'' flows. -Refer to \fBCONJUNCTIVE MATCH FIELDS\fR in \fBovs\-fields\fR(7) for details. -.IP -The \fBconjunction\fR action and \fBconj_id\fR field were introduced -in Open vSwitch 2.4. -. -.IP "\fBclone(\fR[\fIaction\fR][\fB,\fIaction\fR...]\fB)\fR" -Executes each nested \fIaction\fR, saving much of the packet and -pipeline state beforehand and then restoring it afterward. The state -that is saved and restored includes all flow data and metadata -(including, for example, \fBct_state\fR), the stack accessed by -\fBpush\fR and \fBpop\fR actions, and the OpenFlow action set. -.IP -This action was added in Open vSwitch 2.6.90. -. -.IP "\fBencap(\fR\fIheader\fR[\fB(\fR\fIprop\fR\fB=\fR\fIvalue\fR,\fItlv\fR\fB(\fR\fIclass\fR,\fItype\fR,\fIvalue\fB)\fR,...\fB)\fR]\fB)\fR" -Encapsulates the packet with a new packet header, e.g., ethernet -or nsh. -. -.RS -.IP "\fIheader\fR" -Used to specify encapsulation header type. -. -.IP "\fIprop\fR\fB=\fR\fIvalue\fR" -Used to specify the initial value for the property in the encapsulation header. -. -.IP "\fItlv\fR\fB(\fR\fIclass\fR,\fItype\fR,\fIvalue\fB)\fR" -Used to specify the initial value for the TLV (Type Length Value) -in the encapsulation header. -.RE -.IP -For example, \fBencap(ethernet)\fR will encapsulate the L3 packet with -Ethernet header. -.IP -\fBencap(nsh(md_type=1))\fR will encapsulate the packet with nsh header -and nsh metadata type 1. -.IP -\fBencap(nsh(md_type=2,tlv(0x1000,10,0x12345678)))\fR will encapsulate -the packet with nsh header and nsh metadata type 2, and the nsh TLV with -class 0x1000 and type 10 is set to 0x12345678. -.IP -\fIprop\fR\fB=\fR\fIvalue\fR is just used to set some -necessary fields for encapsulation header initialization. Other fields -in the encapsulation header must be set by \fBset_field\fR action. New -encapsulation header implementation must add new match fields and -corresponding \fBset\fR action in order that \fBset_field\fR action can -change the fields in the encapsulation header on demand. -.IP -\fBencap(nsh(md_type=1)),\fR -\fBset_field:0x1234->nsh_spi,set_field:0x11223344->nsh_c1\fR -is an example to encapsulate nsh header and set nsh spi and c1. -.IP -This action was added in Open vSwitch 2.8. -. -.IP "\fBdecap(\fR[\fBpacket_type(ns=\fR\fInamespace\fR\fB,type=\fR\fItype\fR\fB)\fR]\fB)\fR" -Decapsulates the outer packet header. -. -.RS -.IP "\fBpacket_type(ns=\fR\fInamespace\fR\fB,type=\fR\fItype\fR\fB)\fR" -It is optional and used to specify the outer header type of the -decapsulated packet. \fInamespace\fR is 0 for Ethernet packet, -1 for L3 packet, \fItype\fR\ is L3 protocol type, e.g., -0x894f for nsh, 0x0 for Ethernet. -.RE -.IP -By default, \fBdecap()\fR will decapsulate the outer packet header -according to the packet header type, if -\fBpacket_type(ns=\fR\fInamespace\fR\fB,type=\fR\fItype\fR\fB)\fR -is given, it will decapsulate the given packet header, it will fail -if the actual outer packet header type is not of -\fBpacket_type(ns=\fR\fInamespace\fR\fB,type=\fR\fItype\fR\fB)\fR. -.IP -This action was added in Open vSwitch 2.8. -.RE -. +Specifies a comma-separated list of actions to take on a packet when +the flow entry matches. If no \fIaction\fR is specified, then packets +matching the flow are dropped. See \fBovs\-actions\fR(7) for details +on the syntax and semantics of actions. +K .PP An opaque identifier called a cookie can be used as a handle to identify a set of flows: @@ -2586,6 +1537,7 @@ Additional examples may be found documented as part of related sections. .SH "SEE ALSO" . .BR ovs\-fields (7), +.BR ovs\-actions (7), .BR ovs\-appctl (8), .BR ovs\-vswitchd (8), .BR ovs\-vswitchd.conf.db (8) diff --git a/vswitchd/vswitch.xml b/vswitchd/vswitch.xml index 170e843f1280..afeb72807fcf 100644 --- a/vswitchd/vswitch.xml +++ b/vswitchd/vswitch.xml @@ -5381,7 +5381,7 @@ ovs-vsctl add-port br0 p0 -- set Interface p0 type=patch options:peer=p1 \ <p> With <em>flow-based sampling</em>, <code>sample</code> actions in the OpenFlow flow table drive IPFIX sampling. See - <code>ovs-ofctl</code>(8) for a description of the + <code>ovs-actions</code>(7) for a description of the <code>sample</code> action. </p>

[ovs-dev,3/3] ovs-actions: New document describing OVS actions in detail.

Commit Message

Comments

Patch