X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=ofproto%2Fofproto-unixctl.man;h=89013d9322b806f98f5ef09d7ee62c788e2c5c6b;hb=HEAD;hp=3e36fe6362db14fa90fad4b6bc6feba08567ee5f;hpb=8706009e555bb9fa04a5679e4be2c7c67506802b;p=sliver-openvswitch.git diff --git a/ofproto/ofproto-unixctl.man b/ofproto/ofproto-unixctl.man index 3e36fe636..89013d932 100644 --- a/ofproto/ofproto-unixctl.man +++ b/ofproto/ofproto-unixctl.man @@ -6,68 +6,127 @@ 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 priority tun_id in_port packet\fR" -.IQ "\fBofproto/trace \fIswitch flow \fB\-generate\fR" -Traces the path of an imaginary packet through \fIswitch\fR. Both -forms require \fIswitch\fR, the switch on which the packet arrived -(one of those listed by \fBofproto/list\fR). The first form specifies -a packet's contents explicitly: +.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 \(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 +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: +. .RS -.IP "\fIpriority\fR" -Packet QoS priority. Use \fB0\fR if QoS is not setup. -.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 "\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 -The second form specifies the packet's contents implicitly: +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 "\fIflow\fR" -A flow in one of two forms: either the form printed by -\fBovs\-dpctl\fR(8)'s \fBdump\-flows\fR command, or in a format -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. \fB\*(PN\fR generates an arbitrary packet -that has the specified \fIflow\fR. +.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 +(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 -\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, but side effects such as MAC learning will occur. +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 "\fBofproto/trace \fIswitch flow\fR" -Traces the path of a packet in an imaginary flow through -\fIswitch\fR. The arguments are: +.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 "\fIswitch\fR" -The switch on which the packet arrived (one of those listed by -\fBofproto/list\fR). -.IP "\fIflow\fR" -A flow in one of two forms: either the form printed by -\fBovs\-dpctl\fR(8)'s \fBdump\-flows\fR command, or in a format -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. +.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 -\fB\*(PN\fR will respond with extensive information on how a packet -in \fIflow\fR would be handled if it were received by -\fIswitch\fR. No packet will actually be sent. Some side effects may -occur, but MAC learning in particular will not. +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