X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-ofctl.8.in;h=c43b48c7d654b8e503bd4278042b827c9700cda5;hb=b0a17866c3145fd35e844e1b66c499c55ecf6f1d;hp=609df9f2fcf1959855248beb78c9bf94612ea1d0;hpb=0f3f3c3db0a997ddb512bf9f0a9a1df7d5252f84;p=sliver-openvswitch.git diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in index 609df9f2f..c43b48c7d 100644 --- a/utilities/ovs-ofctl.8.in +++ b/utilities/ovs-ofctl.8.in @@ -190,6 +190,90 @@ 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 1.1+ Group Table Commands" +. +The following commands work only with switches that support OpenFlow +1.1 or later. Because support for OpenFlow 1.1 and later is still +experimental in Open vSwitch, it is necessary to explicitly enable +these protocol versions in \fBovs\-ofctl\fR (using \fB\-O\fR) and in +the switch itself (with the \fBprotocols\fR column in the \fBBridge\fR +table). For more information, see ``Q: What versions of OpenFlow does +Open vSwitch support?'' in the Open vSwitch FAQ. +. +.IP "\fBdump\-groups \fIswitch" +Prints to the console all group entries in \fIswitch\fR's tables. Each line +of output is a group entry as described in \fBGroup Syntax\fR below. +. +.IP "\fBdump\-group\-features \fIswitch" +Prints to the console the group features of the \fIswitch\fR. +. +.IP "\fBdump\-group-stats \fIswitch \fR[\fIgroups\fR]" +Prints to the console statistics for the specified \fIgroups in the +\fIswitch\fR's tables. If \fIgroups\fR is omitted then statistics for all +groups are printed. See \fBGroup Syntax\fR, below, for the syntax of +\fIgroups\fR. +. +.IP "\fBmod\-table \fIswitch\fR \fItable_id\fR \fIflow_miss_handling\fR" +An OpenFlow 1.0 switch looks up each packet that arrives at the switch +in table 0, then in table 1 if there is no match in table 0, then in +table 2, and so on until the packet finds a match in some table. +Finally, if no match was found, the switch sends the packet to the +controller +.IP +OpenFlow 1.1 and later offer more flexibility. This command +configures the flow table miss handling configuration for table +\fItable_id\fR in \fIswitch\fR. \fItable_id\fR may be an OpenFlow +table number between 0 and 254, inclusive, or the keyword \fBALL\fR to +modify all tables. \fIflow_miss_handling\fR may be any one of the +following: +.RS +.IP \fBdrop\fR +Drop the packet. +.IP \fBcontinue\fR +Continue to the next table in the pipeline. (This is how an OpenFlow +1.0 switch always handles packets that do not match any flow, in +tables other than the last one.) +.IP \fBcontroller\fR +Send to controller. (This is how an OpenFlow 1.0 switch always +handles packets that do not match any flow in the last table.) +.RE +. +.SS "OpenFlow 1.3+ Switch Meter Table Commands" +. +These commands manage the meter table in an OpenFlow switch. In each +case, \fImeter\fR specifies a meter entry in the format described in +\fBMeter Syntax\fR, below. +. +.PP +OpenFlow 1.3 introduced support for meters, so these commands only +work with switches that support OpenFlow 1.3 or later. The caveats +described for groups in the previous section also apply to meters. +. +.IP "\fBadd\-meter \fIswitch meter\fR" +Add a meter entry to \fIswitch\fR's tables. The \fImeter\fR syntax is +described in section \fBMeter Syntax\fR, below. +. +.IP "\fBmod\-meter \fIswitch meter\fR" +Modify an existing meter. +. +.IP "\fBdel\-meters \fIswitch\fR" +.IQ "\fBdel\-meter \fIswitch\fR [\fImeter\fR]" +Delete entries from \fIswitch\fR's meter table. \fImeter\fR can specify +a single meter with syntax \fBmeter=\fIid\fR, or all meters with syntax +\fBmeter=all\fR. +. +.IP "\fBdump\-meters \fIswitch\fR" +.IQ "\fBdump\-meter \fIswitch\fR [\fImeter\fR]" +Print meter configuration. \fImeter\fR can specify a single meter with +syntax \fBmeter=\fIid\fR, or all meters with syntax \fBmeter=all\fR. +. +.IP "\fBmeter\-stats \fIswitch\fR [\fImeter\fR]" +Print meter statistics. \fImeter\fR can specify a single meter with +syntax \fBmeter=\fIid\fR, or all meters with syntax \fBmeter=all\fR. +. +.IP "\fBmeter\-features \fIswitch\fR" +Print meter features. +. .SS "OpenFlow Switch Flow Table Commands" . These commands manage the flow table in an OpenFlow switch. In each @@ -258,6 +342,30 @@ keyword \fBLOCAL\fR (the preferred way to refer to the OpenFlow ``local'' port), or the keyword \fBNONE\fR to indicate that the packet was generated by the switch itself. . +.SS "OpenFlow Switch Group Table Commands" +. +These commands manage the group table in an OpenFlow switch. In each +case, \fIgroup\fR specifies a group entry in the format described in +\fBGroup Syntax\fR, below, and \fIfile\fR is a text file that contains +zero or more groups in the same syntax, one per line. + +.IP "\fBadd\-group \fIswitch group\fR" +.IQ "\fBadd\-group \fIswitch \fB\- < \fIfile\fR" +.IQ "\fBadd\-groups \fIswitch file\fR" +Add each group entry to \fIswitch\fR's tables. +. +.IP "\fBmod\-group \fIswitch group\fR" +.IQ "\fBmod\-group \fIswitch \fB\- < \fIfile\fR" +Modify the action buckets in entries from \fIswitch\fR's tables for +each group entry. +. +.IP "\fBdel\-groups \fIswitch\fR" +.IQ "\fBdel\-groups \fIswitch \fR[\fIgroup\fR]" +.IQ "\fBdel\-groups \fIswitch \fB\- < \fIfile\fR" +Deletes entries from \fIswitch\fR's group table. With only a +\fIswitch\fR argument, deletes all groups. Otherwise, deletes the group +for each group entry. +. .SS "OpenFlow Switch Monitoring Commands" . .IP "\fBsnoop \fIswitch\fR" @@ -370,6 +478,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 @@ -529,8 +645,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). @@ -540,7 +656,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 @@ -598,7 +714,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 @@ -651,6 +767,9 @@ 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. . @@ -775,6 +894,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 @@ -787,6 +917,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 @@ -801,6 +938,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. . @@ -928,20 +1068,17 @@ from the IP TTL (64 if the packet is not 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. +A limitation of the implementation is that processing of actions will stop +if \fBpush_mpls\fR follows another \fBpush_mpls\fR unless there is a +\fBpop_mpls\fR in between. . .IP \fBpop_mpls\fR:\fIethertype\fR -Strips the outermost MPLS label stack entry. If the MPLS label -stripped was the only one, changes the ethertype of a packet to -\fIethertype\fR, which should not ordinarily be an MPLS Ethertype. -. -.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. +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. A further limitation is that processing of +actions will stop if \fBpop_mpls\fR follows another \fBpop_mpls\fR unless +there is a \fBpush_mpls\fR in between. . .IP \fBmod_dl_src\fB:\fImac\fR Sets the source Ethernet address to \fImac\fR. @@ -956,15 +1093,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 @@ -1063,6 +1200,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 @@ -1070,7 +1224,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, @@ -1182,6 +1336,7 @@ For best performance, segregate learned flows into a table (using 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 . .RS .IP \fBapply_actions(\fR[\fIaction\fR][\fB,\fIaction\fR...]\fB) @@ -1199,9 +1354,14 @@ field will be replaced with the corresponding bit from \fIvalue\fR. Both \fIvalue\fR and \fImask\fR are 64-bit values that are decimal by default; use a \fB0x\fR prefix to specify them in hexadecimal. . +.IP \fBmeter\fR:\fImeter_id\fR +Apply the \fImeter_id\fR before any other actions. If a meter band rate is +exceeded, the packet may be dropped, or modified, depending on the meter +band type. See the description of the \fBMeter Table Commands\fR, above, +for more details. +. .IP \fBgoto_table\fR:\fItable\fR Indicates the next table in the process pipeline. -.RE . .IP "\fBfin_timeout(\fIargument\fR[\fB,\fIargument\fR]\fB)" This action changes the idle timeout or hard timeout, or both, of this @@ -1224,6 +1384,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 @@ -1326,7 +1510,7 @@ and \fBdel\-flows\fR commands support one additional optional field: .TP \fBout_port=\fIport\fR If set, a matching flow must include an output action to \fIport\fR, -which must an OpenFlow port number or name (e.g. \fBlocal\fR). +which must be an OpenFlow port number or name (e.g. \fBlocal\fR). . .SS "Table Entry Output" . @@ -1365,6 +1549,131 @@ of \fBduration\fR. (This is separate from \fBduration\fR because The integer number of seconds that have passed without any packets passing through the flow. . +.SS "Group Syntax" +.PP +Some \fBovs\-ofctl\fR commands accept an argument that describes a group or +groups. Such flow descriptions comprise a series +\fIfield\fB=\fIvalue\fR assignments, separated by commas or white +space. (Embedding spaces into a group description normally requires +quoting to prevent the shell from breaking the description into +multiple arguments.). Unless noted otherwise only the last instance +of each field is honoured. +.PP +.IP \fBgroup_id=\fIid\fR +The integer group id of group. +When this field is specified in \fBdel-groups\fR or \fBdump-groups\fR, +the keyword "all" may be used to designate all groups. +. +This field is required. + + +.IP \fBtype=\fItype\fR +The type of the group. This \fBadd-group\fR, \fBadd-groups\fR and +\fBdel-groups\fR command require this field. The following keywords +designated the allowed types: +.RS +.IP \fBall\fR +Execute all buckets in the group. +.IP \fBselect\fR +Execute one bucket in the group. +The switch should select the bucket in such a way that should implement +equal load sharing is achieved. The switch may optionally select the +bucket based on bucket weights. +.IP \fBindirect\fR +Executes the one bucket in the group. +.IP \fBff\fR +.IQ \fBfast_failover\fR +Executes the first live bucket in the group which is associated with +a live port or group. +.RE + +.IP \fBbucket\fR=\fIbucket_parameters\fR +The \fBadd-group\fR, \fBadd-groups\fR and \fBmod-group\fR commands +require at least one bucket field. Bucket fields must appear after +all other fields. +. +Multiple bucket fields to specify multiple buckets. +The order in which buckets are specified corresponds to their order in +the group. If the type of the group is "indirect" then only one group may +be specified. +. +\fIbucket_parameters\fR consists of a list of \fIfield\fB=\fIvalue\fR +assignments, separated by commas or white space followed by a +comma-separated list of actions. +The syntax of actions are same +to \fBactions=\fR field described in \fBFlow Syntax\fR above. +The fields for \fIbucket_parameters\fR are: +. +.RS +.IP \fBweight=\fIvalue\fR +The relative weight of the bucket as an integer. This may be used by the switch +during bucket select for groups whose \fBtype\fR is \fBselect\fR. +.IP \fBwatch_port=\fIport\fR +Port used to determine liveness of group. +This or the \fBwatch_group\fR field is required +for groups whose \fBtype\fR is \fBff\fR or \fBfast_failover\fR. +.IP \fBwatch_group=\fIgroup_id\fR +Group identifier of group used to determine liveness of group. +This or the \fBwatch_port\fR field is required +for groups whose \fBtype\fR is \fBff\fR or \fBfast_failover\fR. +.RE +. +.SS "Meter Syntax" +.PP +The meter table commands accept an argument that describes a meter. +Such meter descriptions comprise a series \fIfield\fB=\fIvalue\fR +assignments, separated by commas or white space. +(Embedding spaces into a group description normally requires +quoting to prevent the shell from breaking the description into +multiple arguments.). Unless noted otherwise only the last instance +of each field is honoured. +.PP +.IP \fBmeter=\fIid\fR +The integer meter id of the meter. +When this field is specified in \fBdel-meter\fR, \fBdump-meter\fR, or +\fBmeter-stats\fR, the keyword "all" may be used to designate all meters. +. +This field is required, exept for \fBmeter-stats\fR, which dumps all stats +when this field is not specified. + +.IP \fBkbps\fR +.IQ \fBpktps\fR +The unit for the meter band rate parameters, either kilobits per second, or +packets per second, respectively. One of these must be specified. The burst +size unit corresponds to the rate unit by dropping the "per second", i.e., +burst is in units of kilobits or packets, respectively. + +.IP \fBburst\fR +Specify burst size for all bands, or none of them, if this flag is not given. + +.IP \fBstats\fR +Collect meter and band statistics. + +.IP \fBbands\fR=\fIband_parameters\fR +The \fBadd-meter\fR and \fBmod-meter\fR commands require at least one +band specification. Bands must appear after all other fields. +.RS +.IP \fBtype=\fItype\fR +The type of the meter band. This keyword starts a new band specification. +Each band specifies a rate above which the band is to take some action. The +action depends on the band type. If multiple bands' rate is exceeded, then +the band with the highest rate among the exceeded bands is selected. +The following keywords designate the allowed +meter band types: +.RS +.IP \fBdrop\fR +Drop packets exceeding the band's rate limit. +.RE +. +.IP "The other \fIband_parameters\fR are:" +.IP \fBrate=\fIvalue\fR +The relative rate limit for this band, in kilobits per second or packets per +second, depending on the meter flags defined above. +.IP \fBburst_size=\fIport\fR +The maximum burst allowed for the band. If unspecified, the switch is free to +select some reasonable value depending on it's configuration. +.RE +. .SH OPTIONS .TP \fB\-\-strict\fR @@ -1477,7 +1786,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 @@ -1538,3 +1847,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)