X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-ofctl.8.in;h=100faf023fea93342e566b0831130d1652ddf79b;hb=75a75043564dc9b002fffa6c6ad71e0d4d5c892e;hp=54d222a473ff04f8ff25e2f89e2d248ea813250f;hpb=4e312e694f1e9e34ed0aad7d5778b73d7add270d;p=sliver-openvswitch.git diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in index 54d222a47..100faf023 100644 --- a/utilities/ovs-ofctl.8.in +++ b/utilities/ovs-ofctl.8.in @@ -4,7 +4,7 @@ . ns . IP "\\$1" .. -.TH ovs\-ofctl 8 "January 2010" "Open vSwitch" "Open vSwitch Manual" +.TH ovs\-ofctl 8 "January 2011" "Open vSwitch" "Open vSwitch Manual" .ds PN ovs\-ofctl . .SH NAME @@ -54,13 +54,6 @@ Prints to the console information on \fIswitch\fR, including information on its flow tables and ports. . .TP -\fBstatus \fIswitch\fR [\fIkey\fR] -Prints to the console a series of key-value pairs that report the -status of \fIswitch\fR. If \fIkey\fR is specified, only the key-value -pairs whose key names begin with \fIkey\fR are printed. If \fIkey\fR is -omitted, all key-value pairs are printed. -. -.TP \fBdump\-tables \fIswitch\fR Prints to the console statistics for each of the flow tables used by \fIswitch\fR. @@ -115,33 +108,75 @@ the statistics are aggregated across all flows in the switch's flow tables. See \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR. The output format is descrbed in \fBTable Entry Output\fR. . -.TP -\fBadd\-flow \fIswitch flow\fR -Add the flow entry as described by \fIflow\fR to the \fIswitch\fR's -tables. The flow entry is in the format described in \fBFlow Syntax\fR, -below. -. -.TP -\fBadd\-flows \fIswitch file\fR -Add flow entries as described in \fIfile\fR to \fIswitch\fR's -tables. Each line in \fIfile\fR is a flow entry in the format -described in \fBFlow Syntax\fR, below. +.IP "\fBqueue\-stats \fIswitch \fR[\fIport \fR[\fIqueue\fR]]" +Prints to the console statistics for the specified \fIqueue\fR on +\fIport\fR within \fIswitch\fR. Either of \fIport\fR or \fIqueue\fR +or both may be omitted (or equivalently specified as \fBALL\fR). If +both are omitted, statistics are printed for all queues on all ports. +If only \fIqueue\fR is omitted, then statistics are printed for all +queues on \fIport\fR; if only \fIport\fR is omitted, then statistics +are printed for \fIqueue\fR on every port where it exists. +. +.SS "OpenFlow Switch Flow Table Commands" +. +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" +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" +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" +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" +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 +\fIswitch\fR, deleting flows from \fIswitch\fR that are not in +\fIfile\fR, and updating flows in \fIswitch\fR whose actions, cookie, +or timeouts differ in \fIfile\fR. . -.TP -\fBmod\-flows \fIswitch flow\fR -Modify the actions in entries from the \fIswitch\fR's tables -that match \fIflow\fR. When invoked with the \fB\-\-strict\fR option, -wildcards are not treated as active for matching purposes. See -\fBFlow Syntax\fR, below, for the syntax of \fIflows\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 +is printed preceded by a \fB\-\fR, and a flow that is in \fIsource2\fR +but not in \fIsource1\fR is printed preceded by a \fB+\fR. If a flow +exists in both \fIsource1\fR and \fIsource2\fR with different actions, +cookie, or timeouts, then both versions are printed preceded by +\fB\-\fR and \fB+\fR, respectively. +.IP +\fIsource1\fR and \fIsource2\fR may each name a file or a switch. If +a name begins with \fB/\fR or \fB.\fR, then it is considered to be a +file name. A name that contains \fB:\fR is considered to be a switch. +Otherwise, it is a file if a file by that name exists, a switch if +not. +.IP +For this command, an exit status of 0 means that no differences were +found, 1 means that an error occurred, and 2 means that some +differences were found. . -.TP -\fBdel\-flows \fIswitch \fR[\fIflow\fR] -Deletes entries from the \fIswitch\fR's tables that match -\fIflow\fR. When invoked with the \fB\-\-strict\fR option, wildcards are -not treated as active for matching purposes. If \fIflow\fR is -omitted and the \fB\-\-strict\fR option is not used, all flows in the -switch's tables are removed. See \fBFlow Syntax\fR, below, for the -syntax of \fIflows\fR. +.SS "OpenFlow Switch Monitoring Commands" . .IP "\fBsnoop \fIswitch\fR" Connects to \fIswitch\fR and prints to the console all OpenFlow @@ -168,11 +203,10 @@ If a switch has no controller configured, or if the configured controller is disconnected, no traffic is sent, so monitoring will not show any traffic. . -.IQ "\fBmonitor \fIswitch\fR [\fImiss-len\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 @@ -262,6 +296,26 @@ Matches an Ethernet source (or destination) address specified as 6 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 @@ -290,24 +344,31 @@ or 0x0806, the values of \fBnw_src\fR and \fBnw_dst\fR are ignored .IP \fBnw_proto=\fIproto\fR When \fBip\fR or \fBdl_type=0x0800\fR is specified, matches IP protocol type \fIproto\fR, which is specified as a decimal number -between 0 and 255, inclusive (e.g. 6 to match TCP packets). +between 0 and 255, inclusive (e.g. 1 to match ICMP packets or 6 to match +TCP packets). +.IP +When \fBipv6\fR or \fBdl_type=0x86dd\fR is specified, matches IPv6 +header type \fIproto\fR, which is specified as a decimal number between +0 and 255, inclusive (e.g. 58 to match ICMPv6 packets or 6 to match +TCP). The header type is the terminal header as described in the +\fBDESIGN\fR document. .IP When \fBarp\fR or \fBdl_type=0x0806\fR is specified, matches the lower 8 bits of the ARP opcode. ARP opcodes greater than 255 are treated as 0. .IP -When \fBdl_type\fR is wildcarded or set to a value other than 0x0800 -or 0x0806, the value of \fBnw_proto\fR is ignored (see \fBFlow +When \fBdl_type\fR is wildcarded or set to a value other than 0x0800, +0x0806, or 0x86dd, the value of \fBnw_proto\fR is ignored (see \fBFlow Syntax\fR above). . .IP \fBnw_tos=\fItos\fR -Matches IP ToS/DSCP field \fItos\fR, which is specified as a decimal -number between 0 and 255, inclusive. Note that the two lower reserved -bits are ignored for matching purposes. +Matches IP ToS/DSCP or IPv6 traffic class field \fItos\fR, which is +specified as a decimal number between 0 and 255, inclusive. Note that +the two lower reserved bits are ignored for matching purposes. .IP -The value of \fBnw_proto\fR is ignored unless \fBdl_type=0x0800\fR, -\fBip\fR, \fBicmp\fR, \fBtcp\fR, or \fBudp\fR is also specified (see -\fBFlow Syntax\fR above). +When \fBdl_type\fR is wildcarded or set to a value other than 0x0800, +0x0806, or 0x86dd, the value of \fBnw_tos\fR is ignored (see \fBFlow +Syntax\fR above). . .IP \fBtp_src=\fIport\fR .IQ \fBtp_dst=\fIport\fR @@ -322,13 +383,32 @@ these settings are ignored (see \fBFlow Syntax\fR above). . .IP \fBicmp_type=\fItype\fR .IQ \fBicmp_code=\fIcode\fR -When \fBdl_type\fR and \fBnw_proto\fR specify ICMP, \fItype\fR matches -the ICMP type and \fIcode\fR matches the ICMP code. Each is specified -as a decimal number between 0 and 255, inclusive. +When \fBdl_type\fR and \fBnw_proto\fR specify ICMP or ICMPv6, \fItype\fR +matches the ICMP type and \fIcode\fR matches the ICMP code. Each is +specified as a decimal number between 0 and 255, inclusive. .IP 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: . @@ -348,8 +428,139 @@ Same as \fBdl_type=0x0800,nw_proto=17\fR. Same as \fBdl_type=0x0806\fR. . .PP -The \fBadd\-flow\fR and \fBadd\-flows\fR commands require an additional -field, which must be the final field specified: +The following field assignments require support for the NXM (Nicira +Extended Match) extension to OpenFlow. When one of these is specified, +\fBovs\-ofctl\fR will automatically attempt to negotiate use of this +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 +the source and target hardware address, respectively. An address is +specified as 6 pairs of hexadecimal digits delimited by colons. +. +.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 +or \fBtcp6\fR), matches IPv6 source (or destination) address \fIipv6\fR, +which may be specified as defined in RFC 2373. The preferred format is +\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fR, where +\fIx\fR are the hexadecimal values of the eight 16-bit pieces of the +address. A single instance of \fB::\fR may be used to indicate multiple +groups of 16-bits of zeros. The optional \fInetmask\fR allows +restricting a match to an IPv6 address prefix. A netmask is specified +as a CIDR block (e.g. \fB2001:db8:3c4d:1::/64\fR). +. +.IP \fBnd_target=\fIipv6\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 +\fBipv6_src\fR and \fBipv6_dst\fR fields. +. +.IP \fBnd_sll=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR +When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify IPv6 +Neighbor Solicitation (ICMPv6 type 135), matches the source link\-layer +address option. An address is specified as 6 pairs of hexadecimal +digits delimited by colons. +. +.IP \fBnd_tll=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR +When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify IPv6 +Neighbor Advertisement (ICMPv6 type 136), matches the target link\-layer +address option. An address is specified as 6 pairs of hexadecimal +digits delimited by colons. +. +.IP \fBtun_id=\fItunnel-id\fR[\fB/\fImask\fR] +Matches tunnel identifier \fItunnel-id\fR. Only packets that arrive +over a tunnel that carries a key (e.g. GRE with the RFC 2890 key +extension) will have a nonzero tunnel ID. If \fImask\fR is omitted, +\fItunnel-id\fR is the exact tunnel ID to match; if \fImask\fR is +specified, then a 1-bit in \fImask\fR indicates that the corresponding +bit in \fItunnel-id\fR must match exactly, and a 0-bit wildcards that +bit. +.IP +In an attempt to be compatible with more switches, \fBovs\-ofctl\fR will +prefer to use the ``tunnel ID from cookie'' Nicira extension to NXM. +The use of this extension comes with three caveats: the top 32 bits of +the \fBcookie\fR (see below) are used for \fItunnel-id\fR and thus +unavailable for other use, specifying \fBtun_id\fR on \fBdump\-flows\fR +or \fBdump\-aggregate\fR has no effect, and \fImask\fR is not supported. +If any of these caveats apply, \fBovs-ofctl\fR will use NXM. +. +.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 +the switch. \fIvalue\fR and \fImask\fR are 32-bit integers, by +default in decimal (use a \fB0x\fR prefix to specify hexadecimal). +Arbitrary \fImask\fR values are allowed: a 1-bit in \fImask\fR +indicates that the corresponding bit in \fIvalue\fR must match +exactly, and a 0-bit wildcards that bit. +.IP +When a packet enters an OpenFlow switch, all of the registers are set +to 0. Only explicit Nicira extension actions change register values. +. +.PP +Defining IPv6 flows (those with \fBdl_type\fR equal to 0x86dd) requires +support for NXM. The following shorthand notations are available for +IPv6-related flows: +. +.IP \fBipv6\fR +Same as \fBdl_type=0x86dd\fR. +. +.IP \fBtcp6\fR +Same as \fBdl_type=0x86dd,nw_proto=6\fR. +. +.IP \fBudp6\fR +Same as \fBdl_type=0x86dd,nw_proto=17\fR. +. +.IP \fBicmp6\fR +Same as \fBdl_type=0x86dd,nw_proto=58\fR. +. +.PP +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 @@ -360,7 +571,19 @@ 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 +\fIport\fR. The number of supported queues depends on the switch; +some OpenFlow implementations do not support queuing at all. . .IP \fBnormal\fR Subjects the packet to the device's normal L2/L3 processing. (This @@ -384,8 +607,10 @@ omitted, then the entire packet is sent. . .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. @@ -437,20 +662,182 @@ 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 -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. +.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 \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 \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 +OpenFlow implementations do not support queuing at all. +. +.IP \fBpop_queue\fR +Restores the queue to the value it was before any \fBset_queue\fR +actions were applied. +. +.IP \fBnote:\fR[\fIhh\fR]... +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" +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. +Each \fIstart\fR and \fIend\fR pair, which are inclusive, must specify +the same number of bits and must fit within its respective field. +Shorthands for \fB[\fIstart\fB..\fIend\fB]\fR exist: use +\fB[\fIbit\fB]\fR to specify a single bit or \fB[]\fR to specify an +entire field. +.IP +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 +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 \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. +. +.IP "\fBmultipath(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIn_links\fB, \fIarg\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR" +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 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, +\fBhash_threshold\fR, \fBhrw\fR, and \fBiter_hash\fR. Only +the \fBiter_hash\fR algorithm uses \fIarg\fR. +.IP +Refer to \fBnicira\-ext.h\fR for more details. . -.RE +.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 field as +described above. +.IP +Currently, \fIid\fR should be the OpenFlow port number of an interface on the +bridge. If it isn't then \fIdst\fB[\fIstart\fB..\fIend\fB]\fR will be +populated with the OpenFlow port "none". If \fIid\fR is a member of a bond, +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. +. +.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 +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 OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does -not yet expose to the user.) +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 @@ -460,11 +847,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 \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBdel\-flows\fR commands -support an additional optional field: +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 do not allow priority to be specified. . .IP \fBpriority=\fIvalue\fR The priority at which a wildcarded entry will match in comparison to @@ -481,8 +872,8 @@ optional fields: .TP \fBidle_timeout=\fIseconds\fR Causes the flow to expire after the given number of seconds of -inactivity. A value of 0 prevents a flow from expiring due to -inactivity. The default is 60 seconds. +inactivity. A value of 0 (the default) prevents a flow from expiring due to +inactivity. . .IP \fBhard_timeout=\fIseconds\fR Causes the flow to expire after the given number of seconds, @@ -497,18 +888,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: -. -.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 @@ -543,6 +922,38 @@ described in \fBFlow Syntax\fR, above. \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: +.RS +.IP "\fBopenflow10\fR" +This is the standard OpenFlow 1.0 flow format. It should be supported +by all OpenFlow switches. +. +.IP "\fBnxm\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 +registers. +.RE +.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. +. +.IP "\fB\-m\fR" +.IQ "\fB\-\-more\fR" +Increases the verbosity of OpenFlow messages printed and logged by +\fBovs\-ofctl\fR commands. Specify this option more than once to +increase verbosity further. .SS "Public Key Infrastructure Options" .so lib/ssl.man .so lib/vlog.man @@ -550,19 +961,16 @@ Uses strict matching when running flow modification commands. . .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"