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| \
  10 \fIpacket\fR]"
  11 .IQ "\fBofproto/trace\fR \fIbridge\fR \fIbr_flow\fR \
  12 [\fB\-generate \fR| \fIpacket\fR]"
  13 Traces the path of an imaginary packet through \fIswitch\fR and
  14 reports the path that it took.  The packet's headers (e.g. source and
  15 destination) and metadata (e.g. input port), together called its
  16 ``flow,'' are usually all that matter for this purpose.  You can
  17 specify the flow in the following ways:
  18 .
  19 .RS
  20 .IP "\fIdpname\fR \fIodp_flow\fR"
  21 \fIodp_flow\fR is a flow in the form printed by \fBovs\-dpctl\fR(8)'s
  22 \fBdump\-flows\fR command.  If all of your bridges have the same type,
  23 which is the common case, then you can omit \fIdpname\fR, but if you
  24 have bridges of different types (say, both \fBovs-netdev\fR and
  25 \fBovs-system\fR), then you need to specify a \fIdpname\fR to disambiguate.
  26 .
  27 .IP "\fIbridge\fR \fIbr_flow\fR"
  28 \fIbr_flow\fR is a flow in the form similar to that accepted by
  29 \fBovs\-ofctl\fR(8)'s \fBadd\-flow\fR command.  (This is not an
  30 OpenFlow flow: besides other differences, it never contains
  31 wildcards.)  \fIbridge\fR names of the bridge through which
  32 \fIbr_flow\fR should be traced.
  33 .RE
  34 .
  35 .IP
  36 Most commonly, one specifies only a flow, using one of the forms
  37 above, but sometimes one might need to specify an actual packet
  38 instead of just a flow:
  39 .
  40 .RS
  41 .IP "Side effects."
  42 Some actions have side effects.  For example, the \fBnormal\fR action
  43 can update the MAC learning table, and the \fBlearn\fR action can
  44 change OpenFlow tables.  \fBofproto/trace\fR only performs side
  45 effects when a packet is specified.  If you want side effects to take
  46 place, then you must supply a packet.
  47 .
  48 .IP
  49 (Output actions are obviously side effects too, but
  50 \fBofproto/trace\fR never executes them, even when one specifies a
  51 packet.)
  52 .
  53 .IP "Incomplete information."
  54 Most of the time, Open vSwitch can figure out everything about the
  55 path of a packet using just the flow, but in some special
  56 circumstances it needs to look at parts of the packet that are not
  57 included in the flow.  When this is the case, and you do not supply a
  58 packet, then \fBofproto/trace\fR will tell you it needs a packet.
  59 .RE
  60 .
  61 .IP
  62 If you wish to include a packet as part of the \fBofproto/trace\fR
  63 operation, there are two ways to do it:
  64 .
  65 .RS
  66 .IP \fB\-generate\fR
  67 This option, added to one of the ways to specify a flow already
  68 described, causes Open vSwitch to internally generate a packet with
  69 the flow described and then to use that packet.  If your goal is to
  70 execute side effects, then \fB\-generate\fR is the easiest way to do
  71 it, but \fB\-generate\fR is not a good way to fill in incomplete
  72 information, because it generates packets based on only the flow
  73 information, which means that the packets really do not have any more
  74 information than the flow.
  75 .
  76 .IP \fIpacket\fR
  77 This form supplies an explicit \fIpacket\fR as a sequence of hex
  78 digits.  An Ethernet frame is at least 14 bytes long, so there must be
  79 at least 28 hex digits.  Obviously, it is inconvenient to type in the
  80 hex digits by hand, so the \fBovs\-pcap\fR(1) and
  81 \fBovs\-tcpundump\fR(1) utilities provide easier ways.
  82 .IP
  83 With this form, packet headers are extracted directly from
  84 \fIpacket\fR, so the \fIodp_flow\fR or \fIbr_flow\fR should specify
  85 only metadata. The metadata can be:
  86 .RS
  87 .IP \fIskb_priority\fR
  88 Packet QoS priority.
  89 .IP \fIpkt_mark\fR
  90 Mark of the packet.
  91 .IP \fItun_id\fR
  92 The tunnel ID on which the packet arrived.
  93 .IP \fIin_port\fR
  94 The port on which the packet arrived.
  95 .RE
  96 .
  97 The in_port value is kernel datapath port number for the first format
  98 and OpenFlow port number for the second format. The numbering of these
  99 two types of port usually differs and there is no relationship.
 100 .RE
 101 .IP "\fBofproto/self\-check\fR [\fIswitch\fR]"
 102 Runs an internal consistency check on \fIswitch\fR, if specified,
 103 otherwise on all ofproto instances, and responds with a brief summary
 104 of the results.  If the summary reports any errors, then the Open
 105 vSwitch logs should contain more detailed information.  Please pass
 106 along errors reported by this command to the Open vSwitch developers
 107 as bugs.