7 .TH ovs\-ofctl 8 "January 2011" "Open vSwitch" "Open vSwitch Manual"
11 ovs\-ofctl \- administer OpenFlow switches
15 [\fIoptions\fR] \fIcommand \fR[\fIswitch\fR] [\fIargs\fR\&...]
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.
24 .SS "OpenFlow Switch Management Commands"
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.
30 Most of these commands take an argument that specifies the method for
31 connecting to an OpenFlow switch. The following connection methods
35 .so lib/vconn-active.man
38 This is short for \fBunix:\fIfile\fR, as long as \fIfile\fR does not
42 This is short for \fBunix:@RUNDIR@/\fIbridge\fB.mgmt\fR, as long as
43 \fIbridge\fR does not contain a colon.
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.
53 Prints to the console information on \fIswitch\fR, including
54 information on its flow tables and ports.
57 \fBdump\-tables \fIswitch\fR
58 Prints to the console statistics for each of the flow tables used by
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.
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
77 Enables the interface. This is equivalent to ``ifconfig up'' on a Unix
81 Disables the interface. This is equivalent to ``ifconfig down'' on a Unix
85 When a \fIflood\fR action is specified, traffic will be sent out this
86 interface. This is the default posture for monitored ports.
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.
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.
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.
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.
120 .SS "OpenFlow Switch Flow Table Commands"
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.
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.
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.
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.
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.
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.
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
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.
173 .SS "OpenFlow Switch Monitoring Commands"
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.
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.
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.
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.
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.)
213 This command may be useful for debugging switch or controller
216 .SS "OpenFlow Switch and Controller Commands"
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.
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
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.
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
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
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.
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.)
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.
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.
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.
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).
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:
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
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.)
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
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).
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
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).
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
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.
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
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
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.
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
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
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).
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.
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).
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.
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
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.
407 The following shorthand notations are also available:
410 Same as \fBdl_type=0x0800\fR.
413 Same as \fBdl_type=0x0800,nw_proto=1\fR.
416 Same as \fBdl_type=0x0800,nw_proto=6\fR.
419 Same as \fBdl_type=0x0800,nw_proto=17\fR.
422 Same as \fBdl_type=0x0806\fR.
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.
431 .IP \fBvlan_tci=\fItci\fR[\fB/\fImask\fR]
432 Matches modified VLAN TCI \fItci\fR. If \fImask\fR is omitted,
433 \fItci\fR is the exact VLAN TCI to match; if \fImask\fR is specified,
434 then a 1-bit in \fItci\fR indicates that the corresponding bit in
435 \fItci\fR must match exactly, and a 0-bit wildcards that bit. Both
436 \fItci\fR and \fImask\fR are 16-bit values that are decimal by
437 default; use a \fB0x\fR prefix to specify them in hexadecimal.
440 The value that \fBvlan_tci\fR matches against is 0 for a packet that
441 has no 802.1Q header. Otherwise, it is the TCI value from the 802.1Q
442 header with the CFI bit (with value \fB0x1000\fR) forced to 1.
447 Match only packets without an 802.1Q header.
448 .IP \fBvlan_tci=0xf123\fR
449 Match packets tagged with priority 7 in VLAN 0x123.
450 .IP \fBvlan_tci=0x1123/0x1fff\fR
451 Match packets tagged with VLAN 0x123 (and any priority).
452 .IP \fBvlan_tci=0x5000/0xf000\fR
453 Match packets tagged with priority 2 (in any VLAN).
454 .IP \fBvlan_tci=0/0xfff\fR
455 Match packets with no 802.1Q header or tagged with VLAN 0 (and any
457 .IP \fBvlan_tci=0x5000/0xe000\fR
458 Match packets with no 802.1Q header or tagged with priority 2 (in any
460 .IP \fBvlan_tci=0/0xefff\fR
461 Match packets with no 802.1Q header or tagged with VLAN 0 and priority
465 Some of these matching possibilities can also be achieved with
466 \fBdl_vlan\fR and \fBdl_vlan_pcp\fR.
468 .IP \fBarp_sha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
469 .IQ \fBarp_tha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
470 When \fBdl_type\fR specifies ARP, \fBarp_sha\fR and \fBarp_tha\fR match
471 the source and target hardware address, respectively. An address is
472 specified as 6 pairs of hexadecimal digits delimited by colons.
474 .IP \fBipv6_src=\fIipv6\fR[\fB/\fInetmask\fR]
475 .IQ \fBipv6_dst=\fIipv6\fR[\fB/\fInetmask\fR]
476 When \fBdl_type\fR is 0x86dd (possibly via shorthand, e.g., \fBipv6\fR
477 or \fBtcp6\fR), matches IPv6 source (or destination) address \fIipv6\fR,
478 which may be specified as defined in RFC 2373. The preferred format is
479 \fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fR, where
480 \fIx\fR are the hexadecimal values of the eight 16-bit pieces of the
481 address. A single instance of \fB::\fR may be used to indicate multiple
482 groups of 16-bits of zeros. The optional \fInetmask\fR allows
483 restricting a match to an IPv6 address prefix. A netmask is specified
484 as a CIDR block (e.g. \fB2001:db8:3c4d:1::/64\fR).
486 .IP \fBnd_target=\fIipv6\fR
487 When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify
488 IPv6 Neighbor Discovery (ICMPv6 type 135 or 136), matches the target address
489 \fIipv6\fR. \fIipv6\fR is in the same format described earlier for the
490 \fBipv6_src\fR and \fBipv6_dst\fR fields.
492 .IP \fBnd_sll=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
493 When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify IPv6
494 Neighbor Solicitation (ICMPv6 type 135), matches the source link\-layer
495 address option. An address is specified as 6 pairs of hexadecimal
496 digits delimited by colons.
498 .IP \fBnd_tll=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
499 When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify IPv6
500 Neighbor Advertisement (ICMPv6 type 136), matches the target link\-layer
501 address option. An address is specified as 6 pairs of hexadecimal
502 digits delimited by colons.
504 .IP \fBtun_id=\fItunnel-id\fR[\fB/\fImask\fR]
505 Matches tunnel identifier \fItunnel-id\fR. Only packets that arrive
506 over a tunnel that carries a key (e.g. GRE with the RFC 2890 key
507 extension) will have a nonzero tunnel ID. If \fImask\fR is omitted,
508 \fItunnel-id\fR is the exact tunnel ID to match; if \fImask\fR is
509 specified, then a 1-bit in \fImask\fR indicates that the corresponding
510 bit in \fItunnel-id\fR must match exactly, and a 0-bit wildcards that
513 In an attempt to be compatible with more switches, \fBovs\-ofctl\fR will
514 prefer to use the ``tunnel ID from cookie'' Nicira extension to NXM.
515 The use of this extension comes with three caveats: the top 32 bits of
516 the \fBcookie\fR (see below) are used for \fItunnel-id\fR and thus
517 unavailable for other use, specifying \fBtun_id\fR on \fBdump\-flows\fR
518 or \fBdump\-aggregate\fR has no effect, and \fImask\fR is not supported.
519 If any of these caveats apply, \fBovs-ofctl\fR will use NXM.
521 .IP "\fBreg\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]"
522 Matches \fIvalue\fR either exactly or with optional \fImask\fR in
523 register number \fIidx\fR. The valid range of \fIidx\fR depends on
524 the switch. \fIvalue\fR and \fImask\fR are 32-bit integers, by
525 default in decimal (use a \fB0x\fR prefix to specify hexadecimal).
526 Arbitrary \fImask\fR values are allowed: a 1-bit in \fImask\fR
527 indicates that the corresponding bit in \fIvalue\fR must match
528 exactly, and a 0-bit wildcards that bit.
530 When a packet enters an OpenFlow switch, all of the registers are set
531 to 0. Only explicit Nicira extension actions change register values.
534 Defining IPv6 flows (those with \fBdl_type\fR equal to 0x86dd) requires
535 support for NXM. The following shorthand notations are available for
539 Same as \fBdl_type=0x86dd\fR.
542 Same as \fBdl_type=0x86dd,nw_proto=6\fR.
545 Same as \fBdl_type=0x86dd,nw_proto=17\fR.
548 Same as \fBdl_type=0x86dd,nw_proto=58\fR.
551 Finally, field assignments to \fBduration\fR, \fBn_packets\fR, or
552 \fBn_bytes\fR are ignored to allow output from the \fBdump\-flows\fR
553 command to be used as input for other commands that parse flows.
556 The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands
557 require an additional field, which must be the final field specified:
559 .IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR
560 Specifies a comma-separated list of actions to take on a packet when the
561 flow entry matches. If no \fItarget\fR is specified, then packets
562 matching the flow are dropped. The \fItarget\fR may be a decimal port
563 number designating the physical port on which to output the packet, or one
564 of the following keywords:
567 .IP \fBoutput\fR:\fIport\fR
568 Outputs the packet on the port specified by \fIport\fR.
570 .IP \fBenqueue\fR:\fIport\fB:\fIqueue\fR
571 Enqueues the packet on the specified \fIqueue\fR within port
572 \fIport\fR. The number of supported queues depends on the switch;
573 some OpenFlow implementations do not support queuing at all.
576 Subjects the packet to the device's normal L2/L3 processing. (This
577 action is not implemented by all OpenFlow switches.)
580 Outputs the packet on all switch physical ports other than the port on
581 which it was received and any ports on which flooding is disabled
582 (typically, these would be ports disabled by the IEEE 802.1D spanning
586 Outputs the packet on all switch physical ports other than the port on
587 which it was received.
589 .IP \fBcontroller\fR:\fImax_len\fR
590 Sends the packet to the OpenFlow controller as a ``packet in''
591 message. If \fImax_len\fR is a number, then it specifies the maximum
592 number of bytes that should be sent. If \fImax_len\fR is \fBALL\fR or
593 omitted, then the entire packet is sent.
596 Outputs the packet on the ``local port,'' which corresponds to the
597 network device that has the same name as the bridge.
600 Outputs the packet on the port from which it was received.
603 Discards the packet, so no further processing or forwarding takes place.
604 If a drop action is used, no other actions may be specified.
606 .IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR
607 Modifies the VLAN id on a packet. The VLAN tag is added or modified
608 as necessary to match the value specified. If the VLAN tag is added,
609 a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set
612 .IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR
613 Modifies the VLAN priority on a packet. The VLAN tag is added or modified
614 as necessary to match the value specified. Valid values are between 0
615 (lowest) and 7 (highest). If the VLAN tag is added, a vid of zero is used
616 (see the \fBmod_vlan_vid\fR action to set this).
619 Strips the VLAN tag from a packet if it is present.
621 .IP \fBmod_dl_src\fB:\fImac\fR
622 Sets the source Ethernet address to \fImac\fR.
624 .IP \fBmod_dl_dst\fB:\fImac\fR
625 Sets the destination Ethernet address to \fImac\fR.
627 .IP \fBmod_nw_src\fB:\fIip\fR
628 Sets the IPv4 source address to \fIip\fR.
630 .IP \fBmod_nw_dst\fB:\fIip\fR
631 Sets the IPv4 destination address to \fIip\fR.
633 .IP \fBmod_tp_src\fB:\fIport\fR
634 Sets the TCP or UDP source port to \fIport\fR.
636 .IP \fBmod_tp_dst\fB:\fIport\fR
637 Sets the TCP or UDP destination port to \fIport\fR.
639 .IP \fBmod_nw_tos\fB:\fItos\fR
640 Sets the IP ToS/DSCP field to \fItos\fR. Valid values are between 0 and
641 255, inclusive. Note that the two lower reserved bits are never
646 The following actions are Nicira vendor extensions that, as of this writing, are
647 only known to be implemented by Open vSwitch:
651 .IP \fBresubmit\fB:\fIport\fR
652 Re-searches the OpenFlow flow table with the \fBin_port\fR field
653 replaced by \fIport\fR and executes the actions found, if any, in
654 addition to any other actions in this flow entry. Recursive
655 \fBresubmit\fR actions are ignored.
657 .IP \fBset_tunnel\fB:\fIid\fR
658 .IQ \fBset_tunnel64\fB:\fIid\fR
659 If outputting to a port that encapsulates the packet in a tunnel and
660 supports an identifier (such as GRE), sets the identifier to \fBid\fR.
661 If the \fBset_tunnel\fR form is used and \fIid\fR fits in 32 bits,
662 then this uses an action extension that is supported by Open vSwitch
663 1.0 and later. Otherwise, if \fIid\fR is a 64-bit value, it requires
664 Open vSwitch 1.1 or later.
666 .IP \fBset_queue\fB:\fIqueue\fR
667 Sets the queue that should be used to \fIqueue\fR when packets are
668 output. The number of supported queues depends on the switch; some
669 OpenFlow implementations do not support queuing at all.
672 Restores the queue to the value it was before any \fBset_queue\fR
673 actions were applied.
675 .IP \fBnote:\fR[\fIhh\fR]...
676 Does nothing at all. Any number of bytes represented as hex digits
677 \fIhh\fR may be included. Pairs of hex digits may be separated by
678 periods for readability.
680 .IP "\fBmove:\fIsrc\fB[\fIstart\fB..\fIend\fB]->\fIdst\fB[\fIstart\fB..\fIend\fB]\fR"
681 Copies the named bits from field \fIsrc\fR to field \fIdst\fR.
682 \fIsrc\fR and \fIdst\fR must be NXM field names as defined in
683 \fBnicira\-ext.h\fR, e.g. \fBNXM_OF_UDP_SRC\fR or \fBNXM_NX_REG0\fR.
684 Each \fIstart\fR and \fIend\fR pair, which are inclusive, must specify
685 the same number of bits and must fit within its respective field.
686 Shorthands for \fB[\fIstart\fB..\fIend\fB]\fR exist: use
687 \fB[\fIbit\fB]\fR to specify a single bit or \fB[]\fR to specify an
690 Examples: \fBmove:NXM_NX_REG0[0..5]\->NXM_NX_REG1[26..31]\fR copies the
691 six bits numbered 0 through 5, inclusive, in register 0 into bits 26
692 through 31, inclusive;
693 \fBmove:NXM_NX_REG0[0..15]->NXM_OF_VLAN_TCI[]\fR copies the least
694 significant 16 bits of register 0 into the VLAN TCI field.
696 .IP "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]"
697 Writes \fIvalue\fR to bits \fIstart\fR through \fIend\fR, inclusive,
700 Example: \fBload:55\->NXM_NX_REG2[0..5]\fR loads value 55 (bit pattern
701 \fB110111\fR) into bits 0 through 5, inclusive, in register 2.
703 .IP "\fBmultipath(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIn_links\fB, \fIarg\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR"
704 Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter,
705 then the applies multipath link selection \fIalgorithm\fR (with
706 parameter \fIarg\fR) to choose one of \fIn_links\fR output links
707 numbered 0 through \fIn_links\fR minus 1, and stores the link into
708 \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as
711 Currently, \fIfields\fR must be either \fBeth_src\fR or
712 \fBsymmetric_l4\fR and \fIalgorithm\fR must be one of \fBmodulo_n\fR,
713 \fBhash_threshold\fR, \fBhrw\fR, and \fBiter_hash\fR. Only
714 the \fBiter_hash\fR algorithm uses \fIarg\fR.
716 Refer to \fBnicira\-ext.h\fR for more details.
718 .IP "\fBautopath(\fIid\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR"
719 Given \fIid\fR, chooses an OpenFlow port and populates it in
720 \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as
723 Currently, \fIid\fR should be the OpenFlow port number of an interface on the
724 bridge. If it isn't then \fIdst\fB[\fIstart\fB..\fIend\fB]\fR will be
725 populated with the OpenFlow port "none". If \fIid\fR is a member of a bond,
726 the normal bond selection logic will be used to choose the destination port.
727 Otherwise, the register will be populated with \fIid\fR itself.
729 Refer to \fBnicira\-ext.h\fR for more details.
731 .IP "\fBbundle(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, slaves:[\fIs1\fB, \fIs2\fB, ...])\fR"
732 Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter, then
733 applies the bundle link selection \fIalgorithm\fR to choose one of the listed
734 slaves represented as \fIslave_type\fR. Currently the only supported
735 \fIslave_type\fR is \fBofport\fR. Thus, each \fIs1\fR through \fIsN\fR should
736 be an OpenFlow port number. Outputs to the selected slave.
738 Currently, \fIfields\fR must be either \fBeth_src\fR or \fBsymmetric_l4\fR and
739 \fIalgorithm\fR must be one of \fBhrw\fR and \fBactive_backup\fR.
741 Example: \fBbundle(eth_src,0,hrw,ofport,slaves:4,8)\fR uses an Ethernet source
742 hash with basis 0, to select between OpenFlow ports 4 and 8 using the Highest
743 Random Weight algorithm.
745 Refer to \fBnicira\-ext.h\fR for more details.
747 .IP "\fBbundle_load(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, \fIdst\fB[\fIstart\fB..\fIend\fB], slaves:[\fIs1\fB, \fIs2\fB, ...])\fR"
748 Has the same behavior as the \fBbundle\fR action, with one exception. Instead
749 of outputting to the selected slave, it writes its selection to
750 \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as described
753 Example: \fBbundle_load(eth_src,0,hrw,ofport,NXM_NX_REG0[],slaves:4,8)\fR uses
754 an Ethernet source hash with basis 0, to select between OpenFlow ports 4 and 8
755 using the Highest Random Weight algorithm, and writes the selection to
758 Refer to \fBnicira\-ext.h\fR for more details.
762 (The OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does
763 not yet expose to the user.)
766 The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands
767 support an additional optional field:
769 .IP \fBcookie=\fIvalue\fR
771 A cookie is an opaque identifier that can be associated with the flow.
772 \fIvalue\fR can be any 64-bit number and need not be unique among
773 flows. If this field is omitted, these commands set a default cookie
777 The following additional field sets the priority for flows added by
778 the \fBadd\-flow\fR and \fBadd\-flows\fR commands. For
779 \fBmod\-flows\fR and \fBdel\-flows\fR when \fB\-\-strict\fR is
780 specified, priority must match along with the rest of the flow
781 specification. Other commands do not allow priority to be specified.
783 .IP \fBpriority=\fIvalue\fR
784 The priority at which a wildcarded entry will match in comparison to
785 others. \fIvalue\fR is a number between 0 and 65535, inclusive. A higher
786 \fIvalue\fR will match before a lower one. An exact-match entry will always
787 have priority over an entry containing wildcards, so it has an implicit
788 priority value of 65535. When adding a flow, if the field is not specified,
789 the flow's priority will default to 32768.
792 The \fBadd\-flow\fR and \fBadd\-flows\fR commands support additional
796 \fBidle_timeout=\fIseconds\fR
797 Causes the flow to expire after the given number of seconds of
798 inactivity. A value of 0 (the default) prevents a flow from expiring due to
801 .IP \fBhard_timeout=\fIseconds\fR
802 Causes the flow to expire after the given number of seconds,
803 regardless of activity. A value of 0 (the default) gives the flow no
804 hard expiration deadline.
807 The \fBdump\-flows\fR, \fBdump\-aggregate\fR, \fBdel\-flow\fR
808 and \fBdel\-flows\fR commands support one additional optional field:
811 \fBout_port=\fIport\fR
812 If set, a matching flow must include an output action to \fIport\fR.
814 .SS "Table Entry Output"
816 The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information
817 about the entries in a datapath's tables. Each line of output is a
818 unique flow entry, which begins with some common information:
821 The number of seconds the entry has been in the table.
824 The table that contains the flow. When a packet arrives, the switch
825 begins searching for an entry at the lowest numbered table. Tables are
826 numbered as shown by the \fBdump\-tables\fR command.
829 The priority of the entry in relation to other entries within the same
830 table. A higher value will match before a lower one.
833 The number of packets that have matched the entry.
836 The total number of bytes from packets that have matched the entry.
839 The rest of the line consists of a description of the flow entry as
840 described in \fBFlow Syntax\fR, above.
846 Uses strict matching when running flow modification commands.
848 .IP "\fB\-F \fIformat\fR"
849 .IQ "\fB\-\-flow\-format=\fIformat\fR"
850 \fBovs\-ofctl\fR supports the following flow formats, in order of
851 increasing capability:
853 .IP "\fBopenflow10\fR"
854 This is the standard OpenFlow 1.0 flow format. It should be supported
855 by all OpenFlow switches.
857 .IP "\fBnxm\fR (Nicira Extended Match)"
858 This Nicira extension to OpenFlow is flexible and extensible. It
859 supports all of the Nicira flow extensions, such as \fBtun_id\fR and
863 Usually, \fBovs\-ofctl\fR picks the correct format automatically. For
864 commands that modify the flow table, \fBovs\-ofctl\fR by default uses
865 the most widely supported flow format that supports the flows being
866 added. For commands that query the flow table, \fBovs\-ofctl\fR by
867 default queries and uses the most advanced format supported by the
870 This option, where \fIformat\fR is one of the formats listed in the
871 above table, overrides \fBovs\-ofctl\fR's default choice of flow
872 format. If a command cannot work as requested using the requested
873 flow format, \fBovs\-ofctl\fR will report a fatal error.
877 Increases the verbosity of OpenFlow messages printed and logged by
878 \fBovs\-ofctl\fR commands. Specify this option more than once to
879 increase verbosity further.
880 .SS "Public Key Infrastructure Options"
887 The following examples assume that \fBovs\-vswitchd\fR has a bridge
888 named \fBbr0\fR configured.
891 \fBovs\-ofctl dump\-tables br0\fR
892 Prints out the switch's table stats. (This is more interesting after
893 some traffic has passed through.)
896 \fBovs\-ofctl dump\-flows br0\fR
897 Prints the flow entries in the switch.
902 .BR ovs\-controller (8),
903 .BR ovs\-vswitchd (8)