.
These commands manage the flow table in an OpenFlow switch. In each
case, \fIflow\fR specifies a flow entry in the format described in
-\fBFlow Syntax\fR, below, and \fIfile\fR is a text file that contains
-zero or more flows in the same syntax, one per line.
-.
-.IP "\fBadd\-flow \fIswitch flow\fR"
-.IQ "\fBadd\-flow \fIswitch \fB\- < \fIfile\fR"
-.IQ "\fBadd\-flows \fIswitch file\fR"
+\fBFlow Syntax\fR, below, \fIfile\fR is a text file that contains zero
+or more flows in the same syntax, one per line, and the optional
+\fB\-\-bundle\fR option operates the command as a single atomic
+transation, see option \fB\-\-bundle\fR, below.
+.
+.IP "[\fB\-\-bundle\fR] \fBadd\-flow \fIswitch flow\fR"
+.IQ "[\fB\-\-bundle\fR] \fBadd\-flow \fIswitch \fB\- < \fIfile\fR"
+.IQ "[\fB\-\-bundle\fR] \fBadd\-flows \fIswitch file\fR"
Add each flow entry to \fIswitch\fR's tables.
.
-.IP "[\fB\-\-strict\fR] \fBmod\-flows \fIswitch flow\fR"
-.IQ "[\fB\-\-strict\fR] \fBmod\-flows \fIswitch \fB\- < \fIfile\fR"
+Each flow specification (e.g., each line in \fIfile\fR) may start with
+\fBadd\fR, \fBmodify\fR, \fBdelete\fR, \fBmodify_strict\fR, or
+\fBdelete_strict\fR keyword to specify whether a flow is to be added,
+modified, or deleted, and whether the modify or delete is strict or
+not. For backwards compatibility a flow specification without one of
+these keywords is treated as a flow add. All flow mods are executed
+in the order specified.
+.
+.IP "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBmod\-flows \fIswitch flow\fR"
+.IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBmod\-flows \fIswitch \fB\- < \fIfile\fR"
Modify the actions in entries from \fIswitch\fR's tables that match
the specified flows. With \fB\-\-strict\fR, wildcards are not treated
as active for matching purposes.
.
-.IP "\fBdel\-flows \fIswitch\fR"
-.IQ "[\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fR[\fIflow\fR]"
-.IQ "[\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fB\- < \fIfile\fR"
+.IP "[\fB\-\-bundle\fR] \fBdel\-flows \fIswitch\fR"
+.IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fR[\fIflow\fR]"
+.IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fB\- < \fIfile\fR"
Deletes entries from \fIswitch\fR's flow table. With only a
\fIswitch\fR argument, deletes all flows. Otherwise, deletes flow
entries that match the specified flows. With \fB\-\-strict\fR,
wildcards are not treated as active for matching purposes.
.
-.IP "[\fB\-\-readd\fR] \fBreplace\-flows \fIswitch file\fR"
+.IP "[\fB\-\-bundle\fR] [\fB\-\-readd\fR] \fBreplace\-flows \fIswitch file\fR"
Reads flow entries from \fIfile\fR (or \fBstdin\fR if \fIfile\fR is
\fB\-\fR) and queries the flow table from \fIswitch\fR. Then it fixes
up any differences, adding flows from \fIflow\fR that are missing on
(e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block
(e.g. \fB192.168.1.0/24\fR).
.
+.IP \fBtun_gbp_id=\fIvalue\fR[\fB/\fImask\fR]
+.IQ \fBtun_gbp_flags=\fIvalue\fR[\fB/\fImask\fR]
+Matches the group policy identifier and flags in the VXLAN header. Only
+packets that arrive over a VXLAN tunnel with the "gbp" extension
+enabled can have this field set. The fields may also be referred to by
+NXM_NX_TUN_GBP_ID[] (16 bits) and NXM_NX_TUN_GBP_FLAGS[] (8 bits) in
+the context of field manipulation actions. If these fields are set and
+the packet matched by the flow is encapsulated in a VXLAN-GBP tunnel,
+then the policy identifier and flags are transmitted to the destination
+VXLAN tunnel endpoint.
+.IP
+The \fBtun_gbp_flags\fR field has the following format:
+.IP
+.in +2
+\f(CR+-+-+-+-+-+-+-+-+\fR
+.br
+\f(CR|-|D|-|-|A|-|-|-|\fR
+.br
+\f(CR+-+-+-+-+-+-+-+-+\fR
+
+.B D :=
+Don't Learn bit. When set, this bit indicates that the egress
+tunnel endpoint MUST NOT learn the source address of the encapsulated
+frame.
+
+.B A :=
+Indicates that the group policy has already been applied to
+this packet. Policies MUST NOT be applied by devices when the A bit is
+set.
+.in -2
+.IP
+For more information, please see the corresponding IETF draft:
+https://tools.ietf.org/html/draft-smith-vxlan-group-policy
+.
.IP "\fBreg\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]"
Matches \fIvalue\fR either exactly or with optional \fImask\fR in
register number \fIidx\fR. The valid range of \fIidx\fR depends on
\fBreg3\fR, and so on.
.IP
These fields were added in Open vSwitch 2.3 to conform with the
-OpenFlow 1.5 (draft) specification. OpenFlow 1.5 calls these fields
+OpenFlow 1.5 specification. OpenFlow 1.5 calls these fields
just the ``packet registers,'' but Open vSwitch already had 32-bit
registers by that name, which is why Open vSwitch refers to the
standard registers as ``extended registers''.
\fBUNSET\fR.
.IP
This field was introduced in Open vSwitch 2.4 to conform with the
-OpenFlow 1.5 (draft) specification.
+OpenFlow 1.5 specification.
+.
+.IP \fBconj_id=\fIvalue\fR
+Matches the given 32-bit \fIvalue\fR against the conjunction ID. This
+is used only with the \fBconjunction\fR action (see below).
+.IP
+This field was introduced in Open vSwitch 2.4.
+.
.PP
Defining IPv6 flows (those with \fBdl_type\fR equal to 0x86dd) requires
support for NXM. The following shorthand notations are available for
.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 (draft) standard \fBcopy_field\fR action. The ONF has
+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
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"
+An individual OpenFlow flow can match only a single value for each
+field. However, situations often arise where one wants to match one
+of a set of values within a field or fields. For matching a single
+field against a set, it is straightforward and efficient to add
+multiple flows to the flow table, one for each value in the set. For
+example, one might use the following flows to send packets with IP
+source address \fIa\fR, \fIb\fR, \fIc\fR, or \fId\fR to the OpenFlow
+controller:
+.RS +1in
+.br
+\fBip,ip_src=\fIa\fB actions=controller\fR
+.br
+\fBip,ip_src=\fIb\fB actions=controller\fR
+.br
+\fBip,ip_src=\fIc\fB actions=controller\fR
+.br
+\fBip,ip_src=\fId\fB actions=controller\fR
+.br
+.RE
+.IP
+Similarly, these flows send packets with IP destination address
+\fIe\fR, \fIf\fR, \fIg\fR, or \fIh\fR to the OpenFlow controller:
+.RS +1in
+.br
+\fBip,ip_dst=\fIe\fB actions=controller\fR
+.br
+\fBip,ip_dst=\fIf\fB actions=controller\fR
+.br
+\fBip,ip_dst=\fIg\fB actions=controller\fR
+.br
+\fBip,ip_dst=\fIh\fB actions=controller\fR
+.br
+.RE
+.IP
+Installing all of the above flows in a single flow table yields a
+disjunctive effect: a packet is sent to the controller if \fBip_src\fR
+\[mo] {\fIa\fR,\fIb\fR,\fIc\fR,\fId\fR} or \fBip_dst\fR \[mo]
+{\fIe\fR,\fIf\fR,\fIg\fR,\fIh\fR} (or both). (Pedantically, if both
+of the above sets of flows are present in the flow table, they should
+have different priorities, because OpenFlow says that the results are
+undefined when two flows with same priority can both match a single
+packet.)
+.IP
+Suppose, on the other hand, one wishes to match conjunctively, that
+is, to send a packet to the controller only if both \fBip_src\fR \[mo]
+{\fIa\fR,\fIb\fR,\fIc\fR,\fId\fR} and \fBip_dst\fR \[mo]
+{\fIe\fR,\fIf\fR,\fIg\fR,\fIh\fR}. This requires 4 \[mu] 4 = 16
+flows, one for each possible pairing of \fBip_src\fR and \fBip_dst\fR.
+That is acceptable for our small example, but it does not gracefully
+extend to larger sets or greater numbers of dimensions.
+.IP
+The \fBconjunction\fR action is a solution for conjunctive matches
+that is built into Open vSwitch. A \fBconjunction\fR action ties
+groups of individual OpenFlow flows into higher-level ``conjunctive
+flows''. Each group corresponds to one dimension, and each flow
+within the group matches one possible value for the dimension. A
+packet that matches one flow from each group matches the conjunctive
+flow.
+.IP
+To implement a conjunctive flow with \fBconjunction\fR, assign the
+conjunctive flow a 32-bit \fIid\fR, which must be unique within an
+OpenFlow table. Assign each of the \fIn\fR \[>=] 2 dimensions a
+unique number from 1 to \fIn\fR; the ordering is unimportant. Add one
+flow to the OpenFlow flow table for each possible value of each
+dimension with \fBconjunction(\fIid, \fIk\fB/\fIn\fB)\fR as the flow's
+actions, where \fIk\fR is the number assigned to the flow's dimension.
+Together, these flows specify the conjunctive flow's match condition.
+When the conjunctive match condition is met, Open vSwitch looks up one
+more flow that specifies the conjunctive flow's actions and receives
+its statistics. This flow is found by setting \fBconj_id\fR to the
+specified \fIid\fR and then again searching the flow table.
+.IP
+The following flows provide an example. Whenever the IP source is one
+of the values in the flows that match on the IP source (dimension 1 of
+2), \fIand\fR the IP destination is one of the values in the flows
+that match on IP destination (dimension 2 of 2), Open vSwitch searches
+for a flow that matches \fBconj_id\fR against the conjunction ID
+(1234), finding the first flow listed below.
+.RS +1in
+.br
+.B "conj_id=1234 actions=controller"
+.br
+.B "ip,ip_src=10.0.0.1 actions=conjunction(1234, 1/2)"
+.br
+.B "ip,ip_src=10.0.0.4 actions=conjunction(1234, 1/2)"
+.br
+.B "ip,ip_src=10.0.0.6 actions=conjunction(1234, 1/2)"
+.br
+.B "ip,ip_src=10.0.0.7 actions=conjunction(1234, 1/2)"
+.br
+.B "ip,ip_dst=10.0.0.2 actions=conjunction(1234, 2/2)"
+.br
+.B "ip,ip_dst=10.0.0.5 actions=conjunction(1234, 2/2)"
+.br
+.B "ip,ip_dst=10.0.0.7 actions=conjunction(1234, 2/2)"
+.br
+.B "ip,ip_dst=10.0.0.8 actions=conjunction(1234, 2/2)"
+.RE
+.IP
+Many subtleties exist:
+.RS
+.IP \(bu
+In the example above, every flow in a single dimension has the same
+form, that is, dimension 1 matches on \fBip_src\fR, dimension 2 on
+\fBip_dst\fR, but this is not a requirement. Different flows within a
+dimension may match on different bits within a field (e.g. IP network
+prefixes of different lengths, or TCP/UDP port ranges as bitwise
+matches), or even on entirely different fields (e.g. to match packets
+for TCP source port 80 or TCP destination port 80).
+.IP \(bu
+The flows within a dimension can vary their matches across more than
+one field, e.g. to match only specific pairs of IP source and
+destination addresses or L4 port numbers.
+.IP \(bu
+A flow may have multiple \fBconjunction\fR actions, with different
+\fIid\fR values. This is useful for multiple conjunctive flows with
+overlapping sets. If one conjunctive flow matches packets with both
+\fBip_src\fR \[mo] {\fIa\fR,\fIb\fR} and \fBip_dst\fR \[mo]
+{\fId\fR,\fIe\fR} and a second conjunctive flow matches \fBip_src\fR
+\[mo] {\fIb\fR,\fIc\fR} and \fBip_dst\fR \[mo] {\fIf\fR,\fIg\fR}, for
+example, then the flow that matches \fBip_src=\fIb\fR would have two
+\fBconjunction\fR actions, one for each conjunctive flow. The order
+of \fBconjunction\fR actions within a list of actions is not
+significant.
+.IP \(bu
+A flow with \fBconjunction\fR actions may not have any other actions.
+(It would not be useful.)
+.IP \(bu
+All of the flows that constitute a conjunctive flow with a given
+\fIid\fR must have the same priority. (Flows with the same \fIid\fR
+but different priorities are currently treated as different
+conjunctive flows, that is, currently \fIid\fR values need only be
+unique within an OpenFlow table at a given priority. This behavior
+isn't guaranteed to stay the same in later releases, so please use
+\fIid\fR values unique within an OpenFlow table.)
+.IP \(bu
+Conjunctive flows must not overlap with each other, at a given
+priority, that is, any given packet must be able to match at most one
+conjunctive flow at a given priority. Overlapping conjunctive flows
+yield unpredictable results.
+.IP \(bu
+Following a conjunctive flow match, the search for the flow with
+\fBconj_id=\fIid\fR is done in the same general-purpose way as other flow
+table searches, so one can use flows with \fBconj_id=\fIid\fR to act
+differently depending on circumstances. (One exception is that the
+search for the \fBconj_id=\fIid\fR flow itself ignores conjunctive flows,
+to avoid recursion.) If the search with \fBconj_id=\fIid\fR fails, Open
+vSwitch acts as if the conjunctive flow had not matched at all, and
+continues searching the flow table for other matching flows.
+.IP \(bu
+OpenFlow prerequisite checking occurs for the flow with
+\fBconj_id=\fIid\fR in the same way as any other flow, e.g. in an
+OpenFlow 1.1+ context, putting a \fBmod_nw_src\fR action into the
+example above would require adding an \fBip\fR match, like this:
+.RS +1in
+.br
+.B "conj_id=1234,ip actions=mod_nw_src:1.2.3.4,controller"
+.br
+.RE
+.IP \(bu
+OpenFlow prerequisite checking also occurs for the individual flows
+that comprise a conjunctive match in the same way as any other flow.
+.IP \(bu
+The flows that constitute a conjunctive flow do not have useful
+statistics. They are never updated with byte or packet counts, and so
+on. (For such a flow, therefore, the idle and hard timeouts work much
+the same way.)
+.IP \(bu
+Conjunctive flows can be a useful building block for negation, that
+is, inequality matches like \fBtcp_src\fR \[!=] 80. To implement an
+inequality match, convert it to a pair of range matches, e.g. 0 \[<=]
+\fBtcp_src\ < 80 and 80 < \fBtcp_src\fR \[<=] 65535, then convert each
+of the range matches into a collection of bitwise matches as explained
+above in the description of \fBtcp_src\fR.
+.IP \(bu
+Sometimes there is a choice of which flows include a particular match.
+For example, suppose that we added an extra constraint to our example,
+to match on \fBip_src\fR \[mo] {\fIa\fR,\fIb\fR,\fIc\fR,\fId\fR} and
+\fBip_dst\fR \[mo] {\fIe\fR,\fIf\fR,\fIg\fR,\fIh\fR} and \fBtcp_dst\fR
+= \fIi\fR. One way to implement this is to add the new constraint to
+the \fBconj_id\fR flow, like this:
+.RS +1in
+.br
+\fBconj_id=1234,tcp,tcp_dst=\fIi\fB actions=mod_nw_src:1.2.3.4,controller\fR
+.br
+.RE
+.IP
+\fIbut this is not recommended\fR because of the cost of the extra
+flow table lookup. Instead, add the constraint to the individual
+flows, either in one of the dimensions or (slightly better) all of
+them.
+.IP \(bu
+A conjunctive match must have \fIn\fR \[>=] 2 dimensions (otherwise a
+conjunctive match is not necessary). Open vSwitch enforces this.
+.IP \(bu
+Each dimension within a conjunctive match should ordinarily have more
+than one flow. Open vSwitch does not enforce this.
+.RE
+.IP
+The \fBconjunction\fR action and \fBconj_id\fR field were introduced
+in Open vSwitch 2.4.
.RE
.
.PP
It is an error if there is no bucket persent group in whose \fBbucket_id\fR is
\fIid\fR.
+.IP \fBselection_method\fR=\fImethod\fR
+The selection method used to select a bucket for a select group.
+This is a string of 1 to 15 bytes in length known to lower layers.
+This field is optional for \fBadd\-group\fR, \fBadd\-groups\fR and
+\fBmod\-group\fR commands on groups of type \fBselect\fR. Prohibited
+otherwise. The default value is the empty string.
+.IP
+This option will use a Netronome OpenFlow extension which is only supported
+when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later.
+
+.IP \fBselection_method_param\fR=\fIparam\fR
+64-bit integer parameter to the selection method selected by the
+\fBselection_method\fR field. The parameter's use is defined by the
+lower-layer that implements the \fBselection_method\fR. It is optional if
+the \fBselection_method\fR field is specified as a non-empty string.
+Prohibited otherwise. The default value is zero.
+.IP
+This option will use a Netronome OpenFlow extension which is only supported
+when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later.
+
+.IP \fBfields\fR=\fIparam\fR
+The field parameters to selection method selected by the
+\fBselection_method\fR field. The syntax is described in \fBFlow Syntax\fR
+with the additional restrictions that if a value is provided it is
+treated as a wildcard mask and wildcard masks following a slash are
+prohibited. The pre-requisites of fields must be provided by any flows that
+output to the group. The use of the fields is defined by the lower-layer
+that implements the \fBselection_method\fR. They are optional if the
+\fBselection_method\fR field is specified as a non-empty string.
+Prohibited otherwise. The default is no fields.
+.IP
+This option will use a Netronome OpenFlow extension which is only supported
+when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later.
+
.IP \fBbucket\fR=\fIbucket_parameters\fR
The \fBadd-group\fR, \fBadd-groups\fR and \fBmod-group\fR commands
require at least one bucket field. Bucket fields must appear after
0xffffff00 are reserved.
.
This field was added in Open vSwitch 2.4 to conform with the OpenFlow
-1.5 (draft) specification. It is not supported when earlier versions
+1.5 specification. It is not supported when earlier versions
of OpenFlow are used. Open vSwitch will automatically allocate bucket
ids when they are not specified.
.IP \fBactions=\fR[\fIaction\fR][\fB,\fIaction\fR...]\fR
.IP \fBrate=\fIvalue\fR
The relative rate limit for this band, in kilobits per second or packets per
second, depending on the meter flags defined above.
-.IP \fBburst_size=\fIport\fR
-The maximum burst allowed for the band. If unspecified, the switch is free to
-select some reasonable value depending on it's configuration.
+.IP \fBburst_size=\fIsize\fR
+The maximum burst allowed for the band. If \fBpktps\fR is specified,
+then \fIsize\fR is a packet count, otherwise it is in kilobits. If
+unspecified, the switch is free to select some reasonable value
+depending on its configuration.
.RE
.
.SH OPTIONS
\fB\-\-strict\fR
Uses strict matching when running flow modification commands.
.
+.IP "\fB\-\-bundle\fR"
+Execute flow mods as an OpenFlow 1.4 atomic bundle transaction.
+.RS
+.IP \(bu
+Within a bundle, all flow mods are processed in the order they appear
+and as a single atomic transaction, meaning that if one of them fails,
+the whole transaction fails and none of the changes are made to the
+\fIswitch\fR's flow table, and that each given datapath packet
+traversing the OpenFlow tables sees the flow tables either as before
+the transaction, or after all the flow mods in the bundle have been
+successfully applied.
+.IP \(bu
+The beginning and the end of the flow table modification commands in a
+bundle are delimited with OpenFlow 1.4 bundle control messages, which
+makes it possible to stream the included commands without explicit
+OpenFlow barriers, which are otherwise used after each flow table
+modification command. This may make large modifications execute
+faster as a bundle.
+.IP \(bu
+Bundles require OpenFlow 1.4 or higher. An explicit \fB-O
+OpenFlow14\fR option is not needed, but you may need to enable
+OpenFlow 1.4 support for OVS by setting the OVSDB \fIprotocols\fR
+column in the \fIbridge\fR table.
+.RE
+.
.so lib/ofp-version.man
.
.IP "\fB\-F \fIformat\fR[\fB,\fIformat\fR...]"
projects / cascardo / ovs.git / blobdiff