X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-ofctl.8.in;h=f2ed8a48f7c767c416d448387e6763c0acf4fc64;hb=7f76372156020c305de539ef6b1ab13f8cb19de0;hp=c4fbed90bd212f27fb011e1afb27ba2fb0541dd9;hpb=2c6d841118a6b14cc5b03fc3b549143a6b7ce143;p=sliver-openvswitch.git diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in index c4fbed90b..f2ed8a48f 100644 --- a/utilities/ovs-ofctl.8.in +++ b/utilities/ovs-ofctl.8.in @@ -143,7 +143,7 @@ Deletes entries from \fIswitch\fR's flow table. With only a 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 @@ -151,6 +151,12 @@ 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 @@ -270,8 +276,13 @@ may be specified to explicitly mark any of these fields as a wildcard. (\fB*\fR should be quoted to protect it from shell expansion.) . .IP \fBin_port=\fIport_no\fR -Matches physical port \fIport_no\fR. Switch ports are numbered as +Matches OpenFlow port \fIport_no\fR. Ports are numbered as displayed by \fBovs\-ofctl show\fR. +.IP +(The \fBresubmit\fR action can search OpenFlow flow tables with +arbitrary \fBin_port\fR values, so flows that match port numbers that +do not exist from an OpenFlow perspective can still potentially be +matched.) . .IP \fBdl_vlan=\fIvlan\fR Matches IEEE 802.1q Virtual LAN tag \fIvlan\fR. Specify \fB0xffff\fR @@ -553,8 +564,8 @@ Finally, field assignments to \fBduration\fR, \fBn_packets\fR, or command to be used as input for other commands that parse flows. . .PP -The \fBadd\-flow\fR and \fBadd\-flows\fR commands require an additional -field, which must be the final field specified: +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 @@ -565,7 +576,14 @@ of the following keywords: . .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 @@ -596,6 +614,9 @@ omitted, then the entire packet is sent. Outputs the packet on the ``local port,'' which corresponds to the 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. If a drop action is used, no other actions may be specified. @@ -646,15 +667,21 @@ only known to be implemented by Open vSwitch: .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 @@ -674,7 +701,7 @@ 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. . -.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. @@ -687,12 +714,12 @@ entire field. 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. @@ -702,7 +729,7 @@ Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter, 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 @@ -714,7 +741,7 @@ Refer to \fBnicira\-ext.h\fR for more details. . .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 @@ -724,11 +751,98 @@ the normal bond selection logic will be used to choose the destination port. 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 -(The OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does -not yet expose to the user.) +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 +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 @@ -738,14 +852,15 @@ support an additional optional field: . 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 @@ -778,10 +893,6 @@ and \fBdel\-flows\fR commands support one additional optional field: \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: -. .SS "Table Entry Output" . The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information