]>
Commit | Line | Data |
---|---|---|
7aa697dd BP |
1 | .SS "OFPROTO COMMANDS" |
2 | These commands manage the core OpenFlow switch implementation (called | |
3 | \fBofproto\fR). | |
876b0e1c | 4 | . |
7aa697dd BP |
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. | |
876b0e1c | 8 | . |
b490b189 BP |
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" | |
50aa28fd | 13 | Traces the path of an imaginary packet through \fIswitch\fR and |
aee0979b BP |
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: | |
50aa28fd | 33 | . |
7aa697dd | 34 | .RS |
50aa28fd AW |
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. | |
dc29f566 | 48 | .RE |
50aa28fd | 49 | . |
876b0e1c | 50 | .IP |
0f2f05bb | 51 | .RS |
b490b189 BP |
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 | . | |
6f068379 BP |
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 | . | |
b490b189 BP |
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. | |
0f2f05bb YHW |
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 | |
50aa28fd AW |
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 | . | |
8b3b8dd1 | 120 | .RS |
50aa28fd AW |
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 | |
aee0979b | 124 | change OpenFlow tables. The trace commands only perform side |
50aa28fd AW |
125 | effects when a packet is specified. If you want side effects to take |
126 | place, then you must supply a packet. | |
127 | . | |
8b3b8dd1 | 128 | .IP |
418a7a84 BP |
129 | (Output actions are obviously side effects too, but |
130 | the trace commands never execute them, even when one specifies a | |
131 | packet.) | |
876b0e1c | 132 | . |
50aa28fd AW |
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 | |
aee0979b | 138 | packet, then a trace command will tell you it needs a packet. |
876b0e1c | 139 | .RE |
50aa28fd | 140 | . |
876b0e1c | 141 | .IP |
aee0979b BP |
142 | If you wish to include a packet as part of a trace operation, there |
143 | are two ways to do it: | |
50aa28fd AW |
144 | . |
145 | .RS | |
b490b189 | 146 | .IP \fB\-\-generate\fR |
50aa28fd AW |
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 | |
b490b189 BP |
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 | |
50aa28fd AW |
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. | |
6f068379 BP |
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. | |
50aa28fd AW |
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. | |
876b0e1c | 167 | .IP |
50aa28fd AW |
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. | |
1362e248 JG |
174 | .IP \fIpkt_mark\fR |
175 | Mark of the packet. | |
07659514 JS |
176 | .IP \fIct_state\fR |
177 | Connection state of the packet. | |
178 | .IP \fIct_zone\fR | |
179 | Connection tracking zone for packet. | |
8e53fe8c JS |
180 | .IP \fIct_mark\fR |
181 | Connection mark of the packet. | |
9daf2348 JS |
182 | .IP \fIct_label\fR |
183 | Connection label of the packet. | |
50aa28fd AW |
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 | |
aee0979b | 189 | .RE |
50aa28fd | 190 | . |
aee0979b | 191 | .IP |
50aa28fd AW |
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. | |
aee0979b | 195 | . |
27e3debd TR |
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 |