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