]>
Commit | Line | Data |
---|---|---|
4acd1e87 BP |
1 | <?xml version="1.0" encoding="utf-8"?> |
2 | <manpage program="ovn-trace" section="8" title="ovn-trace"> | |
3 | <h1>Name</h1> | |
4 | <p>ovn-trace -- Open Virtual Network logical network tracing utility</p> | |
5 | ||
6 | <h1>Synopsis</h1> | |
7 | <p><code>ovn-trace</code> [<var>options</var>] <var>datapath</var> <var>microflow</var></p> | |
8 | <p><code>ovn-trace</code> [<var>options</var>] <code>--detach</code></p> | |
9 | ||
10 | <h1>Description</h1> | |
11 | <p> | |
12 | This utility simulates packet forwarding within an OVN logical network. | |
13 | It can be used to run through ``what-if'' scenarios: if a packet | |
14 | originates at a logical port, what will happen to it and where will it | |
15 | ultimately end up? Users already familiar with the Open vSwitch | |
16 | <code>ofproto/trace</code> command described in | |
17 | <code>ovs-vswitch</code>(8) will find <code>ovn-trace</code> to be a | |
18 | similar tool for logical networks. | |
19 | </p> | |
20 | ||
21 | <p> | |
22 | <code>ovn-trace</code> works by reading the <code>Logical_Flow</code> and | |
23 | other tables from the OVN southbound database (see | |
24 | <code>ovn-sb</code>(5)). It simulates a packet's path through logical | |
25 | networks by repeatedly looking it up in the logical flow table, following | |
26 | the entire tree of possibilities. | |
27 | </p> | |
28 | ||
29 | <p> | |
30 | <code>ovn-trace</code> simulates only the OVN logical network. It does | |
31 | not simulate the physical elements on which the logical network is | |
32 | layered. This means that, for example, it is unimportant how VMs are | |
33 | distributed among hypervisors, or whether their hypervisors are | |
34 | functioning and reachable, so <code>ovn-trace</code> will yield the same | |
35 | results regardless. There is one important exception: | |
36 | <code>ovn-northd</code>, the daemon that generates the logical flows that | |
37 | <code>ovn-trace</code> simulates, treats logical ports differently based | |
38 | on whether they are up or down. Thus, if you see surprising results, | |
39 | ensure that the ports involved in a simulation are up. | |
40 | </p> | |
41 | ||
42 | <p> | |
43 | The simplest way to use <code>ovn-trace</code> is to provide | |
44 | <var>datapath</var> and <var>microflow</var> arguments on the command | |
45 | line. In this case, it simulates the behavior of a single packet and | |
46 | exits. For an alternate usage model, see <code>Daemon Mode</code> below. | |
47 | </p> | |
48 | ||
49 | <p> | |
50 | The <var>datapath</var> argument specifies the name of a logical | |
51 | datapath. Acceptable names are the <code>name</code> from the northbound | |
52 | <code>Logical_Switch</code> or <code>Logical_Router</code> table, the | |
53 | UUID of a record from one of those tables, or the UUID of a record from | |
54 | the southbound <code>Datapath_Binding</code> table. | |
55 | </p> | |
56 | ||
57 | <p> | |
58 | The <var>microflow</var> argument describes the packet whose forwarding | |
59 | is to be simulated, in the syntax of an OVN logical expression, as | |
60 | described in <code>ovn-sb</code>(5), to express constraints. The parser | |
61 | understands prerequisites; for example, if the expression refers to | |
62 | <code>ip4.src</code>, there is no need to explicitly state | |
63 | <code>ip4</code> or <code>eth.type == 0x800</code>. | |
64 | </p> | |
65 | ||
66 | <p> | |
67 | For reasonable L2 behavior, the microflow should include at least | |
68 | <code>inport</code> and <code>eth.dst</code>, plus <code>eth.src</code> | |
69 | if port security is enabled. For example: | |
70 | </p> | |
71 | <pre> | |
72 | inport == "lp11" && eth.src == 00:01:02:03:04:05 && eth.dst == ff:ff:ff:ff:ff:ff | |
73 | </pre> | |
74 | ||
75 | <p> | |
76 | For reasonable L3 behavior, <var>microflow</var> should also include | |
77 | <code>ip4.src</code> and <code>ip4.dst</code> (or <code>ip6.src</code> | |
78 | and <code>ip6.dst</code>) and <code>ip.ttl</code>. For example: | |
79 | </p> | |
80 | <pre> | |
81 | inport == "lp111" && eth.src == f0:00:00:00:01:11 && eth.dst == 00:00:00:00:ff:11 | |
82 | && ip4.src == 192.168.11.1 && ip4.dst == 192.168.22.2 && ip.ttl == 64 | |
83 | </pre> | |
84 | ||
85 | <p>Here's an ARP microflow example:</p> | |
86 | <pre> | |
87 | inport == "lp123" | |
88 | && eth.dst == ff:ff:ff:ff:ff:ff && eth.src == f0:00:00:00:01:11 | |
89 | && arp.op == 1 && arp.sha == f0:00:00:00:01:11 && arp.spa == 192.168.1.11 | |
90 | && arp.tha == ff:ff:ff:ff:ff:ff && arp.tpa == 192.168.2.22 | |
91 | </pre> | |
92 | ||
93 | <p> | |
94 | <code>ovn-trace</code> will reject erroneous microflow expressions, which | |
95 | beyond syntax errors fall into two categories. First, they can be | |
96 | ambiguous. For example, <code>tcp.src == 80</code> is ambiguous because | |
97 | it does not state IPv4 or IPv6 as the Ethernet type. <code>ip4 | |
98 | && tcp.src > 1024</code> is also ambiguous because it does not | |
99 | constrain bits of <code>tcp.src</code> to particular values. Second, | |
100 | they can be contradictory, e.g. <code>ip4 && ip6</code>. | |
101 | </p> | |
102 | ||
103 | <h1>Output</h1> | |
104 | ||
105 | <p> | |
106 | <code>ovn-trace</code> supports the three different forms of output, each | |
107 | described in a separate section below. Regardless of the selected output | |
108 | format, <code>ovn-trace</code> starts the output with a line that shows | |
109 | the microflow being traced in OpenFlow syntax. | |
110 | </p> | |
111 | ||
112 | <h2>Detailed Output</h2> | |
113 | ||
114 | <p> | |
115 | The detailed form of output is also the default form. This form groups | |
116 | output into sections headed up by the ingress or egress pipeline being | |
d8026bbf BP |
117 | traversed. Each pipeline lists each table that was visited (by number and |
118 | name), the <code>ovn-northd</code> source file and line number of the code | |
119 | that added the flow, the match expression and priority of the logical flow | |
120 | that was matched, and the actions that were executed. | |
4acd1e87 BP |
121 | </p> |
122 | ||
123 | <p> | |
124 | The execution of OVN logical actions naturally forms a ``control stack'' | |
125 | that resembles that of a program in conventional programming languages | |
126 | such as C or Java. Because the <code>next</code> action that calls into | |
127 | another logical flow table for a lookup is a recursive construct, OVN | |
128 | ``programs'' in practice tend to form deep control stacks that, displayed | |
129 | in the obvious way using additional indentation for each level, quickly | |
130 | use up the horizontal space on all but the widest displays. To make | |
131 | detailed output more readable, without loss of generality, | |
132 | <code>ovn-trace</code> omits indentation for ``tail recursion,'' that is, | |
133 | when <code>next</code> is the last action in a logical flow, it does not | |
134 | indent details of the next table lookup more deeply. Output still uses | |
135 | indentation when it is needed for clarity. | |
136 | </p> | |
137 | ||
138 | <p> | |
139 | OVN ``programs'' traces also tend to encounter long strings of logical | |
140 | flows with match expression <code>1</code> (which matches every packet) | |
f850c889 JP |
141 | and the single action <code>next;</code>. These are uninteresting |
142 | and merely clutter output, so <code>ovn-trace</code> omits them | |
143 | entirely even from detailed output. | |
4acd1e87 BP |
144 | </p> |
145 | ||
146 | <p> | |
147 | The following excerpt from detailed <code>ovn-trace</code> output shows a | |
148 | section for a packet traversing the ingress pipeline of logical datapath | |
149 | <code>ls1</code> with ingress logical port <code>lp111</code>. The | |
150 | packet matches a logical flow in table 0 (aka | |
151 | <code>ls_in_port_sec_l2</code>) with priority 50 and executes | |
152 | <code>next(1);</code> to pass to table 1. Tables 1 through 11 are | |
153 | trivial and omitted. In table 12 (aka <code>ls_in_l2_lkup</code>), the | |
154 | packet matches a flow with priority 50 based on its Ethernet destination | |
155 | address and the flow's actions output the packet to the | |
156 | <code>lrp11-attachement</code> logical port. | |
157 | </p> | |
158 | ||
159 | <pre fixed="yes"> | |
160 | ingress(dp="ls1", inport="lp111") | |
161 | --------------------------------- | |
162 | 0. ls_in_port_sec_l2: inport == "lp111", priority 50 | |
163 | next(1); | |
164 | 12. ls_in_l2_lkup: eth.dst == 00:00:00:00:ff:11, priority 50 | |
165 | outport = "lrp11-attachment"; | |
166 | output; | |
167 | </pre> | |
168 | ||
169 | <h2>Summary Output</h2> | |
170 | ||
171 | <p> | |
172 | Summary output includes the logical pipelines visited by a packet and the | |
173 | logical actions executed on it. Compared to the detailed output, | |
174 | however, it removes details of tables and logical flows traversed by a | |
175 | packet. It uses a format closer to that of a programming language and | |
176 | does not attempt to avoid indentation. The summary output equivalent to | |
177 | the above detailed output fragment is: | |
178 | </p> | |
179 | ||
180 | <pre fixed="yes"> | |
181 | ingress(dp="ls1", inport="lp111") { | |
182 | outport = "lrp11-attachment"; | |
183 | output; | |
184 | ... | |
185 | }; | |
186 | </pre> | |
187 | ||
188 | <h2>Minimal Output</h2> | |
189 | ||
190 | <p> | |
191 | Minimal output includes only actions that modify packet data (not | |
192 | including OVN registers or metadata such as <code>outport</code>) and | |
193 | <code>output</code> actions that actually deliver a packet to a logical | |
194 | port (excluding patch ports). The operands of actions that modify packet | |
195 | data are displayed reduced to constants, e.g. <code>ip4.dst = | |
196 | reg0;</code> might be show as <code>ip4.dst = 192.168.0.1;</code> if that | |
197 | was the value actually loaded. This yields output even simpler than the | |
198 | summary format. (Users familiar with Open vSwitch may recognize this as | |
199 | similar in spirit to the datapath actions listed at the bottom of | |
200 | <code>ofproto/trace</code> output.) | |
201 | </p> | |
202 | ||
203 | <p> | |
204 | The minimal output format reflects the externally seen behavior of the | |
205 | logical networks more than it does the implementation. This makes this | |
206 | output format the most suitable for use in regression tests, because it | |
207 | is least likely to change when logical flow tables are rearranged without | |
208 | semantic change. | |
209 | </p> | |
210 | ||
211 | <h1>Daemon Mode</h1> | |
212 | ||
213 | <p> | |
214 | If <code>ovn-trace</code> is invoked with the <code>--detach</code> option | |
215 | (see <code>Daemon Options</code>, below), it runs in the background as a | |
216 | daemon and accepts commands from <code>ovs-appctl</code> (or another | |
217 | JSON-RPC client) indefinitely. The currently supported commands are | |
218 | described below. | |
219 | </p> | |
220 | ||
221 | <p> | |
222 | ||
223 | </p> | |
224 | ||
225 | <dl> | |
226 | <dt><code>trace</code> [<var>options</var>] <var>datapath</var> <var>microflow</var></dt> | |
227 | <dd> | |
228 | Traces <var>microflow</var> through <var>datapath</var> and replies with | |
229 | the results of the trace. Accepts the <var>options</var> described under | |
230 | <code>Trace Options</code> below. | |
231 | </dd> | |
232 | ||
233 | <dt><code>exit</code></dt> | |
234 | <dd>Causes <code>ovn-trace</code> to gracefully terminate.</dd> | |
235 | </dl> | |
236 | ||
237 | <h1>Options</h1> | |
238 | ||
239 | <h2>Trace Options</h2> | |
240 | ||
241 | <dl> | |
242 | <dt><code>--detailed</code></dt> | |
243 | <dt><code>--summary</code></dt> | |
244 | <dt><code>--minimal</code></dt> | |
245 | <dd> | |
246 | These options control the form and level of detail in | |
247 | <code>ovn-trace</code> output. If more than one of these options is | |
248 | specified, all of the selected forms are output, in the order listed | |
249 | above, each headed by a banner line. If none of these options is | |
250 | given, <code>--detailed</code> is the default. See | |
251 | <code>Output</code>, above, for a description of each kind of output. | |
252 | </dd> | |
253 | ||
254 | <dt><code>--all</code></dt> | |
255 | <dd> | |
256 | Selects all three forms of output. | |
257 | </dd> | |
258 | </dl> | |
259 | ||
260 | <h2>Daemon Options</h2> | |
261 | <xi:include href="lib/daemon.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> | |
262 | ||
263 | <h2>Logging Options</h2> | |
264 | <xi:include href="lib/vlog.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> | |
265 | ||
266 | <h2>PKI Options</h2> | |
267 | <p> | |
268 | PKI configuration is required to use SSL for the connection to the | |
269 | database. | |
270 | </p> | |
271 | <xi:include href="lib/ssl.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> | |
272 | ||
273 | <h2>Other Options</h2> | |
274 | ||
275 | <dl> | |
276 | <dt><code>--db</code> <var>database</var></dt> | |
277 | <dd> | |
278 | The OVSDB database remote to contact. If the <env>OVN_SB_DB</env> | |
279 | environment variable is set, its value is used as the default. | |
280 | Otherwise, the default is <code>unix:@RUNDIR@/db.sock</code>, but this | |
281 | default is unlikely to be useful outside of single-machine OVN test | |
282 | environments. | |
283 | </dd> | |
284 | </dl> | |
285 | ||
286 | <xi:include href="lib/common.xml" xmlns:xi="http://www.w3.org/2003/XInclude"/> | |
287 | ||
288 | </manpage> |