297
297
These commands manage the flow table in an OpenFlow switch. In each
298
298
case, \fIflow\fR specifies a flow entry in the format described in
299
\fBFlow Syntax\fR, below, and \fIfile\fR is a text file that contains
300
zero or more flows in the same syntax, one per line.
299
\fBFlow Syntax\fR, below, \fIfile\fR is a text file that contains zero
300
or more flows in the same syntax, one per line, and the optional
301
\fB\-\-bundle\fR option operates the command as a single atomic
302
transation, see option \fB\-\-bundle\fR, below.
302
.IP "\fBadd\-flow \fIswitch flow\fR"
303
.IQ "\fBadd\-flow \fIswitch \fB\- < \fIfile\fR"
304
.IQ "\fBadd\-flows \fIswitch file\fR"
304
.IP "[\fB\-\-bundle\fR] \fBadd\-flow \fIswitch flow\fR"
305
.IQ "[\fB\-\-bundle\fR] \fBadd\-flow \fIswitch \fB\- < \fIfile\fR"
306
.IQ "[\fB\-\-bundle\fR] \fBadd\-flows \fIswitch file\fR"
305
307
Add each flow entry to \fIswitch\fR's tables.
307
.IP "[\fB\-\-strict\fR] \fBmod\-flows \fIswitch flow\fR"
308
.IQ "[\fB\-\-strict\fR] \fBmod\-flows \fIswitch \fB\- < \fIfile\fR"
309
Each flow specification (e.g., each line in \fIfile\fR) may start with
310
\fBadd\fR, \fBmodify\fR, \fBdelete\fR, \fBmodify_strict\fR, or
311
\fBdelete_strict\fR keyword to specify whether a flow is to be added,
312
modified, or deleted, and whether the modify or delete is strict or
313
not. For backwards compatibility a flow specification without one of
314
these keywords is treated as a flow add. All flow mods are executed
315
in the order specified.
317
.IP "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBmod\-flows \fIswitch flow\fR"
318
.IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBmod\-flows \fIswitch \fB\- < \fIfile\fR"
309
319
Modify the actions in entries from \fIswitch\fR's tables that match
310
320
the specified flows. With \fB\-\-strict\fR, wildcards are not treated
311
321
as active for matching purposes.
313
.IP "\fBdel\-flows \fIswitch\fR"
314
.IQ "[\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fR[\fIflow\fR]"
315
.IQ "[\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fB\- < \fIfile\fR"
323
.IP "[\fB\-\-bundle\fR] \fBdel\-flows \fIswitch\fR"
324
.IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fR[\fIflow\fR]"
325
.IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fB\- < \fIfile\fR"
316
326
Deletes entries from \fIswitch\fR's flow table. With only a
317
327
\fIswitch\fR argument, deletes all flows. Otherwise, deletes flow
318
328
entries that match the specified flows. With \fB\-\-strict\fR,
319
329
wildcards are not treated as active for matching purposes.
321
.IP "[\fB\-\-readd\fR] \fBreplace\-flows \fIswitch file\fR"
331
.IP "[\fB\-\-bundle\fR] [\fB\-\-readd\fR] \fBreplace\-flows \fIswitch file\fR"
322
332
Reads flow entries from \fIfile\fR (or \fBstdin\fR if \fIfile\fR is
323
333
\fB\-\fR) and queries the flow table from \fIswitch\fR. Then it fixes
324
334
up any differences, adding flows from \fIflow\fR that are missing on
690
.IP \fBtp_src=\fIport\fR
691
.IQ \fBtp_dst=\fIport\fR
692
When \fBdl_type\fR and \fBnw_proto\fR specify TCP or UDP or SCTP, \fBtp_src\fR
693
and \fBtp_dst\fR match the UDP or TCP or SCTP source or destination port
694
\fIport\fR, respectively, which is specified as a decimal number
695
between 0 and 65535, inclusive (e.g. 80 to match packets originating
713
.IP \fBtcp_src=\fIport\fR
714
.IQ \fBtcp_dst=\fIport\fR
715
.IQ \fBudp_src=\fIport\fR
716
.IQ \fBudp_dst=\fIport\fR
717
.IQ \fBsctp_src=\fIport\fR
718
.IQ \fBsctp_dst=\fIport\fR
719
Matches a TCP, UDP, or SCTP source or destination port \fIport\fR,
720
which is specified as a decimal number between 0 and 65535, inclusive.
698
When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of
699
these settings are ignored (see \fBFlow Syntax\fR above).
722
When \fBdl_type\fR and \fBnw_proto\fR are wildcarded or set to values
723
that do not indicate an appropriate protocol, the values of these
724
settings are ignored (see \fBFlow Syntax\fR above).
701
.IP \fBtp_src=\fIport\fB/\fImask\fR
702
.IQ \fBtp_dst=\fIport\fB/\fImask\fR
703
Bitwise match on TCP (or UDP or SCTP) source or destination port,
704
respectively. The \fIport\fR and \fImask\fR are 16-bit numbers
726
.IP \fBtcp_src=\fIport\fB/\fImask\fR
727
.IQ \fBtcp_dst=\fIport\fB/\fImask\fR
728
.IQ \fBudp_src=\fIport\fB/\fImask\fR
729
.IQ \fBudp_dst=\fIport\fB/\fImask\fR
730
.IQ \fBsctp_src=\fIport\fB/\fImask\fR
731
.IQ \fBsctp_dst=\fIport\fB/\fImask\fR
732
Bitwise match on TCP (or UDP or SCTP) source or destination port.
733
The \fIport\fR and \fImask\fR are 16-bit numbers
705
734
written in decimal or in hexadecimal prefixed by \fB0x\fR. Each 1-bit
706
735
in \fImask\fR requires that the corresponding bit in \fIport\fR must
707
736
match. Each 0-bit in \fImask\fR causes the corresponding bit to be
1388
1492
through 31, inclusive;
1389
1493
\fBmove:NXM_NX_REG0[0..15]\->NXM_OF_VLAN_TCI[]\fR copies the least
1390
1494
significant 16 bits of register 0 into the VLAN TCI field.
1496
In OpenFlow 1.0 through 1.4, \fBmove\fR ordinarily uses an Open
1497
vSwitch extension to OpenFlow. In OpenFlow 1.5, \fBmove\fR uses the
1498
OpenFlow 1.5 standard \fBcopy_field\fR action. The ONF has
1499
also made \fBcopy_field\fR available as an extension to OpenFlow 1.3.
1500
Open vSwitch 2.4 and later understands this extension and uses it if a
1501
controller uses it, but for backward compatibility with older versions
1502
of Open vSwitch, \fBovs\-ofctl\fR does not use it.
1392
.IP "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]"
1393
Writes \fIvalue\fR to bits \fIstart\fR through \fIend\fR, inclusive,
1504
.IP "\fBset_field:\fIvalue\fR[/\fImask\fR]\fB\->\fIdst"
1505
.IQ "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]"
1506
Loads a literal value into a field or part of a field. With
1507
\fBset_field\fR, \fBvalue\fR and the optional \fBmask\fR are given in
1508
the customary syntax for field \fIdst\fR, which is expressed as a
1509
field name. For example, \fBset_field:00:11:22:33:44:55->eth_src\fR
1510
sets the Ethernet source address to 00:11:22:33:44:55. With
1511
\fBload\fR, \fIvalue\fR must be an integer value (in decimal or
1512
prefixed by \fB0x\fR for hexadecimal) and \fIdst\fR is the NXM or OXM
1513
name for the field. For example,
1514
\fBload:0x001122334455->OXM_OF_ETH_DST[]\fR has the same effect as the
1515
prior \fBset_field\fR example.
1396
Example: \fBload:55\->NXM_NX_REG2[0..5]\fR loads value 55 (bit pattern
1397
\fB110111\fR) into bits 0 through 5, inclusive, in register 2.
1517
The two forms exist for historical reasons. Open vSwitch 1.1
1518
introduced \fBNXAST_REG_LOAD\fR as a Nicira extension to OpenFlow 1.0
1519
and used \fBload\fR to express it. Later, OpenFlow 1.2 introduced a
1520
standard \fBOFPAT_SET_FIELD\fR action that was restricted to loading
1521
entire fields, so Open vSwitch added the form \fBset_field\fR with
1522
this restriction. OpenFlow 1.5 extended \fBOFPAT_SET_FIELD\fR to the
1523
point that it became a superset of \fBNXAST_REG_LOAD\fR. Open vSwitch
1524
translates either syntax as necessary for the OpenFlow version in use:
1525
in OpenFlow 1.0 and 1.1, \fBNXAST_REG_LOAD\fR; in OpenFlow 1.2, 1.3,
1526
and 1.4, \fBNXAST_REG_LOAD\fR for \fBload\fR or for loading a
1527
subfield, \fBOFPAT_SET_FIELD\fR otherwise; and OpenFlow 1.5 and later,
1528
\fBOFPAT_SET_FIELD\fR.
1399
1530
.IP "\fBpush:\fIsrc\fB[\fIstart\fB..\fIend\fB]"
1400
1531
Pushes \fIstart\fR to \fIend\fR bits inclusive, in fields
1696
1834
other tables, or different levels of the \fBresubmit\fR call stack,
1697
1835
are ignored. Actions in the action set is still executed (specify
1698
1836
\fBclear_actions\fR before \fBexit\fR to discard them).
1838
.IP "\fBconjunction(\fIid\fB, \fIk\fB/\fIn\fR\fB)\fR"
1839
An individual OpenFlow flow can match only a single value for each
1840
field. However, situations often arise where one wants to match one
1841
of a set of values within a field or fields. For matching a single
1842
field against a set, it is straightforward and efficient to add
1843
multiple flows to the flow table, one for each value in the set. For
1844
example, one might use the following flows to send packets with IP
1845
source address \fIa\fR, \fIb\fR, \fIc\fR, or \fId\fR to the OpenFlow
1849
\fBip,ip_src=\fIa\fB actions=controller\fR
1851
\fBip,ip_src=\fIb\fB actions=controller\fR
1853
\fBip,ip_src=\fIc\fB actions=controller\fR
1855
\fBip,ip_src=\fId\fB actions=controller\fR
1859
Similarly, these flows send packets with IP destination address
1860
\fIe\fR, \fIf\fR, \fIg\fR, or \fIh\fR to the OpenFlow controller:
1863
\fBip,ip_dst=\fIe\fB actions=controller\fR
1865
\fBip,ip_dst=\fIf\fB actions=controller\fR
1867
\fBip,ip_dst=\fIg\fB actions=controller\fR
1869
\fBip,ip_dst=\fIh\fB actions=controller\fR
1873
Installing all of the above flows in a single flow table yields a
1874
disjunctive effect: a packet is sent to the controller if \fBip_src\fR
1875
\[mo] {\fIa\fR,\fIb\fR,\fIc\fR,\fId\fR} or \fBip_dst\fR \[mo]
1876
{\fIe\fR,\fIf\fR,\fIg\fR,\fIh\fR} (or both). (Pedantically, if both
1877
of the above sets of flows are present in the flow table, they should
1878
have different priorities, because OpenFlow says that the results are
1879
undefined when two flows with same priority can both match a single
1882
Suppose, on the other hand, one wishes to match conjunctively, that
1883
is, to send a packet to the controller only if both \fBip_src\fR \[mo]
1884
{\fIa\fR,\fIb\fR,\fIc\fR,\fId\fR} and \fBip_dst\fR \[mo]
1885
{\fIe\fR,\fIf\fR,\fIg\fR,\fIh\fR}. This requires 4 \[mu] 4 = 16
1886
flows, one for each possible pairing of \fBip_src\fR and \fBip_dst\fR.
1887
That is acceptable for our small example, but it does not gracefully
1888
extend to larger sets or greater numbers of dimensions.
1890
The \fBconjunction\fR action is a solution for conjunctive matches
1891
that is built into Open vSwitch. A \fBconjunction\fR action ties
1892
groups of individual OpenFlow flows into higher-level ``conjunctive
1893
flows''. Each group corresponds to one dimension, and each flow
1894
within the group matches one possible value for the dimension. A
1895
packet that matches one flow from each group matches the conjunctive
1898
To implement a conjunctive flow with \fBconjunction\fR, assign the
1899
conjunctive flow a 32-bit \fIid\fR, which must be unique within an
1900
OpenFlow table. Assign each of the \fIn\fR \[>=] 2 dimensions a
1901
unique number from 1 to \fIn\fR; the ordering is unimportant. Add one
1902
flow to the OpenFlow flow table for each possible value of each
1903
dimension with \fBconjunction(\fIid, \fIk\fB/\fIn\fB)\fR as the flow's
1904
actions, where \fIk\fR is the number assigned to the flow's dimension.
1905
Together, these flows specify the conjunctive flow's match condition.
1906
When the conjunctive match condition is met, Open vSwitch looks up one
1907
more flow that specifies the conjunctive flow's actions and receives
1908
its statistics. This flow is found by setting \fBconj_id\fR to the
1909
specified \fIid\fR and then again searching the flow table.
1911
The following flows provide an example. Whenever the IP source is one
1912
of the values in the flows that match on the IP source (dimension 1 of
1913
2), \fIand\fR the IP destination is one of the values in the flows
1914
that match on IP destination (dimension 2 of 2), Open vSwitch searches
1915
for a flow that matches \fBconj_id\fR against the conjunction ID
1916
(1234), finding the first flow listed below.
1919
.B "conj_id=1234 actions=controller"
1921
.B "ip,ip_src=10.0.0.1 actions=conjunction(1234, 1/2)"
1923
.B "ip,ip_src=10.0.0.4 actions=conjunction(1234, 1/2)"
1925
.B "ip,ip_src=10.0.0.6 actions=conjunction(1234, 1/2)"
1927
.B "ip,ip_src=10.0.0.7 actions=conjunction(1234, 1/2)"
1929
.B "ip,ip_dst=10.0.0.2 actions=conjunction(1234, 2/2)"
1931
.B "ip,ip_dst=10.0.0.5 actions=conjunction(1234, 2/2)"
1933
.B "ip,ip_dst=10.0.0.7 actions=conjunction(1234, 2/2)"
1935
.B "ip,ip_dst=10.0.0.8 actions=conjunction(1234, 2/2)"
1938
Many subtleties exist:
1941
In the example above, every flow in a single dimension has the same
1942
form, that is, dimension 1 matches on \fBip_src\fR, dimension 2 on
1943
\fBip_dst\fR, but this is not a requirement. Different flows within a
1944
dimension may match on different bits within a field (e.g. IP network
1945
prefixes of different lengths, or TCP/UDP port ranges as bitwise
1946
matches), or even on entirely different fields (e.g. to match packets
1947
for TCP source port 80 or TCP destination port 80).
1949
The flows within a dimension can vary their matches across more than
1950
one field, e.g. to match only specific pairs of IP source and
1951
destination addresses or L4 port numbers.
1953
A flow may have multiple \fBconjunction\fR actions, with different
1954
\fIid\fR values. This is useful for multiple conjunctive flows with
1955
overlapping sets. If one conjunctive flow matches packets with both
1956
\fBip_src\fR \[mo] {\fIa\fR,\fIb\fR} and \fBip_dst\fR \[mo]
1957
{\fId\fR,\fIe\fR} and a second conjunctive flow matches \fBip_src\fR
1958
\[mo] {\fIb\fR,\fIc\fR} and \fBip_dst\fR \[mo] {\fIf\fR,\fIg\fR}, for
1959
example, then the flow that matches \fBip_src=\fIb\fR would have two
1960
\fBconjunction\fR actions, one for each conjunctive flow. The order
1961
of \fBconjunction\fR actions within a list of actions is not
1964
A flow with \fBconjunction\fR actions may also include \fBnote\fR
1965
actions for annotations, but not any other kind of actions. (They
1966
would not be useful because they would never be executed.)
1968
All of the flows that constitute a conjunctive flow with a given
1969
\fIid\fR must have the same priority. (Flows with the same \fIid\fR
1970
but different priorities are currently treated as different
1971
conjunctive flows, that is, currently \fIid\fR values need only be
1972
unique within an OpenFlow table at a given priority. This behavior
1973
isn't guaranteed to stay the same in later releases, so please use
1974
\fIid\fR values unique within an OpenFlow table.)
1976
Conjunctive flows must not overlap with each other, at a given
1977
priority, that is, any given packet must be able to match at most one
1978
conjunctive flow at a given priority. Overlapping conjunctive flows
1979
yield unpredictable results.
1981
Following a conjunctive flow match, the search for the flow with
1982
\fBconj_id=\fIid\fR is done in the same general-purpose way as other flow
1983
table searches, so one can use flows with \fBconj_id=\fIid\fR to act
1984
differently depending on circumstances. (One exception is that the
1985
search for the \fBconj_id=\fIid\fR flow itself ignores conjunctive flows,
1986
to avoid recursion.) If the search with \fBconj_id=\fIid\fR fails, Open
1987
vSwitch acts as if the conjunctive flow had not matched at all, and
1988
continues searching the flow table for other matching flows.
1990
OpenFlow prerequisite checking occurs for the flow with
1991
\fBconj_id=\fIid\fR in the same way as any other flow, e.g. in an
1992
OpenFlow 1.1+ context, putting a \fBmod_nw_src\fR action into the
1993
example above would require adding an \fBip\fR match, like this:
1996
.B "conj_id=1234,ip actions=mod_nw_src:1.2.3.4,controller"
2000
OpenFlow prerequisite checking also occurs for the individual flows
2001
that comprise a conjunctive match in the same way as any other flow.
2003
The flows that constitute a conjunctive flow do not have useful
2004
statistics. They are never updated with byte or packet counts, and so
2005
on. (For such a flow, therefore, the idle and hard timeouts work much
2008
Conjunctive flows can be a useful building block for negation, that
2009
is, inequality matches like \fBtcp_src\fR \[!=] 80. To implement an
2010
inequality match, convert it to a pair of range matches, e.g. 0 \[<=]
2011
\fBtcp_src\ < 80 and 80 < \fBtcp_src\fR \[<=] 65535, then convert each
2012
of the range matches into a collection of bitwise matches as explained
2013
above in the description of \fBtcp_src\fR.
2015
Sometimes there is a choice of which flows include a particular match.
2016
For example, suppose that we added an extra constraint to our example,
2017
to match on \fBip_src\fR \[mo] {\fIa\fR,\fIb\fR,\fIc\fR,\fId\fR} and
2018
\fBip_dst\fR \[mo] {\fIe\fR,\fIf\fR,\fIg\fR,\fIh\fR} and \fBtcp_dst\fR
2019
= \fIi\fR. One way to implement this is to add the new constraint to
2020
the \fBconj_id\fR flow, like this:
2023
\fBconj_id=1234,tcp,tcp_dst=\fIi\fB actions=mod_nw_src:1.2.3.4,controller\fR
2027
\fIbut this is not recommended\fR because of the cost of the extra
2028
flow table lookup. Instead, add the constraint to the individual
2029
flows, either in one of the dimensions or (slightly better) all of
2032
A conjunctive match must have \fIn\fR \[>=] 2 dimensions (otherwise a
2033
conjunctive match is not necessary). Open vSwitch enforces this.
2035
Each dimension within a conjunctive match should ordinarily have more
2036
than one flow. Open vSwitch does not enforce this.
2039
The \fBconjunction\fR action and \fBconj_id\fR field were introduced
2040
in Open vSwitch 2.4.
1870
2220
a live port or group.
2223
.IP \fBcommand_bucket_id=\fIid\fR
2224
The bucket to operate on. The \fBinsert-buckets\fR and \fBremove-buckets\fR
2225
commands require this field. It is prohibited for other commands.
2226
\fIid\fR may be an integer or one of the following keywords:
2229
Operate on all buckets in the group.
2230
Only valid when used with the \fBremove-buckets\fR command in which
2231
case the effect is to remove all buckets from the group.
2233
Operate on the first bucket present in the group.
2234
In the case of the \fBinsert-buckets\fR command the effect is to
2235
insert new bucets just before the first bucket already present in the group;
2236
or to replace the buckets of the group if there are no buckets already present
2238
In the case of the \fBremove-buckets\fR command the effect is to
2239
remove the first bucket of the group; or do nothing if there are no
2240
buckets present in the group.
2242
Operate on the last bucket present in the group.
2243
In the case of the \fBinsert-buckets\fR command the effect is to
2244
insert new bucets just after the last bucket already present in the group;
2245
or to replace the buckets of the group if there are no buckets already present
2247
In the case of the \fBremove-buckets\fR command the effect is to
2248
remove the last bucket of the group; or do nothing if there are no
2249
buckets present in the group.
2252
If \fIid\fR is an integer then it should correspond to the \fBbucket_id\fR
2253
of a bucket present in the group.
2254
In case of the \fBinsert-buckets\fR command the effect is to
2255
insert buckets just before the bucket in the group whose \fBbucket_id\fR is
2257
In case of the \fBiremove-buckets\fR command the effect is to
2258
remove the in the group whose \fBbucket_id\fR is \fIid\fR.
2259
It is an error if there is no bucket persent group in whose \fBbucket_id\fR is
2262
.IP \fBselection_method\fR=\fImethod\fR
2263
The selection method used to select a bucket for a select group.
2264
This is a string of 1 to 15 bytes in length known to lower layers.
2265
This field is optional for \fBadd\-group\fR, \fBadd\-groups\fR and
2266
\fBmod\-group\fR commands on groups of type \fBselect\fR. Prohibited
2267
otherwise. The default value is the empty string.
2269
This option will use a Netronome OpenFlow extension which is only supported
2270
when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later.
2272
.IP \fBselection_method_param\fR=\fIparam\fR
2273
64-bit integer parameter to the selection method selected by the
2274
\fBselection_method\fR field. The parameter's use is defined by the
2275
lower-layer that implements the \fBselection_method\fR. It is optional if
2276
the \fBselection_method\fR field is specified as a non-empty string.
2277
Prohibited otherwise. The default value is zero.
2279
This option will use a Netronome OpenFlow extension which is only supported
2280
when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later.
2282
.IP \fBfields\fR=\fIparam\fR
2283
The field parameters to selection method selected by the
2284
\fBselection_method\fR field. The syntax is described in \fBFlow Syntax\fR
2285
with the additional restrictions that if a value is provided it is
2286
treated as a wildcard mask and wildcard masks following a slash are
2287
prohibited. The pre-requisites of fields must be provided by any flows that
2288
output to the group. The use of the fields is defined by the lower-layer
2289
that implements the \fBselection_method\fR. They are optional if the
2290
\fBselection_method\fR field is specified as a non-empty string.
2291
Prohibited otherwise. The default is no fields.
2293
This option will use a Netronome OpenFlow extension which is only supported
2294
when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later.
1873
2296
.IP \fBbucket\fR=\fIbucket_parameters\fR
1874
2297
The \fBadd-group\fR, \fBadd-groups\fR and \fBmod-group\fR commands
1875
2298
require at least one bucket field. Bucket fields must appear after
added
removed
utilities/ovs-ofctl.8.in
