X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-ofctl.8.in;h=c43b48c7d654b8e503bd4278042b827c9700cda5;hb=455ecd775d46f96fed8f307f44958a2a07ebcfff;hp=e66c6057086b875e0ed0c6778c4541f8083a7a45;hpb=799a91bb8002f30f36c7e90a49d82388d989af38;p=sliver-openvswitch.git diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in index e66c60570..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. . @@ -798,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 @@ -812,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. . @@ -939,21 +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. 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. +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. @@ -968,10 +1093,10 @@ 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, which must be a multiple of @@ -1099,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, @@ -1211,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) @@ -1228,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 @@ -1379,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" . @@ -1418,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 @@ -1530,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