ofproto-dpif: Introduce "internal flows" for handling flow table misses.

[openvswitch] / utilities / ovs-ofctl.8.in

diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in
index 8de6af947383bfc24e36bd1c1da312f91e7583ba..4f54208abd8102620c480549f241657b78cbe8d7 100644 (file)
--- a/utilities/ovs-ofctl.8.in
+++ b/utilities/ovs-ofctl.8.in
@@ -66,6 +66,12 @@ associated with that device will be printed.  \fInetdev\fR can be an
 OpenFlow assigned port number or device name, e.g. \fBeth0\fR.
 .
 .TP
 OpenFlow assigned port number or device name, e.g. \fBeth0\fR.
 .
 .TP

+\fBdump\-ports\-desc \fIswitch\fR
+Prints to the console detailed information about network devices
+associated with \fIswitch\fR (version 1.7 or later).  This is a subset
+of the information provided by the \fBshow\fR command.
+.
+.TP

 \fBmod\-port \fIswitch\fR \fInetdev\fR \fIaction\fR
 Modify characteristics of an interface monitored by \fIswitch\fR.  
 \fInetdev\fR can be referred to by its OpenFlow assigned port number or 
 \fBmod\-port \fIswitch\fR \fInetdev\fR \fIaction\fR
 Modify characteristics of an interface monitored by \fIswitch\fR.  
 \fInetdev\fR can be referred to by its OpenFlow assigned port number or 


@@ -654,7 +660,7 @@ as a CIDR block (e.g. \fB2001:db8:3c4d:1::/64\fR).
 When \fBdl_type\fR is 0x86dd (possibly via shorthand, e.g., \fBipv6\fR
 or \fBtcp6\fR), matches IPv6 flow label \fIlabel\fR.
 .
 When \fBdl_type\fR is 0x86dd (possibly via shorthand, e.g., \fBipv6\fR
 or \fBtcp6\fR), matches IPv6 flow label \fIlabel\fR.
 .

-.IP \fBnd_target=\fIipv6\fR
+.IP \fBnd_target=\fIipv6\fR[\fB/\fInetmask\fR]

 When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify
 IPv6 Neighbor Discovery (ICMPv6 type 135 or 136), matches the target address
 \fIipv6\fR.  \fIipv6\fR is in the same format described earlier for the
 When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify
 IPv6 Neighbor Discovery (ICMPv6 type 135 or 136), matches the target address
 \fIipv6\fR.  \fIipv6\fR is in the same format described earlier for the


@@ -756,11 +762,35 @@ tree protocol).
 Outputs the packet on all switch physical ports other than the port on
 which it was received.
 .
 Outputs the packet on all switch physical ports other than the port on
 which it was received.
 .

-.IP \fBcontroller\fR:\fImax_len\fR
+.IP \fBcontroller(\fIkey\fB=\fIvalue\fR...\fB)

 Sends the packet to the OpenFlow controller as a ``packet in''
 Sends the packet to the OpenFlow controller as a ``packet in''

-message.  If \fImax_len\fR is a number, then it specifies the maximum
-number of bytes that should be sent.  If \fImax_len\fR is \fBALL\fR or
-omitted, then the entire packet is sent.
+message.  The supported key-value pairs are:
+.RS
+.IP "\fBmax_len=\fInbytes\fR"
+Limit to \fInbytes\fR the number of bytes of the packet to send to
+the controller.  By default the entire packet is sent.
+.IP "\fBreason=\fIreason\fR"
+Specify \fIreason\fR as the reason for sending the message in the
+``packet in'' message.  The supported reasons are \fBaction\fR (the
+default), \fBno_match\fR, and \fBinvalid_ttl\fR.
+.IP "\fBid=\fIcontroller-id\fR"
+Specify \fIcontroller-id\fR, a 16-bit integer, as the connection ID of
+the OpenFlow controller or controllers to which the ``packet in''
+message should be sent.  The default is zero.  Zero is also the
+default connection ID for each controller connection, and a given
+controller connection will only have a nonzero connection ID if its
+controller uses the \fBNXT_SET_CONTROLLER_ID\fR Nicira extension to
+OpenFlow.
+.RE
+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).
+.
+.IP \fBcontroller\fR
+.IQ \fBcontroller\fR[\fB:\fInbytes\fR]
+Shorthand for \fBcontroller()\fR or
+\fBcontroller(max_len=\fInbytes\fB)\fR, respectively.

 .
 .IP \fBlocal\fR
 Outputs the packet on the ``local port,'' which corresponds to the
 .
 .IP \fBlocal\fR
 Outputs the packet on the ``local port,'' which corresponds to the


@@ -862,6 +892,10 @@ processing.
 Does nothing at all.  Any number of bytes represented as hex digits
 \fIhh\fR may be included.  Pairs of hex digits may be separated by
 periods for readability.
 Does nothing at all.  Any number of bytes represented as hex digits
 \fIhh\fR may be included.  Pairs of hex digits may be separated by
 periods for readability.

+The \fBnote\fR action's format doesn't include an exact length for its
+payload, so the provided bytes will be padded on the right by enough
+bytes with value 0 to make the total number 6 more than a multiple of
+8.

 .
 .IP "\fBmove:\fIsrc\fB[\fIstart\fB..\fIend\fB]\->\fIdst\fB[\fIstart\fB..\fIend\fB]\fR"
 Copies the named bits from field \fIsrc\fR to field \fIdst\fR.
 .
 .IP "\fBmove:\fIsrc\fB[\fIstart\fB..\fIend\fB]\->\fIdst\fB[\fIstart\fB..\fIend\fB]\fR"
 Copies the named bits from field \fIsrc\fR to field \fIdst\fR.


