\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
+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
\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
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"
+.SS "OpenFlow Switch Tunnel TLV Table Commands"
.
-Open vSwitch maintains a mapping table between Geneve options (defined
-by <class, type, length>) and an NXM field \fBtun_metadata\fIn\fR,
+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 mapping must be explicitly
-specified by the user through the following commands.
+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 Geneve option mapping is specified with the syntax
+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-geneve-map br0 "{class=0xffff,type=0,len=4}->tun_metadata0"
+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 Geneve mapping table is shared between all OpenFlow
+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\-geneve\-map \fIswitch option\fR[\fB,\fIoption\fR]..."
+.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\-geneve\-map \fIswitch \fR[\fIoption\fR[\fB,\fIoption\fR]]..."
-Delete each \fIoption\fR from \fIswitch\fR's table, or all Geneve option
+.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\-geneve\-map \fIswitch\fR"
+.IP "\fBdump\-tlv\-map \fIswitch\fR"
Show the currently mapped fields in the switch's option table as well
as switch capabilities.
.
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
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
simply match on an option being present.
.IP
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
+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,
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
-flow.
+connection.
.IP
The following flags describe the state of the tracking:
.RS
-.IP "\fB0x80: 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.
-.IP "\fB0x40: rpl\fR"
+.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 "\fB0x20: inv\fR"
+.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:
.PP
- Packets are unexpected length for protocol.
.RE
-.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 "\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
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]
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 is submitted to the connection
-tracker, but the pipeline does not fork and the ct match fields are not
-populated. It is strongly recommended to specify a table later than the current
-table to prevent loops.
+\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
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.
+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. These actions
-are in the same format as the actions accepted as part of a flow, however
-there are additional restrictions applied. For instance, only actions which
-modify the ct fields are accepted within the \fBexec\fR action. Furthermore,
-some actions may only be performed in this context, for instance modifying the
-ct_mark field:
+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
\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
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. 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.
+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
same IP message.
.IP
Currently, connection tracking is only available on Linux kernels with the
-nf_conntrack module loaded.
-.
-.RE
+nf_conntrack module loaded. The \fBct\fR action was introduced in Open vSwitch
+2.5.
.
.IP \fBdec_ttl\fR
.IQ \fBdec_ttl(\fIid1\fR[\fB,\fIid2\fR]...\fB)\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
.
.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