X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=utilities%2Fovs-ofctl.8.in;h=afd86c5607aa56959cf76a30dc4895bcdb71a0b5;hb=0c3d5fc89a341d31774f24ddaf7360a5ba4a641f;hp=45574b4df95bc01a1aaf40e7fa689c5f1bbbf19b;hpb=e729e7935e5c77eae1ca4a8040d05626f61cf9a2;p=sliver-openvswitch.git diff --git a/utilities/ovs-ofctl.8.in b/utilities/ovs-ofctl.8.in index 45574b4df..afd86c560 100644 --- a/utilities/ovs-ofctl.8.in +++ b/utilities/ovs-ofctl.8.in @@ -216,6 +216,15 @@ 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. . +.IP "\fBpacket\-out \fIswitch in_port actions packet\fR..." +Connects to \fIswitch\fR and instructs it to execute the OpenFlow +\fIactions\fR on each \fIpacket\fR. For the purpose of executing the +actions, the packets are considered to have arrived on \fIin_port\fR, +which may be an OpenFlow assigned port number, an OpenFlow port name +(e.g. \fBeth0\fR), the keyword \fBlocal\fR for the OpenFlow ``local'' +port \fBOFPP_LOCAL\fR, or the keyword \fBnone\fR to indicate that the +packet was generated by the switch itself. +. .SS "OpenFlow Switch Monitoring Commands" . .IP "\fBsnoop \fIswitch\fR" @@ -243,7 +252,7 @@ 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. . -.IP "\fBmonitor \fIswitch\fR [\fImiss-len\fR]" +.IP "\fBmonitor \fIswitch\fR [\fImiss-len\fR] [\fIinvalid_ttl\fR]" Connects to \fIswitch\fR and prints to the console all OpenFlow messages received. Usually, \fIswitch\fR should specify the name of a bridge in the \fBovs\-vswitchd\fR database. @@ -256,6 +265,13 @@ does not send these and other asynchronous messages to an specified on this argument. (Thus, if \fImiss\-len\fR is not specified, very little traffic will ordinarily be printed.) .IP +.IP +If \fBinvalid_ttl\fR is passed, \fBovs\-ofctl\fR sends an OpenFlow ``set +configuration'' message at connection setup time that requests +\fIINVALID_TTL_TO_CONTROLLER\fR, so that \fBovs\-ofctl monitor\fR can +receive ``packets-in'' messages when TTL reaches zero on \fBdec_ttl\fR action. +.IP + This command may be useful for debugging switch or controller implementations. . @@ -436,13 +452,75 @@ above). .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 -\fIport\fR, respectively. which is specified as a decimal number +\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). .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 \fBtp_src=\fIport\fB/\fImask\fR +.IQ \fBtp_dst=\fIport\fB/\fImask\fR +Bitwise match on TCP (or UDP) 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 +match. Each 0-bit in \fImask\fR causes the corresponding bit to be +ignored. +.IP +Bitwise matches on transport ports are rarely useful in isolation, but +a group of them can be used to reduce the number of flows required to +match on a range of transport ports. For example, suppose that the +goal is to match TCP source ports 1000 to 1999, inclusive. One way is +to insert 1000 flows, each of which matches on a single source port. +Another way is to look at the binary representations of 1000 and 1999, +as follows: +.br +.B "01111101000" +.br +.B "11111001111" +.br +and then to transform those into a series of bitwise matches that +accomplish the same results: +.br +.B "01111101xxx" +.br +.B "0111111xxxx" +.br +.B "10xxxxxxxxx" +.br +.B "110xxxxxxxx" +.br +.B "1110xxxxxxx" +.br +.B "11110xxxxxx" +.br +.B "1111100xxxx" +.br +which become the following when written in the syntax required by +\fBovs\-ofctl\fR: +.br +.B "tcp,tp_src=0x03e8/0xfff8" +.br +.B "tcp,tp_src=0x03f0/0xfff0" +.br +.B "tcp,tp_src=0x0400/0xfe00" +.br +.B "tcp,tp_src=0x0600/0xff00" +.br +.B "tcp,tp_src=0x0700/0xff80" +.br +.B "tcp,tp_src=0x0780/0xffc0" +.br +.B "tcp,tp_src=0x07c0/0xfff0" +.IP +Only Open vSwitch 1.6 and later supports bitwise matching on transport +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. +. .IP \fBicmp_type=\fItype\fR .IQ \fBicmp_code=\fIcode\fR When \fBdl_type\fR and \fBnw_proto\fR specify ICMP or ICMPv6, \fItype\fR @@ -737,7 +815,7 @@ Sets the TCP or UDP source port to \fIport\fR. Sets the TCP or UDP destination port to \fIport\fR. . .IP \fBmod_nw_tos\fB:\fItos\fR -Sets the IP ToS/DSCP field to \fItos\fR. Valid values are between 0 and +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. . @@ -778,6 +856,16 @@ OpenFlow implementations do not support queuing at all. Restores the queue to the value it was before any \fBset_queue\fR actions were applied. . +.IP \fBdec_ttl\fR +Decrement TTL of IPv4 packet or hop limit of IPv6 packet. If the +TTL or hop limit is initially zero, no decrement occurs. Instead, +a ``packet-in'' message with reason code \fBOFPR_INVALID_TTL\fR is +sent to each connected controller that has enabled receiving them, +if any. 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 @@ -955,7 +1043,11 @@ 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. +specification. For \fBmod\-flows\fR without \fB\-\-strict\fR, +priority is only significant if the command creates a new flow, that +is, non-strict \fBmod\-flows\fR does not match on priority and will +not change the priority of existing flows. 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 @@ -966,20 +1058,33 @@ priority value of 65535. When adding a flow, if the field is not specified, the flow's priority will default to 32768. . .PP -The \fBadd\-flow\fR and \fBadd\-flows\fR commands support additional -optional fields: +The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands +support the following additional options. These options affect only +new flows. Thus, for \fBadd\-flow\fR and \fBadd\-flows\fR, these +options are always significant, but for \fBmod\-flows\fR they are +significant only if the command creates a new flow, that is, their +values do not update or affect existing flows. . -.TP -\fBidle_timeout=\fIseconds\fR +.IP "\fBidle_timeout=\fIseconds\fR" Causes the flow to expire after the given number of seconds of -inactivity. A value of 0 (the default) prevents a flow from expiring due to -inactivity. +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, regardless of activity. A value of 0 (the default) gives the flow no hard expiration deadline. . +.IP "\fBsend_flow_rem\fR" +Marks the flow with a flag that causes the switch to generate a ``flow +removed'' message and send it to interested controllers when the flow +later expires or is removed. +. +.IP "\fBcheck_overlap\fR" +Forces the switch to check that the flow match does not overlap that +of any different flow with the same priority in the same table. (This +check is expensive so it is best to avoid it.) +. .PP The \fBdump\-flows\fR, \fBdump\-aggregate\fR, \fBdel\-flow\fR and \fBdel\-flows\fR commands support one additional optional field: @@ -992,19 +1097,13 @@ If set, a matching flow must include an output action to \fIport\fR. . The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information about the entries in a datapath's tables. Each line of output is a -unique flow entry, which begins with some common information: -. -.IP \fBduration\fR -The number of seconds the entry has been in the table. +flow entry as described in \fBFlow Syntax\fR, above, plus some +additional fields: . -.IP \fBtable_id\fR -The table that contains the flow. When a packet arrives, the switch -begins searching for an entry at the lowest numbered table. Tables are -numbered as shown by the \fBdump\-tables\fR command. -. -.IP \fBpriority\fR -The priority of the entry in relation to other entries within the same -table. A higher value will match before a lower one. +.IP \fBduration=\fIsecs\fR +The time, in seconds, that the entry has been in the table. +\fIsecs\fR includes as much precision as the switch provides, possibly +to nanosecond resolution. . .IP \fBn_packets\fR The number of packets that have matched the entry. @@ -1013,9 +1112,23 @@ The number of packets that have matched the entry. The total number of bytes from packets that have matched the entry. . .PP -The rest of the line consists of a description of the flow entry as -described in \fBFlow Syntax\fR, above. -. +The following additional fields are included only if the switch is +Open vSwitch 1.6 or later and the NXM flow format is used to dump the +flow (see the description of the \fB\-\-flow-format\fR option below). +The values of these additional fields are approximations only and in +particular \fBidle_age\fR will sometimes become nonzero even for busy +flows. +. +.IP \fBhard_age=\fIsecs\fR +The integer number of seconds since the flow was added or modified. +\fBhard_age\fR is displayed only if it differs from the integer part +of \fBduration\fR. (This is separate from \fBduration\fR because +\fBmod\-flows\fR restarts the \fBhard_timeout\fR timer without zeroing +\fBduration\fR.) +. +.IP \fBidle_age=\fIsecs\fR +The integer number of seconds that have passed without any packets +passing through the flow. . .SH OPTIONS .TP @@ -1049,16 +1162,49 @@ 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\-P \fIformat\fR" +.IQ "\fB\-\-packet\-in\-format=\fIformat\fR" +\fBovs\-ofctl\fR supports the following packet_in formats, in order of +increasing capability: +.RS +.IP "\fBopenflow10\fR" +This is the standard OpenFlow 1.0 packet in format. It should be supported by +all OpenFlow switches. +. +.IP "\fBnxm\fR (Nicira Extended Match)" +This packet_in format includes flow metadata encoded using the NXM format. +. +.RE +.IP +Usually, \fBovs\-ofctl\fR prefers the \fBnxm\fR packet_in format, but will +allow the switch to choose its default if \fBnxm\fR is unsupported. When +\fIformat\fR is one of the formats listed in the above table, \fBovs\-ofctl\fR +will insist on the selected format. If the switch does not support the +requested format, \fBovs\-ofctl\fR will report a fatal error. This option only +affects the \fBmonitor\fR command. +. .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. +. +.ds DD \ +\fBovs\-ofctl\fR detaches only when executing the \fBmonitor\fR or \ +\fBsnoop\fR commands. +.so lib/daemon.man .SS "Public Key Infrastructure Options" .so lib/ssl.man .so lib/vlog.man .so lib/common.man . +.SH "RUNTIME MANAGEMENT COMMANDS" +\fBovs\-appctl\fR(8) can send commands to a running \fBovs\-ofctl\fR process. +The currently supported commands only apply when executing the \fBmonitor\fR or +\fBsnoop\fR commands and are described below. +.IP "\fBexit\fR" +Causes \fBovs\-ofctl\fR to gracefully terminate. .SH EXAMPLES . The following examples assume that \fBovs\-vswitchd\fR has a bridge