ofproto/ofproto-unixctl.man

   1 .SS "OFPROTO COMMANDS"
   2 These commands manage the core OpenFlow switch implementation (called
   3 \fBofproto\fR).
   4 .
   5 .IP "\fBofproto/list\fR"
   6 Lists the names of the running ofproto instances.  These are the names
   7 that may be used on \fBofproto/trace\fR.
   8 .
   9 .IP "\fBofproto/trace\fR [\fIdpname\fR] \fIodp_flow\fR [\fB\-generate \fR| \fIpacket\fR]"
  10 .IQ "\fBofproto/trace\fR \fIbridge\fR \fIbr_flow\fR [\fB\-generate \fR| \fIpacket\fR]"
  11 .IQ "\fBofproto/trace\-packet\-out\fR [\fB\-consistent\fR] [\fIdpname\fR] \fIodp_flow\fR [\fB\-generate \fR| \fIpacket\fR] \fIactions\fR"
  12 .IQ "\fBofproto/trace\-packet\-out\fR [\fB\-consistent\fR] \fIbridge\fR \fIbr_flow\fR [\fB\-generate \fR| \fIpacket\fR] \fIactions\fR"
  13 Traces the path of an imaginary packet through \fIswitch\fR and
  14 reports the path that it took.  The initial treatment of the packet
  15 varies based on the command:
  16 .
  17 .RS
  18 .IP \(bu
  19 \fBofproto/trace\fR looks the packet up in the OpenFlow flow table, as
  20 if the packet had arrived on an OpenFlow port.
  21 .
  22 .IP \(bu
  23 \fBofproto/trace\-packet\-out\fR applies the specified OpenFlow
  24 \fIactions\fR, as if the packet, flow, and actions had been specified
  25 in an OpenFlow ``packet-out'' request.
  26 .RE
  27 .
  28 .IP
  29 The packet's headers (e.g. source and destination) and metadata
  30 (e.g. input port), together called its ``flow,'' are usually all that
  31 matter for the purpose of tracing a packet.  You can specify the flow
  32 in the following ways:
  33 .
  34 .RS
  35 .IP "\fIdpname\fR \fIodp_flow\fR"
  36 \fIodp_flow\fR is a flow in the form printed by \fBovs\-dpctl\fR(8)'s
  37 \fBdump\-flows\fR command.  If all of your bridges have the same type,
  38 which is the common case, then you can omit \fIdpname\fR, but if you
  39 have bridges of different types (say, both \fBovs-netdev\fR and
  40 \fBovs-system\fR), then you need to specify a \fIdpname\fR to disambiguate.
  41 .
  42 .IP "\fIbridge\fR \fIbr_flow\fR"
  43 \fIbr_flow\fR is a flow in the form similar to that accepted by
  44 \fBovs\-ofctl\fR(8)'s \fBadd\-flow\fR command.  (This is not an
  45 OpenFlow flow: besides other differences, it never contains
  46 wildcards.)  \fIbridge\fR names of the bridge through which
  47 \fIbr_flow\fR should be traced.
  48 .RE
  49 .
  50 .IP
  51 Most commonly, one specifies only a flow, using one of the forms
  52 above, but sometimes one might need to specify an actual packet
  53 instead of just a flow:
  54 .
  55 .RS
  56 .IP "Side effects."
  57 Some actions have side effects.  For example, the \fBnormal\fR action
  58 can update the MAC learning table, and the \fBlearn\fR action can
  59 change OpenFlow tables.  The trace commands only perform side
  60 effects when a packet is specified.  If you want side effects to take
  61 place, then you must supply a packet.
  62 .
  63 .IP
  64 (Output actions are obviously side effects too, but
  65 the trace commands never execute them, even when one specifies a
  66 packet.)
  67 .
  68 .IP "Incomplete information."
  69 Most of the time, Open vSwitch can figure out everything about the
  70 path of a packet using just the flow, but in some special
  71 circumstances it needs to look at parts of the packet that are not
  72 included in the flow.  When this is the case, and you do not supply a
  73 packet, then a trace command will tell you it needs a packet.
  74 .RE
  75 .
  76 .IP
  77 If you wish to include a packet as part of a trace operation, there
  78 are two ways to do it:
  79 .
  80 .RS
  81 .IP \fB\-generate\fR
  82 This option, added to one of the ways to specify a flow already
  83 described, causes Open vSwitch to internally generate a packet with
  84 the flow described and then to use that packet.  If your goal is to
  85 execute side effects, then \fB\-generate\fR is the easiest way to do
  86 it, but \fB\-generate\fR is not a good way to fill in incomplete
  87 information, because it generates packets based on only the flow
  88 information, which means that the packets really do not have any more
  89 information than the flow.
  90 .
  91 .IP \fIpacket\fR
  92 This form supplies an explicit \fIpacket\fR as a sequence of hex
  93 digits.  An Ethernet frame is at least 14 bytes long, so there must be
  94 at least 28 hex digits.  Obviously, it is inconvenient to type in the
  95 hex digits by hand, so the \fBovs\-pcap\fR(1) and
  96 \fBovs\-tcpundump\fR(1) utilities provide easier ways.
  97 .IP
  98 With this form, packet headers are extracted directly from
  99 \fIpacket\fR, so the \fIodp_flow\fR or \fIbr_flow\fR should specify
 100 only metadata. The metadata can be:
 101 .RS
 102 .IP \fIskb_priority\fR
 103 Packet QoS priority.
 104 .IP \fIpkt_mark\fR
 105 Mark of the packet.
 106 .IP \fItun_id\fR
 107 The tunnel ID on which the packet arrived.
 108 .IP \fIin_port\fR
 109 The port on which the packet arrived.
 110 .RE
 111 .RE
 112 .
 113 .IP
 114 The in_port value is kernel datapath port number for the first format
 115 and OpenFlow port number for the second format. The numbering of these
 116 two types of port usually differs and there is no relationship.
 117 .
 118 .IP
 119 \fBofproto\-trace\-packet\-out\fR accepts an additional
 120 \fB\-consistent\fR option.  With this option specified, the command
 121 rejects \fIactions\fR that are inconsistent with the specified packet.
 122 (An example of an inconsistency is attempting to strip the VLAN tag
 123 from a packet that does not have a VLAN tag.)  Open vSwitch ignores
 124 most forms of inconsistency in OpenFlow 1.0 and rejects
 125 inconsistencies in later versions of OpenFlow.  The option is
 126 necessary because the command does not ordinarily imply a particular
 127 OpenFlow version.  One exception is that, when \fIactions\fR includes
 128 an action that only OpenFlow 1.1 and later supports (such as
 129 \fBpush_vlan\fR), \fB\-consistent\fR is automatically enabled.
 130 .IP "\fBofproto/self\-check\fR [\fIswitch\fR]"
 131 Runs an internal consistency check on \fIswitch\fR, if specified,
 132 otherwise on all ofproto instances, and responds with a brief summary
 133 of the results.  If the summary reports any errors, then the Open
 134 vSwitch logs should contain more detailed information.  Please pass
 135 along errors reported by this command to the Open vSwitch developers
 136 as bugs.