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 a connection
203 named on \fBovs\-openflowd\fR(8)'s \fB\-l\fR or \fB\-\-listen\fR command line
206 If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set
207 configuration'' message at connection setup time that requests
208 \fImiss-len\fR bytes of each packet that misses the flow table. Open vSwitch
209 does not send these and other asynchronous messages to an
210 \fBovs\-ofctl monitor\fR client connection unless a nonzero value is
211 specified on this argument. (Thus, if \fImiss\-len\fR is not
212 specified, very little traffic will ordinarily be printed.)
214 This command may be useful for debugging switch or controller
217 .SS "OpenFlow Switch and Controller Commands"
219 The following commands, like those in the previous section, may be
220 applied to OpenFlow switches, using any of the connection methods
221 described in that section. Unlike those commands, these may also be
222 applied to OpenFlow controllers.
225 \fBprobe \fItarget\fR
226 Sends a single OpenFlow echo-request message to \fItarget\fR and waits
227 for the response. With the \fB\-t\fR or \fB\-\-timeout\fR option, this
228 command can test whether an OpenFlow switch or controller is up and
232 \fBping \fItarget \fR[\fIn\fR]
233 Sends a series of 10 echo request packets to \fItarget\fR and times
234 each reply. The echo request packets consist of an OpenFlow header
235 plus \fIn\fR bytes (default: 64) of randomly generated payload. This
236 measures the latency of individual requests.
239 \fBbenchmark \fItarget n count\fR
240 Sends \fIcount\fR echo request packets that each consist of an
241 OpenFlow header plus \fIn\fR bytes of payload and waits for each
242 response. Reports the total time required. This is a measure of the
243 maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte
248 Some \fBovs\-ofctl\fR commands accept an argument that describes a flow or
249 flows. Such flow descriptions comprise a series
250 \fIfield\fB=\fIvalue\fR assignments, separated by commas or white
251 space. (Embedding spaces into a flow description normally requires
252 quoting to prevent the shell from breaking the description into
255 Flow descriptions should be in \fBnormal form\fR. This means that a
256 flow may only specify a value for an L3 field if it also specifies a
257 particular L2 protocol, and that a flow may only specify an L4 field
258 if it also specifies particular L2 and L3 protocol types. For
259 example, if the L2 protocol type \fBdl_type\fR is wildcarded, then L3
260 fields \fBnw_src\fR, \fBnw_dst\fR, and \fBnw_proto\fR must also be
261 wildcarded. Similarly, if \fBdl_type\fR or \fBnw_proto\fR (the L3
262 protocol type) is wildcarded, so must be \fBtp_dst\fR and
263 \fBtp_src\fR, which are L4 fields. \fBovs\-ofctl\fR will warn about
264 flows not in normal form.
266 The following field assignments describe how a flow matches a packet.
267 If any of these assignments is omitted from the flow syntax, the field
268 is treated as a wildcard; thus, if all of them are omitted, the
269 resulting flow matches all packets. The string \fB*\fR or \fBANY\fR
270 may be specified to explicitly mark any of these fields as a wildcard.
271 (\fB*\fR should be quoted to protect it from shell expansion.)
273 .IP \fBin_port=\fIport_no\fR
274 Matches physical port \fIport_no\fR. Switch ports are numbered as
275 displayed by \fBovs\-ofctl show\fR.
277 .IP \fBdl_vlan=\fIvlan\fR
278 Matches IEEE 802.1q Virtual LAN tag \fIvlan\fR. Specify \fB0xffff\fR
279 as \fIvlan\fR to match packets that are not tagged with a Virtual LAN;
280 otherwise, specify a number between 0 and 4095, inclusive, as the
281 12-bit VLAN ID to match.
283 .IP \fBdl_vlan_pcp=\fIpriority\fR
284 Matches IEEE 802.1q Priority Code Point (PCP) \fIpriority\fR, which is
285 specified as a value between 0 and 7, inclusive. A higher value
286 indicates a higher frame priority level.
288 .IP \fBdl_src=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
289 .IQ \fBdl_dst=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
290 Matches an Ethernet source (or destination) address specified as 6
291 pairs of hexadecimal digits delimited by colons
292 (e.g. \fB00:0A:E4:25:6B:B0\fR).
294 .IP \fBdl_type=\fIethertype\fR
295 Matches Ethernet protocol type \fIethertype\fR, which is specified as an
296 integer between 0 and 65535, inclusive, either in decimal or as a
297 hexadecimal number prefixed by \fB0x\fR (e.g. \fB0x0806\fR to match ARP
300 .IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR]
301 .IQ \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR]
302 When \fBdl_type\fR is 0x0800 (possibly via shorthand, e.g. \fBip\fR
303 or \fBtcp\fR), matches IPv4 source (or destination) address \fIip\fR,
304 which may be specified as an IP address or host name
305 (e.g. \fB192.168.1.1\fR or \fBwww.example.com\fR). The optional
306 \fInetmask\fR allows restricting a match to an IPv4 address prefix.
307 The netmask may be specified as a dotted quad
308 (e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block
309 (e.g. \fB192.168.1.0/24\fR).
311 When \fBdl_type=0x0806\fR or \fBarp\fR is specified, matches the
312 \fBar_spa\fR or \fBar_tpa\fR field, respectively, in ARP packets for
315 When \fBdl_type\fR is wildcarded or set to a value other than 0x0800
316 or 0x0806, the values of \fBnw_src\fR and \fBnw_dst\fR are ignored
317 (see \fBFlow Syntax\fR above).
319 .IP \fBnw_proto=\fIproto\fR
320 When \fBip\fR or \fBdl_type=0x0800\fR is specified, matches IP
321 protocol type \fIproto\fR, which is specified as a decimal number
322 between 0 and 255, inclusive (e.g. 1 to match ICMP packets or 6 to match
325 When \fBipv6\fR or \fBdl_type=0x86dd\fR is specified, matches IPv6
326 header type \fIproto\fR, which is specified as a decimal number between
327 0 and 255, inclusive (e.g. 58 to match ICMPv6 packets or 6 to match
328 TCP). The header type is the terminal header as described in the
329 \fBDESIGN\fR document.
331 When \fBarp\fR or \fBdl_type=0x0806\fR is specified, matches the lower
332 8 bits of the ARP opcode. ARP opcodes greater than 255 are treated as
335 When \fBdl_type\fR is wildcarded or set to a value other than 0x0800,
336 0x0806, or 0x86dd, the value of \fBnw_proto\fR is ignored (see \fBFlow
339 .IP \fBnw_tos=\fItos\fR
340 Matches IP ToS/DSCP or IPv6 traffic class field \fItos\fR, which is
341 specified as a decimal number between 0 and 255, inclusive. Note that
342 the two lower reserved bits are ignored for matching purposes.
344 When \fBdl_type\fR is wildcarded or set to a value other than 0x0800,
345 0x0806, or 0x86dd, the value of \fBnw_tos\fR is ignored (see \fBFlow
348 .IP \fBtp_src=\fIport\fR
349 .IQ \fBtp_dst=\fIport\fR
350 When \fBdl_type\fR and \fBnw_proto\fR specify TCP or UDP, \fBtp_src\fR
351 and \fBtp_dst\fR match the UDP or TCP source or destination port
352 \fIport\fR, respectively. which is specified as a decimal number
353 between 0 and 65535, inclusive (e.g. 80 to match packets originating
356 When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of
357 these settings are ignored (see \fBFlow Syntax\fR above).
359 .IP \fBicmp_type=\fItype\fR
360 .IQ \fBicmp_code=\fIcode\fR
361 When \fBdl_type\fR and \fBnw_proto\fR specify ICMP or ICMPv6, \fItype\fR
362 matches the ICMP type and \fIcode\fR matches the ICMP code. Each is
363 specified as a decimal number between 0 and 255, inclusive.
365 When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of
366 these settings are ignored (see \fBFlow Syntax\fR above).
369 The following shorthand notations are also available:
372 Same as \fBdl_type=0x0800\fR.
375 Same as \fBdl_type=0x0800,nw_proto=1\fR.
378 Same as \fBdl_type=0x0800,nw_proto=6\fR.
381 Same as \fBdl_type=0x0800,nw_proto=17\fR.
384 Same as \fBdl_type=0x0806\fR.
387 The following field assignments require support for the NXM (Nicira
388 Extended Match) extension to OpenFlow. When one of these is specified,
389 \fBovs\-ofctl\fR will automatically attempt to negotiate use of this
390 extension. If the switch does not support NXM, then \fBovs\-ofctl\fR
391 will report a fatal error.
393 .IP \fBarp_sha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
394 .IQ \fBarp_tha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
395 When \fBdl_type\fR specifies ARP, \fBarp_sha\fR and \fBarp_tha\fR match
396 the source and target hardware address, respectively. An address is
397 specified as 6 pairs of hexadecimal digits delimited by colons.
399 .IP \fBipv6_src=\fIipv6\fR[\fB/\fInetmask\fR]
400 .IQ \fBipv6_dst=\fIipv6\fR[\fB/\fInetmask\fR]
401 When \fBdl_type\fR is 0x86dd (possibly via shorthand, e.g., \fBipv6\fR
402 or \fBtcp6\fR), matches IPv6 source (or destination) address \fIipv6\fR,
403 which may be specified as defined in RFC 2373. The preferred format is
404 \fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fR, where
405 \fIx\fR are the hexadecimal values of the eight 16-bit pieces of the
406 address. A single instance of \fB::\fR may be used to indicate multiple
407 groups of 16-bits of zeros. The optional \fInetmask\fR allows
408 restricting a match to an IPv6 address prefix. A netmask is specified
409 as a CIDR block (e.g. \fB2001:db8:3c4d:1::/64\fR).
411 .IP \fBnd_target=\fIipv6\fR
412 When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify
413 IPv6 Neighbor Discovery (ICMPv6 type 135 or 136), matches the target address
414 \fIipv6\fR. \fIipv6\fR is in the same format described earlier for the
415 \fBipv6_src\fR and \fBipv6_dst\fR fields.
417 .IP \fBnd_sll=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
418 When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify IPv6
419 Neighbor Solicitation (ICMPv6 type 135), matches the source link\-layer
420 address option. An address is specified as 6 pairs of hexadecimal
421 digits delimited by colons.
423 .IP \fBnd_tll=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR
424 When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify IPv6
425 Neighbor Advertisement (ICMPv6 type 136), matches the target link\-layer
426 address option. An address is specified as 6 pairs of hexadecimal
427 digits delimited by colons.
429 .IP \fBtun_id=\fItunnel-id\fR[\fB/\fImask\fR]
430 Matches tunnel identifier \fItunnel-id\fR. Only packets that arrive
431 over a tunnel that carries a key (e.g. GRE with the RFC 2890 key
432 extension) will have a nonzero tunnel ID. If \fImask\fR is omitted,
433 \fItunnel-id\fR is the exact tunnel ID to match; if \fImask\fR is
434 specified, then a 1-bit in \fImask\fR indicates that the corresponding
435 bit in \fItunnel-id\fR must match exactly, and a 0-bit wildcards that
438 In an attempt to be compatible with more switches, \fBovs\-ofctl\fR will
439 prefer to use the ``tunnel ID from cookie'' Nicira extension to NXM.
440 The use of this extension comes with three caveats: the top 32 bits of
441 the \fBcookie\fR (see below) are used for \fItunnel-id\fR and thus
442 unavailable for other use, specifying \fBtun_id\fR on \fBdump\-flows\fR
443 or \fBdump\-aggregate\fR has no effect, and \fImask\fR is not supported.
444 If any of these caveats apply, \fBovs-ofctl\fR will use NXM.
446 .IP "\fBreg\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]"
447 Matches \fIvalue\fR either exactly or with optional \fImask\fR in
448 register number \fIidx\fR. The valid range of \fIidx\fR depends on
449 the switch. \fIvalue\fR and \fImask\fR are 32-bit integers, by
450 default in decimal (use a \fB0x\fR prefix to specify hexadecimal).
451 Arbitrary \fImask\fR values are allowed: a 1-bit in \fImask\fR
452 indicates that the corresponding bit in \fIvalue\fR must match
453 exactly, and a 0-bit wildcards that bit.
455 When a packet enters an OpenFlow switch, all of the registers are set
456 to 0. Only explicit Nicira extension actions change register values.
459 Defining IPv6 flows (those with \fBdl_type\fR equal to 0x86dd) requires
460 support for NXM. The following shorthand notations are available for
464 Same as \fBdl_type=0x86dd\fR.
467 Same as \fBdl_type=0x86dd,nw_proto=6\fR.
470 Same as \fBdl_type=0x86dd,nw_proto=17\fR.
473 Same as \fBdl_type=0x86dd,nw_proto=58\fR.
476 The \fBadd\-flow\fR and \fBadd\-flows\fR commands require an additional
477 field, which must be the final field specified:
479 .IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR
480 Specifies a comma-separated list of actions to take on a packet when the
481 flow entry matches. If no \fItarget\fR is specified, then packets
482 matching the flow are dropped. The \fItarget\fR may be a decimal port
483 number designating the physical port on which to output the packet, or one
484 of the following keywords:
487 .IP \fBoutput\fR:\fIport\fR
488 Outputs the packet on the port specified by \fIport\fR.
490 .IP \fBenqueue\fR:\fIport\fB:\fIqueue\fR
491 Enqueues the packet on the specified \fIqueue\fR within port
492 \fIport\fR. The number of supported queues depends on the switch;
493 some OpenFlow implementations do not support queuing at all.
496 Subjects the packet to the device's normal L2/L3 processing. (This
497 action is not implemented by all OpenFlow switches.)
500 Outputs the packet on all switch physical ports other than the port on
501 which it was received and any ports on which flooding is disabled
502 (typically, these would be ports disabled by the IEEE 802.1D spanning
506 Outputs the packet on all switch physical ports other than the port on
507 which it was received.
509 .IP \fBcontroller\fR:\fImax_len\fR
510 Sends the packet to the OpenFlow controller as a ``packet in''
511 message. If \fImax_len\fR is a number, then it specifies the maximum
512 number of bytes that should be sent. If \fImax_len\fR is \fBALL\fR or
513 omitted, then the entire packet is sent.
516 Outputs the packet on the ``local port,'' which corresponds to the
517 \fBof\fIn\fR network device (see \fBCONTACTING THE CONTROLLER\fR in
518 \fBovs\-openflowd\fR(8) for information on the \fBof\fIn\fR network device).
521 Discards the packet, so no further processing or forwarding takes place.
522 If a drop action is used, no other actions may be specified.
524 .IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR
525 Modifies the VLAN id on a packet. The VLAN tag is added or modified
526 as necessary to match the value specified. If the VLAN tag is added,
527 a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set
530 .IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR
531 Modifies the VLAN priority on a packet. The VLAN tag is added or modified
532 as necessary to match the value specified. Valid values are between 0
533 (lowest) and 7 (highest). If the VLAN tag is added, a vid of zero is used
534 (see the \fBmod_vlan_vid\fR action to set this).
537 Strips the VLAN tag from a packet if it is present.
539 .IP \fBmod_dl_src\fB:\fImac\fR
540 Sets the source Ethernet address to \fImac\fR.
542 .IP \fBmod_dl_dst\fB:\fImac\fR
543 Sets the destination Ethernet address to \fImac\fR.
545 .IP \fBmod_nw_src\fB:\fIip\fR
546 Sets the IPv4 source address to \fIip\fR.
548 .IP \fBmod_nw_dst\fB:\fIip\fR
549 Sets the IPv4 destination address to \fIip\fR.
551 .IP \fBmod_tp_src\fB:\fIport\fR
552 Sets the TCP or UDP source port to \fIport\fR.
554 .IP \fBmod_tp_dst\fB:\fIport\fR
555 Sets the TCP or UDP destination port to \fIport\fR.
557 .IP \fBmod_nw_tos\fB:\fItos\fR
558 Sets the IP ToS/DSCP field to \fItos\fR. Valid values are between 0 and
559 255, inclusive. Note that the two lower reserved bits are never
564 The following actions are Nicira vendor extensions that, as of this writing, are
565 only known to be implemented by Open vSwitch:
569 .IP \fBresubmit\fB:\fIport\fR
570 Re-searches the OpenFlow flow table with the \fBin_port\fR field
571 replaced by \fIport\fR and executes the actions found, if any, in
572 addition to any other actions in this flow entry. Recursive
573 \fBresubmit\fR actions are ignored.
575 .IP \fBset_tunnel\fB:\fIid\fR
576 .IQ \fBset_tunnel64\fB:\fIid\fR
577 If outputting to a port that encapsulates the packet in a tunnel and
578 supports an identifier (such as GRE), sets the identifier to \fBid\fR.
579 If the \fBset_tunnel\fR form is used and \fIid\fR fits in 32 bits,
580 then this uses an action extension that is supported by Open vSwitch
581 1.0 and later. Otherwise, if \fIid\fR is a 64-bit value, it requires
582 Open vSwitch 1.1 or later.
584 .IP \fBdrop_spoofed_arp\fR
585 Stops processing further actions, if the packet being processed is an
586 Ethernet+IPv4 ARP packet for which the source Ethernet address inside
587 the ARP packet differs from the source Ethernet address in the
590 This action is deprecated in favor of defining flows using the
591 \fBarp_sha\fR match field described earlier and will likely be removed
592 in a future version of Open vSwitch.
594 .IP \fBset_queue\fB:\fIqueue\fR
595 Sets the queue that should be used to \fIqueue\fR when packets are
596 output. The number of supported queues depends on the switch; some
597 OpenFlow implementations do not support queuing at all.
600 Restores the queue to the value it was before any \fBset_queue\fR
601 actions were applied.
603 .IP \fBnote:\fR[\fIhh\fR]...
604 Does nothing at all. Any number of bytes represented as hex digits
605 \fIhh\fR may be included. Pairs of hex digits may be separated by
606 periods for readability.
608 .IP "\fBmove:\fIsrc\fB[\fIstart\fB..\fIend\fB]->\fIdst\fB[\fIstart\fB..\fIend\fB]\fR"
609 Copies the named bits from field \fIsrc\fR to field \fIdst\fR.
610 \fIsrc\fR and \fIdst\fR must be NXM field names as defined in
611 \fBnicira\-ext.h\fR, e.g. \fBNXM_OF_UDP_SRC\fR or \fBNXM_NX_REG0\fR.
612 Each \fIstart\fR and \fIend\fR pair, which are inclusive, must specify
613 the same number of bits and must fit within its respective field.
614 Shorthands for \fB[\fIstart\fB..\fIend\fB]\fR exist: use
615 \fB[\fIbit\fB]\fR to specify a single bit or \fB[]\fR to specify an
618 Examples: \fBmove:NXM_NX_REG0[0..5]\->NXM_NX_REG1[26..31]\fR copies the
619 six bits numbered 0 through 5, inclusive, in register 0 into bits 26
620 through 31, inclusive;
621 \fBmove:NXM_NX_REG0[0..15]->NXM_OF_VLAN_TCI[]\fR copies the least
622 significant 16 bits of register 0 into the VLAN TCI field.
624 .IP "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]"
625 Writes \fIvalue\fR to bits \fIstart\fR through \fIend\fR, inclusive,
628 Example: \fBload:55\->NXM_NX_REG2[0..5]\fR loads value 55 (bit pattern
629 \fB110111\fR) into bits 0 through 5, inclusive, in register 2.
631 .IP "\fBmultipath(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIn_links\fB, \fIarg\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR"
632 Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter,
633 then the applies multipath link selection \fIalgorithm\fR (with
634 parameter \fIarg\fR) to choose one of \fIn_links\fR output links
635 numbered 0 through \fIn_links\fR minus 1, and stores the link into
636 \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM register as
639 Currently, \fIfields\fR must be either \fBeth_src\fR or
640 \fBsymmetric_l4\fR and \fIalgorithm\fR must be one of \fBmodulo_n\fR,
641 \fBhash_threshold\fR, \fBhrw\fR, and \fBiter_hash\fR. Only
642 the \fBiter_hash\fR algorithm uses \fIarg\fR.
644 Refer to \fBnicira\-ext.h\fR for more details.
646 .IP "\fBautopath(\fIid\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR"
647 Given \fIid\fR, chooses an OpenFlow port and populates it in
648 \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM register as
651 Currently, \fIid\fR should be the OpenFlow port number of an interface on the
652 bridge. If it isn't then \fIdst\fB[\fIstart\fB..\fIend\fB]\fR will be
653 populated with the OpenFlow port "none". If \fIid\fR is a member of a bond,
654 the normal bond selection logic will be used to choose the destination port.
655 Otherwise, the register will be populated with \fIid\fR itself.
657 Refer to \fBnicira\-ext.h\fR for more details.
661 (The OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does
662 not yet expose to the user.)
665 The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands
666 support an additional optional field:
668 .IP \fBcookie=\fIvalue\fR
670 A cookie is an opaque identifier that can be associated with the flow.
671 \fIvalue\fR can be any 64-bit number and need not be unique among
675 The following additional field sets the priority for flows added by
676 the \fBadd\-flow\fR and \fBadd\-flows\fR commands. For
677 \fBmod\-flows\fR and \fBdel\-flows\fR when \fB\-\-strict\fR is
678 specified, priority must match along with the rest of the flow
679 specification. Other commands ignore the priority value.
681 .IP \fBpriority=\fIvalue\fR
682 The priority at which a wildcarded entry will match in comparison to
683 others. \fIvalue\fR is a number between 0 and 65535, inclusive. A higher
684 \fIvalue\fR will match before a lower one. An exact-match entry will always
685 have priority over an entry containing wildcards, so it has an implicit
686 priority value of 65535. When adding a flow, if the field is not specified,
687 the flow's priority will default to 32768.
690 The \fBadd\-flow\fR and \fBadd\-flows\fR commands support additional
694 \fBidle_timeout=\fIseconds\fR
695 Causes the flow to expire after the given number of seconds of
696 inactivity. A value of 0 (the default) prevents a flow from expiring due to
699 .IP \fBhard_timeout=\fIseconds\fR
700 Causes the flow to expire after the given number of seconds,
701 regardless of activity. A value of 0 (the default) gives the flow no
702 hard expiration deadline.
705 The \fBdump\-flows\fR, \fBdump\-aggregate\fR, \fBdel\-flow\fR
706 and \fBdel\-flows\fR commands support one additional optional field:
709 \fBout_port=\fIport\fR
710 If set, a matching flow must include an output action to \fIport\fR.
713 The \fBdump\-flows\fR and \fBdump\-aggregate\fR commands support an
714 additional optional field:
716 .IP \fBtable=\fInumber\fR
717 If specified, limits the flows about which statistics are gathered to
718 those in the table with the given \fInumber\fR. Tables are numbered
719 as shown by the \fBdump\-tables\fR command.
721 If this field is not specified, or if \fInumber\fR is given as
722 \fB255\fR, statistics are gathered about flows from all tables.
724 .SS "Table Entry Output"
726 The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information
727 about the entries in a datapath's tables. Each line of output is a
728 unique flow entry, which begins with some common information:
731 The number of seconds the entry has been in the table.
734 The table that contains the flow. When a packet arrives, the switch
735 begins searching for an entry at the lowest numbered table. Tables are
736 numbered as shown by the \fBdump\-tables\fR command.
739 The priority of the entry in relation to other entries within the same
740 table. A higher value will match before a lower one.
743 The number of packets that have matched the entry.
746 The total number of bytes from packets that have matched the entry.
749 The rest of the line consists of a description of the flow entry as
750 described in \fBFlow Syntax\fR, above.
756 Uses strict matching when running flow modification commands.
758 .IP "\fB\-F \fIformat\fR"
759 .IQ "\fB\-\-flow\-format=\fIformat\fR"
760 \fBovs\-ofctl\fR supports the following flow formats, in order of
761 increasing capability:
763 .IP "\fBopenflow10\fR"
764 This is the standard OpenFlow 1.0 flow format. It should be supported
765 by all OpenFlow switches.
767 .IP "\fBtun_id_from_cookie\fR"
768 This Nicira extension to OpenFlow adds minimal and limited support for
769 \fBtun_id\fR, but it does not support any other Nicira flow
770 extensions. (This flow format is deprecated.)
772 .IP "\fBnxm\fR (Nicira Extended Match)"
773 This Nicira extension to OpenFlow is flexible and extensible. It
774 supports all of the Nicira flow extensions, such as \fBtun_id\fR and
778 Usually, \fBovs\-ofctl\fR picks the correct format automatically. For
779 commands that modify the flow table, \fBovs\-ofctl\fR by default uses
780 the most widely supported flow format that supports the flows being
781 added. For commands that query the flow table, \fBovs\-ofctl\fR by
782 default queries and uses the most advanced format supported by the
785 This option, where \fIformat\fR is one of the formats listed in the
786 above table, overrides \fBovs\-ofctl\fR's default choice of flow
787 format. If a command cannot work as requested using the requested
788 flow format, \fBovs\-ofctl\fR will report a fatal error.
792 Increases the verbosity of OpenFlow messages printed and logged by
793 \fBovs\-ofctl\fR commands. Specify this option more than once to
794 increase verbosity further.
795 .SS "Public Key Infrastructure Options"
802 The following examples assume that an OpenFlow switch on the local
803 host has been configured to listen for management connections on a
804 Unix domain socket named \fB@RUNDIR@/openflow.sock\fR, e.g. by
805 specifying \fB\-\-listen=punix:@RUNDIR@/openflow.sock\fR on the
806 \fBovs\-openflowd\fR(8) command line.
809 \fBovs\-ofctl dump\-tables unix:@RUNDIR@/openflow.sock\fR
810 Prints out the switch's table stats. (This is more interesting after
811 some traffic has passed through.)
814 \fBovs\-ofctl dump\-flows unix:@RUNDIR@/openflow.sock\fR
815 Prints the flow entries in the switch.
820 .BR ovs\-controller (8),
821 .BR ovs\-vswitchd (8)