entries that match the specified flows. With \fB\-\-strict\fR,
wildcards are not treated as active for matching purposes.
.
-.IP "\fBreplace\-flows \fIswitch file\fR"
+.IP "[\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
\fIfile\fR, and updating flows in \fIswitch\fR whose actions, cookie,
or timeouts differ in \fIfile\fR.
.
+.IP
+With \fB\-\-readd\fR, \fBovs\-ofctl\fR adds all the flows from
+\fIfile\fR, even those that exist with the same actions, cookie, and
+timeout in \fIswitch\fR. This resets all the flow packet and byte
+counters to 0, which can be useful for debugging.
+.
.IP "\fBdiff\-flows \fIsource1 source2\fR"
Reads flow entries from \fIsource1\fR and \fIsource2\fR and prints the
differences. A flow that is in \fIsource1\fR but not in \fIsource2\fR
.
.IP "\fBmonitor \fIswitch\fR [\fImiss-len\fR]"
Connects to \fIswitch\fR and prints to the console all OpenFlow
-messages received. Usually, \fIswitch\fR should specify a connection
-named on \fBovs\-openflowd\fR(8)'s \fB\-l\fR or \fB\-\-listen\fR command line
-option.
+messages received. Usually, \fIswitch\fR should specify the name of a
+bridge in the \fBovs\-vswitchd\fR database.
.IP
If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set
configuration'' message at connection setup time that requests
pairs of hexadecimal digits delimited by colons
(e.g. \fB00:0A:E4:25:6B:B0\fR).
.
+.IP \fBdl_dst=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB/\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
+Matches an Ethernet destination address 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. Only
+the following masks are allowed:
+.RS
+.IP \fB01:00:00:00:00:00\fR
+Match only the multicast bit. Thus,
+\fBdl_dst=01:00:00:00:00:00/01:00:00:00:00:00\fR matches all multicast
+(including broadcast) Ethernet packets, and
+\fBdl_dst=00:00:00:00:00:00/01:00:00:00:00:00\fR matches all unicast
+Ethernet packets.
+.IP \fBfe:ff:ff:ff:ff:ff\fR
+Match all bits except the multicast bit. This is probably not useful.
+.IP \fBff:ff:ff:ff:ff:ff\fR
+Exact match (equivalent to omitting the mask).
+.IP \fB00:00:00:00:00:00\fR
+Wildcard all bits (equivalent to \fBdl_dst=*\fR.)
+.RE
+.
.IP \fBdl_type=\fIethertype\fR
Matches Ethernet protocol type \fIethertype\fR, which is specified as an
integer between 0 and 65535, inclusive, either in decimal or as a
When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of
these settings are ignored (see \fBFlow Syntax\fR above).
.
+.IP \fBtable=\fInumber\fR
+If specified, limits the flow manipulation and flow dump commands to
+only apply to the table with the given \fInumber\fR.
+\fInumber\fR is a number between 0 and 254, inclusive.
+.
+Behavior varies if \fBtable\fR is not specified. For flow table
+modification commands without \fB\-\-strict\fR, the switch will choose
+the table for these commands to operate on. For flow table
+modification commands with \fB\-\-strict\fR, the command will operate
+on any single matching flow in any table; it will do nothing if there
+are matches in more than one table. The \fBdump-flows\fR and
+\fBdump-aggregate\fR commands will gather statistics about flows from
+all tables.
+.IP
+When this field is specified in \fBadd-flow\fR, \fBadd-flows\fR,
+\fBmod-flows\fR and \fBdel-flows\fR commands, it activates a Nicira
+extension to OpenFlow, which as of this writing is only known to be
+implemented by Open vSwitch.
+.
.PP
The following shorthand notations are also available:
.
extension. If the switch does not support NXM, then \fBovs\-ofctl\fR
will report a fatal error.
.
+.IP \fBvlan_tci=\fItci\fR[\fB/\fImask\fR]
+Matches modified VLAN TCI \fItci\fR. If \fImask\fR is omitted,
+\fItci\fR is the exact VLAN TCI to match; if \fImask\fR is specified,
+then a 1-bit in \fItci\fR indicates that the corresponding bit in
+\fItci\fR must match exactly, and a 0-bit wildcards that bit. Both
+\fItci\fR and \fImask\fR are 16-bit values that are decimal by
+default; use a \fB0x\fR prefix to specify them in hexadecimal.
+.
+.IP
+The value that \fBvlan_tci\fR matches against is 0 for a packet that
+has no 802.1Q header. Otherwise, it is the TCI value from the 802.1Q
+header with the CFI bit (with value \fB0x1000\fR) forced to 1.
+.IP
+Examples:
+.RS
+.IP \fBvlan_tci=0\fR
+Match only packets without an 802.1Q header.
+.IP \fBvlan_tci=0xf123\fR
+Match packets tagged with priority 7 in VLAN 0x123.
+.IP \fBvlan_tci=0x1123/0x1fff\fR
+Match packets tagged with VLAN 0x123 (and any priority).
+.IP \fBvlan_tci=0x5000/0xf000\fR
+Match packets tagged with priority 2 (in any VLAN).
+.IP \fBvlan_tci=0/0xfff\fR
+Match packets with no 802.1Q header or tagged with VLAN 0 (and any
+priority).
+.IP \fBvlan_tci=0x5000/0xe000\fR
+Match packets with no 802.1Q header or tagged with priority 2 (in any
+VLAN).
+.IP \fBvlan_tci=0/0xefff\fR
+Match packets with no 802.1Q header or tagged with VLAN 0 and priority
+0.
+.RE
+.IP
+Some of these matching possibilities can also be achieved with
+\fBdl_vlan\fR and \fBdl_vlan_pcp\fR.
+.
.IP \fBarp_sha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
.IQ \fBarp_tha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
When \fBdl_type\fR specifies ARP, \fBarp_sha\fR and \fBarp_tha\fR match
Same as \fBdl_type=0x86dd,nw_proto=58\fR.
.
.PP
-The \fBadd\-flow\fR and \fBadd\-flows\fR commands require an additional
-field, which must be the final field specified:
+Finally, field assignments to \fBduration\fR, \fBn_packets\fR, or
+\fBn_bytes\fR are ignored to allow output from the \fBdump\-flows\fR
+command to be used as input for other commands that parse flows.
+.
+.PP
+The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands
+require an additional field, which must be the final field specified:
.
.IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR
Specifies a comma-separated list of actions to take on a packet when the
.
.RS
.IP \fBoutput\fR:\fIport\fR
-Outputs the packet on the port specified by \fIport\fR.
+.IQ \fBoutput\fR:\fIsrc\fB[\fIstart\fB..\fIend\fB]
+Outputs the packet. If \fIport\fR is an OpenFlow port number, outputs directly
+to it. Otherwise, outputs to the OpenFlow port number read from \fIsrc\fR
+which must be an NXM field as described above. Outputting to an NXM field is
+an OpenFlow extension which is not supported by standard OpenFlow switches.
+.IP
+Example: \fBoutput:NXM_NX_REG0[16..31]\fR outputs to the OpenFlow port number
+written in the upper half of register 0.
.
.IP \fBenqueue\fR:\fIport\fB:\fIqueue\fR
Enqueues the packet on the specified \fIqueue\fR within port
.
.IP \fBlocal\fR
Outputs the packet on the ``local port,'' which corresponds to the
-\fBof\fIn\fR network device (see \fBCONTACTING THE CONTROLLER\fR in
-\fBovs\-openflowd\fR(8) for information on the \fBof\fIn\fR network device).
+network device that has the same name as the bridge.
+.
+.IP \fBin_port\fR
+Outputs the packet on the port from which it was received.
.
.IP \fBdrop\fR
Discards the packet, so no further processing or forwarding takes place.
.RS
.
.IP \fBresubmit\fB:\fIport\fR
-Re-searches the OpenFlow flow table with the \fBin_port\fR field
-replaced by \fIport\fR and executes the actions found, if any, in
-addition to any other actions in this flow entry. Recursive
-\fBresubmit\fR actions are ignored.
+.IQ \fBresubmit\fB(\fR[\fIport\fR]\fB,\fR[\fItable\fR]\fB)
+Re-searches this OpenFlow flow table (or the table whose number is
+specified by \fItable\fR) with the \fBin_port\fR field replaced by
+\fIport\fR (if \fIport\fR is specified) and executes the actions
+found, if any, in addition to any other actions in this flow entry.
+.IP
+Recursive \fBresubmit\fR actions are obeyed up to an
+implementation-defined maximum depth. Open vSwitch 1.0.1 and earlier
+did not support recursion; Open vSwitch before 1.2.90 did not support
+\fItable\fR.
.
.IP \fBset_tunnel\fB:\fIid\fR
.IQ \fBset_tunnel64\fB:\fIid\fR
If outputting to a port that encapsulates the packet in a tunnel and
-supports an identifier (such as GRE), sets the identifier to \fBid\fR.
+supports an identifier (such as GRE), sets the identifier to \fIid\fR.
If the \fBset_tunnel\fR form is used and \fIid\fR fits in 32 bits,
then this uses an action extension that is supported by Open vSwitch
1.0 and later. Otherwise, if \fIid\fR is a 64-bit value, it requires
Open vSwitch 1.1 or later.
.
-.IP \fBdrop_spoofed_arp\fR
-Stops processing further actions, if the packet being processed is an
-Ethernet+IPv4 ARP packet for which the source Ethernet address inside
-the ARP packet differs from the source Ethernet address in the
-Ethernet header.
-.IP
-This action is deprecated in favor of defining flows using the
-\fBarp_sha\fR match field described earlier and will likely be removed
-in a future version of Open vSwitch.
-.
.IP \fBset_queue\fB:\fIqueue\fR
Sets the queue that should be used to \fIqueue\fR when packets are
output. The number of supported queues depends on the switch; some
\fIhh\fR may be included. Pairs of hex digits may be separated by
periods for readability.
.
-.IP "\fBmove:\fIsrc\fB[\fIstart\fB..\fIend\fB]->\fIdst\fB[\fIstart\fB..\fIend\fB]\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.
\fIsrc\fR and \fIdst\fR must be NXM field names as defined in
\fBnicira\-ext.h\fR, e.g. \fBNXM_OF_UDP_SRC\fR or \fBNXM_NX_REG0\fR.
Examples: \fBmove:NXM_NX_REG0[0..5]\->NXM_NX_REG1[26..31]\fR copies the
six bits numbered 0 through 5, inclusive, in register 0 into bits 26
through 31, inclusive;
-\fBmove:NXM_NX_REG0[0..15]->NXM_OF_VLAN_TCI[]\fR copies the least
+\fBmove:NXM_NX_REG0[0..15]\->NXM_OF_VLAN_TCI[]\fR copies the least
significant 16 bits of register 0 into the VLAN TCI field.
.
.IP "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]"
Writes \fIvalue\fR to bits \fIstart\fR through \fIend\fR, inclusive,
-in field \fBdst\fR.
+in field \fIdst\fR.
.IP
Example: \fBload:55\->NXM_NX_REG2[0..5]\fR loads value 55 (bit pattern
\fB110111\fR) into bits 0 through 5, inclusive, in register 2.
then the applies multipath link selection \fIalgorithm\fR (with
parameter \fIarg\fR) to choose one of \fIn_links\fR output links
numbered 0 through \fIn_links\fR minus 1, and stores the link into
-\fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM register as
+\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
.
.IP "\fBautopath(\fIid\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR"
Given \fIid\fR, chooses an OpenFlow port and populates it in
-\fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM register as
+\fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as
described above.
.IP
Currently, \fIid\fR should be the OpenFlow port number of an interface on the
Otherwise, the register will be populated with \fIid\fR itself.
.IP
Refer to \fBnicira\-ext.h\fR for more details.
-.RE
.
+.IP "\fBbundle(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, slaves:[\fIs1\fB, \fIs2\fB, ...])\fR"
+Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter, then
+applies the bundle link selection \fIalgorithm\fR to choose one of the listed
+slaves represented as \fIslave_type\fR. Currently the only supported
+\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.
.IP
-(The OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does
-not yet expose to the user.)
+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
+Random Weight algorithm.
+.IP
+Refer to \fBnicira\-ext.h\fR for more details.
+.
+.IP "\fBbundle_load(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, \fIdst\fB[\fIstart\fB..\fIend\fB], slaves:[\fIs1\fB, \fIs2\fB, ...])\fR"
+Has the same behavior as the \fBbundle\fR action, with one exception. Instead
+of outputting to the selected slave, it writes its selection to
+\fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as described
+above.
+.IP
+Example: \fBbundle_load(eth_src, 0, hrw, ofport, NXM_NX_REG0[],
+slaves:4, 8)\fR uses an Ethernet source hash with basis 0, to select
+between OpenFlow ports 4 and 8 using the Highest Random Weight
+algorithm, and writes the selection to \fBNXM_NX_REG0[]\fR.
+.IP
+Refer to \fBnicira\-ext.h\fR for more details.
+.
+.IP "\fBlearn(\fIargument\fR[\fB,\fIargument\fR]...\fB)\fR"
+This action adds or modifies a flow in an OpenFlow table, similar to
+\fBovs\-ofctl \-\-strict mod\-flows\fR. The arguments specify the
+flow's match fields, actions, and other properties, as follows. At
+least one match criterion and one action argument should ordinarily be
+specified.
+.RS
+.IP \fBidle_timeout=\fIseconds\fR
+.IQ \fBhard_timeout=\fIseconds\fR
+.IQ \fBpriority=\fIvalue\fR
+These key-value pairs have the same meaning as in the usual
+\fBovs\-ofctl\fR flow syntax.
+.
+.IP \fBtable=\fInumber\fR
+The table in which the new flow should be inserted. Specify a decimal
+number between 0 and 254. The default, if \fBtable\fR is unspecified,
+is table 1.
+.
+.IP \fIfield\fB=\fIvalue\fR
+.IQ \fIfield\fB[\fIstart\fB..\fIend\fB]=\fIsrc\fB[\fIstart\fB..\fIend\fB]\fR
+.IQ \fIfield\fB[\fIstart\fB..\fIend\fB]\fR
+Adds a match criterion to the new flow.
+.IP
+The first form specifies that \fIfield\fR must match the literal
+\fIvalue\fR, e.g. \fBdl_type=0x0800\fR. All of the fields and values
+for \fBovs\-ofctl\fR flow syntax are available with their usual
+meanings.
+.IP
+The second form specifies that \fIfield\fB[\fIstart\fB..\fIend\fB]\fR
+in the new flow must match \fIsrc\fB[\fIstart\fB..\fIend\fB]\fR taken
+from the flow currently being processed.
+.IP
+The third form is a shorthand for the second form. It specifies that
+\fIfield\fB[\fIstart\fB..\fIend\fB]\fR in the new flow must match
+\fIfield\fB[\fIstart\fB..\fIend\fB]\fR taken from the flow currently
+being processed.
+.
+.IP \fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]
+.IQ \fBload:\fIsrc\fB[\fIstart\fB..\fIend\fB]\->\fIdst\fB[\fIstart\fB..\fIend\fB]
+.
+Adds a \fBload\fR action to the new flow.
+.IP
+The first form loads the literal \fIvalue\fR into bits \fIstart\fR
+through \fIend\fR, inclusive, in field \fIdst\fR. Its syntax is the
+same as the \fBload\fR action described earlier in this section.
+.IP
+The second form loads \fIsrc\fB[\fIstart\fB..\fIend\fB]\fR, a value
+from the flow currently being processed, into bits \fIstart\fR
+through \fIend\fR, inclusive, in field \fIdst\fR.
+.
+.IP \fBoutput:\fIfield\fB[\fIstart\fB..\fIend\fB]\fR
+Add an \fBoutput\fR action to the new flow's actions, that outputs to
+the OpenFlow port taken from \fIfield\fB[\fIstart\fB..\fIend\fB]\fR,
+which must be an NXM field as described above.
+.RE
+.IP
+For best performance, segregate learned flows into a table (using
+\fBtable=\fInumber\fR) that is not used for any other flows except
+possibly for a lowest-priority ``catch-all'' flow, that is, a flow
+with no match criteria. (This is why the default \fBtable\fR is 1, to
+keep the learned flows separate from the primary flow table 0.)
+.RE
.
.PP
The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands
.
A cookie is an opaque identifier that can be associated with the flow.
\fIvalue\fR can be any 64-bit number and need not be unique among
-flows.
+flows. If this field is omitted, these commands set a default cookie
+value of 0.
.
.PP
The following additional field sets the priority for flows added by
the \fBadd\-flow\fR and \fBadd\-flows\fR commands. For
\fBmod\-flows\fR and \fBdel\-flows\fR when \fB\-\-strict\fR is
specified, priority must match along with the rest of the flow
-specification. Other commands ignore the priority value.
+specification. Other commands do not allow priority to be specified.
.
.IP \fBpriority=\fIvalue\fR
The priority at which a wildcarded entry will match in comparison to
\fBout_port=\fIport\fR
If set, a matching flow must include an output action to \fIport\fR.
.
-.PP
-The \fBdump\-flows\fR and \fBdump\-aggregate\fR commands support an
-additional optional field:
-.
-.IP \fBtable=\fInumber\fR
-If specified, limits the flows about which statistics are gathered to
-those in the table with the given \fInumber\fR. Tables are numbered
-as shown by the \fBdump\-tables\fR command.
-.
-If this field is not specified, or if \fInumber\fR is given as
-\fB255\fR, statistics are gathered about flows from all tables.
-.
.SS "Table Entry Output"
.
The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information
.
.SH EXAMPLES
.
-The following examples assume that an OpenFlow switch on the local
-host has been configured to listen for management connections on a
-Unix domain socket named \fB@RUNDIR@/openflow.sock\fR, e.g. by
-specifying \fB\-\-listen=punix:@RUNDIR@/openflow.sock\fR on the
-\fBovs\-openflowd\fR(8) command line.
+The following examples assume that \fBovs\-vswitchd\fR has a bridge
+named \fBbr0\fR configured.
.
.TP
-\fBovs\-ofctl dump\-tables unix:@RUNDIR@/openflow.sock\fR
+\fBovs\-ofctl dump\-tables br0\fR
Prints out the switch's table stats. (This is more interesting after
some traffic has passed through.)
.
.TP
-\fBovs\-ofctl dump\-flows unix:@RUNDIR@/openflow.sock\fR
+\fBovs\-ofctl dump\-flows br0\fR
Prints the flow entries in the switch.
.
.SH "SEE ALSO"
git://git.onelab.eu / sliver-openvswitch.git / blobdiff