X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-ofctl.8.in;h=85b2e44cad072b69407f8f257b90620b7d8aef42;hb=015ac88281952a1b43ad46e9e6300db1c6e3647b;hp=9ea09737bc276722537a3562aa17f8bd4b5a5e68;hpb=7a97619ae4484604c15b846ce7268094e048729a;p=sliver-openvswitch.git diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in index 9ea09737b..85b2e44ca 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 2011" "Open vSwitch" "Open vSwitch Manual" +.TH ovs\-ofctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" .ds PN ovs\-ofctl . .SH NAME @@ -20,6 +20,7 @@ The program is a command line tool for monitoring and administering OpenFlow switches. It can also show the current state of an OpenFlow switch, including features, configuration, and table entries. +It should work with any OpenFlow switch, not just Open vSwitch. . .SS "OpenFlow Switch Management Commands" .PP @@ -369,6 +370,14 @@ response. Reports the total time required. This is a measure of the maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte messages. . +.SS "Other Commands" +. +.IP "\fBofp\-parse\fR \fIfile\fR" +Reads \fIfile\fR (or \fBstdin\fR if \fIfile\fR is \fB\-\fR) as a +series of OpenFlow messages in the binary format used on an OpenFlow +connection, and prints them to the console. This can be useful for +printing OpenFlow messages captured from a TCP stream. +. .SS "Flow Syntax" .PP Some \fBovs\-ofctl\fR commands accept an argument that describes a flow or @@ -392,8 +401,8 @@ flows not in normal form. The following field assignments describe how a flow matches a packet. If any of these assignments is omitted from the flow syntax, the field is treated as a wildcard; thus, if all of them are omitted, the -resulting flow matches all packets. The string \fB*\fR or \fBANY\fR -may be specified to explicitly mark any of these fields as a wildcard. +resulting flow matches all packets. The string \fB*\fR 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\fR @@ -468,8 +477,12 @@ When \fBdl_type=0x0806\fR or \fBarp\fR is specified, matches the \fBar_spa\fR or \fBar_tpa\fR field, respectively, in ARP packets for IPv4 and Ethernet. .IP -When \fBdl_type\fR is wildcarded or set to a value other than 0x0800 -or 0x0806, the values of \fBnw_src\fR and \fBnw_dst\fR are ignored +When \fBdl_type=0x8035\fR or \fBrarp\fR is specified, matches the +\fBar_spa\fR or \fBar_tpa\fR field, respectively, in RARP packets for +IPv4 and Ethernet. +.IP +When \fBdl_type\fR is wildcarded or set to a value other than 0x0800, +0x0806, or 0x8035, the values of \fBnw_src\fR and \fBnw_dst\fR are ignored (see \fBFlow Syntax\fR above). . .IP \fBnw_proto=\fIproto\fR @@ -488,9 +501,13 @@ 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 \fBrarp\fR or \fBdl_type=0x8035\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, -0x0806, or 0x86dd, the value of \fBnw_proto\fR is ignored (see \fBFlow -Syntax\fR above). +0x0806, 0x8035 or 0x86dd, the value of \fBnw_proto\fR is ignored (see +\fBFlow Syntax\fR above). . .IP \fBnw_tos=\fItos\fR Matches IP ToS/DSCP or IPv6 traffic class field \fItos\fR, which is @@ -520,8 +537,8 @@ above). . .IP \fBtp_src=\fIport\fR .IQ \fBtp_dst=\fIport\fR -When \fBdl_type\fR and \fBnw_proto\fR specify TCP or UDP, \fBtp_src\fR -and \fBtp_dst\fR match the UDP or TCP source or destination port +When \fBdl_type\fR and \fBnw_proto\fR specify TCP or UDP or SCTP, \fBtp_src\fR +and \fBtp_dst\fR match the UDP or TCP or SCTP source or destination port \fIport\fR, respectively, which is specified as a decimal number between 0 and 65535, inclusive (e.g. 80 to match packets originating from a HTTP server). @@ -531,7 +548,7 @@ these settings are ignored (see \fBFlow Syntax\fR above). . .IP \fBtp_src=\fIport\fB/\fImask\fR .IQ \fBtp_dst=\fIport\fB/\fImask\fR -Bitwise match on TCP (or UDP) source or destination port, +Bitwise match on TCP (or UDP or SCTP) source or destination port, respectively. The \fIport\fR and \fImask\fR are 16-bit numbers written in decimal or in hexadecimal prefixed by \fB0x\fR. Each 1-bit in \fImask\fR requires that the corresponding bit in \fIport\fR must @@ -589,7 +606,7 @@ ports. .IP Like the exact-match forms of \fBtp_src\fR and \fBtp_dst\fR described above, the bitwise match forms apply only when \fBdl_type\fR and -\fBnw_proto\fR specify TCP or UDP. +\fBnw_proto\fR specify TCP or UDP or SCTP. . .IP \fBicmp_type=\fItype\fR .IQ \fBicmp_code=\fIcode\fR @@ -642,9 +659,15 @@ Same as \fBdl_type=0x0800,nw_proto=6\fR. .IP \fBudp\fR Same as \fBdl_type=0x0800,nw_proto=17\fR. . +.IP \fBsctp\fR +Same as \fBdl_type=0x0800,nw_proto=132\fR. +. .IP \fBarp\fR Same as \fBdl_type=0x0806\fR. . +.IP \fBrarp\fR +Same as \fBdl_type=0x8035\fR. +. .PP The following field assignments require support for the NXM (Nicira Extended Match) extension to OpenFlow. When one of these is specified, @@ -712,9 +735,9 @@ command, above, for more details. . .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. +When \fBdl_type\fR specifies either ARP or RARP, \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] @@ -763,6 +786,17 @@ 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 \fBtun_src=\fIip\fR[\fB/\fInetmask\fR] +.IQ \fBtun_dst=\fIip\fR[\fB/\fInetmask\fR] +Matches tunnel IPv4 source (or destination) address \fIip\fR. Only packets +that arrive over a tunnel will have nonzero tunnel addresses. +The address may be specified as an IP address or host name +(e.g. \fB192.168.1.1\fR or \fBwww.example.com\fR). The optional +\fInetmask\fR allows restricting a match to a masked IPv4 address. +The netmask may be specified as a dotted quad +(e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block +(e.g. \fB192.168.1.0/24\fR). +. .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 @@ -775,6 +809,13 @@ exactly, and a 0-bit wildcards that bit. When a packet enters an OpenFlow switch, all of the registers are set to 0. Only explicit Nicira extension actions change register values. . +.IP \fBpkt_mark=\fIvalue\fR[\fB/\fImask\fR] +Matches packet metadata mark \fIvalue\fR either exactly or with optional +\fImask\fR. The mark is associated data that may be passed into other +system components in order to facilitate interaction between subsystems. +On Linux this corresponds to the skb mark but the exact implementation is +platform-dependent. +. .PP Defining IPv6 flows (those with \fBdl_type\fR equal to 0x86dd) requires support for NXM. The following shorthand notations are available for @@ -789,6 +830,9 @@ Same as \fBdl_type=0x86dd,nw_proto=6\fR. .IP \fBudp6\fR Same as \fBdl_type=0x86dd,nw_proto=17\fR. . +.IP \fBsctp6\fR +Same as \fBdl_type=0x86dd,nw_proto=132\fR. +. .IP \fBicmp6\fR Same as \fBdl_type=0x86dd,nw_proto=58\fR. . @@ -903,6 +947,35 @@ for the tag. Only ethertype 0x8100 should be used. (0x88a8 which the spec allows isn't supported at the moment.) A priority of zero and the tag of zero are used for the new tag. . +.IP \fBpush_mpls\fR:\fIethertype\fR +If the packet does not already contain any MPLS labels, changes the +packet's Ethertype to \fIethertype\fR, which must be either the MPLS +unicast Ethertype \fB0x8847\fR or the MPLS multicast Ethertype +\fB0x8848\fR, and then pushes an initial label stack entry. The label +stack entry's default label is 2 if the packet contains IPv6 and 0 +otherwise, its default traffic control value is the low 3 bits of the +packet's DSCP value (0 if the packet is not IP), and its TTL is copied +from the IP TTL (64 if the packet is not IP). +.IP +If the packet does already contain an MPLS label, pushes a new +outermost label as a copy of the existing outermost label. +.IP +There are some limitations in the implementation. \fBpush_mpls\fR +followed by another \fBpush_mpls\fR will result in the first +\fBpush_mpls\fR being discarded. +. +.IP \fBpop_mpls\fR:\fIethertype\fR +Strips the outermost MPLS label stack entry. +Currently the implementation restricts \fIethertype\fR to a non-MPLS Ethertype +and thus \fBpop_mpls\fR should only be applied to packets with +an MPLS label stack depth of one. +. +.IP +There are some limitations in the implementation. \fBpop_mpls\fR +followed by another \fBpush_mpls\fR without an intermediate +\fBpush_mpls\fR will result in the first \fBpush_mpls\fR being +discarded. +. .IP \fBmod_dl_src\fB:\fImac\fR Sets the source Ethernet address to \fImac\fR. . @@ -916,15 +989,15 @@ Sets the IPv4 source address to \fIip\fR. Sets the IPv4 destination address to \fIip\fR. . .IP \fBmod_tp_src\fB:\fIport\fR -Sets the TCP or UDP source port to \fIport\fR. +Sets the TCP or UDP or SCTP source port to \fIport\fR. . .IP \fBmod_tp_dst\fB:\fIport\fR -Sets the TCP or UDP destination port to \fIport\fR. +Sets the TCP or UDP or SCTP destination port to \fIport\fR. . .IP \fBmod_nw_tos\fB:\fItos\fR -Sets the IPv4 ToS/DSCP field to \fItos\fR. Valid values are between 0 and -255, inclusive. Note that the two lower reserved bits are never -modified. +Sets the IPv4 ToS/DSCP field to \fItos\fR, which must be a multiple of +4 between 0 and 255. This action does not modify the two least +significant bits of the ToS field (the ECN bits). .RE .IP The following actions are Nicira vendor extensions that, as of this writing, are @@ -978,6 +1051,19 @@ invalid ttl packets. If controller ids are not specified, the ``packet_in'' message will be sent only to the controllers having controller id zero which have registered for the invalid ttl packets. . +.IP \fBset_mpls_ttl\fR:\fIttl\fR +Set the TTL of the outer MPLS label stack entry of a packet. +\fIttl\fR should be in the range 0 to 255 inclusive. +. +.IP \fBdec_mpls_ttl\fR +Decrement TTL of the outer MPLS label stack entry of a packet. If the TTL +is initially zero, no decrement occurs. Instead, a ``packet-in'' message +with reason code \fBOFPR_INVALID_TTL\fR is sent to each connected +controller with controller id zer that has enabled receiving them. +Processing the current set of actions then stops. However, if the current +set of actions was reached through ``resubmit'' then remaining actions in +outer levels resume processing. +. .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 @@ -1010,6 +1096,23 @@ in field \fIdst\fR. 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 "\fBpush:\fIsrc\fB[\fIstart\fB..\fIend\fB]" +Pushes \fIstart\fR to \fIend\fR bits inclusive, in fields +on top of the stack. +.IP +Example: \fBpush:NXM_NX_REG2[0..5]\fR push the value stored in register +2 bits 0 through 5, inclusive, on to the internal stack. +. +.IP "\fBpop:\fIdst\fB[\fIstart\fB..\fIend\fB]" +Pops from the top of the stack, retrieves the \fIstart\fR to \fIend\fR bits +inclusive, from the value popped and store them into the corresponding +bits in \fIdst\fR. +. +.IP +Example: \fBpop:NXM_NX_REG2[0..5]\fR pops the value from top of the stack. +Set register 2 bits 0 through 5, inclusive, based on bits 0 through 5 from the +value just popped. +. .IP "\fBset_field:\fIvalue\fB\->\fIdst" Writes the literal \fIvalue\fR into the field \fIdst\fR, which should be specified as a name used for matching. (This is similar to @@ -1017,7 +1120,7 @@ be specified as a name used for matching. (This is similar to Open Flow 1.2 and above.) . .IP -Example: \fBset_field:fe80:0123:4567:890a:a6ba:dbff:fefe:59fa\->ipv6_src\fR +Example: \fBset_field:00:11:22:33:44:55->eth_src\fR. . .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, @@ -1034,21 +1137,6 @@ the \fBiter_hash\fR algorithm uses \fIarg\fR. .IP Refer to \fBnicira\-ext.h\fR for more details. . -.IP "\fBautopath(\fIid\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR" -Deprecated and slated for removal in Feburary 2013. -.IP -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 @@ -1186,6 +1274,30 @@ flow's creation, not since the receipt of the FIN or RST.) .RE .IP This action was added in Open vSwitch 1.5.90. +. +.IP "\fBsample(\fIargument\fR[\fB,\fIargument\fR]...\fB)\fR" +Samples packets and sends one sample for every sampled packet. +.IP +\fIargument\fR takes the following forms: +.RS +.IP "\fBprobability=\fIpackets\fR" +The number of sampled packets out of 65535. Must be greater or equal to 1. +.IP "\fBcollector_set_id=\fIid\fR" +The unsigned 32-bit integer identifier of the set of sample collectors +to send sampled packets to. Defaults to 0. +.IP "\fBobs_domain_id=\fIid\fR" +When sending samples to IPFIX collectors, the unsigned 32-bit integer +Observation Domain ID sent in every IPFIX flow record. Defaults to 0. +.IP "\fBobs_point_id=\fIid\fR" +When sending samples to IPFIX collectors, the unsigned 32-bit integer +Observation Point ID sent in every IPFIX flow record. Defaults to 0. +.RE +.IP +Refer to \fBovs\-vswitchd.conf.db\fR(8) for more details on +configuring sample collector sets. +.IP +This action was added in Open vSwitch 1.10.90. +. .IP "\fBexit\fR" This action causes Open vSwitch to immediately halt execution of further actions. Those actions which have already been executed are unaffected. Any @@ -1332,6 +1444,8 @@ passing through the flow. \fB\-\-strict\fR Uses strict matching when running flow modification commands. . +.so lib/ofp-version.man +. .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 @@ -1356,6 +1470,11 @@ registers. Open vSwitch 1.1 and later supports this flow format. 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. +. +.IP "\fBOXM-OpenFlow12\fR" +.IQ "\fBOXM-OpenFlow13\fR" +These are the standard OXM (OpenFlow Extensible Match) flow format in +OpenFlow 1.2 and 1.3, respectively. .RE . .IP @@ -1368,6 +1487,8 @@ Any supported flow format. \fBOpenFlow10\-table_id\fR or \fBOpenFlow10+table_id\fR. .IP "\fBNXM\fR" \fBNXM\-table_id\fR or \fBNXM+table_id\fR. +.IP "\fBOXM\fR" +\fBOXM-OpenFlow12\fR or \fBOXM-OpenFlow13\fR. .RE . .IP @@ -1430,7 +1551,7 @@ A flow that does not specify any part of a field that is used for sorting is sorted after all the flows that do specify the field. For example, \fB\-\-sort=tcp_src\fR will sort all the flows that specify a TCP source port in ascending order, followed by the flows that do not -specify a TCP source port at all. +specify a TCP source port at all. .IP \(bu A flow that only specifies some bits in a field is sorted as if the wildcarded bits were zero. For example, \fB\-\-sort=nw_src\fR would @@ -1491,3 +1612,4 @@ Prints the flow entries in the switch. .BR ovs\-appctl (8), .BR ovs\-controller (8), .BR ovs\-vswitchd (8) +.BR ovs\-vswitchd.conf.db (8)