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 [\fIoptions\fR] [\fIdpname\fR] \fIodp_flow\fR [\fIpacket\fR]
  10 .IQ "\fBofproto/trace\fR [\fIoptions\fR] \fIbridge\fR \fIbr_flow\fR [\fIpacket\fR]]
  11 .IQ "\fBofproto/trace\-packet\-out\fR [\fIoptions\fR] [\fIdpname\fR] \fIodp_flow\fR [\fIpacket\fR] \fIactions\fR"
  12 .IQ "\fBofproto/trace\-packet\-out\fR [\fIoptions\fR \fIbridge\fR \fIbr_flow\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 .RS
  52 These commands support the following options:
  53 .IP \fB\-\-generate\fR
  54 Generate a packet from the flow (see below for more information).
  55 .
  56 .IP "\fB\-\-l7 \fIpayload\fR"
  57 .IQ "\fB\-\-l7\-len \fIlength\fR"
  58 Accepted only with \fB\-\-generate\fR (see below for more
  59 information).
  60 .
  61 .IP \fB\-\-consistent\fR
  62 Accepted by \fBofproto\-trace\-packet\-out\fR only.  With this option,
  63 the command rejects \fIactions\fR that are inconsistent with the
  64 specified packet.  (An example of an inconsistency is attempting to
  65 strip the VLAN tag from a packet that does not have a VLAN tag.)  Open
  66 vSwitch ignores most forms of inconsistency in OpenFlow 1.0 and
  67 rejects inconsistencies in later versions of OpenFlow.  The option is
  68 necessary because the command does not ordinarily imply a particular
  69 OpenFlow version.  One exception is that, when \fIactions\fR includes
  70 an action that only OpenFlow 1.1 and later supports (such as
  71 \fBpush_vlan\fR), \fB\-\-consistent\fR is automatically enabled.
  72 .
  73 .IP "--ct-next \fIflags\fR"
  74 When the traced flow triggers conntrack actions, \fBofproto/trace\fR
  75 will automatically trace the forked packet processing pipeline with
  76 user specified ct_state.  This option sets the ct_state flags that the
  77 conntrack module will report. The \fIflags\fR must be a comma- or
  78 space-separated list of the following connection tracking flags:
  79 .
  80 .RS
  81 .IP \(bu
  82 \fBtrk\fR: Include to indicate connection tracking has taken place.
  83 .
  84 .IP \(bu
  85 \fBnew\fR: Include to indicate a new flow.
  86 .
  87 .IP \(bu
  88 \fBest\fR: Include to indicate an established flow.
  89 .
  90 .IP \(bu
  91 \fBrel\fR: Include to indicate a related flow.
  92 .
  93 .IP \(bu
  94 \fBrpl\fR: Include to indicate a reply flow.
  95 .
  96 .IP \(bu
  97 \fBinv\fR: Include to indicate a connection entry in a bad state.
  98 .
  99 .IP \(bu
 100 \fBdnat\fR: Include to indicate a packet whose destination IP address has been
 101 changed.
 102 .
 103 .IP \(bu
 104 \fBsnat\fR: Include to indicate a packet whose source IP address has been
 105 changed.
 106 .
 107 .RE
 108 .
 109 .IP
 110 When --ct-next is unspecified, or when there are fewer --ct-next options than
 111 ct actions, the \fIflags\fR default to trk,new.
 112 .
 113 .RE
 114 .
 115 .IP
 116 Most commonly, one specifies only a flow, using one of the forms
 117 above, but sometimes one might need to specify an actual packet
 118 instead of just a flow:
 119 .
 120 .RS
 121 .IP "Side effects."
 122 Some actions have side effects.  For example, the \fBnormal\fR action
 123 can update the MAC learning table, and the \fBlearn\fR action can
 124 change OpenFlow tables.  The trace commands only perform side
 125 effects when a packet is specified.  If you want side effects to take
 126 place, then you must supply a packet.
 127 .
 128 .IP
 129 (Output actions are obviously side effects too, but
 130 the trace commands never execute them, even when one specifies a
 131 packet.)
 132 .
 133 .IP "Incomplete information."
 134 Most of the time, Open vSwitch can figure out everything about the
 135 path of a packet using just the flow, but in some special
 136 circumstances it needs to look at parts of the packet that are not
 137 included in the flow.  When this is the case, and you do not supply a
 138 packet, then a trace command will tell you it needs a packet.
 139 .RE
 140 .
 141 .IP
 142 If you wish to include a packet as part of a trace operation, there
 143 are two ways to do it:
 144 .
 145 .RS
 146 .IP \fB\-\-generate\fR
 147 This option, added to one of the ways to specify a flow already
 148 described, causes Open vSwitch to internally generate a packet with
 149 the flow described and then to use that packet.  If your goal is to
 150 execute side effects, then \fB\-\-generate\fR is the easiest way to do
 151 it, but \fB\-\-generate\fR is not a good way to fill in incomplete
 152 information, because it generates packets based on only the flow
 153 information, which means that the packets really do not have any more
 154 information than the flow.
 155 .IP
 156 By default, for protocols that allow arbitrary L7 payloads, the
 157 generated packet has 64 bytes of payload.  Use \fB\-\-l7\-len\fR to
 158 change the payload length, or \fB\-\-l7\fR to specify the exact
 159 contents of the payload.
 160 .
 161 .IP \fIpacket\fR
 162 This form supplies an explicit \fIpacket\fR as a sequence of hex
 163 digits.  An Ethernet frame is at least 14 bytes long, so there must be
 164 at least 28 hex digits.  Obviously, it is inconvenient to type in the
 165 hex digits by hand, so the \fBovs\-pcap\fR(1) and
 166 \fBovs\-tcpundump\fR(1) utilities provide easier ways.
 167 .IP
 168 With this form, packet headers are extracted directly from
 169 \fIpacket\fR, so the \fIodp_flow\fR or \fIbr_flow\fR should specify
 170 only metadata. The metadata can be:
 171 .RS
 172 .IP \fIskb_priority\fR
 173 Packet QoS priority.
 174 .IP \fIpkt_mark\fR
 175 Mark of the packet.
 176 .IP \fIct_state\fR
 177 Connection state of the packet.
 178 .IP \fIct_zone\fR
 179 Connection tracking zone for packet.
 180 .IP \fIct_mark\fR
 181 Connection mark of the packet.
 182 .IP \fIct_label\fR
 183 Connection label of the packet.
 184 .IP \fItun_id\fR
 185 The tunnel ID on which the packet arrived.
 186 .IP \fIin_port\fR
 187 The port on which the packet arrived.
 188 .RE
 189 .RE
 190 .
 191 .IP
 192 The in_port value is kernel datapath port number for the first format
 193 and OpenFlow port number for the second format. The numbering of these
 194 two types of port usually differs and there is no relationship.
 195 .
 196 .
 197 .IP "Usage examples:"
 198 .RS 4
 199 .PP
 200 \fBTrace an unicast ICMP echo request on ingress port 1 to destination MAC
 201 00:00:5E:00:53:01\fR
 202 .RS 4
 203 .nf
 204 ofproto/trace br in_port=1,icmp,icmp_type=8,\\
 205 dl_dst=00:00:5E:00:53:01
 206 .RE
 207 .fi
 208 .PP
 209 \fBTrace an unicast ICMP echo reply on ingress port 1 to destination MAC
 210 00:00:5E:00:53:01\fR
 211 .RS 4
 212 .nf
 213 ofproto/trace br in_port=1,icmp,icmp_type=0,\\
 214 dl_dst=00:00:5E:00:53:01
 215 .fi
 216 .RE
 217 .PP
 218 \fBTrace an ARP request on ingress port 1\fR
 219 .RS 4
 220 .nf
 221 ofproto/trace br in_port=1,arp,arp_op=1
 222 .fi
 223 .RE
 224 .PP
 225 \fBTrace an ARP reply on ingress port 1\fR
 226 .RS 4
 227 .nf
 228 ofproto/trace br in_port=1,arp,arp_op=2
 229 .fi
 230 .RE
 231 .RE