\fBdump\-table\-features \fIswitch\fR
Prints to the console features for each of the flow tables used by
\fIswitch\fR.
-.
-.IP "\fBmod\-table \fIswitch\fR \fItable_id\fR \fIflow_miss_handling\fR"
-An OpenFlow 1.0 switch looks up each packet that arrives at the switch
-in table 0, then in table 1 if there is no match in table 0, then in
-table 2, and so on until the packet finds a match in some table.
-Finally, if no match was found, the switch sends the packet to the
-controller
-.IP
-OpenFlow 1.1 and later offer more flexibility. This command
-configures the flow table miss handling configuration for table
-\fItable_id\fR in \fIswitch\fR. \fItable_id\fR may be an OpenFlow
-table number between 0 and 254, inclusive, or the keyword \fBALL\fR to
-modify all tables. \fIflow_miss_handling\fR may be any one of the
-following:
+.TP
+\fBdump\-table\-desc \fIswitch\fR
+Prints to the console configuration for each of the flow tables used
+by \fIswitch\fR for OpenFlow 1.4+.
+.IP "\fBmod\-table \fIswitch\fR \fItable_id\fR \fIsetting\fR"
+This command configures flow table settings for OpenFlow table
+\fItable_id\fR within \fIswitch\fR. The available settings depend on
+the OpenFlow version in use. In OpenFlow 1.1 and 1.2 (which must be
+enabled with the \fB\-O\fR option) only, \fBmod\-table\fR configures
+behavior when no flow is found when a packet is looked up in a flow
+table. The following \fIsetting\fR values are available:
.RS
.IP \fBdrop\fR
Drop the packet.
Send to controller. (This is how an OpenFlow 1.0 switch always
handles packets that do not match any flow in the last table.)
.RE
+.IP
+In OpenFlow 1.4 and later (which must be enabled with the \fB\-O\fR
+option) only, \fBmod\-table\fR configures the behavior when a
+controller attempts to add a flow to a flow table that is full. The
+following \fIsetting\fR values are available:
+.RS
+.IP \fBevict\fR
+Delete some existing flow from the flow table, according to the
+algorithm described for the \fBFlow_Table\fR table in
+\fBovs-vswitchd.conf.db\fR(5).
+.IP \fBnoevict\fR
+Refuse to add the new flow. (Eviction might still be enabled through
+the \fBoverflow_policy\fR oclumn in the \fBFlow_Table\fR table
+documented in \fBovs-vswitchd.conf.db\fR(5).)
+.RE
.
.TP
\fBdump\-ports \fIswitch\fR [\fInetdev\fR]
.
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
If no \fIcommand_bucket_id\fR is present in the group specification then all
buckets of the group are removed.
.
+.SS "OpenFlow Switch Geneve Option Table Commands"
+.
+In order to work with Geneve options, it is necessary to maintain a mapping
+table between an option (defined by <class, type, length>) and an NXM field
+that can be operated on for the purposes of matches, actions, etc. This
+mapping must be explicitly specified by the user through the following
+commands. The format for \fIoptions\fR is given in \fBOption Syntax\fR below.
+
+Note that a given mapping should not be changed while it is in active use by
+a flow. The result of doing so is undefined.
+
+Currently, the Geneve mapping table is shared between all OpenFlow
+switches in a given instance of Open vSwitch. This restriction will
+be lifted in the future to allow for easier management.
+
+These commands are Nicira extensions to OpenFlow and require Open vSwitch
+2.5 or later.
+
+.IP "\fBadd\-geneve\-map \fIswitch options\fR"
+Add each option entry to \fIswitch\fR's tables. Duplicate fields are
+rejected.
+.
+.IP "\fBdel\-geneve\-map \fIswitch \fR[\fIoptions\fR]"
+Delete each option entry in \fIswitch\fR's tables based on its field index.
+Fields that aren't already mapped will be ignored. If no options are
+specified then the entire table will be cleared.
+.
+.IP "\fBdump\-geneve\-map \fIswitch\fR"
+Show the currently mapped fields in the switch's option table as well
+as switch capabilities.
+.
+.IP "\fBOption Syntax\fR"
+\fB{class=\fIclass\fB,type=\fItype\fB,len=\fIlength\fB}->tun_metadata\fIn\fR
+
+An option can be specified in this form (repeating as necessary and
+separated by commas). For example, the follow is used to map a new option:
+
+.RS
+add-geneve-map br0 "{class=0xffff,type=0,len=4}->tun_metadata0"
+.RE
+.
.SS "OpenFlow Switch Monitoring Commands"
.
.IP "\fBsnoop \fIswitch\fR"
(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 "\fBtun_metadata\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]"
+Matches \fIvalue\fR either exactly or with optional \fImask\fR in
+tunnel metadata field number \fIidx\fR (numbered from 0 to 63).
+Tunnel metadata fields can be dynamically assigned onto the data
+contained in the options of Geneve packets using the commands
+described in the section \fBOpenFlow Switch Geneve Option Table
+Commands\fR. Once assigned, the length of the field is variable
+according to the size of the option. Before updating a mapping in
+the option table, flows with references to it should be removed,
+otherwise the result is non-deterministic.
+.IP
+These fields were introduced in Open vSwitch 2.5.
+.
.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
.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
\fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as
described above.
.IP
-Currently, \fIfields\fR must be either \fBeth_src\fR or
-\fBsymmetric_l4\fR and \fIalgorithm\fR must be one of \fBmodulo_n\fR,
+\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.
+.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
\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 or \fBsymmetric_l4\fR and
-\fIalgorithm\fR must be one of \fBhrw\fR and \fBactive_backup\fR.
+Currently, \fIfields\fR must be either \fBeth_src\fR, \fBsymmetric_l4\fR, \fBsymmetric_l3l4\fR, or \fBsymmetric_l3l4+udp\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
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.)
+A flow with \fBconjunction\fR actions may also include \fBnote\fR
+actions for annotations, but not any other kind of actions. (They
+would not be useful because they would never be executed.)
.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
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