@@ -1074,6 +1108,13 @@ others.  \fIvalue\fR is a number between 0 and 65535, inclusive.  A higher
 have priority over an entry containing wildcards, so it has an implicit 
 priority value of 65535.  When adding a flow, if the field is not specified, 
 the flow's priority will default to 32768.
 have priority over an entry containing wildcards, so it has an implicit 
 priority value of 65535.  When adding a flow, if the field is not specified, 
 the flow's priority will default to 32768.

+.IP
+OpenFlow leaves behavior undefined when two or more flows with the
+same priority can match a single packet.  Some users expect
+``sensible'' behavior, such as more specific flows taking precedence
+over less specific flows, but OpenFlow does not specify this and Open
+vSwitch does not implement it.  Users should therefore take care to
+use priorities to ensure the behavior that they expect.

 .
 .PP
 The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands
 .
 .PP
 The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands


@@ -1153,33 +1194,55 @@ passing through the flow.
 \fB\-\-strict\fR
 Uses strict matching when running flow modification commands.
 .
 \fB\-\-strict\fR
 Uses strict matching when running flow modification commands.
 .

-.IP "\fB\-F \fIformat\fR"
-.IQ "\fB\-\-flow\-format=\fIformat\fR"
-\fBovs\-ofctl\fR supports the following flow formats, in order of
-increasing capability:
+.IP "\fB\-F \fIformat\fR[\fB,\fIformat\fR...]"
+.IQ "\fB\-\-flow\-format=\fIformat\fR[\fB,\fIformat\fR...]"
+\fBovs\-ofctl\fR supports the following individual flow formats, any
+number of which may be listed as \fIformat\fR:

 .RS
 .RS

-.IP "\fBopenflow10\fR"
-This is the standard OpenFlow 1.0 flow format.  It should be supported
-by all OpenFlow switches.
+.IP "\fBOpenFlow10\-table_id\fR"
+This is the standard OpenFlow 1.0 flow format.  All OpenFlow switches
+and all versions of Open vSwitch support this flow format.

 .
 .

-.IP "\fBnxm\fR (Nicira Extended Match)"
+.IP "\fBOpenFlow10+table_id\fR"
+This is the standard OpenFlow 1.0 flow format plus a Nicira extension
+that allows \fBovs\-ofctl\fR to specify the flow table in which a
+particular flow should be placed.  Open vSwitch 1.2 and later supports
+this flow format.
+.
+.IP "\fBNXM\-table_id\fR (Nicira Extended Match)"

 This Nicira extension to OpenFlow is flexible and extensible.  It
 supports all of the Nicira flow extensions, such as \fBtun_id\fR and
 This Nicira extension to OpenFlow is flexible and extensible.  It
 supports all of the Nicira flow extensions, such as \fBtun_id\fR and

-registers.
+registers.  Open vSwitch 1.1 and later supports this flow format.
+.
+.IP "\fBNXM+table_id\fR (Nicira Extended Match)"
+This combines Nicira Extended match with the ability to place a flow
+in a specific table.  Open vSwitch 1.2 and later supports this flow
+format.

 .RE
 .RE

+.

 .IP
 .IP

-Usually, \fBovs\-ofctl\fR picks the correct format automatically.  For
-commands that modify the flow table, \fBovs\-ofctl\fR by default uses
-the most widely supported flow format that supports the flows being
-added.  For commands that query the flow table, \fBovs\-ofctl\fR by
-default queries and uses the most advanced format supported by the
-switch.
-.IP
-This option, where \fIformat\fR is one of the formats listed in the
-above table, overrides \fBovs\-ofctl\fR's default choice of flow
-format.  If a command cannot work as requested using the requested
-flow format, \fBovs\-ofctl\fR will report a fatal error.
+\fBovs\-ofctl\fR also supports the following abbreviations for
+collections of flow formats:
+.RS
+.IP "\fBany\fR"
+Any supported flow format.
+.IP "\fBOpenFlow10\fR"
+\fBOpenFlow10\-table_id\fR or \fBOpenFlow10+table_id\fR.
+.IP "\fBNXM\fR"
+\fBNXM\-table_id\fR or \fBNXM+table_id\fR.
+.RE

 .
 .

+.IP
+For commands that modify the flow table, \fBovs\-ofctl\fR by default
+negotiates the most widely supported flow format that supports the
+flows being added.  For commands that query the flow table,
+\fBovs\-ofctl\fR by default uses the most advanced format supported by
+the switch.
+.IP
+This option, where \fIformat\fR is a comma-separated list of one or
+more of the formats listed above, limits \fBovs\-ofctl\fR's choice of
+flow format.  If a command cannot work as requested using one of the
+specified flow formats, \fBovs\-ofctl\fR will report a fatal error.

 .
 .IP "\fB\-P \fIformat\fR"
 .IQ "\fB\-\-packet\-in\-format=\fIformat\fR"
 .
 .IP "\fB\-P \fIformat\fR"
 .IQ "\fB\-\-packet\-in\-format=\fIformat\fR"


@@ -1202,6 +1265,10 @@ 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.
 .
 requested format, \fBovs\-ofctl\fR will report a fatal error.  This option only
 affects the \fBmonitor\fR command.
 .

+.IP "\fB\-\-timestamp\fR"
+Print a timestamp before each received packet.  This option only
+affects the \fBmonitor\fR and \fBsnoop\fR commands.
+.

 .IP "\fB\-m\fR"
 .IQ "\fB\-\-more\fR"
 Increases the verbosity of OpenFlow messages printed and logged by
 .IP "\fB\-m\fR"
 .IQ "\fB\-\-more\fR"
 Increases the verbosity of OpenFlow messages printed and logged by