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