X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=ofproto%2Fofproto-unixctl.man;h=89013d9322b806f98f5ef09d7ee62c788e2c5c6b;hb=HEAD;hp=06db7e04de24b5b2f06c47911a0083b17c6191eb;hpb=876b0e1c74a43c4edf261e3ca571a440d01b0b4c;p=sliver-openvswitch.git diff --git a/ofproto/ofproto-unixctl.man b/ofproto/ofproto-unixctl.man index 06db7e04d..89013d932 100644 --- a/ofproto/ofproto-unixctl.man +++ b/ofproto/ofproto-unixctl.man @@ -6,49 +6,131 @@ These commands manage the core OpenFlow switch implementation (called Lists the names of the running ofproto instances. These are the names that may be used on \fBofproto/trace\fR. . -.IP "\fBofproto/trace \fIswitch tun_id in_port packet\fR" -Traces the path of an imaginary packet through \fIswitch\fR. The -arguments are: +.IP "\fBofproto/trace\fR [\fIdpname\fR] \fIodp_flow\fR [\fB\-generate \fR| \fIpacket\fR]" +.IQ "\fBofproto/trace\fR \fIbridge\fR \fIbr_flow\fR [\fB\-generate \fR| \fIpacket\fR]" +.IQ "\fBofproto/trace\-packet\-out\fR [\fB\-consistent\fR] [\fIdpname\fR] \fIodp_flow\fR [\fB\-generate \fR| \fIpacket\fR] \fIactions\fR" +.IQ "\fBofproto/trace\-packet\-out\fR [\fB\-consistent\fR] \fIbridge\fR \fIbr_flow\fR [\fB\-generate \fR| \fIpacket\fR] \fIactions\fR" +Traces the path of an imaginary packet through \fIswitch\fR and +reports the path that it took. The initial treatment of the packet +varies based on the command: +. .RS -.IP "\fIswitch\fR" -The switch on which the packet arrived (one of those listed by -\fBofproto/list\fR). -.IP "\fItun_id\fR" -The tunnel ID on which the packet arrived. Use -\fB0\fR if the packet did not arrive through a tunnel. -.IP "\fIin_port\fR" -The OpenFlow port on which the packet arrived. Use \fB65534\fR if the -packet arrived on \fBOFPP_LOCAL\fR, the local port. -.IP "\fIpacket\fR" -A sequence of hex digits specifying the packet's contents. An -Ethernet frame is at least 14 bytes long, so there must be at least 28 -hex digits. Obviously, it is inconvenient to type in the hex digits -by hand, so the \fBovs\-pcap\fR(1) and \fBovs\-tcpundump\fR(1) -utilities provide easier ways. +.IP \(bu +\fBofproto/trace\fR looks the packet up in the OpenFlow flow table, as +if the packet had arrived on an OpenFlow port. +. +.IP \(bu +\fBofproto/trace\-packet\-out\fR applies the specified OpenFlow +\fIactions\fR, as if the packet, flow, and actions had been specified +in an OpenFlow ``packet-out'' request. .RE +. .IP -\fB\*(PN\fR will respond with extensive information on how the packet -would be handled if it were to be received. The packet will not -actually be sent. +The packet's headers (e.g. source and destination) and metadata +(e.g. input port), together called its ``flow,'' are usually all that +matter for the purpose of tracing a packet. You can specify the flow +in the following ways: . -.IP "\fBofproto/trace \fIswitch odp_flow\fR" -Traces the path of a packet in an imaginary flow through -\fIswitch\fR. The arguments are: .RS -.IP "\fIswitch\fR" -The switch on which the packet arrived (one of those listed by -\fBofproto/list\fR). -.IP "\fIodp_flow\fR" -A flow in the form printed by \fBovs\-dpctl\fR(8)'s \fBdump\-flows\fR -command. This is not an OpenFlow flow: besides other differences, it -never contains wildcards. +.IP "\fIdpname\fR \fIodp_flow\fR" +\fIodp_flow\fR is a flow in the form printed by \fBovs\-dpctl\fR(8)'s +\fBdump\-flows\fR command. If all of your bridges have the same type, +which is the common case, then you can omit \fIdpname\fR, but if you +have bridges of different types (say, both \fBovs-netdev\fR and +\fBovs-system\fR), then you need to specify a \fIdpname\fR to disambiguate. +. +.IP "\fIbridge\fR \fIbr_flow\fR" +\fIbr_flow\fR is a flow in the form similar to that accepted by +\fBovs\-ofctl\fR(8)'s \fBadd\-flow\fR command. (This is not an +OpenFlow flow: besides other differences, it never contains +wildcards.) \fIbridge\fR names of the bridge through which +\fIbr_flow\fR should be traced. .RE +. +.IP +Most commonly, one specifies only a flow, using one of the forms +above, but sometimes one might need to specify an actual packet +instead of just a flow: +. +.RS +.IP "Side effects." +Some actions have side effects. For example, the \fBnormal\fR action +can update the MAC learning table, and the \fBlearn\fR action can +change OpenFlow tables. The trace commands only perform side +effects when a packet is specified. If you want side effects to take +place, then you must supply a packet. +. .IP -\fB\*(PN\fR will respond with extensive information on how a packet -in \fIodp_flow\fR would be handled if it were received by -\fIswitch\fR. No packet will actually be sent. +(Output actions are obviously side effects too, but +the trace commands never execute them, even when one specifies a +packet.) +. +.IP "Incomplete information." +Most of the time, Open vSwitch can figure out everything about the +path of a packet using just the flow, but in some special +circumstances it needs to look at parts of the packet that are not +included in the flow. When this is the case, and you do not supply a +packet, then a trace command will tell you it needs a packet. +.RE +. +.IP +If you wish to include a packet as part of a trace operation, there +are two ways to do it: +. +.RS +.IP \fB\-generate\fR +This option, added to one of the ways to specify a flow already +described, causes Open vSwitch to internally generate a packet with +the flow described and then to use that packet. If your goal is to +execute side effects, then \fB\-generate\fR is the easiest way to do +it, but \fB\-generate\fR is not a good way to fill in incomplete +information, because it generates packets based on only the flow +information, which means that the packets really do not have any more +information than the flow. +. +.IP \fIpacket\fR +This form supplies an explicit \fIpacket\fR as a sequence of hex +digits. An Ethernet frame is at least 14 bytes long, so there must be +at least 28 hex digits. Obviously, it is inconvenient to type in the +hex digits by hand, so the \fBovs\-pcap\fR(1) and +\fBovs\-tcpundump\fR(1) utilities provide easier ways. +.IP +With this form, packet headers are extracted directly from +\fIpacket\fR, so the \fIodp_flow\fR or \fIbr_flow\fR should specify +only metadata. The metadata can be: +.RS +.IP \fIskb_priority\fR +Packet QoS priority. +.IP \fIpkt_mark\fR +Mark of the packet. +.IP \fItun_id\fR +The tunnel ID on which the packet arrived. +.IP \fIin_port\fR +The port on which the packet arrived. +.RE +.RE +. +.IP +The in_port value is kernel datapath port number for the first format +and OpenFlow port number for the second format. The numbering of these +two types of port usually differs and there is no relationship. +. .IP -This form of \fBofproto/trace\fR cannot determine the complete set of -datapath actions in some corner cases. If the results say that this -is the case, rerun \fBofproto/trace\fR supplying a packet in the flow -to get complete results. +\fBofproto\-trace\-packet\-out\fR accepts an additional +\fB\-consistent\fR option. With this option specified, the command +rejects \fIactions\fR that are inconsistent with the specified packet. +(An example of an inconsistency is attempting to strip the VLAN tag +from a packet that does not have a VLAN tag.) Open vSwitch ignores +most forms of inconsistency in OpenFlow 1.0 and rejects +inconsistencies in later versions of OpenFlow. The option is +necessary because the command does not ordinarily imply a particular +OpenFlow version. One exception is that, when \fIactions\fR includes +an action that only OpenFlow 1.1 and later supports (such as +\fBpush_vlan\fR), \fB\-consistent\fR is automatically enabled. +.IP "\fBofproto/self\-check\fR [\fIswitch\fR]" +Runs an internal consistency check on \fIswitch\fR, if specified, +otherwise on all ofproto instances, and responds with a brief summary +of the results. If the summary reports any errors, then the Open +vSwitch logs should contain more detailed information. Please pass +along errors reported by this command to the Open vSwitch developers +as bugs.