0a2a5e9884b83be78625ad57ff7d0c3215385d58
[sliver-openvswitch.git] / utilities / ovs-ofctl.8.in
1 .\" -*- nroff -*-
2 .de IQ
3 .  br
4 .  ns
5 .  IP "\\$1"
6 ..
7 .TH ovs\-ofctl 8 "January 2010" "Open vSwitch" "Open vSwitch Manual"
8 .ds PN ovs\-ofctl
9 .
10 .SH NAME
11 ovs\-ofctl \- administer OpenFlow switches
12 .
13 .SH SYNOPSIS
14 .B ovs\-ofctl
15 [\fIoptions\fR] \fIcommand \fR[\fIswitch\fR] [\fIargs\fR\&...]
16 .
17 .SH DESCRIPTION
18 The
19 .B ovs\-ofctl
20 program is a command line tool for monitoring and administering
21 OpenFlow switches.  It can also show the current state of an OpenFlow
22 switch, including features, configuration, and table entries.
23 .
24 .SS "OpenFlow Switch Management Commands"
25 .PP
26 These commands allow \fBovs\-ofctl\fR to monitor and administer an OpenFlow
27 switch.  It is able to show the current state of a switch, including
28 features, configuration, and table entries.
29 .PP
30 Most of these commands take an argument that specifies the method for
31 connecting to an OpenFlow switch.  The following connection methods
32 are supported:
33 .
34 .RS
35 .so lib/vconn-active.man
36 .
37 .IP "\fIfile\fR"
38 This is short for \fBunix:\fIfile\fR, as long as \fIfile\fR does not
39 contain a colon.
40 .
41 .IP \fIbridge\fR
42 This is short for \fBunix:@RUNDIR@/\fIbridge\fB.mgmt\fR, as long as
43 \fIbridge\fR does not contain a colon.
44 .
45 .IP [\fItype\fB@\fR]\fIdp\fR
46 Attempts to look up the bridge associated with \fIdp\fR and open as
47 above.  If \fItype\fR is given, it specifies the datapath provider of
48 \fIdp\fR, otherwise the default provider \fBsystem\fR is assumed.
49 .RE
50 .
51 .TP
52 \fBshow \fIswitch\fR
53 Prints to the console information on \fIswitch\fR, including
54 information on its flow tables and ports.
55 .
56 .TP
57 \fBstatus \fIswitch\fR [\fIkey\fR]
58 Prints to the console a series of key-value pairs that report the
59 status of \fIswitch\fR.  If \fIkey\fR is specified, only the key-value
60 pairs whose key names begin with \fIkey\fR are printed.  If \fIkey\fR is
61 omitted, all key-value pairs are printed.
62 .
63 .TP
64 \fBdump\-tables \fIswitch\fR
65 Prints to the console statistics for each of the flow tables used by
66 \fIswitch\fR.
67 .
68 .TP
69 \fBdump\-ports \fIswitch\fR [\fInetdev\fR]
70 Prints to the console statistics for network devices associated with 
71 \fIswitch\fR.  If \fInetdev\fR is specified, only the statistics
72 associated with that device will be printed.  \fInetdev\fR can be an
73 OpenFlow assigned port number or device name, e.g. \fBeth0\fR.
74 .
75 .TP
76 \fBmod\-port \fIswitch\fR \fInetdev\fR \fIaction\fR
77 Modify characteristics of an interface monitored by \fIswitch\fR.  
78 \fInetdev\fR can be referred to by its OpenFlow assigned port number or 
79 the device name, e.g. \fBeth0\fR.  The \fIaction\fR may be any one of the
80 following:
81 .
82 .RS
83 .IP \fBup\fR
84 Enables the interface.  This is equivalent to ``ifconfig up'' on a Unix
85 system.
86 .
87 .IP \fBdown\fR
88 Disables the interface.  This is equivalent to ``ifconfig down'' on a Unix
89 system.
90 .
91 .IP \fBflood\fR
92 When a \fIflood\fR action is specified, traffic will be sent out this
93 interface.  This is the default posture for monitored ports.
94 .
95 .IP \fBnoflood\fR
96 When a \fIflood\fR action is specified, traffic will not be sent out 
97 this interface.  This is primarily useful to prevent loops when a
98 spanning tree protocol is not in use.
99 .
100 .RE
101 .
102 .TP
103 \fBdump\-flows \fIswitch \fR[\fIflows\fR]
104 Prints to the console all flow entries in \fIswitch\fR's
105 tables that match \fIflows\fR.  If \fIflows\fR is omitted, all flows
106 in the switch are retrieved.  See \fBFlow Syntax\fR, below, for the
107 syntax of \fIflows\fR.  The output format is described in 
108 \fBTable Entry Output\fR.
109 .
110 .TP
111 \fBdump\-aggregate \fIswitch \fR[\fIflows\fR]
112 Prints to the console aggregate statistics for flows in 
113 \fIswitch\fR's tables that match \fIflows\fR.  If \fIflows\fR is omitted, 
114 the statistics are aggregated across all flows in the switch's flow
115 tables.  See \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR.
116 The output format is descrbed in \fBTable Entry Output\fR.
117 .
118 .IP "\fBqueue\-stats \fIswitch \fR[\fIport \fR[\fIqueue\fR]]"
119 Prints to the console statistics for the specified \fIqueue\fR on
120 \fIport\fR within \fIswitch\fR.  Either of \fIport\fR or \fIqueue\fR
121 or both may be omitted (or equivalently specified as \fBALL\fR).  If
122 both are omitted, statistics are printed for all queues on all ports.
123 If only \fIqueue\fR is omitted, then statistics are printed for all
124 queues on \fIport\fR; if only \fIport\fR is omitted, then statistics
125 are printed for \fIqueue\fR on every port where it exists.
126 .
127 .TP
128 \fBadd\-flow \fIswitch flow\fR
129 Add the flow entry as described by \fIflow\fR to the \fIswitch\fR's 
130 tables.  The flow entry is in the format described in \fBFlow Syntax\fR, 
131 below.
132 .
133 .TP
134 \fBadd\-flows \fIswitch file\fR
135 Add flow entries as described in \fIfile\fR to \fIswitch\fR's 
136 tables.  Each line in \fIfile\fR is a flow entry in the format
137 described in \fBFlow Syntax\fR, below.
138 .
139 .TP
140 \fBmod\-flows \fIswitch flow\fR
141 Modify the actions in entries from the \fIswitch\fR's tables 
142 that match \fIflow\fR.  When invoked with the \fB\-\-strict\fR option,
143 wildcards are not treated as active for matching purposes.  See 
144 \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR.
145 .
146 .TP
147 \fBdel\-flows \fIswitch \fR[\fIflow\fR]
148 Deletes entries from the \fIswitch\fR's tables that match
149 \fIflow\fR.  When invoked with the \fB\-\-strict\fR option, wildcards are 
150 not treated as active for matching purposes.  If \fIflow\fR is 
151 omitted and the \fB\-\-strict\fR option is not used, all flows in the 
152 switch's tables are removed.  See \fBFlow Syntax\fR, below, for the 
153 syntax of \fIflows\fR.
154 .
155 .IP "\fBsnoop \fIswitch\fR"
156 Connects to \fIswitch\fR and prints to the console all OpenFlow
157 messages received.  Unlike other \fBovs\-ofctl\fR commands, if
158 \fIswitch\fR is the name of a bridge, then the \fBsnoop\fR command
159 connects to a Unix domain socket named
160 \fB@RUNDIR@/\fIbridge\fB.snoop\fR.  \fBovs\-vswitchd\fR listens on
161 such a socket for each bridge and sends to it all of the OpenFlow
162 messages sent to or received from its configured OpenFlow controller.
163 Thus, this command can be used to view OpenFlow protocol activity
164 between a switch and its controller.
165 .IP
166 When a switch has more than one controller configured, only the
167 traffic to and from a single controller is output.  If none of the
168 controllers is configured as a master or a slave (using a Nicira
169 extension to OpenFlow), then a controller is chosen arbitrarily among
170 them.  If there is a master controller, it is chosen; otherwise, if
171 there are any controllers that are not masters or slaves, one is
172 chosen arbitrarily; otherwise, a slave controller is chosen
173 arbitrarily.  This choice is made once at connection time and does not
174 change as controllers reconfigure their roles.
175 .IP
176 If a switch has no controller configured, or if
177 the configured controller is disconnected, no traffic is sent, so
178 monitoring will not show any traffic.
179 .
180 .IQ "\fBmonitor \fIswitch\fR [\fImiss-len\fR]"
181 Connects to \fIswitch\fR and prints to the console all OpenFlow
182 messages received.  Usually, \fIswitch\fR should specify a connection
183 named on \fBovs\-openflowd\fR(8)'s \fB\-l\fR or \fB\-\-listen\fR command line
184 option.
185 .IP
186 If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set
187 configuration'' message at connection setup time that requests
188 \fImiss-len\fR bytes of each packet that misses the flow table.  Open vSwitch
189 does not send these and other asynchronous messages to an
190 \fBovs\-ofctl monitor\fR client connection unless a nonzero value is
191 specified on this argument.  (Thus, if \fImiss\-len\fR is not
192 specified, very little traffic will ordinarily be printed.)
193 .IP
194 This command may be useful for debugging switch or controller
195 implementations.
196 .
197 .SS "OpenFlow Switch and Controller Commands"
198 .
199 The following commands, like those in the previous section, may be
200 applied to OpenFlow switches, using any of the connection methods
201 described in that section.  Unlike those commands, these may also be
202 applied to OpenFlow controllers.
203 .
204 .TP
205 \fBprobe \fItarget\fR
206 Sends a single OpenFlow echo-request message to \fItarget\fR and waits
207 for the response.  With the \fB\-t\fR or \fB\-\-timeout\fR option, this
208 command can test whether an OpenFlow switch or controller is up and
209 running.
210 .
211 .TP
212 \fBping \fItarget \fR[\fIn\fR]
213 Sends a series of 10 echo request packets to \fItarget\fR and times
214 each reply.  The echo request packets consist of an OpenFlow header
215 plus \fIn\fR bytes (default: 64) of randomly generated payload.  This
216 measures the latency of individual requests.
217 .
218 .TP
219 \fBbenchmark \fItarget n count\fR
220 Sends \fIcount\fR echo request packets that each consist of an
221 OpenFlow header plus \fIn\fR bytes of payload and waits for each
222 response.  Reports the total time required.  This is a measure of the
223 maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte
224 messages.
225 .
226 .SS "Flow Syntax"
227 .PP
228 Some \fBovs\-ofctl\fR commands accept an argument that describes a flow or
229 flows.  Such flow descriptions comprise a series
230 \fIfield\fB=\fIvalue\fR assignments, separated by commas or white
231 space.  (Embedding spaces into a flow description normally requires
232 quoting to prevent the shell from breaking the description into
233 multiple arguments.)
234 .PP
235 Flow descriptions should be in \fBnormal form\fR.  This means that a
236 flow may only specify a value for an L3 field if it also specifies a
237 particular L2 protocol, and that a flow may only specify an L4 field
238 if it also specifies particular L2 and L3 protocol types.  For
239 example, if the L2 protocol type \fBdl_type\fR is wildcarded, then L3
240 fields \fBnw_src\fR, \fBnw_dst\fR, and \fBnw_proto\fR must also be
241 wildcarded.  Similarly, if \fBdl_type\fR or \fBnw_proto\fR (the L3
242 protocol type) is wildcarded, so must be \fBtp_dst\fR and
243 \fBtp_src\fR, which are L4 fields.  \fBovs\-ofctl\fR will warn about
244 flows not in normal form.
245 .PP
246 The following field assignments describe how a flow matches a packet.
247 If any of these assignments is omitted from the flow syntax, the field
248 is treated as a wildcard; thus, if all of them are omitted, the
249 resulting flow matches all packets.  The string \fB*\fR or \fBANY\fR
250 may be specified to explicitly mark any of these fields as a wildcard.  
251 (\fB*\fR should be quoted to protect it from shell expansion.)
252 .
253 .IP \fBin_port=\fIport_no\fR
254 Matches physical port \fIport_no\fR.  Switch ports are numbered as
255 displayed by \fBovs\-ofctl show\fR.
256 .
257 .IP \fBdl_vlan=\fIvlan\fR
258 Matches IEEE 802.1q Virtual LAN tag \fIvlan\fR.  Specify \fB0xffff\fR
259 as \fIvlan\fR to match packets that are not tagged with a Virtual LAN;
260 otherwise, specify a number between 0 and 4095, inclusive, as the
261 12-bit VLAN ID to match.
262 .
263 .IP \fBdl_vlan_pcp=\fIpriority\fR
264 Matches IEEE 802.1q Priority Code Point (PCP) \fIpriority\fR, which is
265 specified as a value between 0 and 7, inclusive.  A higher value
266 indicates a higher frame priority level.
267 .
268 .IP \fBdl_src=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
269 .IQ \fBdl_dst=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
270 Matches an Ethernet source (or destination) address specified as 6
271 pairs of hexadecimal digits delimited by colons
272 (e.g. \fB00:0A:E4:25:6B:B0\fR).
273 .
274 .IP \fBdl_type=\fIethertype\fR
275 Matches Ethernet protocol type \fIethertype\fR, which is specified as an
276 integer between 0 and 65535, inclusive, either in decimal or as a 
277 hexadecimal number prefixed by \fB0x\fR (e.g. \fB0x0806\fR to match ARP 
278 packets).
279 .
280 .IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR]
281 .IQ \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR]
282 When \fBdl_type\fR is 0x0800 (possibly via shorthand, e.g. \fBip\fR
283 or \fBtcp\fR), matches IPv4 source (or destination) address \fIip\fR,
284 which may be specified as an IP address or host name
285 (e.g. \fB192.168.1.1\fR or \fBwww.example.com\fR).  The optional
286 \fInetmask\fR allows restricting a match to an IPv4 address prefix.
287 The netmask may be specified as a dotted quad
288 (e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block
289 (e.g. \fB192.168.1.0/24\fR).
290 .IP
291 When \fBdl_type=0x0806\fR or \fBarp\fR is specified, matches the
292 \fBar_spa\fR or \fBar_tpa\fR field, respectively, in ARP packets for
293 IPv4 and Ethernet.
294 .IP
295 When \fBdl_type\fR is wildcarded or set to a value other than 0x0800
296 or 0x0806, the values of \fBnw_src\fR and \fBnw_dst\fR are ignored
297 (see \fBFlow Syntax\fR above).
298 .
299 .IP \fBnw_proto=\fIproto\fR
300 When \fBip\fR or \fBdl_type=0x0800\fR is specified, matches IP
301 protocol type \fIproto\fR, which is specified as a decimal number
302 between 0 and 255, inclusive (e.g. 6 to match TCP packets).
303 .IP
304 When \fBarp\fR or \fBdl_type=0x0806\fR is specified, matches the lower
305 8 bits of the ARP opcode.  ARP opcodes greater than 255 are treated as
306 0.
307 .IP
308 When \fBdl_type\fR is wildcarded or set to a value other than 0x0800
309 or 0x0806, the value of \fBnw_proto\fR is ignored (see \fBFlow
310 Syntax\fR above).
311 .
312 .IP \fBnw_tos=\fItos\fR
313 Matches IP ToS/DSCP field \fItos\fR, which is specified as a decimal 
314 number between 0 and 255, inclusive.  Note that the two lower reserved
315 bits are ignored for matching purposes.
316 .IP
317 The value of \fBnw_proto\fR is ignored unless \fBdl_type=0x0800\fR,
318 \fBip\fR, \fBicmp\fR, \fBtcp\fR, or \fBudp\fR is also specified (see
319 \fBFlow Syntax\fR above).
320 .
321 .IP \fBtp_src=\fIport\fR
322 .IQ \fBtp_dst=\fIport\fR
323 When \fBdl_type\fR and \fBnw_proto\fR specify TCP or UDP, \fBtp_src\fR
324 and \fBtp_dst\fR match the UDP or TCP source or destination port
325 \fIport\fR, respectively. which is specified as a decimal number
326 between 0 and 65535, inclusive (e.g. 80 to match packets originating
327 from a HTTP server).
328 .IP
329 When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of
330 these settings are ignored (see \fBFlow Syntax\fR above).
331 .
332 .IP \fBicmp_type=\fItype\fR
333 .IQ \fBicmp_code=\fIcode\fR
334 When \fBdl_type\fR and \fBnw_proto\fR specify ICMP, \fItype\fR matches
335 the ICMP type and \fIcode\fR matches the ICMP code.  Each is specified
336 as a decimal number between 0 and 255, inclusive.
337 .IP
338 When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of
339 these settings are ignored (see \fBFlow Syntax\fR above).
340 .IP \fBtun_id=\fItunnel\-id\fR
341 Matches tunnel identifier \fItunnel\-id\fR.  Only packets that arrive
342 over a tunnel that carries a key (e.g. GRE with the RFC 2890 key
343 extension) will have a nonzero tunnel ID.
344 .IP
345 \fBtun_id\fR requires use of one of two Nicira extensions to OpenFlow:
346 .RS
347 .IP "NXM (Nicira Extended Match)"
348 This extension fully supports \fBtun_id\fR. 
349 .IP "Tunnel ID from Cookie"
350 This extension supports \fBtun_id\fR with two caveats: the top 32 bits
351 of the \fBcookie\fR (see below) are used for \fItunnel\-id\fR and thus
352 unavailable for other use, and specifying \fBtun_id\fR on
353 \fBdump\-flows\fR or \fBdump\-aggregate\fR has no effect.
354 .RE
355 .IP
356 When \fBtun_id\fR is specified, \fBovs\-ofctl\fR will automatically
357 attempt to negotiate use of one of these extensions.  It will use the
358 ``tunnel ID from cookie'' extension if neither caveat applies and NXM
359 otherwise.  If the switch does not support the needed extension, then
360 \fBovs\-ofctl\fR will report a fatal error.
361 .IP "\fBreg\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]"
362 Matches \fIvalue\fR either exactly or with optional \fImask\fR in
363 register number \fIidx\fR.  The valid range of \fIidx\fR depends on
364 the switch.  \fIvalue\fR and \fImask\fR are 32-bit integers, by
365 default in decimal (use a \fB0x\fR prefix to specify hexadecimal).
366 Arbitrary \fImask\fR values are allowed: a 1-bit in \fImask\fR
367 indicates that the corresponding bit in \fIvalue\fR must match
368 exactly, and a 0-bit wildcards that bit.
369 .IP
370 When a packet enters an OpenFlow switch, all of the registers are set
371 to 0.  Only explicit Nicira extension actions change register values.
372 .IP
373 Register matches require support for the NXM (Nicira Extended Match)
374 extension to OpenFlow.  When a register match is specified,
375 \fBovs\-ofctl\fR will automatically attempt to negotiate use of this
376 extension.  If the switch does not support NXM, then \fBovs\-ofctl\fR
377 will report a fatal error.
378 .
379 .PP
380 The following shorthand notations are also available:
381 .
382 .IP \fBip\fR
383 Same as \fBdl_type=0x0800\fR.
384 .
385 .IP \fBicmp\fR
386 Same as \fBdl_type=0x0800,nw_proto=1\fR.
387 .
388 .IP \fBtcp\fR
389 Same as \fBdl_type=0x0800,nw_proto=6\fR.
390 .
391 .IP \fBudp\fR
392 Same as \fBdl_type=0x0800,nw_proto=17\fR.
393 .
394 .IP \fBarp\fR
395 Same as \fBdl_type=0x0806\fR.
396 .
397 .PP
398 The \fBadd\-flow\fR and \fBadd\-flows\fR commands require an additional
399 field, which must be the final field specified:
400 .
401 .IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR
402 Specifies a comma-separated list of actions to take on a packet when the 
403 flow entry matches.  If no \fItarget\fR is specified, then packets
404 matching the flow are dropped.  The \fItarget\fR may be a decimal port 
405 number designating the physical port on which to output the packet, or one 
406 of the following keywords:
407 .
408 .RS
409 .IP \fBoutput\fR:\fIport\fR
410 Outputs the packet on the port specified by \fIport\fR.
411 .
412 .IP \fBenqueue\fR:\fIport\fB:\fIqueue\fR
413 Enqueues the packet on the specified \fIqueue\fR within port
414 \fIport\fR.  The number of supported queues depends on the switch;
415 some OpenFlow implementations do not support queuing at all.
416 .
417 .IP \fBnormal\fR
418 Subjects the packet to the device's normal L2/L3 processing.  (This
419 action is not implemented by all OpenFlow switches.)
420 .
421 .IP \fBflood\fR
422 Outputs the packet on all switch physical ports other than the port on
423 which it was received and any ports on which flooding is disabled
424 (typically, these would be ports disabled by the IEEE 802.1D spanning
425 tree protocol).
426 .
427 .IP \fBall\fR
428 Outputs the packet on all switch physical ports other than the port on
429 which it was received.
430 .
431 .IP \fBcontroller\fR:\fImax_len\fR
432 Sends the packet to the OpenFlow controller as a ``packet in''
433 message.  If \fImax_len\fR is a number, then it specifies the maximum
434 number of bytes that should be sent.  If \fImax_len\fR is \fBALL\fR or
435 omitted, then the entire packet is sent.
436 .
437 .IP \fBlocal\fR
438 Outputs the packet on the ``local port,'' which corresponds to the
439 \fBof\fIn\fR network device (see \fBCONTACTING THE CONTROLLER\fR in
440 \fBovs\-openflowd\fR(8) for information on the \fBof\fIn\fR network device).
441 .
442 .IP \fBdrop\fR
443 Discards the packet, so no further processing or forwarding takes place.
444 If a drop action is used, no other actions may be specified.
445 .
446 .IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR
447 Modifies the VLAN id on a packet.  The VLAN tag is added or modified 
448 as necessary to match the value specified.  If the VLAN tag is added,
449 a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set
450 this).
451 .
452 .IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR
453 Modifies the VLAN priority on a packet.  The VLAN tag is added or modified 
454 as necessary to match the value specified.  Valid values are between 0
455 (lowest) and 7 (highest).  If the VLAN tag is added, a vid of zero is used 
456 (see the \fBmod_vlan_vid\fR action to set this).
457 .
458 .IP \fBstrip_vlan\fR
459 Strips the VLAN tag from a packet if it is present.
460 .
461 .IP \fBmod_dl_src\fB:\fImac\fR
462 Sets the source Ethernet address to \fImac\fR.
463 .
464 .IP \fBmod_dl_dst\fB:\fImac\fR
465 Sets the destination Ethernet address to \fImac\fR.
466 .
467 .IP \fBmod_nw_src\fB:\fIip\fR
468 Sets the IPv4 source address to \fIip\fR.
469 .
470 .IP \fBmod_nw_dst\fB:\fIip\fR
471 Sets the IPv4 destination address to \fIip\fR.
472 .
473 .IP \fBmod_tp_src\fB:\fIport\fR
474 Sets the TCP or UDP source port to \fIport\fR.
475 .
476 .IP \fBmod_tp_dst\fB:\fIport\fR
477 Sets the TCP or UDP destination port to \fIport\fR.
478 .
479 .IP \fBmod_nw_tos\fB:\fItos\fR
480 Sets the IP ToS/DSCP field to \fItos\fR.  Valid values are between 0 and
481 255, inclusive.  Note that the two lower reserved bits are never
482 modified.
483 .
484 .RE
485 .IP
486 The following actions are Nicira vendor extensions that, as of this writing, are
487 only known to be implemented by Open vSwitch:
488 .
489 .RS
490 .
491 .IP \fBresubmit\fB:\fIport\fR
492 Re-searches the OpenFlow flow table with the \fBin_port\fR field
493 replaced by \fIport\fR and executes the actions found, if any, in
494 addition to any other actions in this flow entry.  Recursive
495 \fBresubmit\fR actions are ignored.
496 .
497 .IP \fBset_tunnel\fB:\fIid\fR
498 .IQ \fBset_tunnel64\fB:\fIid\fR
499 If outputting to a port that encapsulates the packet in a tunnel and
500 supports an identifier (such as GRE), sets the identifier to \fBid\fR.
501 If the \fBset_tunnel\fR form is used and \fIid\fR fits in 32 bits,
502 then this uses an action extension that is supported by Open vSwitch
503 1.0 and later.  Otherwise, if \fIid\fR is a 64-bit value, it requires
504 Open vSwitch 1.1 or later.
505 .
506 .IP \fBdrop_spoofed_arp\fR
507 Stops processing further actions, if the packet being processed is an
508 Ethernet+IPv4 ARP packet for which the source Ethernet address inside
509 the ARP packet differs from the source Ethernet address in the
510 Ethernet header.
511 .
512 This is useful because OpenFlow does not provide a way to match on the
513 Ethernet addresses inside ARP packets, so there is no other way to
514 drop spoofed ARPs other than sending every ARP packet to a controller.
515 .
516 .IP \fBset_queue\fB:\fIqueue\fR
517 Sets the queue that should be used to \fIqueue\fR when packets are
518 output.  The number of supported queues depends on the switch; some
519 OpenFlow implementations do not support queuing at all.
520 .
521 .IP \fBpop_queue\fR
522 Restores the queue to the value it was before any \fBset_queue\fR
523 actions were applied.
524 .
525 .IP \fBnote:\fR[\fIhh\fR]...
526 Does nothing at all.  Any number of bytes represented as hex digits
527 \fIhh\fR may be included.  Pairs of hex digits may be separated by
528 periods for readability.
529 .
530 .IP "\fBmove:\fIsrc\fB[\fIstart\fB..\fIend\fB]->\fIdst\fB[\fIstart\fB..\fIend\fB]\fR"
531 Copies the named bits from field \fIsrc\fR to field \fIdst\fR.
532 \fIsrc\fR and \fIdst\fR must be NXM field names as defined in
533 \fBnicira\-ext.h\fR, e.g. \fBNXM_OF_UDP_SRC\fR or \fBNXM_NX_REG0\fR.
534 Each \fIstart\fR and \fIend\fR pair, which are inclusive, must specify
535 the same number of bits and must fit within its respective field.
536 Shorthands for \fB[\fIstart\fB..\fIend\fB]\fR exist: use
537 \fB[\fIbit\fB]\fR to specify a single bit or \fB[]\fR to specify an
538 entire field.
539 .IP
540 Examples: \fBmove:NXM_NX_REG0[0..5]\->NXM_NX_REG1[26..31]\fR copies the
541 six bits numbered 0 through 5, inclusive, in register 0 into bits 26
542 through 31, inclusive;
543 \fBmove:NXM_NX_REG0[0..15]->NXM_OF_VLAN_TCI[]\fR copies the least
544 significant 16 bits of register 0 into the VLAN TCI field.
545 .
546 .IP "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]"
547 Writes \fIvalue\fR to bits \fIstart\fR through \fIend\fR, inclusive,
548 in field \fBdst\fR.
549 .IP
550 Example: \fBload:55\->NXM_NX_REG2[0..5]\fR loads value 55 (bit pattern
551 \fB110111\fR) into bits 0 through 5, inclusive, in register 2.
552 .
553 .IP "\fBmultipath(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIn_links\fB, \fIarg\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR"
554 Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter,
555 then the applies multipath link selection \fIalgorithm\fR (with
556 parameter \fIarg\fR) to choose one of \fIn_links\fR output links
557 numbered 0 through \fIn_links\fR minus 1, and stores the link into
558 \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM register as
559 described above.
560 .IP
561 Currently, \fIfields\fR must be either \fBeth_src\fR or
562 \fBsymmetric_l4\fR and \fIalgorithm\fR must be one of \fBmodulo_n\fR,
563 \fBhash_threshold\fR, \fBhrw\fR, and \fBiter_hash\fR.  Only
564 the \fBiter_hash\fR algorithm uses \fIarg\fR.
565 .IP
566 Refer to \fBnicira\-ext.h\fR for more details.
567 .RE
568 .
569 .IP
570 (The OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does
571 not yet expose to the user.)
572 .
573 .PP
574 The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands
575 support an additional optional field:
576 .
577 .IP \fBcookie=\fIvalue\fR
578 .
579 A cookie is an opaque identifier that can be associated with the flow.
580 \fIvalue\fR can be any 64-bit number and need not be unique among
581 flows.
582 .
583 .PP
584 The following additional field sets the priority for flows added by
585 the \fBadd\-flow\fR and \fBadd\-flows\fR commands.  For
586 \fBmod\-flows\fR and \fBdel\-flows\fR when \fB\-\-strict\fR is
587 specified, priority must match along with the rest of the flow
588 specification.  Other commands ignore the priority value.
589 .
590 .IP \fBpriority=\fIvalue\fR
591 The priority at which a wildcarded entry will match in comparison to
592 others.  \fIvalue\fR is a number between 0 and 65535, inclusive.  A higher 
593 \fIvalue\fR will match before a lower one.  An exact-match entry will always 
594 have priority over an entry containing wildcards, so it has an implicit 
595 priority value of 65535.  When adding a flow, if the field is not specified, 
596 the flow's priority will default to 32768.
597 .
598 .PP
599 The \fBadd\-flow\fR and \fBadd\-flows\fR commands support additional
600 optional fields:
601 .
602 .TP
603 \fBidle_timeout=\fIseconds\fR
604 Causes the flow to expire after the given number of seconds of
605 inactivity.  A value of 0 (the default) prevents a flow from expiring due to
606 inactivity.
607 .
608 .IP \fBhard_timeout=\fIseconds\fR
609 Causes the flow to expire after the given number of seconds,
610 regardless of activity.  A value of 0 (the default) gives the flow no
611 hard expiration deadline.
612 .
613 .PP
614 The \fBdump\-flows\fR, \fBdump\-aggregate\fR, \fBdel\-flow\fR 
615 and \fBdel\-flows\fR commands support one additional optional field:
616 .
617 .TP
618 \fBout_port=\fIport\fR
619 If set, a matching flow must include an output action to \fIport\fR.
620 .
621 .PP
622 The \fBdump\-flows\fR and \fBdump\-aggregate\fR commands support an
623 additional optional field:
624 .
625 .IP \fBtable=\fInumber\fR
626 If specified, limits the flows about which statistics are gathered to
627 those in the table with the given \fInumber\fR.  Tables are numbered
628 as shown by the \fBdump\-tables\fR command.
629 .
630 If this field is not specified, or if \fInumber\fR is given as
631 \fB255\fR, statistics are gathered about flows from all tables.
632 .
633 .SS "Table Entry Output"
634 .
635 The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information 
636 about the entries in a datapath's tables.  Each line of output is a 
637 unique flow entry, which begins with some common information:
638 .
639 .IP \fBduration\fR
640 The number of seconds the entry has been in the table.
641 .
642 .IP \fBtable_id\fR
643 The table that contains the flow.  When a packet arrives, the switch 
644 begins searching for an entry at the lowest numbered table.  Tables are 
645 numbered as shown by the \fBdump\-tables\fR command.
646 .
647 .IP \fBpriority\fR
648 The priority of the entry in relation to other entries within the same
649 table.  A higher value will match before a lower one.
650 .
651 .IP \fBn_packets\fR
652 The number of packets that have matched the entry.
653 .
654 .IP \fBn_bytes\fR
655 The total number of bytes from packets that have matched the entry.
656 .
657 .PP
658 The rest of the line consists of a description of the flow entry as 
659 described in \fBFlow Syntax\fR, above.
660 .
661 .
662 .SH OPTIONS
663 .TP
664 \fB\-\-strict\fR
665 Uses strict matching when running flow modification commands.
666 .
667 .IP "\fB\-F \fIformat\fR"
668 .IQ "\fB\-\-flow\-format=\fIformat\fR"
669 \fBovs\-ofctl\fR supports the following flow formats, in order of
670 increasing capability:
671 .RS
672 .IP "\fBopenflow10\fR"
673 This is the standard OpenFlow 1.0 flow format.  It should be supported
674 by all OpenFlow switches.
675 .
676 .IP "\fBtun_id_from_cookie\fR"
677 This Nicira extension to OpenFlow adds minimal and limited support for
678 \fBtun_id\fR, but it does not support any other Nicira flow
679 extensions.  (This flow format is deprecated.)
680 .
681 .IP "\fBnxm\fR (Nicira Extended Match)"
682 This Nicira extension to OpenFlow is flexible and extensible.  It
683 supports all of the Nicira flow extensions, such as \fBtun_id\fR and
684 registers.
685 .RE
686 .IP
687 Usually, \fBovs\-ofctl\fR picks the correct format automatically.  For
688 commands that modify the flow table, \fBovs\-ofctl\fR by default uses
689 the most widely supported flow format that supports the flows being
690 added.  For commands that query the flow table, \fBovs\-ofctl\fR by
691 default queries and uses the most advanced format supported by the
692 switch.
693 .IP
694 This option, where \fIformat\fR is one of the formats listed in the
695 above table, overrides \fBovs\-ofctl\fR's default choice of flow
696 format.  If a command cannot work as requested using the requested
697 flow format, \fBovs\-ofctl\fR will report a fatal error.
698 .
699 .IP "\fB\-m\fR"
700 .IQ "\fB\-\-more\fR"
701 Increases the verbosity of OpenFlow messages printed and logged by
702 \fBovs\-ofctl\fR commands.  Specify this option more than once to
703 increase verbosity further.
704 .SS "Public Key Infrastructure Options"
705 .so lib/ssl.man
706 .so lib/vlog.man
707 .so lib/common.man
708 .
709 .SH EXAMPLES
710 .
711 The following examples assume that an OpenFlow switch on the local
712 host has been configured to listen for management connections on a
713 Unix domain socket named \fB@RUNDIR@/openflow.sock\fR, e.g. by
714 specifying \fB\-\-listen=punix:@RUNDIR@/openflow.sock\fR on the
715 \fBovs\-openflowd\fR(8) command line.
716 .
717 .TP
718 \fBovs\-ofctl dump\-tables unix:@RUNDIR@/openflow.sock\fR
719 Prints out the switch's table stats.  (This is more interesting after
720 some traffic has passed through.)
721 .
722 .TP
723 \fBovs\-ofctl dump\-flows unix:@RUNDIR@/openflow.sock\fR
724 Prints the flow entries in the switch.
725 .
726 .SH "SEE ALSO"
727 .
728 .BR ovs\-appctl (8),
729 .BR ovs\-controller (8),
730 .BR ovs\-vswitchd (8)