\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 column in the \fBFlow_Table\fR table
+documented in \fBovs-vswitchd.conf.db\fR(5).)
+.IP \fBvacancy:\fIlow\fB,\fIhigh\fR
+Enables sending vacancy events to controllers using \fBTABLE_STATUS\fR
+messages, based on percentage thresholds \fIlow\fR and \fIhigh\fR.
+.IP \fBnovacancy\fR
+Disables vacancy events.
+.RE
.
.TP
\fBdump\-ports \fIswitch\fR [\fInetdev\fR]
\fIport\fR is omitted, then statistics are printed for \fIqueue\fR on
every port where it exists.
.
+.IP "\fBqueue\-get\-config \fIswitch [\fIport \fR[\fIqueue\fR]]"
+Prints to the console the configuration of \fIqueue\fR on \fIport\fR
+in \fIswitch\fR. If \fIport\fR is omitted or \fBANY\fR, reports
+queues for all port. If \fIqueue\fR is omitted or \fBANY\fR, reports
+all queues. For OpenFlow 1.3 and earlier, the output always includes
+all queues, ignoring \fIqueue\fR if specified.
+.IP
+This command has limited usefulness, because ports often have no
+configured queues and because the OpenFlow protocol provides only very
+limited information about the configuration of a queue.
+.
.SS "OpenFlow 1.1+ Group Table Commands"
.
The following commands work only with switches that support OpenFlow
.
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 Tunnel TLV Table Commands"
+.
+Open vSwitch maintains a mapping table between tunnel option TLVs (defined
+by <class, type, length>) and NXM fields \fBtun_metadata\fIn\fR,
+where \fIn\fR ranges from 0 to 63, that can be operated on for the
+purposes of matches, actions, etc. This TLV table can be used for
+Geneve option TLVs or other protocols with options in same TLV format
+as Geneve options. This mapping must be explicitly specified by the user
+through the following commands.
+
+A TLV mapping is specified with the syntax
+\fB{class=\fIclass\fB,type=\fItype\fB,len=\fIlength\fB}->tun_metadata\fIn\fR.
+When an option mapping exists for a given \fBtun_metadata\fIn\fR,
+matching on the defined field becomes possible, e.g.:
+
+.RS
+ovs-ofctl add-tlv-map br0 "{class=0xffff,type=0,len=4}->tun_metadata0"
+.PP
+ovs-ofctl add-flow br0 tun_metadata0=1234,actions=controller
+.RE
+
+A mapping should not be changed while it is in active
+use by a flow. The result of doing so is undefined.
+
+Currently, the TLV 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\-tlv\-map \fIswitch option\fR[\fB,\fIoption\fR]..."
+Add each \fIoption\fR to \fIswitch\fR's tables. Duplicate fields are
+rejected.
+.
+.IP "\fBdel\-tlv\-map \fIswitch \fR[\fIoption\fR[\fB,\fIoption\fR]]..."
+Delete each \fIoption\fR from \fIswitch\fR's table, or all option TLV
+mapping if no \fIoption\fR is specified.
+Fields that aren't mapped are ignored.
+.
+.IP "\fBdump\-tlv\-map \fIswitch\fR"
+Show the currently mapped fields in the switch's option table as well
+as switch capabilities.
+.
.SS "OpenFlow Switch Monitoring Commands"
.
.IP "\fBsnoop \fIswitch\fR"
messages received. Unlike other \fBovs\-ofctl\fR commands, if
\fIswitch\fR is the name of a bridge, then the \fBsnoop\fR command
connects to a Unix domain socket named
-\fB@RUNDIR@/\fIbridge\fB.snoop\fR. \fBovs\-vswitchd\fR listens on
+\fB@RUNDIR@/\fIswitch\fB.snoop\fR. \fBovs\-vswitchd\fR listens on
such a socket for each bridge and sends to it all of the OpenFlow
messages sent to or received from its configured OpenFlow controller.
Thus, this command can be used to view OpenFlow protocol activity
configuration'' message at connection setup time that requests
\fBINVALID_TTL_TO_CONTROLLER\fR, so that \fBovs\-ofctl monitor\fR can
receive ``packet-in'' messages when TTL reaches zero on \fBdec_ttl\fR action.
+Only OpenFlow 1.1 and 1.2 support \fBinvalid_ttl\fR; Open vSwitch also
+implements it for OpenFlow 1.0 as an extension.
.IP
\fBwatch:\fR[\fB\fIspec\fR...] causes \fBovs\-ofctl\fR to send a
``monitor request'' Nicira extension message to the switch at
.IP \fBip\fR
Same as \fBdl_type=0x0800\fR.
.
+.IP \fBipv6\fR
+Same as \fBdl_type=0x86dd\fR.
+.
.IP \fBicmp\fR
Same as \fBdl_type=0x0800,nw_proto=1\fR.
.
+.IP \fBicmp6\fR
+Same as \fBdl_type=0x86dd,nw_proto=58\fR.
+.
.IP \fBtcp\fR
Same as \fBdl_type=0x0800,nw_proto=6\fR.
.
+.IP \fBtcp6\fR
+Same as \fBdl_type=0x86dd,nw_proto=6\fR.
+.
.IP \fBudp\fR
Same as \fBdl_type=0x0800,nw_proto=17\fR.
.
+.IP \fBudp6\fR
+Same as \fBdl_type=0x86dd,nw_proto=17\fR.
+.
.IP \fBsctp\fR
Same as \fBdl_type=0x0800,nw_proto=132\fR.
.
+.IP \fBsctp6\fR
+Same as \fBdl_type=0x86dd,nw_proto=132\fR.
+.
.IP \fBarp\fR
Same as \fBdl_type=0x0806\fR.
.
.IP \fBrarp\fR
Same as \fBdl_type=0x8035\fR.
.
+.IP \fBmpls\fR
+Same as \fBdl_type=0x8847\fR.
+.
+.IP \fBmplsm\fR
+Same as \fBdl_type=0x8848\fR.
+.
.PP
The following field assignments require support for the NXM (Nicira
Extended Match) extension to OpenFlow. When one of these is specified,
address is specified as 6 pairs of hexadecimal digits delimited by colons
(e.g. \fB00:0A:E4:25:6B:B0\fR), with a wildcard mask following the slash.
.
-
+.IP \fBarp_op=\fIopcode\fR
+When \fBdl_type\fR specifies either ARP or RARP, \fBarp_op\fR matches the
+ARP opcode. Only ARP opcodes between 1 and 255 should be specified for
+matching.
+.
.IP \fBipv6_src=\fIipv6\fR[\fB/\fInetmask\fR]
.IQ \fBipv6_dst=\fIipv6\fR[\fB/\fInetmask\fR]
When \fBdl_type\fR is 0x86dd (possibly via shorthand, e.g., \fBipv6\fR
corresponding bit in \fItunnel-id\fR must match exactly, and a 0-bit
wildcards that bit.
.
+.IP \fBtun_flags=\fIflags\fR
+Matches flags indicating various aspects of the tunnel encapsulation. Currently,
+there is only one flag defined:
+.IP
+\fBoam\fR: The tunnel protocol indicated that this is an OAM control packet.
+.IP
+Flags can be prefixed by \fB+\fR or \fB-\fR to indicate that the flag should
+be matched as either present or not present, respectively. In addition, flags
+can be specified without a prefix and separated by \fB|\fR to indicate an exact
+match.
+.IP
+Note that it is possible for newer version of Open vSwitch to introduce
+additional flags with varying meaning. It is therefore not recommended to use
+an exact match on this field since the behavior of these new flags is unknown
+and should be ignored.
+.IP
+For non-tunneled packets, the value is 0.
+.IP
+This field was introduced in Open vSwitch 2.5.
+.
.IP \fBtun_src=\fIip\fR[\fB/\fInetmask\fR]
.IQ \fBtun_dst=\fIip\fR[\fB/\fInetmask\fR]
Matches tunnel IPv4 source (or destination) address \fIip\fR. Only packets
For more information, please see the corresponding IETF draft:
https://tools.ietf.org/html/draft-smith-vxlan-group-policy
.
+.IP "\fBtun_metadata\fIidx\fR[\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).
+The act of specifying a field implies a match on the existence
+of that field in the packet in addition to the masked value. As
+a shorthand, it is possible to specify only the field name to
+simply match on an option being present.
+.IP
+Tunnel metadata fields can be dynamically assigned onto the data
+contained in the option TLVs of packets (e.g. Geneve variable
+options stores zero or more options in TLV format and tunnel
+metadata can be assigned onto these option TLVs) using the
+commands described in the section \fBOpenFlow Switch Tunnel TLV 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
.IP
This field was introduced in Open vSwitch 2.4.
.
+.IP \fBct_state=\fIflags\fB/\fImask\fR
+.IQ \fBct_state=\fR[\fB+\fIflag\fR...][\fB-\fIflag\fR...]
+Bitwise match on connection state flags. This is used with the \fBct\fR
+action (see below).
+.IP
+The \fBct_state\fR field provides information from a connection tracking
+module. It describes whether the packet has previously traversed the
+connection tracker (tracked, or trk) and, if it has been tracked, any
+additional information that the connection tracker was able to provide about
+the connection that the current packet belongs to.
+.IP
+Individual packets may be in one of two states: Untracked or tracked. When the
+\fBct\fR action is executed on a packet, it becomes tracked for the the
+remainder of OpenFlow pipeline processing. Once a packet has become tracked,
+the state of its corresponding connection may be determined. Note that the
+\fBct_state\fR is only significant for the current \fBct_zone\fR.
+.IP
+Connections may be in one of two states: uncommitted or committed. Connections
+are uncommitted by default. To determine ongoing information about a
+connection, like whether the connection is established or not, the connection
+must be committed. When the \fBct\fR action is executed on a packet with the
+\fBcommit\fR parameter, the connection will become committed and will remain in
+this state until the end of the connection. Committed connections store state
+beyond the duration of packet processing.
+.IP
+The \fIflags\fR and \fImask\fR are 32-bit numbers written in decimal or
+in hexadecimal prefixed by \fB0x\fR. Each 1-bit in \fImask\fR requires
+that the corresponding bit in \fIflags\fR must match. Each 0-bit in
+\fImask\fR causes the corresponding bit to be ignored.
+.IP
+Alternatively, the flags can be specified by their symbolic names
+(listed below), each preceded by either \fB+\fR for a flag that must
+be set, or \fB\-\fR for a flag that must be unset, without any other
+delimiters between the flags. Flags not mentioned are wildcarded. For
+example, \fBtcp,ct_state=+trk\-new\fR matches TCP packets that
+have been run through the connection tracker and do not establish a new
+connection.
+.IP
+The following flags describe the state of the tracking:
+.RS
+.IP "\fB0x01: new\fR"
+This is the beginning of a new connection. This flag may only be present for
+uncommitted connections.
+.IP "\fB0x02: est\fR"
+This is part of an already existing connection. This flag may only be present
+for committed connections.
+.IP "\fB0x04: rel\fR"
+This is a connection that is related to an existing connection, for
+instance ICMP "destination unreachable" messages or FTP data connections. This
+flag may only be present for committed connections.
+.IP "\fB0x08: rpl\fR"
+The flow is in the reply direction, meaning it did not initiate the
+connection. This flag may only be present for committed connections.
+.IP "\fB0x10: inv\fR"
+The state is invalid, meaning that the connection tracker couldn't identify the
+connection. This flag is a catch-all for any problems that the connection
+tracker may have, for example:
+.RS
+.PP
+- L3/L4 protocol handler is not loaded/unavailable. With the Linux kernel
+datapath, this may mean that the "nf_conntrack_ipv4" or "nf_conntrack_ipv6"
+modules are not loaded.
+.PP
+- L3/L4 protocol handler determines that the packet is malformed.
+.PP
+- Packets are unexpected length for protocol.
+.RE
+.IP "\fB0x20: trk\fR"
+This packet is tracked, meaning that it has previously traversed the connection
+tracker. If this flag is not set, then no other flags will be set. If this flag
+is set, then the packet is tracked and other flags may also be set.
+.PP
+This field was introduced in Open vSwitch 2.5.
+.RE
+.
+.PP
+The following fields are associated with the connection tracker and will only
+be populated for tracked packets. The \fBct\fR action will populate these
+fields, and allows modification of some of the below fields.
+.IP \fBct_zone=\fIzone
+Matches the given 16-bit connection \fIzone\fR exactly. This represents the
+most recent connection tracking context that \fBct\fR was executed in. Each
+zone is an independent connection tracking context, so if you wish to track
+the same packet in multiple contexts then you must use the \fBct\fR action
+multiple times. Introduced in Open vSwitch 2.5.
+.
+.IP \fBct_mark=\fIvalue\fR[\fB/\fImask\fR]
+Matches the given 32-bit connection mark \fIvalue\fR either exactly or with
+optional \fImask\fR. This represents metadata associated with the connection
+that the current packet is part of. Introduced in Open vSwitch 2.5.
+.
+.IP \fBct_label=\fIvalue\fR[\fB/\fImask\fR]
+Matches the given 128-bit connection labels \fIvalue\fR either exactly or with
+optional \fImask\fR. This represents metadata associated with the connection
+that the current packet is part of. Introduced in Open vSwitch 2.5.
+.
.PP
Defining IPv6 flows (those with \fBdl_type\fR equal to 0x86dd) requires
support for NXM. The following shorthand notations are available for
Outputs the packet on the port from which it was received.
.
.IP \fBcontroller(\fIkey\fB=\fIvalue\fR...\fB)
-Sends the packet to the OpenFlow controller as a ``packet in''
+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"
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.
+.
.RE
.IP
-Any \fIreason\fR other than \fBaction\fR and any nonzero
-\fIcontroller-id\fR uses a Nicira vendor extension that, as of this
-writing, is only known to be implemented by Open vSwitch (version 1.6
-or later).
+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]
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 the Ethertype
+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.
Restores the queue to the value it was before any \fBset_queue\fR
actions were applied.
.
+.IP \fBct\fR
+.IQ \fBct\fB(\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. 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 \fBtable=\fInumber\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, with the \fBct_state\fR and other ct match fields set. If the
+\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->ct_mark\fR
+Store a 32-bit metadata value with the connection. If the connection is
+committed, then 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->ct_label\fR
+Store a 128-bit metadata value with the connection. If the connection is
+committed, then 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. Supported types include:
+.RS
+.IP \fBftp\fR
+Look for negotiation of FTP data connections. If a subsequent FTP data
+connection arrives which is related, the \fBct\fR action will set the
+\fBrel\fR flag in the \fBct_state\fR field for packets sent through \fBct\fR.
+.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).
+.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
+Currently, connection tracking is only available on Linux kernels with the
+nf_conntrack module loaded. The \fBct\fR action was introduced in Open vSwitch
+2.5.
+.
.IP \fBdec_ttl\fR
-.IQ \fBdec_ttl\fB[\fR(\fIid1,id2\fI)\fR]\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,
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. This action
-also optionally supports the ability to specify a list of valid
-controller ids. Each of controllers in the list will receive the
-``packet_in'' message only if they have registered to receive the
+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.
\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
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
+\fBtcp_src\fR < 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
.
.PP
The \fBdump\-flows\fR, \fBdump\-aggregate\fR, \fBdel\-flow\fR
-and \fBdel\-flows\fR commands support one additional optional field:
+and \fBdel\-flows\fR commands support these additional optional fields:
.
.TP
\fBout_port=\fIport\fR
If set, a matching flow must include an output action to \fIport\fR,
which must be an OpenFlow port number or name (e.g. \fBlocal\fR).
.
+.TP
+\fBout_group=\fIport\fR
+If set, a matching flow must include an \fBgroup\fR action naming
+\fIgroup\fR, which must be an OpenFlow group number. This field
+is supported in Open vSwitch 2.5 and later and requires OpenFlow 1.1
+or later.
+.
.SS "Table Entry Output"
.
The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information
\fBmod\-group\fR commands on groups of type \fBselect\fR. Prohibited
otherwise. The default value is the empty string.
.IP
+Other than the empty string, \fBhash\fR is currently the only defined
+selection method.
+.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.
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
+.IP \fBfields\fR=\fIfield\fR
+.IQ \fBfields(\fIfield\fR[\fB=\fImask\fR]\fR...\fB)\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
\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...]"
.
.IP "\fB\-P \fIformat\fR"
.IQ "\fB\-\-packet\-in\-format=\fIformat\fR"
-\fBovs\-ofctl\fR supports the following packet_in formats, in order of
+\fBovs\-ofctl\fR supports the following ``packet-in'' formats, in order of
increasing capability:
.RS
-.IP "\fBopenflow10\fR"
-This is the standard OpenFlow 1.0 packet in format. It should be supported by
-all OpenFlow switches.
-.
-.IP "\fBnxm\fR (Nicira Extended Match)"
-This packet_in format includes flow metadata encoded using the NXM format.
+.IP "\fBstandard\fR"
+This uses the \fBOFPT_PACKET_IN\fR message, the standard ``packet-in''
+message for any given OpenFlow version. Every OpenFlow switch that
+supports a given OpenFlow version supports this format.
+.
+.IP "\fBnxt_packet_in\fR"
+This uses the \fBNXT_PACKET_IN\fR message, which adds many of the
+capabilities of the OpenFlow 1.1 and later ``packet-in'' messages
+before those OpenFlow versions were available in Open vSwitch. Open
+vSwitch 1.1 and later support this format. Only Open vSwitch 2.6 and
+later, however, support it for OpenFlow 1.1 and later (but there is
+little reason to use it with those versions of OpenFlow).
+.
+.IP "\fBnxt_packet_in2\fR"
+This uses the \fBNXT_PACKET_IN2\fR message, which is extensible and
+should avoid the need to define new formats later. In particular,
+this format supports passing arbitrary user-provided data to a
+controller using the \fBuserdata\fB option on the \fBcontroller\fR
+action. Open vSwitch 2.6 and later support this format.
.
.RE
.IP
-Usually, \fBovs\-ofctl\fR prefers the \fBnxm\fR packet_in format, but will
-allow the switch to choose its default if \fBnxm\fR is unsupported. When
-\fIformat\fR is one of the formats listed in the above table, \fBovs\-ofctl\fR
-will insist on the selected format. If the switch does not support the
-requested format, \fBovs\-ofctl\fR will report a fatal error. This option only
-affects the \fBmonitor\fR command.
+Without this option, \fBovs\-ofctl\fR prefers \fBnxt_packet_in2\fR if
+the switch supports it. Otherwise, if OpenFlow 1.0 is in use,
+\fBovs\-ofctl\fR prefers \fBnxt_packet_in\fR if the switch supports
+it. Otherwise, \fBovs\-ofctl\fR falls back to the \fBstandard\fR
+packet-in format. When this option is specified, \fBovs\-ofctl\fR
+insists on the selected format. If the switch does not support the
+requested format, \fBovs\-ofctl\fR will report a fatal error.
+.IP
+Before version 2.6, Open vSwitch called \fBstandard\fR format
+\fBopenflow10\fR and \fBnxt_packet_in\fR format \fBnxm\fR, and
+\fBovs\-ofctl\fR still accepts these names as synonyms. (The name
+\fBopenflow10\fR was a misnomer because this format actually varies
+from one OpenFlow version to another; it is not consistently OpenFlow
+1.0 format. Similarly, when \fBnxt_packet_in2\fR was introduced, the
+name \fBnxm\fR became confusing because it also uses OXM/NXM.)
+.
+.IP
+This option affects only the \fBmonitor\fR command.
.
.IP "\fB\-\-timestamp\fR"
Print a timestamp before each received packet. This option only
projects / cascardo / ovs.git / blobdiff