]>
Commit | Line | Data |
---|---|---|
f30f26be | 1 | .TH ovs\-ofctl 8 "June 2009" "Open vSwitch" "Open vSwitch Manual" |
064af421 BP |
2 | .ds PN ovs\-ofctl |
3 | ||
4 | .SH NAME | |
5 | ovs\-ofctl \- administer OpenFlow switches | |
6 | ||
7 | .SH SYNOPSIS | |
8 | .B ovs\-ofctl | |
9 | [\fIoptions\fR] \fIcommand \fR[\fIswitch\fR] [\fIargs\fR\&...] | |
10 | ||
11 | .SH DESCRIPTION | |
12 | The | |
13 | .B ovs\-ofctl | |
14 | program is a command line tool for monitoring and administering | |
15 | OpenFlow switches. It can also show the current state of an OpenFlow | |
16 | switch, including features, configuration, and table entries. | |
17 | ||
18 | .SS "OpenFlow Switch Management Commands" | |
19 | ||
20 | These commands allow \fBovs\-ofctl\fR to monitor and administer an OpenFlow | |
21 | switch. It is able to show the current state of a switch, including | |
22 | features, configuration, and table entries. | |
23 | ||
24 | Most of these commands take an argument that specifies the method for | |
25 | connecting to an OpenFlow switch. The following connection methods | |
26 | are supported: | |
27 | ||
28 | .RS | |
84ee7bcf BP |
29 | .so lib/vconn-active.man |
30 | . | |
064af421 BP |
31 | .IP "\fIfile\fR" |
32 | This is short for \fBunix:\fIfile\fR, as long as \fIfile\fR does not | |
33 | contain a colon. | |
84ee7bcf | 34 | . |
1a6f1e2a JG |
35 | .IP \fIbridge\fR |
36 | This is short for \fBunix:@RUNDIR@/\fIbridge\fB.mgmt\fR, as long as | |
37 | \fIbridge\fR does not contain a colon. | |
38 | . | |
39 | .IP [\fItype\fB@\fR]\fIdp\fR | |
40 | Attempts to look up the bridge associated with \fIdp\fR and open as | |
41 | above. If \fItype\fR is given, it specifies the datapath provider of | |
42 | \fIdp\fR, otherwise the default provider \fBsystem\fR is assumed. | |
064af421 BP |
43 | .RE |
44 | ||
45 | .TP | |
46 | \fBshow \fIswitch\fR | |
47 | Prints to the console information on \fIswitch\fR, including | |
48 | information on its flow tables and ports. | |
49 | ||
50 | .TP | |
51 | \fBstatus \fIswitch\fR [\fIkey\fR] | |
52 | Prints to the console a series of key-value pairs that report the | |
53 | status of \fIswitch\fR. If \fIkey\fR is specified, only the key-value | |
54 | pairs whose key names begin with \fIkey\fR are printed. If \fIkey\fR is | |
55 | omitted, all key-value pairs are printed. | |
56 | ||
57 | .TP | |
58 | \fBdump-tables \fIswitch\fR | |
59 | Prints to the console statistics for each of the flow tables used by | |
60 | \fIswitch\fR. | |
61 | ||
62 | .TP | |
63 | \fBdump-ports \fIswitch\fR | |
64 | Prints to the console statistics for each of the network devices | |
65 | associated with \fIswitch\fR. | |
66 | ||
67 | .TP | |
68 | \fBmod-port \fIswitch\fR \fInetdev\fR \fIaction\fR | |
69 | Modify characteristics of an interface monitored by \fIswitch\fR. | |
70 | \fInetdev\fR can be referred to by its OpenFlow assigned port number or | |
71 | the device name, e.g. \fBeth0\fR. The \fIaction\fR may be any one of the | |
72 | following: | |
73 | ||
74 | .RS | |
75 | .IP \fBup\fR | |
76 | Enables the interface. This is equivalent to ``ifconfig up'' on a Unix | |
77 | system. | |
78 | ||
79 | .IP \fBdown\fR | |
80 | Disables the interface. This is equivalent to ``ifconfig down'' on a Unix | |
81 | system. | |
82 | ||
83 | .IP \fBflood\fR | |
84 | When a \fIflood\fR action is specified, traffic will be sent out this | |
85 | interface. This is the default posture for monitored ports. | |
86 | ||
87 | .IP \fBnoflood\fR | |
88 | When a \fIflood\fR action is specified, traffic will not be sent out | |
89 | this interface. This is primarily useful to prevent loops when a | |
90 | spanning tree protocol is not in use. | |
91 | ||
92 | .RE | |
93 | ||
94 | .TP | |
95 | \fBdump-flows \fIswitch \fR[\fIflows\fR] | |
96 | Prints to the console all flow entries in \fIswitch\fR's | |
97 | tables that match \fIflows\fR. If \fIflows\fR is omitted, all flows | |
98 | in the switch are retrieved. See \fBFlow Syntax\fR, below, for the | |
99 | syntax of \fIflows\fR. The output format is described in | |
100 | \fBTable Entry Output\fR. | |
101 | ||
102 | .TP | |
103 | \fBdump-aggregate \fIswitch \fR[\fIflows\fR] | |
104 | Prints to the console aggregate statistics for flows in | |
105 | \fIswitch\fR's tables that match \fIflows\fR. If \fIflows\fR is omitted, | |
106 | the statistics are aggregated across all flows in the switch's flow | |
107 | tables. See \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR. | |
108 | The output format is descrbed in \fBTable Entry Output\fR. | |
109 | ||
110 | .TP | |
111 | \fBadd-flow \fIswitch flow\fR | |
112 | Add the flow entry as described by \fIflow\fR to the \fIswitch\fR's | |
113 | tables. The flow entry is in the format described in \fBFlow Syntax\fR, | |
114 | below. | |
115 | ||
116 | .TP | |
117 | \fBadd-flows \fIswitch file\fR | |
118 | Add flow entries as described in \fIfile\fR to \fIswitch\fR's | |
119 | tables. Each line in \fIfile\fR is a flow entry in the format | |
120 | described in \fBFlow Syntax\fR, below. | |
121 | ||
122 | .TP | |
123 | \fBmod-flows \fIswitch flow\fR | |
124 | Modify the actions in entries from the \fIswitch\fR's tables | |
125 | that match \fIflow\fR. When invoked with the \fB--strict\fR option, | |
126 | wildcards are not treated as active for matching purposes. See | |
127 | \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR. | |
128 | ||
129 | .TP | |
130 | \fBdel-flows \fIswitch \fR[\fIflow\fR] | |
131 | Deletes entries from the \fIswitch\fR's tables that match | |
132 | \fIflow\fR. When invoked with the \fB--strict\fR option, wildcards are | |
133 | not treated as active for matching purposes. If \fIflow\fR is | |
134 | omitted and the \fB--strict\fR option is not used, all flows in the | |
135 | switch's tables are removed. See \fBFlow Syntax\fR, below, for the | |
136 | syntax of \fIflows\fR. | |
137 | ||
138 | .TP | |
139 | \fBmonitor \fIswitch\fR [\fImiss-len\fR [\fIsend-exp]] | |
140 | Connects to \fIswitch\fR and prints to the console all OpenFlow | |
141 | messages received. Usually, \fIswitch\fR should specify a connection | |
8cd4882f | 142 | named on \fBovs\-openflowd\fR(8)'s \fB-l\fR or \fB--listen\fR command line |
064af421 BP |
143 | option. |
144 | ||
145 | If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set | |
146 | configuration'' message at connection setup time that requests | |
147 | \fImiss-len\fR bytes of each packet that misses the flow table. The | |
cae40bbd | 148 | OpenFlow reference implementation does not send these messages to the |
064af421 BP |
149 | \fBovs\-ofctl monitor\fR client connection unless a nonzero value is |
150 | specified on this argument. | |
151 | ||
152 | If \fIsend-exp\fR is specified as \fB1\fR, \fBovs\-ofctl\fR will also | |
153 | request to be sent flow expiration messages. If this argument is | |
154 | omitted, or \fB0\fR is specified, then \fRovs\-ofctl\fR will not request | |
155 | flow expirations. | |
156 | ||
157 | This command may be useful for debugging switch or controller | |
158 | implementations. | |
159 | ||
064af421 BP |
160 | .SS "OpenFlow Switch and Controller Commands" |
161 | ||
162 | The following commands, like those in the previous section, may be | |
163 | applied to OpenFlow switches, using any of the connection methods | |
164 | described in that section. Unlike those commands, these may also be | |
165 | applied to OpenFlow controllers. | |
166 | ||
167 | .TP | |
168 | \fBprobe \fItarget\fR | |
169 | Sends a single OpenFlow echo-request message to \fItarget\fR and waits | |
170 | for the response. With the \fB-t\fR or \fB--timeout\fR option, this | |
171 | command can test whether an OpenFlow switch or controller is up and | |
172 | running. | |
173 | ||
174 | .TP | |
175 | \fBping \fItarget \fR[\fIn\fR] | |
176 | Sends a series of 10 echo request packets to \fItarget\fR and times | |
177 | each reply. The echo request packets consist of an OpenFlow header | |
178 | plus \fIn\fR bytes (default: 64) of randomly generated payload. This | |
179 | measures the latency of individual requests. | |
180 | ||
181 | .TP | |
182 | \fBbenchmark \fItarget n count\fR | |
183 | Sends \fIcount\fR echo request packets that each consist of an | |
184 | OpenFlow header plus \fIn\fR bytes of payload and waits for each | |
185 | response. Reports the total time required. This is a measure of the | |
186 | maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte | |
187 | messages. | |
188 | ||
189 | .SS "Flow Syntax" | |
190 | ||
191 | Some \fBovs\-ofctl\fR commands accept an argument that describes a flow or | |
192 | flows. Such flow descriptions comprise a series | |
193 | \fIfield\fB=\fIvalue\fR assignments, separated by commas or white | |
194 | space. (Embedding spaces into a flow description normally requires | |
195 | quoting to prevent the shell from breaking the description into | |
196 | multiple arguments.) | |
197 | ||
198 | The following field assignments describe how a flow matches a packet. | |
199 | If any of these assignments is omitted from the flow syntax, the field | |
200 | is treated as a wildcard; thus, if all of them are omitted, the | |
201 | resulting flow matches all packets. The string \fB*\fR or \fBANY\fR | |
202 | may be specified to explicitly mark any of these fields as a wildcard. | |
203 | (\fB*\fR should be quoted to protect it from shell expansion.) | |
204 | ||
205 | .IP \fBin_port=\fIport_no\fR | |
206 | Matches physical port \fIport_no\fR. Switch ports are numbered as | |
207 | displayed by \fBovs\-ofctl show\fR. | |
208 | ||
209 | .IP \fBdl_vlan=\fIvlan\fR | |
f30f26be JP |
210 | Matches IEEE 802.1q Virtual LAN tag \fIvlan\fR. Specify \fB0xffff\fR |
211 | as \fIvlan\fR to match packets that are not tagged with a Virtual LAN; | |
064af421 BP |
212 | otherwise, specify a number between 0 and 4095, inclusive, as the |
213 | 12-bit VLAN ID to match. | |
214 | ||
215 | .IP \fBdl_src=\fImac\fR | |
216 | Matches Ethernet source address \fImac\fR, which is specified as 6 pairs | |
217 | of hexadecimal digits delimited by colons (e.g. \fB00:0A:E4:25:6B:B0\fR). | |
218 | ||
219 | .IP \fBdl_dst=\fImac\fR | |
220 | Matches Ethernet destination address \fImac\fR. | |
221 | ||
222 | .IP \fBdl_type=\fIethertype\fR | |
223 | Matches Ethernet protocol type \fIethertype\fR, which is specified as an | |
224 | integer between 0 and 65535, inclusive, either in decimal or as a | |
225 | hexadecimal number prefixed by \fB0x\fR (e.g. \fB0x0806\fR to match ARP | |
226 | packets). | |
227 | ||
228 | .IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR] | |
229 | Matches IPv4 source address \fIip\fR, which may be specified as an | |
230 | IP address or host name (e.g. \fB192.168.1.1\fR or | |
231 | \fBwww.example.com\fR). The optional \fInetmask\fR allows restricting a | |
232 | match to an IPv4 address prefix. The netmask may be specified as a dotted | |
233 | quad (e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block | |
234 | (e.g. \fB192.168.1.0/24\fR). | |
235 | ||
236 | .IP \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR] | |
237 | Matches IPv4 destination address \fIip\fR. | |
238 | ||
239 | .IP \fBnw_proto=\fIproto\fR | |
240 | Matches IP protocol type \fIproto\fR, which is specified as a decimal | |
241 | number between 0 and 255, inclusive (e.g. 6 to match TCP packets). | |
242 | ||
243 | .IP \fBtp_src=\fIport\fR | |
244 | Matches UDP or TCP source port \fIport\fR, which is specified as a decimal | |
245 | number between 0 and 65535, inclusive (e.g. 80 to match packets originating | |
246 | from a HTTP server). | |
247 | ||
248 | .IP \fBtp_dst=\fIport\fR | |
249 | Matches UDP or TCP destination port \fIport\fR. | |
250 | ||
251 | .IP \fBicmp_type=\fItype\fR | |
252 | Matches ICMP message with \fItype\fR, which is specified as a decimal | |
253 | number between 0 and 255, inclusive. | |
254 | ||
255 | .IP \fBicmp_code=\fIcode\fR | |
256 | Matches ICMP messages with \fIcode\fR. | |
257 | ||
258 | .PP | |
259 | The following shorthand notations are also available: | |
260 | ||
261 | .IP \fBip\fR | |
262 | Same as \fBdl_type=0x0800\fR. | |
263 | ||
264 | .IP \fBicmp\fR | |
265 | Same as \fBdl_type=0x0800,nw_proto=1\fR. | |
266 | ||
267 | .IP \fBtcp\fR | |
268 | Same as \fBdl_type=0x0800,nw_proto=6\fR. | |
269 | ||
270 | .IP \fBudp\fR | |
271 | Same as \fBdl_type=0x0800,nw_proto=17\fR. | |
272 | ||
273 | .IP \fBarp\fR | |
274 | Same as \fBdl_type=0x0806\fR. | |
275 | ||
276 | .PP | |
277 | The \fBadd-flow\fR and \fBadd-flows\fR commands require an additional field: | |
278 | ||
279 | .IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR | |
280 | Specifies a comma-separated list of actions to take on a packet when the | |
281 | flow entry matches. If no \fItarget\fR is specified, then packets | |
282 | matching the flow are dropped. The \fItarget\fR may be a decimal port | |
283 | number designating the physical port on which to output the packet, or one | |
284 | of the following keywords: | |
285 | ||
286 | .RS | |
287 | .IP \fBoutput\fR:\fIport\fR | |
288 | Outputs the packet on the port specified by \fIport\fR. | |
289 | ||
290 | .IP \fBnormal\fR | |
291 | Subjects the packet to the device's normal L2/L3 processing. (This | |
292 | action is not implemented by all OpenFlow switches.) | |
293 | ||
294 | .IP \fBflood\fR | |
295 | Outputs the packet on all switch physical ports other than the port on | |
296 | which it was received and any ports on which flooding is disabled | |
297 | (typically, these would be ports disabled by the IEEE 802.1D spanning | |
298 | tree protocol). | |
299 | ||
300 | .IP \fBall\fR | |
301 | Outputs the packet on all switch physical ports other than the port on | |
302 | which it was received. | |
303 | ||
304 | .IP \fBcontroller\fR:\fImax_len\fR | |
305 | Sends the packet to the OpenFlow controller as a ``packet in'' | |
306 | message. If \fImax_len\fR is a number, then it specifies the maximum | |
307 | number of bytes that should be sent. If \fImax_len\fR is \fBALL\fR or | |
308 | omitted, then the entire packet is sent. | |
309 | ||
310 | .IP \fBlocal\fR | |
311 | Outputs the packet on the ``local port,'' which corresponds to the | |
312 | \fBof\fIn\fR network device (see \fBCONTACTING THE CONTROLLER\fR in | |
8cd4882f | 313 | \fBovs\-openflowd\fR(8) for information on the \fBof\fIn\fR network device). |
064af421 BP |
314 | |
315 | .IP \fBdrop\fR | |
316 | Discards the packet, so no further processing or forwarding takes place. | |
317 | If a drop action is used, no other actions may be specified. | |
318 | ||
319 | .IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR | |
320 | Modifies the VLAN id on a packet. The VLAN tag is added or modified | |
321 | as necessary to match the value specified. If the VLAN tag is added, | |
322 | a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set | |
323 | this). | |
324 | ||
325 | .IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR | |
326 | Modifies the VLAN priority on a packet. The VLAN tag is added or modified | |
327 | as necessary to match the value specified. Valid values are between 0 | |
328 | (lowest) and 7 (highest). If the VLAN tag is added, a vid of zero is used | |
329 | (see the \fBmod_vlan_vid\fR action to set this). | |
330 | ||
331 | .IP \fBstrip_vlan\fR | |
332 | Strips the VLAN tag from a packet if it is present. | |
333 | ||
334 | .IP \fBmod_dl_src\fB:\fImac\fR | |
335 | Sets the source Ethernet address to \fImac\fR. | |
336 | ||
337 | .IP \fBmod_dl_dst\fB:\fImac\fR | |
338 | Sets the destination Ethernet address to \fImac\fR. | |
e423eca6 JP |
339 | |
340 | .IP \fBmod_nw_src\fB:\fIip\fR | |
341 | Sets the IPv4 source address to \fIip\fR. | |
342 | ||
343 | .IP \fBmod_nw_dst\fB:\fIip\fR | |
344 | Sets the IPv4 destination address to \fIip\fR. | |
345 | ||
346 | .IP \fBmod_tp_src\fB:\fIport\fR | |
347 | Sets the TCP or UDP source port to \fIport\fR. | |
348 | ||
349 | .IP \fBmod_tp_dst\fB:\fIport\fR | |
350 | Sets the TCP or UDP destination port to \fIport\fR. | |
064af421 BP |
351 | .RE |
352 | ||
353 | .IP | |
354 | (The OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does | |
355 | not yet expose to the user.) | |
356 | ||
357 | .PP | |
358 | The \fBadd-flow\fR, \fBadd-flows\fR, and \fBdel-flows\fR commands | |
359 | support an additional optional field: | |
360 | ||
361 | .IP \fBpriority=\fIvalue\fR | |
362 | The priority at which a wildcarded entry will match in comparison to | |
363 | others. \fIvalue\fR is a number between 0 and 65535, inclusive. A higher | |
364 | \fIvalue\fR will match before a lower one. An exact-match entry will always | |
365 | have priority over an entry containing wildcards, so it has an implicit | |
366 | priority value of 65535. When adding a flow, if the field is not specified, | |
367 | the flow's priority will default to 32768. | |
368 | ||
369 | .PP | |
370 | The \fBadd-flow\fR and \fBadd-flows\fR commands support additional | |
371 | optional fields: | |
372 | ||
373 | .TP | |
374 | \fBidle_timeout=\fIseconds\fR | |
375 | Causes the flow to expire after the given number of seconds of | |
376 | inactivity. A value of 0 prevents a flow from expiring due to | |
377 | inactivity. The default is 60 seconds. | |
378 | ||
379 | .IP \fBhard_timeout=\fIseconds\fR | |
380 | Causes the flow to expire after the given number of seconds, | |
381 | regardless of activity. A value of 0 (the default) gives the flow no | |
382 | hard expiration deadline. | |
383 | ||
384 | .PP | |
385 | The \fBdump-flows\fR, \fBdump-aggregate\fR, \fBdel-flow\fR | |
386 | and \fBdel-flows\fR commands support one additional optional field: | |
387 | ||
388 | .TP | |
389 | \fBout_port=\fIport\fR | |
390 | If set, a matching flow must include an output action to \fIport\fR. | |
391 | ||
392 | .PP | |
393 | The \fBdump-flows\fR and \fBdump-aggregate\fR commands support an | |
394 | additional optional field: | |
395 | ||
396 | .IP \fBtable=\fInumber\fR | |
397 | If specified, limits the flows about which statistics are gathered to | |
398 | those in the table with the given \fInumber\fR. Tables are numbered | |
399 | as shown by the \fBdump-tables\fR command. | |
400 | ||
401 | If this field is not specified, or if \fInumber\fR is given as | |
402 | \fB255\fR, statistics are gathered about flows from all tables. | |
403 | ||
404 | .SS "Table Entry Output" | |
405 | ||
406 | The \fBdump-tables\fR and \fBdump-aggregate\fR commands print information | |
407 | about the entries in a datapath's tables. Each line of output is a | |
408 | unique flow entry, which begins with some common information: | |
409 | ||
410 | .IP \fBduration\fR | |
411 | The number of seconds the entry has been in the table. | |
412 | ||
413 | .IP \fBtable_id\fR | |
414 | The table that contains the flow. When a packet arrives, the switch | |
415 | begins searching for an entry at the lowest numbered table. Tables are | |
416 | numbered as shown by the \fBdump-tables\fR command. | |
417 | ||
418 | .IP \fBpriority\fR | |
419 | The priority of the entry in relation to other entries within the same | |
420 | table. A higher value will match before a lower one. | |
421 | ||
422 | .IP \fBn_packets\fR | |
423 | The number of packets that have matched the entry. | |
424 | ||
425 | .IP \fBn_bytes\fR | |
426 | The total number of bytes from packets that have matched the entry. | |
427 | ||
428 | .PP | |
429 | The rest of the line consists of a description of the flow entry as | |
430 | described in \fBFlow Syntax\fR, above. | |
431 | ||
432 | ||
433 | .SH OPTIONS | |
434 | .TP | |
435 | \fB--strict\fR | |
436 | Uses strict matching when running flow modification commands. | |
437 | ||
84ee7bcf | 438 | .so lib/ssl.man |
064af421 BP |
439 | .so lib/vlog.man |
440 | .so lib/common.man | |
441 | ||
442 | .SH EXAMPLES | |
443 | ||
444 | The following examples assume that an OpenFlow switch on the local | |
445 | host has been configured to listen for management connections on a | |
446 | Unix domain socket named \fB@RUNDIR@/openflow.sock\fR, e.g. by | |
447 | specifying \fB--listen=punix:@RUNDIR@/openflow.sock\fR on the | |
8cd4882f | 448 | \fBovs\-openflowd\fR(8) command line. |
064af421 BP |
449 | |
450 | .TP | |
451 | \fBovs\-ofctl dump-tables unix:@RUNDIR@/openflow.sock\fR | |
452 | Prints out the switch's table stats. (This is more interesting after | |
453 | some traffic has passed through.) | |
454 | ||
455 | .TP | |
456 | \fBovs\-ofctl dump-flows unix:@RUNDIR@/openflow.sock\fR | |
457 | Prints the flow entries in the switch. | |
458 | ||
459 | .SH "SEE ALSO" | |
460 | ||
461 | .BR ovs\-appctl (8), | |
462 | .BR ovs\-controller (8), | |
463 | .BR ovs\-vswitchd (8) |