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 "\fB\-\-ct-next\fR \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 \fB\-\-ct-next\fR is unspecified, or when there are fewer
 111 \fB\-\-ct-next\fR options than ct \fIactions\fR, the \fIflags\fR default to
 112 \fBtrk,new\fR.
 113 .
 114 .RE
 115 .
 116 .IP
 117 Most commonly, one specifies only a flow, using one of the forms
 118 above, but sometimes one might need to specify an actual packet
 119 instead of just a flow:
 120 .
 121 .RS
 122 .IP "Side effects."
 123 Some actions have side effects.  For example, the \fBnormal\fR action
 124 can update the MAC learning table, and the \fBlearn\fR action can
 125 change OpenFlow tables.  The trace commands only perform side
 126 effects when a packet is specified.  If you want side effects to take
 127 place, then you must supply a packet.
 128 .
 129 .IP
 130 (Output actions are obviously side effects too, but
 131 the trace commands never execute them, even when one specifies a
 132 packet.)
 133 .
 134 .IP "Incomplete information."
 135 Most of the time, Open vSwitch can figure out everything about the
 136 path of a packet using just the flow, but in some special
 137 circumstances it needs to look at parts of the packet that are not
 138 included in the flow.  When this is the case, and you do not supply a
 139 packet, then a trace command will tell you it needs a packet.
 140 .RE
 141 .
 142 .IP
 143 If you wish to include a packet as part of a trace operation, there
 144 are two ways to do it:
 145 .
 146 .RS
 147 .IP \fB\-\-generate\fR
 148 This option, added to one of the ways to specify a flow already
 149 described, causes Open vSwitch to internally generate a packet with
 150 the flow described and then to use that packet.  If your goal is to
 151 execute side effects, then \fB\-\-generate\fR is the easiest way to do
 152 it, but \fB\-\-generate\fR is not a good way to fill in incomplete
 153 information, because it generates packets based on only the flow
 154 information, which means that the packets really do not have any more
 155 information than the flow.
 156 .IP
 157 By default, for protocols that allow arbitrary L7 payloads, the
 158 generated packet has 64 bytes of payload.  Use \fB\-\-l7\-len\fR to
 159 change the payload length, or \fB\-\-l7\fR to specify the exact
 160 contents of the payload.
 161 .
 162 .IP \fIpacket\fR
 163 This form supplies an explicit \fIpacket\fR as a sequence of hex
 164 digits.  An Ethernet frame is at least 14 bytes long, so there must be
 165 at least 28 hex digits.  Obviously, it is inconvenient to type in the
 166 hex digits by hand, so the \fBovs\-pcap\fR(1) and
 167 \fBovs\-tcpundump\fR(1) utilities provide easier ways.
 168 .IP
 169 With this form, packet headers are extracted directly from
 170 \fIpacket\fR, so the \fIodp_flow\fR or \fIbr_flow\fR should specify
 171 only metadata. The metadata can be:
 172 .RS
 173 .IP \fIskb_priority\fR
 174 Packet QoS priority.
 175 .IP \fIpkt_mark\fR
 176 Mark of the packet.
 177 .IP \fIct_state\fR
 178 Connection state of the packet.
 179 .IP \fIct_zone\fR
 180 Connection tracking zone for packet.
 181 .IP \fIct_mark\fR
 182 Connection mark of the packet.
 183 .IP \fIct_label\fR
 184 Connection label of the packet.
 185 .IP \fItun_id\fR
 186 The tunnel ID on which the packet arrived.
 187 .IP \fIin_port\fR
 188 The port on which the packet arrived.
 189 .RE
 190 .RE
 191 .
 192 .IP
 193 The in_port value is kernel datapath port number for the first format
 194 and OpenFlow port number for the second format. The numbering of these
 195 two types of port usually differs and there is no relationship.
 196 .
 197 .
 198 .IP "Usage examples:"
 199 .RS 4
 200 .PP
 201 \fBTrace an unicast ICMP echo request on ingress port 1 to destination MAC
 202 00:00:5E:00:53:01\fR
 203 .RS 4
 204 .nf
 205 ofproto/trace br in_port=1,icmp,icmp_type=8,\\
 206 dl_dst=00:00:5E:00:53:01
 207 .RE
 208 .fi
 209 .PP
 210 \fBTrace an unicast ICMP echo reply on ingress port 1 to destination MAC
 211 00:00:5E:00:53:01\fR
 212 .RS 4
 213 .nf
 214 ofproto/trace br in_port=1,icmp,icmp_type=0,\\
 215 dl_dst=00:00:5E:00:53:01
 216 .fi
 217 .RE
 218 .PP
 219 \fBTrace an ARP request on ingress port 1\fR
 220 .RS 4
 221 .nf
 222 ofproto/trace br in_port=1,arp,arp_op=1
 223 .fi
 224 .RE
 225 .PP
 226 \fBTrace an ARP reply on ingress port 1\fR
 227 .RS 4
 228 .nf
 229 ofproto/trace br in_port=1,arp,arp_op=2
 230 .fi
 231 .RE
 232 .RE