]>
Commit | Line | Data |
---|---|---|
a9b4a41a BP |
1 | .\" -*- nroff -*- |
2 | .de IQ | |
3 | . br | |
4 | . ns | |
5 | . IP "\\$1" | |
6 | .. | |
71e17a7a | 7 | .TH ovs\-ofctl 8 "January 2011" "Open vSwitch" "Open vSwitch Manual" |
064af421 | 8 | .ds PN ovs\-ofctl |
a9b4a41a | 9 | . |
064af421 BP |
10 | .SH NAME |
11 | ovs\-ofctl \- administer OpenFlow switches | |
a9b4a41a | 12 | . |
064af421 BP |
13 | .SH SYNOPSIS |
14 | .B ovs\-ofctl | |
15 | [\fIoptions\fR] \fIcommand \fR[\fIswitch\fR] [\fIargs\fR\&...] | |
a9b4a41a | 16 | . |
064af421 BP |
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. | |
a9b4a41a | 23 | . |
064af421 | 24 | .SS "OpenFlow Switch Management Commands" |
a9b4a41a | 25 | .PP |
064af421 BP |
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. | |
a9b4a41a | 29 | .PP |
064af421 BP |
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: | |
a9b4a41a | 33 | . |
064af421 | 34 | .RS |
84ee7bcf BP |
35 | .so lib/vconn-active.man |
36 | . | |
064af421 BP |
37 | .IP "\fIfile\fR" |
38 | This is short for \fBunix:\fIfile\fR, as long as \fIfile\fR does not | |
39 | contain a colon. | |
84ee7bcf | 40 | . |
1a6f1e2a JG |
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. | |
064af421 | 49 | .RE |
a9b4a41a | 50 | . |
064af421 BP |
51 | .TP |
52 | \fBshow \fIswitch\fR | |
53 | Prints to the console information on \fIswitch\fR, including | |
54 | information on its flow tables and ports. | |
a9b4a41a | 55 | . |
064af421 | 56 | .TP |
4e312e69 | 57 | \fBdump\-tables \fIswitch\fR |
064af421 BP |
58 | Prints to the console statistics for each of the flow tables used by |
59 | \fIswitch\fR. | |
a9b4a41a | 60 | . |
064af421 | 61 | .TP |
4e312e69 | 62 | \fBdump\-ports \fIswitch\fR [\fInetdev\fR] |
abaad8cf JP |
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. | |
a9b4a41a | 67 | . |
064af421 | 68 | .TP |
4e312e69 | 69 | \fBmod\-port \fIswitch\fR \fInetdev\fR \fIaction\fR |
064af421 BP |
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: | |
a9b4a41a | 74 | . |
064af421 BP |
75 | .RS |
76 | .IP \fBup\fR | |
77 | Enables the interface. This is equivalent to ``ifconfig up'' on a Unix | |
78 | system. | |
a9b4a41a | 79 | . |
064af421 BP |
80 | .IP \fBdown\fR |
81 | Disables the interface. This is equivalent to ``ifconfig down'' on a Unix | |
82 | system. | |
a9b4a41a | 83 | . |
451256f6 EJ |
84 | .IP \fBforward\fR |
85 | Allows forwarding of traffic on this interface. This is the default posture | |
86 | for all ports. | |
87 | . | |
88 | .IP \fBnoforward\fR | |
89 | Disallows forwarding of traffic on this interface. | |
90 | . | |
064af421 BP |
91 | .IP \fBflood\fR |
92 | When a \fIflood\fR action is specified, traffic will be sent out this | |
93 | interface. This is the default posture for monitored ports. | |
a9b4a41a | 94 | . |
064af421 BP |
95 | .IP \fBnoflood\fR |
96 | When a \fIflood\fR action is specified, traffic will not be sent out | |
97 | this interface. This is primarily useful to prevent loops when a | |
98 | spanning tree protocol is not in use. | |
a9b4a41a | 99 | . |
064af421 | 100 | .RE |
a9b4a41a | 101 | . |
7257b535 BP |
102 | .IP "\fBget\-frags \fIswitch\fR" |
103 | Prints \fIswitch\fR's fragment handling mode. See \fBset\-frags\fR, | |
104 | below, for a description of each fragment handling mode. | |
105 | .IP | |
106 | The \fBshow\fR command also prints the fragment handling mode among | |
107 | its other output. | |
108 | . | |
109 | .IP "\fBset\-frags \fIswitch frag_mode\fR" | |
110 | Configures \fIswitch\fR's treatment of IPv4 and IPv6 fragments. The | |
111 | choices for \fIfrag_mode\fR are: | |
112 | .RS | |
113 | .IP "\fBnormal\fR" | |
114 | Fragments pass through the flow table like non-fragmented packets. | |
115 | The TCP ports, UDP ports, and ICMP type and code fields are always set | |
116 | to 0, even for fragments where that information would otherwise be | |
117 | available (fragments with offset 0). This is the default fragment | |
118 | handling mode for an OpenFlow switch. | |
119 | .IP "\fBdrop\fR" | |
120 | Fragments are dropped without passing through the flow table. | |
121 | .IP "\fBreassemble\fR" | |
122 | The switch reassembles fragments into full IP packets before passing | |
123 | them through the flow table. Open vSwitch does not implement this | |
124 | fragment handling mode. | |
125 | .IP "\fBnx\-match\fR" | |
126 | Fragments pass through the flow table like non-fragmented packets. | |
127 | The TCP ports, UDP ports, and ICMP type and code fields are available | |
128 | for matching for fragments with offset 0, and set to 0 in fragments | |
129 | with nonzero offset. This mode is a Nicira extension. | |
130 | .RE | |
131 | .IP | |
132 | See the description of \fBip_frag\fR, below, for a way to match on | |
133 | whether a packet is a fragment and on its fragment offset. | |
134 | . | |
064af421 | 135 | .TP |
4e312e69 | 136 | \fBdump\-flows \fIswitch \fR[\fIflows\fR] |
064af421 BP |
137 | Prints to the console all flow entries in \fIswitch\fR's |
138 | tables that match \fIflows\fR. If \fIflows\fR is omitted, all flows | |
139 | in the switch are retrieved. See \fBFlow Syntax\fR, below, for the | |
140 | syntax of \fIflows\fR. The output format is described in | |
141 | \fBTable Entry Output\fR. | |
a9b4a41a | 142 | . |
064af421 | 143 | .TP |
4e312e69 | 144 | \fBdump\-aggregate \fIswitch \fR[\fIflows\fR] |
064af421 BP |
145 | Prints to the console aggregate statistics for flows in |
146 | \fIswitch\fR's tables that match \fIflows\fR. If \fIflows\fR is omitted, | |
147 | the statistics are aggregated across all flows in the switch's flow | |
148 | tables. See \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR. | |
3845a3fd | 149 | The output format is described in \fBTable Entry Output\fR. |
a9b4a41a | 150 | . |
d2805da2 BP |
151 | .IP "\fBqueue\-stats \fIswitch \fR[\fIport \fR[\fIqueue\fR]]" |
152 | Prints to the console statistics for the specified \fIqueue\fR on | |
153 | \fIport\fR within \fIswitch\fR. Either of \fIport\fR or \fIqueue\fR | |
154 | or both may be omitted (or equivalently specified as \fBALL\fR). If | |
155 | both are omitted, statistics are printed for all queues on all ports. | |
156 | If only \fIqueue\fR is omitted, then statistics are printed for all | |
157 | queues on \fIport\fR; if only \fIport\fR is omitted, then statistics | |
158 | are printed for \fIqueue\fR on every port where it exists. | |
159 | . | |
4989c59f BP |
160 | .SS "OpenFlow Switch Flow Table Commands" |
161 | . | |
162 | These commands manage the flow table in an OpenFlow switch. In each | |
163 | case, \fIflow\fR specifies a flow entry in the format described in | |
164 | \fBFlow Syntax\fR, below, and \fIfile\fR is a text file that contains | |
165 | zero or more flows in the same syntax, one per line. | |
166 | . | |
167 | .IP "\fBadd\-flow \fIswitch flow\fR" | |
168 | .IQ "\fBadd\-flow \fIswitch \fB\- < \fIfile\fR" | |
169 | .IQ "\fBadd\-flows \fIswitch file\fR" | |
170 | Add each flow entry to \fIswitch\fR's tables. | |
171 | . | |
172 | .IP "[\fB\-\-strict\fR] \fBmod\-flows \fIswitch flow\fR" | |
173 | .IQ "[\fB\-\-strict\fR] \fBmod\-flows \fIswitch \fB\- < \fIfile\fR" | |
174 | Modify the actions in entries from \fIswitch\fR's tables that match | |
175 | the specified flows. With \fB\-\-strict\fR, wildcards are not treated | |
176 | as active for matching purposes. | |
177 | . | |
178 | .IP "\fBdel\-flows \fIswitch\fR" | |
179 | .IQ "[\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fR[\fIflow\fR]" | |
180 | .IQ "[\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fB\- < \fIfile\fR" | |
181 | Deletes entries from \fIswitch\fR's flow table. With only a | |
182 | \fIswitch\fR argument, deletes all flows. Otherwise, deletes flow | |
183 | entries that match the specified flows. With \fB\-\-strict\fR, | |
184 | wildcards are not treated as active for matching purposes. | |
a9b4a41a | 185 | . |
c4ea79bf | 186 | .IP "[\fB\-\-readd\fR] \fBreplace\-flows \fIswitch file\fR" |
0199c526 BP |
187 | Reads flow entries from \fIfile\fR (or \fBstdin\fR if \fIfile\fR is |
188 | \fB\-\fR) and queries the flow table from \fIswitch\fR. Then it fixes | |
189 | up any differences, adding flows from \fIflow\fR that are missing on | |
190 | \fIswitch\fR, deleting flows from \fIswitch\fR that are not in | |
191 | \fIfile\fR, and updating flows in \fIswitch\fR whose actions, cookie, | |
192 | or timeouts differ in \fIfile\fR. | |
193 | . | |
c4ea79bf BP |
194 | .IP |
195 | With \fB\-\-readd\fR, \fBovs\-ofctl\fR adds all the flows from | |
196 | \fIfile\fR, even those that exist with the same actions, cookie, and | |
197 | timeout in \fIswitch\fR. This resets all the flow packet and byte | |
198 | counters to 0, which can be useful for debugging. | |
199 | . | |
0199c526 BP |
200 | .IP "\fBdiff\-flows \fIsource1 source2\fR" |
201 | Reads flow entries from \fIsource1\fR and \fIsource2\fR and prints the | |
202 | differences. A flow that is in \fIsource1\fR but not in \fIsource2\fR | |
203 | is printed preceded by a \fB\-\fR, and a flow that is in \fIsource2\fR | |
204 | but not in \fIsource1\fR is printed preceded by a \fB+\fR. If a flow | |
205 | exists in both \fIsource1\fR and \fIsource2\fR with different actions, | |
206 | cookie, or timeouts, then both versions are printed preceded by | |
207 | \fB\-\fR and \fB+\fR, respectively. | |
208 | .IP | |
209 | \fIsource1\fR and \fIsource2\fR may each name a file or a switch. If | |
210 | a name begins with \fB/\fR or \fB.\fR, then it is considered to be a | |
211 | file name. A name that contains \fB:\fR is considered to be a switch. | |
212 | Otherwise, it is a file if a file by that name exists, a switch if | |
213 | not. | |
214 | .IP | |
215 | For this command, an exit status of 0 means that no differences were | |
216 | found, 1 means that an error occurred, and 2 means that some | |
217 | differences were found. | |
218 | . | |
4989c59f BP |
219 | .SS "OpenFlow Switch Monitoring Commands" |
220 | . | |
0caf6bde BP |
221 | .IP "\fBsnoop \fIswitch\fR" |
222 | Connects to \fIswitch\fR and prints to the console all OpenFlow | |
223 | messages received. Unlike other \fBovs\-ofctl\fR commands, if | |
224 | \fIswitch\fR is the name of a bridge, then the \fBsnoop\fR command | |
225 | connects to a Unix domain socket named | |
226 | \fB@RUNDIR@/\fIbridge\fB.snoop\fR. \fBovs\-vswitchd\fR listens on | |
227 | such a socket for each bridge and sends to it all of the OpenFlow | |
228 | messages sent to or received from its configured OpenFlow controller. | |
229 | Thus, this command can be used to view OpenFlow protocol activity | |
230 | between a switch and its controller. | |
231 | .IP | |
232 | When a switch has more than one controller configured, only the | |
e2bfacb6 BP |
233 | traffic to and from a single controller is output. If none of the |
234 | controllers is configured as a master or a slave (using a Nicira | |
235 | extension to OpenFlow), then a controller is chosen arbitrarily among | |
236 | them. If there is a master controller, it is chosen; otherwise, if | |
237 | there are any controllers that are not masters or slaves, one is | |
238 | chosen arbitrarily; otherwise, a slave controller is chosen | |
239 | arbitrarily. This choice is made once at connection time and does not | |
240 | change as controllers reconfigure their roles. | |
241 | .IP | |
242 | If a switch has no controller configured, or if | |
0caf6bde BP |
243 | the configured controller is disconnected, no traffic is sent, so |
244 | monitoring will not show any traffic. | |
245 | . | |
f0fd1a17 | 246 | .IP "\fBmonitor \fIswitch\fR [\fImiss-len\fR] [\fIinvalid_ttl\fR]" |
064af421 | 247 | Connects to \fIswitch\fR and prints to the console all OpenFlow |
045b2e5c BP |
248 | messages received. Usually, \fIswitch\fR should specify the name of a |
249 | bridge in the \fBovs\-vswitchd\fR database. | |
a9b4a41a | 250 | .IP |
064af421 BP |
251 | If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set |
252 | configuration'' message at connection setup time that requests | |
0caf6bde BP |
253 | \fImiss-len\fR bytes of each packet that misses the flow table. Open vSwitch |
254 | does not send these and other asynchronous messages to an | |
064af421 | 255 | \fBovs\-ofctl monitor\fR client connection unless a nonzero value is |
0caf6bde BP |
256 | specified on this argument. (Thus, if \fImiss\-len\fR is not |
257 | specified, very little traffic will ordinarily be printed.) | |
a9b4a41a | 258 | .IP |
f0fd1a17 PS |
259 | .IP |
260 | If \fBinvalid_ttl\fR is passed, \fBovs\-ofctl\fR sends an OpenFlow ``set | |
261 | configuration'' message at connection setup time that requests | |
262 | \fIINVALID_TTL_TO_CONTROLLER\fR, so that \fBovs\-ofctl monitor\fR can | |
263 | receive ``packets-in'' messages when TTL reaches zero on \fBdec_ttl\fR action. | |
264 | .IP | |
265 | ||
064af421 BP |
266 | This command may be useful for debugging switch or controller |
267 | implementations. | |
a9b4a41a | 268 | . |
064af421 | 269 | .SS "OpenFlow Switch and Controller Commands" |
a9b4a41a | 270 | . |
064af421 BP |
271 | The following commands, like those in the previous section, may be |
272 | applied to OpenFlow switches, using any of the connection methods | |
273 | described in that section. Unlike those commands, these may also be | |
274 | applied to OpenFlow controllers. | |
a9b4a41a | 275 | . |
064af421 BP |
276 | .TP |
277 | \fBprobe \fItarget\fR | |
278 | Sends a single OpenFlow echo-request message to \fItarget\fR and waits | |
4e312e69 | 279 | for the response. With the \fB\-t\fR or \fB\-\-timeout\fR option, this |
064af421 BP |
280 | command can test whether an OpenFlow switch or controller is up and |
281 | running. | |
a9b4a41a | 282 | . |
064af421 BP |
283 | .TP |
284 | \fBping \fItarget \fR[\fIn\fR] | |
285 | Sends a series of 10 echo request packets to \fItarget\fR and times | |
286 | each reply. The echo request packets consist of an OpenFlow header | |
287 | plus \fIn\fR bytes (default: 64) of randomly generated payload. This | |
288 | measures the latency of individual requests. | |
a9b4a41a | 289 | . |
064af421 BP |
290 | .TP |
291 | \fBbenchmark \fItarget n count\fR | |
292 | Sends \fIcount\fR echo request packets that each consist of an | |
293 | OpenFlow header plus \fIn\fR bytes of payload and waits for each | |
294 | response. Reports the total time required. This is a measure of the | |
295 | maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte | |
296 | messages. | |
a9b4a41a | 297 | . |
064af421 | 298 | .SS "Flow Syntax" |
a9b4a41a | 299 | .PP |
064af421 BP |
300 | Some \fBovs\-ofctl\fR commands accept an argument that describes a flow or |
301 | flows. Such flow descriptions comprise a series | |
302 | \fIfield\fB=\fIvalue\fR assignments, separated by commas or white | |
303 | space. (Embedding spaces into a flow description normally requires | |
304 | quoting to prevent the shell from breaking the description into | |
305 | multiple arguments.) | |
a9b4a41a | 306 | .PP |
0b3f2725 BP |
307 | Flow descriptions should be in \fBnormal form\fR. This means that a |
308 | flow may only specify a value for an L3 field if it also specifies a | |
309 | particular L2 protocol, and that a flow may only specify an L4 field | |
310 | if it also specifies particular L2 and L3 protocol types. For | |
311 | example, if the L2 protocol type \fBdl_type\fR is wildcarded, then L3 | |
312 | fields \fBnw_src\fR, \fBnw_dst\fR, and \fBnw_proto\fR must also be | |
313 | wildcarded. Similarly, if \fBdl_type\fR or \fBnw_proto\fR (the L3 | |
314 | protocol type) is wildcarded, so must be \fBtp_dst\fR and | |
315 | \fBtp_src\fR, which are L4 fields. \fBovs\-ofctl\fR will warn about | |
316 | flows not in normal form. | |
317 | .PP | |
064af421 BP |
318 | The following field assignments describe how a flow matches a packet. |
319 | If any of these assignments is omitted from the flow syntax, the field | |
320 | is treated as a wildcard; thus, if all of them are omitted, the | |
321 | resulting flow matches all packets. The string \fB*\fR or \fBANY\fR | |
322 | may be specified to explicitly mark any of these fields as a wildcard. | |
323 | (\fB*\fR should be quoted to protect it from shell expansion.) | |
a9b4a41a | 324 | . |
064af421 | 325 | .IP \fBin_port=\fIport_no\fR |
03a8a29e | 326 | Matches OpenFlow port \fIport_no\fR. Ports are numbered as |
064af421 | 327 | displayed by \fBovs\-ofctl show\fR. |
03a8a29e BP |
328 | .IP |
329 | (The \fBresubmit\fR action can search OpenFlow flow tables with | |
330 | arbitrary \fBin_port\fR values, so flows that match port numbers that | |
331 | do not exist from an OpenFlow perspective can still potentially be | |
332 | matched.) | |
a9b4a41a | 333 | . |
064af421 | 334 | .IP \fBdl_vlan=\fIvlan\fR |
f30f26be JP |
335 | Matches IEEE 802.1q Virtual LAN tag \fIvlan\fR. Specify \fB0xffff\fR |
336 | as \fIvlan\fR to match packets that are not tagged with a Virtual LAN; | |
064af421 BP |
337 | otherwise, specify a number between 0 and 4095, inclusive, as the |
338 | 12-bit VLAN ID to match. | |
a9b4a41a | 339 | . |
959a2ecd JP |
340 | .IP \fBdl_vlan_pcp=\fIpriority\fR |
341 | Matches IEEE 802.1q Priority Code Point (PCP) \fIpriority\fR, which is | |
342 | specified as a value between 0 and 7, inclusive. A higher value | |
343 | indicates a higher frame priority level. | |
a9b4a41a | 344 | . |
ed951f15 BP |
345 | .IP \fBdl_src=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR |
346 | .IQ \fBdl_dst=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR | |
347 | Matches an Ethernet source (or destination) address specified as 6 | |
348 | pairs of hexadecimal digits delimited by colons | |
349 | (e.g. \fB00:0A:E4:25:6B:B0\fR). | |
350 | . | |
cb8ca532 BP |
351 | .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 |
352 | Matches an Ethernet destination address specified as 6 pairs of | |
353 | hexadecimal digits delimited by colons (e.g. \fB00:0A:E4:25:6B:B0\fR), | |
354 | with a wildcard mask following the slash. Only | |
355 | the following masks are allowed: | |
356 | .RS | |
357 | .IP \fB01:00:00:00:00:00\fR | |
358 | Match only the multicast bit. Thus, | |
359 | \fBdl_dst=01:00:00:00:00:00/01:00:00:00:00:00\fR matches all multicast | |
360 | (including broadcast) Ethernet packets, and | |
361 | \fBdl_dst=00:00:00:00:00:00/01:00:00:00:00:00\fR matches all unicast | |
362 | Ethernet packets. | |
363 | .IP \fBfe:ff:ff:ff:ff:ff\fR | |
364 | Match all bits except the multicast bit. This is probably not useful. | |
365 | .IP \fBff:ff:ff:ff:ff:ff\fR | |
366 | Exact match (equivalent to omitting the mask). | |
367 | .IP \fB00:00:00:00:00:00\fR | |
368 | Wildcard all bits (equivalent to \fBdl_dst=*\fR.) | |
369 | .RE | |
370 | . | |
064af421 BP |
371 | .IP \fBdl_type=\fIethertype\fR |
372 | Matches Ethernet protocol type \fIethertype\fR, which is specified as an | |
373 | integer between 0 and 65535, inclusive, either in decimal or as a | |
374 | hexadecimal number prefixed by \fB0x\fR (e.g. \fB0x0806\fR to match ARP | |
375 | packets). | |
a9b4a41a | 376 | . |
064af421 | 377 | .IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR] |
ed951f15 BP |
378 | .IQ \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR] |
379 | When \fBdl_type\fR is 0x0800 (possibly via shorthand, e.g. \fBip\fR | |
380 | or \fBtcp\fR), matches IPv4 source (or destination) address \fIip\fR, | |
381 | which may be specified as an IP address or host name | |
382 | (e.g. \fB192.168.1.1\fR or \fBwww.example.com\fR). The optional | |
383 | \fInetmask\fR allows restricting a match to an IPv4 address prefix. | |
384 | The netmask may be specified as a dotted quad | |
385 | (e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block | |
064af421 | 386 | (e.g. \fB192.168.1.0/24\fR). |
ed951f15 BP |
387 | .IP |
388 | When \fBdl_type=0x0806\fR or \fBarp\fR is specified, matches the | |
389 | \fBar_spa\fR or \fBar_tpa\fR field, respectively, in ARP packets for | |
390 | IPv4 and Ethernet. | |
391 | .IP | |
392 | When \fBdl_type\fR is wildcarded or set to a value other than 0x0800 | |
0b3f2725 BP |
393 | or 0x0806, the values of \fBnw_src\fR and \fBnw_dst\fR are ignored |
394 | (see \fBFlow Syntax\fR above). | |
a9b4a41a | 395 | . |
064af421 | 396 | .IP \fBnw_proto=\fIproto\fR |
ed951f15 BP |
397 | When \fBip\fR or \fBdl_type=0x0800\fR is specified, matches IP |
398 | protocol type \fIproto\fR, which is specified as a decimal number | |
d31f1109 JP |
399 | between 0 and 255, inclusive (e.g. 1 to match ICMP packets or 6 to match |
400 | TCP packets). | |
401 | .IP | |
402 | When \fBipv6\fR or \fBdl_type=0x86dd\fR is specified, matches IPv6 | |
403 | header type \fIproto\fR, which is specified as a decimal number between | |
404 | 0 and 255, inclusive (e.g. 58 to match ICMPv6 packets or 6 to match | |
405 | TCP). The header type is the terminal header as described in the | |
406 | \fBDESIGN\fR document. | |
ed951f15 BP |
407 | .IP |
408 | When \fBarp\fR or \fBdl_type=0x0806\fR is specified, matches the lower | |
409 | 8 bits of the ARP opcode. ARP opcodes greater than 255 are treated as | |
410 | 0. | |
411 | .IP | |
d31f1109 JP |
412 | When \fBdl_type\fR is wildcarded or set to a value other than 0x0800, |
413 | 0x0806, or 0x86dd, the value of \fBnw_proto\fR is ignored (see \fBFlow | |
0b3f2725 | 414 | Syntax\fR above). |
a9b4a41a | 415 | . |
834377ea | 416 | .IP \fBnw_tos=\fItos\fR |
d31f1109 JP |
417 | Matches IP ToS/DSCP or IPv6 traffic class field \fItos\fR, which is |
418 | specified as a decimal number between 0 and 255, inclusive. Note that | |
419 | the two lower reserved bits are ignored for matching purposes. | |
ed951f15 | 420 | .IP |
5c0ceb0a JP |
421 | When \fBdl_type\fR is wildcarded or set to a value other than 0x0800 or |
422 | 0x86dd, the value of \fBnw_tos\fR is ignored (see \fBFlow Syntax\fR | |
423 | above). | |
a9b4a41a | 424 | . |
530180fd JP |
425 | .IP \fBnw_ecn=\fIecn\fR |
426 | Matches \fIecn\fR bits in IP ToS or IPv6 traffic class fields, which is | |
427 | specified as a decimal number between 0 and 3, inclusive. | |
428 | .IP | |
429 | When \fBdl_type\fR is wildcarded or set to a value other than 0x0800 or | |
430 | 0x86dd, the value of \fBnw_ecn\fR is ignored (see \fBFlow Syntax\fR | |
431 | above). | |
432 | . | |
a61680c6 JP |
433 | .IP \fBnw_ttl=\fIttl\fR |
434 | Matches IP TTL or IPv6 hop limit value \fIttl\fR, which is | |
435 | specified as a decimal number between 0 and 255, inclusive. | |
436 | .IP | |
437 | When \fBdl_type\fR is wildcarded or set to a value other than 0x0800 or | |
438 | 0x86dd, the value of \fBnw_ttl\fR is ignored (see \fBFlow Syntax\fR | |
439 | above). | |
440 | .IP | |
441 | . | |
064af421 | 442 | .IP \fBtp_src=\fIport\fR |
ed951f15 BP |
443 | .IQ \fBtp_dst=\fIport\fR |
444 | When \fBdl_type\fR and \fBnw_proto\fR specify TCP or UDP, \fBtp_src\fR | |
445 | and \fBtp_dst\fR match the UDP or TCP source or destination port | |
446 | \fIport\fR, respectively. which is specified as a decimal number | |
447 | between 0 and 65535, inclusive (e.g. 80 to match packets originating | |
064af421 | 448 | from a HTTP server). |
ed951f15 BP |
449 | .IP |
450 | When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of | |
0b3f2725 | 451 | these settings are ignored (see \fBFlow Syntax\fR above). |
a9b4a41a | 452 | . |
064af421 | 453 | .IP \fBicmp_type=\fItype\fR |
ed951f15 | 454 | .IQ \fBicmp_code=\fIcode\fR |
d31f1109 JP |
455 | When \fBdl_type\fR and \fBnw_proto\fR specify ICMP or ICMPv6, \fItype\fR |
456 | matches the ICMP type and \fIcode\fR matches the ICMP code. Each is | |
457 | specified as a decimal number between 0 and 255, inclusive. | |
ed951f15 BP |
458 | .IP |
459 | When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of | |
0b3f2725 | 460 | these settings are ignored (see \fBFlow Syntax\fR above). |
71e17a7a | 461 | . |
6c1491fb BP |
462 | .IP \fBtable=\fInumber\fR |
463 | If specified, limits the flow manipulation and flow dump commands to | |
68c59d15 | 464 | only apply to the table with the given \fInumber\fR between 0 and 254. |
6c1491fb | 465 | . |
68c59d15 BP |
466 | Behavior varies if \fBtable\fR is not specified (equivalent to |
467 | specifying 255 as \fInumber\fR). For flow table | |
6c1491fb BP |
468 | modification commands without \fB\-\-strict\fR, the switch will choose |
469 | the table for these commands to operate on. For flow table | |
470 | modification commands with \fB\-\-strict\fR, the command will operate | |
471 | on any single matching flow in any table; it will do nothing if there | |
472 | are matches in more than one table. The \fBdump-flows\fR and | |
473 | \fBdump-aggregate\fR commands will gather statistics about flows from | |
474 | all tables. | |
475 | .IP | |
476 | When this field is specified in \fBadd-flow\fR, \fBadd-flows\fR, | |
477 | \fBmod-flows\fR and \fBdel-flows\fR commands, it activates a Nicira | |
478 | extension to OpenFlow, which as of this writing is only known to be | |
479 | implemented by Open vSwitch. | |
480 | . | |
71e17a7a | 481 | .PP |
d31f1109 JP |
482 | The following shorthand notations are also available: |
483 | . | |
484 | .IP \fBip\fR | |
485 | Same as \fBdl_type=0x0800\fR. | |
486 | . | |
487 | .IP \fBicmp\fR | |
488 | Same as \fBdl_type=0x0800,nw_proto=1\fR. | |
489 | . | |
490 | .IP \fBtcp\fR | |
491 | Same as \fBdl_type=0x0800,nw_proto=6\fR. | |
492 | . | |
493 | .IP \fBudp\fR | |
494 | Same as \fBdl_type=0x0800,nw_proto=17\fR. | |
495 | . | |
496 | .IP \fBarp\fR | |
497 | Same as \fBdl_type=0x0806\fR. | |
498 | . | |
499 | .PP | |
71e17a7a JP |
500 | The following field assignments require support for the NXM (Nicira |
501 | Extended Match) extension to OpenFlow. When one of these is specified, | |
502 | \fBovs\-ofctl\fR will automatically attempt to negotiate use of this | |
503 | extension. If the switch does not support NXM, then \fBovs\-ofctl\fR | |
504 | will report a fatal error. | |
505 | . | |
33d8c6b4 BP |
506 | .IP \fBvlan_tci=\fItci\fR[\fB/\fImask\fR] |
507 | Matches modified VLAN TCI \fItci\fR. If \fImask\fR is omitted, | |
508 | \fItci\fR is the exact VLAN TCI to match; if \fImask\fR is specified, | |
a8600e1a | 509 | then a 1-bit in \fImask\fR indicates that the corresponding bit in |
33d8c6b4 BP |
510 | \fItci\fR must match exactly, and a 0-bit wildcards that bit. Both |
511 | \fItci\fR and \fImask\fR are 16-bit values that are decimal by | |
512 | default; use a \fB0x\fR prefix to specify them in hexadecimal. | |
513 | . | |
514 | .IP | |
515 | The value that \fBvlan_tci\fR matches against is 0 for a packet that | |
516 | has no 802.1Q header. Otherwise, it is the TCI value from the 802.1Q | |
517 | header with the CFI bit (with value \fB0x1000\fR) forced to 1. | |
518 | .IP | |
519 | Examples: | |
520 | .RS | |
521 | .IP \fBvlan_tci=0\fR | |
522 | Match only packets without an 802.1Q header. | |
523 | .IP \fBvlan_tci=0xf123\fR | |
524 | Match packets tagged with priority 7 in VLAN 0x123. | |
525 | .IP \fBvlan_tci=0x1123/0x1fff\fR | |
526 | Match packets tagged with VLAN 0x123 (and any priority). | |
527 | .IP \fBvlan_tci=0x5000/0xf000\fR | |
528 | Match packets tagged with priority 2 (in any VLAN). | |
529 | .IP \fBvlan_tci=0/0xfff\fR | |
530 | Match packets with no 802.1Q header or tagged with VLAN 0 (and any | |
531 | priority). | |
532 | .IP \fBvlan_tci=0x5000/0xe000\fR | |
533 | Match packets with no 802.1Q header or tagged with priority 2 (in any | |
534 | VLAN). | |
535 | .IP \fBvlan_tci=0/0xefff\fR | |
536 | Match packets with no 802.1Q header or tagged with VLAN 0 and priority | |
537 | 0. | |
538 | .RE | |
539 | .IP | |
540 | Some of these matching possibilities can also be achieved with | |
541 | \fBdl_vlan\fR and \fBdl_vlan_pcp\fR. | |
542 | . | |
7257b535 BP |
543 | .IP \fBip_frag=\fIfrag_type\fR |
544 | When \fBdl_type\fR specifies IP or IPv6, \fIfrag_type\fR | |
545 | specifies what kind of IP fragments or non-fragments to match. The | |
546 | following values of \fIfrag_type\fR are supported: | |
547 | .RS | |
548 | .IP "\fBno\fR" | |
549 | Matches only non-fragmented packets. | |
550 | .IP "\fByes\fR" | |
551 | Matches all fragments. | |
552 | .IP "\fBfirst\fR" | |
553 | Matches only fragments with offset 0. | |
554 | .IP "\fBlater\fR" | |
555 | Matches only fragments with nonzero offset. | |
556 | .IP "\fBnot_later\fR" | |
557 | Matches non-fragmented packets and fragments with zero offset. | |
558 | .RE | |
559 | .IP | |
560 | The \fBip_frag\fR match type is likely to be most useful in | |
561 | \fBnx\-match\fR mode. See the description of the \fBset\-frags\fR | |
562 | command, above, for more details. | |
563 | . | |
bad68a99 JP |
564 | .IP \fBarp_sha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR |
565 | .IQ \fBarp_tha=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR | |
566 | When \fBdl_type\fR specifies ARP, \fBarp_sha\fR and \fBarp_tha\fR match | |
567 | the source and target hardware address, respectively. An address is | |
568 | specified as 6 pairs of hexadecimal digits delimited by colons. | |
569 | . | |
d31f1109 JP |
570 | .IP \fBipv6_src=\fIipv6\fR[\fB/\fInetmask\fR] |
571 | .IQ \fBipv6_dst=\fIipv6\fR[\fB/\fInetmask\fR] | |
572 | When \fBdl_type\fR is 0x86dd (possibly via shorthand, e.g., \fBipv6\fR | |
573 | or \fBtcp6\fR), matches IPv6 source (or destination) address \fIipv6\fR, | |
574 | which may be specified as defined in RFC 2373. The preferred format is | |
575 | \fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fB:\fIx\fR, where | |
576 | \fIx\fR are the hexadecimal values of the eight 16-bit pieces of the | |
577 | address. A single instance of \fB::\fR may be used to indicate multiple | |
578 | groups of 16-bits of zeros. The optional \fInetmask\fR allows | |
579 | restricting a match to an IPv6 address prefix. A netmask is specified | |
580 | as a CIDR block (e.g. \fB2001:db8:3c4d:1::/64\fR). | |
581 | . | |
fa8223b7 JP |
582 | .IP \fBipv6_label=\fIlabel\fR |
583 | When \fBdl_type\fR is 0x86dd (possibly via shorthand, e.g., \fBipv6\fR | |
584 | or \fBtcp6\fR), matches IPv6 flow label \fIlabel\fR. | |
585 | . | |
685a51a5 JP |
586 | .IP \fBnd_target=\fIipv6\fR |
587 | When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify | |
588 | IPv6 Neighbor Discovery (ICMPv6 type 135 or 136), matches the target address | |
589 | \fIipv6\fR. \fIipv6\fR is in the same format described earlier for the | |
590 | \fBipv6_src\fR and \fBipv6_dst\fR fields. | |
591 | . | |
592 | .IP \fBnd_sll=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR | |
593 | When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify IPv6 | |
594 | Neighbor Solicitation (ICMPv6 type 135), matches the source link\-layer | |
595 | address option. An address is specified as 6 pairs of hexadecimal | |
596 | digits delimited by colons. | |
597 | . | |
598 | .IP \fBnd_tll=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR | |
599 | When \fBdl_type\fR, \fBnw_proto\fR, and \fBicmp_type\fR specify IPv6 | |
600 | Neighbor Advertisement (ICMPv6 type 136), matches the target link\-layer | |
601 | address option. An address is specified as 6 pairs of hexadecimal | |
602 | digits delimited by colons. | |
603 | . | |
8368c090 BP |
604 | .IP \fBtun_id=\fItunnel-id\fR[\fB/\fImask\fR] |
605 | Matches tunnel identifier \fItunnel-id\fR. Only packets that arrive | |
4c5df7f7 | 606 | over a tunnel that carries a key (e.g. GRE with the RFC 2890 key |
8368c090 | 607 | extension) will have a nonzero tunnel ID. If \fImask\fR is omitted, |
71e17a7a | 608 | \fItunnel-id\fR is the exact tunnel ID to match; if \fImask\fR is |
8368c090 BP |
609 | specified, then a 1-bit in \fImask\fR indicates that the corresponding |
610 | bit in \fItunnel-id\fR must match exactly, and a 0-bit wildcards that | |
611 | bit. | |
4c5df7f7 | 612 | .IP |
71e17a7a JP |
613 | In an attempt to be compatible with more switches, \fBovs\-ofctl\fR will |
614 | prefer to use the ``tunnel ID from cookie'' Nicira extension to NXM. | |
615 | The use of this extension comes with three caveats: the top 32 bits of | |
616 | the \fBcookie\fR (see below) are used for \fItunnel-id\fR and thus | |
617 | unavailable for other use, specifying \fBtun_id\fR on \fBdump\-flows\fR | |
618 | or \fBdump\-aggregate\fR has no effect, and \fImask\fR is not supported. | |
619 | If any of these caveats apply, \fBovs-ofctl\fR will use NXM. | |
620 | . | |
00b1c62f BP |
621 | .IP "\fBreg\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]" |
622 | Matches \fIvalue\fR either exactly or with optional \fImask\fR in | |
623 | register number \fIidx\fR. The valid range of \fIidx\fR depends on | |
624 | the switch. \fIvalue\fR and \fImask\fR are 32-bit integers, by | |
625 | default in decimal (use a \fB0x\fR prefix to specify hexadecimal). | |
626 | Arbitrary \fImask\fR values are allowed: a 1-bit in \fImask\fR | |
627 | indicates that the corresponding bit in \fIvalue\fR must match | |
628 | exactly, and a 0-bit wildcards that bit. | |
629 | .IP | |
630 | When a packet enters an OpenFlow switch, all of the registers are set | |
631 | to 0. Only explicit Nicira extension actions change register values. | |
a9b4a41a | 632 | . |
064af421 | 633 | .PP |
d31f1109 JP |
634 | Defining IPv6 flows (those with \fBdl_type\fR equal to 0x86dd) requires |
635 | support for NXM. The following shorthand notations are available for | |
636 | IPv6-related flows: | |
a9b4a41a | 637 | . |
d31f1109 JP |
638 | .IP \fBipv6\fR |
639 | Same as \fBdl_type=0x86dd\fR. | |
a9b4a41a | 640 | . |
d31f1109 JP |
641 | .IP \fBtcp6\fR |
642 | Same as \fBdl_type=0x86dd,nw_proto=6\fR. | |
a9b4a41a | 643 | . |
d31f1109 JP |
644 | .IP \fBudp6\fR |
645 | Same as \fBdl_type=0x86dd,nw_proto=17\fR. | |
a9b4a41a | 646 | . |
d31f1109 JP |
647 | .IP \fBicmp6\fR |
648 | Same as \fBdl_type=0x86dd,nw_proto=58\fR. | |
a9b4a41a | 649 | . |
064af421 | 650 | .PP |
2c6d8411 BP |
651 | Finally, field assignments to \fBduration\fR, \fBn_packets\fR, or |
652 | \fBn_bytes\fR are ignored to allow output from the \fBdump\-flows\fR | |
653 | command to be used as input for other commands that parse flows. | |
654 | . | |
655 | .PP | |
c821124b BP |
656 | The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands |
657 | require an additional field, which must be the final field specified: | |
a9b4a41a | 658 | . |
064af421 BP |
659 | .IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR |
660 | Specifies a comma-separated list of actions to take on a packet when the | |
661 | flow entry matches. If no \fItarget\fR is specified, then packets | |
662 | matching the flow are dropped. The \fItarget\fR may be a decimal port | |
663 | number designating the physical port on which to output the packet, or one | |
664 | of the following keywords: | |
a9b4a41a | 665 | . |
064af421 BP |
666 | .RS |
667 | .IP \fBoutput\fR:\fIport\fR | |
f694937d EJ |
668 | .IQ \fBoutput\fR:\fIsrc\fB[\fIstart\fB..\fIend\fB] |
669 | Outputs the packet. If \fIport\fR is an OpenFlow port number, outputs directly | |
670 | to it. Otherwise, outputs to the OpenFlow port number read from \fIsrc\fR | |
671 | which must be an NXM field as described above. Outputting to an NXM field is | |
672 | an OpenFlow extension which is not supported by standard OpenFlow switches. | |
673 | .IP | |
674 | Example: \fBoutput:NXM_NX_REG0[16..31]\fR outputs to the OpenFlow port number | |
675 | written in the upper half of register 0. | |
a9b4a41a | 676 | . |
5682f723 BP |
677 | .IP \fBenqueue\fR:\fIport\fB:\fIqueue\fR |
678 | Enqueues the packet on the specified \fIqueue\fR within port | |
679 | \fIport\fR. The number of supported queues depends on the switch; | |
680 | some OpenFlow implementations do not support queuing at all. | |
681 | . | |
064af421 BP |
682 | .IP \fBnormal\fR |
683 | Subjects the packet to the device's normal L2/L3 processing. (This | |
684 | action is not implemented by all OpenFlow switches.) | |
a9b4a41a | 685 | . |
064af421 BP |
686 | .IP \fBflood\fR |
687 | Outputs the packet on all switch physical ports other than the port on | |
688 | which it was received and any ports on which flooding is disabled | |
689 | (typically, these would be ports disabled by the IEEE 802.1D spanning | |
690 | tree protocol). | |
a9b4a41a | 691 | . |
064af421 BP |
692 | .IP \fBall\fR |
693 | Outputs the packet on all switch physical ports other than the port on | |
694 | which it was received. | |
a9b4a41a | 695 | . |
064af421 BP |
696 | .IP \fBcontroller\fR:\fImax_len\fR |
697 | Sends the packet to the OpenFlow controller as a ``packet in'' | |
698 | message. If \fImax_len\fR is a number, then it specifies the maximum | |
699 | number of bytes that should be sent. If \fImax_len\fR is \fBALL\fR or | |
700 | omitted, then the entire packet is sent. | |
a9b4a41a | 701 | . |
064af421 BP |
702 | .IP \fBlocal\fR |
703 | Outputs the packet on the ``local port,'' which corresponds to the | |
045b2e5c | 704 | network device that has the same name as the bridge. |
a9b4a41a | 705 | . |
64c1e8af JP |
706 | .IP \fBin_port\fR |
707 | Outputs the packet on the port from which it was received. | |
708 | . | |
064af421 BP |
709 | .IP \fBdrop\fR |
710 | Discards the packet, so no further processing or forwarding takes place. | |
711 | If a drop action is used, no other actions may be specified. | |
a9b4a41a | 712 | . |
064af421 BP |
713 | .IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR |
714 | Modifies the VLAN id on a packet. The VLAN tag is added or modified | |
715 | as necessary to match the value specified. If the VLAN tag is added, | |
716 | a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set | |
717 | this). | |
a9b4a41a | 718 | . |
064af421 BP |
719 | .IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR |
720 | Modifies the VLAN priority on a packet. The VLAN tag is added or modified | |
721 | as necessary to match the value specified. Valid values are between 0 | |
722 | (lowest) and 7 (highest). If the VLAN tag is added, a vid of zero is used | |
723 | (see the \fBmod_vlan_vid\fR action to set this). | |
a9b4a41a | 724 | . |
064af421 BP |
725 | .IP \fBstrip_vlan\fR |
726 | Strips the VLAN tag from a packet if it is present. | |
a9b4a41a | 727 | . |
064af421 BP |
728 | .IP \fBmod_dl_src\fB:\fImac\fR |
729 | Sets the source Ethernet address to \fImac\fR. | |
a9b4a41a | 730 | . |
064af421 BP |
731 | .IP \fBmod_dl_dst\fB:\fImac\fR |
732 | Sets the destination Ethernet address to \fImac\fR. | |
a9b4a41a | 733 | . |
e423eca6 JP |
734 | .IP \fBmod_nw_src\fB:\fIip\fR |
735 | Sets the IPv4 source address to \fIip\fR. | |
a9b4a41a | 736 | . |
e423eca6 JP |
737 | .IP \fBmod_nw_dst\fB:\fIip\fR |
738 | Sets the IPv4 destination address to \fIip\fR. | |
a9b4a41a | 739 | . |
e423eca6 JP |
740 | .IP \fBmod_tp_src\fB:\fIport\fR |
741 | Sets the TCP or UDP source port to \fIport\fR. | |
a9b4a41a | 742 | . |
e423eca6 JP |
743 | .IP \fBmod_tp_dst\fB:\fIport\fR |
744 | Sets the TCP or UDP destination port to \fIport\fR. | |
a9b4a41a | 745 | . |
959a2ecd | 746 | .IP \fBmod_nw_tos\fB:\fItos\fR |
c4f2731d | 747 | Sets the IPv4 ToS/DSCP field to \fItos\fR. Valid values are between 0 and |
959a2ecd JP |
748 | 255, inclusive. Note that the two lower reserved bits are never |
749 | modified. | |
a9b4a41a | 750 | . |
659586ef JG |
751 | .RE |
752 | .IP | |
753 | The following actions are Nicira vendor extensions that, as of this writing, are | |
754 | only known to be implemented by Open vSwitch: | |
755 | . | |
756 | .RS | |
757 | . | |
3a2fe1f3 | 758 | .IP \fBresubmit\fB:\fIport\fR |
29901626 BP |
759 | .IQ \fBresubmit\fB(\fR[\fIport\fR]\fB,\fR[\fItable\fR]\fB) |
760 | Re-searches this OpenFlow flow table (or the table whose number is | |
761 | specified by \fItable\fR) with the \fBin_port\fR field replaced by | |
762 | \fIport\fR (if \fIport\fR is specified) and executes the actions | |
763 | found, if any, in addition to any other actions in this flow entry. | |
764 | .IP | |
765 | Recursive \fBresubmit\fR actions are obeyed up to an | |
766 | implementation-defined maximum depth. Open vSwitch 1.0.1 and earlier | |
767 | did not support recursion; Open vSwitch before 1.2.90 did not support | |
768 | \fItable\fR. | |
659586ef JG |
769 | . |
770 | .IP \fBset_tunnel\fB:\fIid\fR | |
b9298d3f BP |
771 | .IQ \fBset_tunnel64\fB:\fIid\fR |
772 | If outputting to a port that encapsulates the packet in a tunnel and | |
5a6861aa | 773 | supports an identifier (such as GRE), sets the identifier to \fIid\fR. |
b9298d3f BP |
774 | If the \fBset_tunnel\fR form is used and \fIid\fR fits in 32 bits, |
775 | then this uses an action extension that is supported by Open vSwitch | |
776 | 1.0 and later. Otherwise, if \fIid\fR is a 64-bit value, it requires | |
777 | Open vSwitch 1.1 or later. | |
3a2fe1f3 | 778 | . |
eedc0097 JP |
779 | .IP \fBset_queue\fB:\fIqueue\fR |
780 | Sets the queue that should be used to \fIqueue\fR when packets are | |
781 | output. The number of supported queues depends on the switch; some | |
782 | OpenFlow implementations do not support queuing at all. | |
783 | . | |
784 | .IP \fBpop_queue\fR | |
785 | Restores the queue to the value it was before any \fBset_queue\fR | |
786 | actions were applied. | |
787 | . | |
f0fd1a17 PS |
788 | .IP \fBdec_ttl\fR |
789 | Decrement TTL of IPv4 packet or hop limit of IPv6 packet. If the | |
790 | TTL or hop limit is initially zero, no decrement occurs. Instead, | |
791 | a ``packet-in'' message with reason code \fBOFPR_INVALID_TTL\fR is | |
792 | sent to each connected controller that has enabled receiving them, | |
793 | if any. Processing the current set of actions then stops. | |
794 | However, if the current set of actions was reached through | |
795 | ``resubmit'' then remaining actions in outer levels resume | |
796 | processing. | |
797 | . | |
96fc46e8 BP |
798 | .IP \fBnote:\fR[\fIhh\fR]... |
799 | Does nothing at all. Any number of bytes represented as hex digits | |
800 | \fIhh\fR may be included. Pairs of hex digits may be separated by | |
801 | periods for readability. | |
f393f81e | 802 | . |
5a6861aa | 803 | .IP "\fBmove:\fIsrc\fB[\fIstart\fB..\fIend\fB]\->\fIdst\fB[\fIstart\fB..\fIend\fB]\fR" |
f393f81e BP |
804 | Copies the named bits from field \fIsrc\fR to field \fIdst\fR. |
805 | \fIsrc\fR and \fIdst\fR must be NXM field names as defined in | |
806 | \fBnicira\-ext.h\fR, e.g. \fBNXM_OF_UDP_SRC\fR or \fBNXM_NX_REG0\fR. | |
807 | Each \fIstart\fR and \fIend\fR pair, which are inclusive, must specify | |
808 | the same number of bits and must fit within its respective field. | |
809 | Shorthands for \fB[\fIstart\fB..\fIend\fB]\fR exist: use | |
810 | \fB[\fIbit\fB]\fR to specify a single bit or \fB[]\fR to specify an | |
811 | entire field. | |
812 | .IP | |
813 | Examples: \fBmove:NXM_NX_REG0[0..5]\->NXM_NX_REG1[26..31]\fR copies the | |
814 | six bits numbered 0 through 5, inclusive, in register 0 into bits 26 | |
815 | through 31, inclusive; | |
5a6861aa | 816 | \fBmove:NXM_NX_REG0[0..15]\->NXM_OF_VLAN_TCI[]\fR copies the least |
f393f81e BP |
817 | significant 16 bits of register 0 into the VLAN TCI field. |
818 | . | |
819 | .IP "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]" | |
820 | Writes \fIvalue\fR to bits \fIstart\fR through \fIend\fR, inclusive, | |
5a6861aa | 821 | in field \fIdst\fR. |
f393f81e BP |
822 | .IP |
823 | Example: \fBload:55\->NXM_NX_REG2[0..5]\fR loads value 55 (bit pattern | |
824 | \fB110111\fR) into bits 0 through 5, inclusive, in register 2. | |
53ddd40a BP |
825 | . |
826 | .IP "\fBmultipath(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIn_links\fB, \fIarg\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR" | |
827 | Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter, | |
828 | then the applies multipath link selection \fIalgorithm\fR (with | |
829 | parameter \fIarg\fR) to choose one of \fIn_links\fR output links | |
830 | numbered 0 through \fIn_links\fR minus 1, and stores the link into | |
43edca57 | 831 | \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as |
53ddd40a BP |
832 | described above. |
833 | .IP | |
834 | Currently, \fIfields\fR must be either \fBeth_src\fR or | |
835 | \fBsymmetric_l4\fR and \fIalgorithm\fR must be one of \fBmodulo_n\fR, | |
836 | \fBhash_threshold\fR, \fBhrw\fR, and \fBiter_hash\fR. Only | |
837 | the \fBiter_hash\fR algorithm uses \fIarg\fR. | |
838 | .IP | |
839 | Refer to \fBnicira\-ext.h\fR for more details. | |
3b6a2571 EJ |
840 | . |
841 | .IP "\fBautopath(\fIid\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR" | |
842 | Given \fIid\fR, chooses an OpenFlow port and populates it in | |
43edca57 | 843 | \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as |
3b6a2571 EJ |
844 | described above. |
845 | .IP | |
846 | Currently, \fIid\fR should be the OpenFlow port number of an interface on the | |
847 | bridge. If it isn't then \fIdst\fB[\fIstart\fB..\fIend\fB]\fR will be | |
848 | populated with the OpenFlow port "none". If \fIid\fR is a member of a bond, | |
849 | the normal bond selection logic will be used to choose the destination port. | |
850 | Otherwise, the register will be populated with \fIid\fR itself. | |
851 | .IP | |
852 | Refer to \fBnicira\-ext.h\fR for more details. | |
daff3353 EJ |
853 | . |
854 | .IP "\fBbundle(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, slaves:[\fIs1\fB, \fIs2\fB, ...])\fR" | |
855 | Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter, then | |
856 | applies the bundle link selection \fIalgorithm\fR to choose one of the listed | |
857 | slaves represented as \fIslave_type\fR. Currently the only supported | |
858 | \fIslave_type\fR is \fBofport\fR. Thus, each \fIs1\fR through \fIsN\fR should | |
859 | be an OpenFlow port number. Outputs to the selected slave. | |
860 | .IP | |
861 | Currently, \fIfields\fR must be either \fBeth_src\fR or \fBsymmetric_l4\fR and | |
862 | \fIalgorithm\fR must be one of \fBhrw\fR and \fBactive_backup\fR. | |
863 | .IP | |
864 | Example: \fBbundle(eth_src,0,hrw,ofport,slaves:4,8)\fR uses an Ethernet source | |
865 | hash with basis 0, to select between OpenFlow ports 4 and 8 using the Highest | |
866 | Random Weight algorithm. | |
867 | .IP | |
868 | Refer to \fBnicira\-ext.h\fR for more details. | |
a368bb53 EJ |
869 | . |
870 | .IP "\fBbundle_load(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, \fIdst\fB[\fIstart\fB..\fIend\fB], slaves:[\fIs1\fB, \fIs2\fB, ...])\fR" | |
871 | Has the same behavior as the \fBbundle\fR action, with one exception. Instead | |
872 | of outputting to the selected slave, it writes its selection to | |
873 | \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as described | |
874 | above. | |
875 | .IP | |
2638c6dc BP |
876 | Example: \fBbundle_load(eth_src, 0, hrw, ofport, NXM_NX_REG0[], |
877 | slaves:4, 8)\fR uses an Ethernet source hash with basis 0, to select | |
878 | between OpenFlow ports 4 and 8 using the Highest Random Weight | |
879 | algorithm, and writes the selection to \fBNXM_NX_REG0[]\fR. | |
a368bb53 EJ |
880 | .IP |
881 | Refer to \fBnicira\-ext.h\fR for more details. | |
75a75043 BP |
882 | . |
883 | .IP "\fBlearn(\fIargument\fR[\fB,\fIargument\fR]...\fB)\fR" | |
884 | This action adds or modifies a flow in an OpenFlow table, similar to | |
885 | \fBovs\-ofctl \-\-strict mod\-flows\fR. The arguments specify the | |
886 | flow's match fields, actions, and other properties, as follows. At | |
887 | least one match criterion and one action argument should ordinarily be | |
888 | specified. | |
889 | .RS | |
890 | .IP \fBidle_timeout=\fIseconds\fR | |
891 | .IQ \fBhard_timeout=\fIseconds\fR | |
892 | .IQ \fBpriority=\fIvalue\fR | |
893 | These key-value pairs have the same meaning as in the usual | |
894 | \fBovs\-ofctl\fR flow syntax. | |
895 | . | |
896 | .IP \fBtable=\fInumber\fR | |
897 | The table in which the new flow should be inserted. Specify a decimal | |
898 | number between 0 and 254. The default, if \fBtable\fR is unspecified, | |
899 | is table 1. | |
900 | . | |
901 | .IP \fIfield\fB=\fIvalue\fR | |
902 | .IQ \fIfield\fB[\fIstart\fB..\fIend\fB]=\fIsrc\fB[\fIstart\fB..\fIend\fB]\fR | |
903 | .IQ \fIfield\fB[\fIstart\fB..\fIend\fB]\fR | |
904 | Adds a match criterion to the new flow. | |
905 | .IP | |
906 | The first form specifies that \fIfield\fR must match the literal | |
907 | \fIvalue\fR, e.g. \fBdl_type=0x0800\fR. All of the fields and values | |
908 | for \fBovs\-ofctl\fR flow syntax are available with their usual | |
909 | meanings. | |
910 | .IP | |
911 | The second form specifies that \fIfield\fB[\fIstart\fB..\fIend\fB]\fR | |
912 | in the new flow must match \fIsrc\fB[\fIstart\fB..\fIend\fB]\fR taken | |
913 | from the flow currently being processed. | |
914 | .IP | |
915 | The third form is a shorthand for the second form. It specifies that | |
916 | \fIfield\fB[\fIstart\fB..\fIend\fB]\fR in the new flow must match | |
917 | \fIfield\fB[\fIstart\fB..\fIend\fB]\fR taken from the flow currently | |
918 | being processed. | |
919 | . | |
920 | .IP \fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB] | |
921 | .IQ \fBload:\fIsrc\fB[\fIstart\fB..\fIend\fB]\->\fIdst\fB[\fIstart\fB..\fIend\fB] | |
922 | . | |
923 | Adds a \fBload\fR action to the new flow. | |
924 | .IP | |
925 | The first form loads the literal \fIvalue\fR into bits \fIstart\fR | |
926 | through \fIend\fR, inclusive, in field \fIdst\fR. Its syntax is the | |
927 | same as the \fBload\fR action described earlier in this section. | |
928 | .IP | |
929 | The second form loads \fIsrc\fB[\fIstart\fB..\fIend\fB]\fR, a value | |
930 | from the flow currently being processed, into bits \fIstart\fR | |
931 | through \fIend\fR, inclusive, in field \fIdst\fR. | |
932 | . | |
933 | .IP \fBoutput:\fIfield\fB[\fIstart\fB..\fIend\fB]\fR | |
934 | Add an \fBoutput\fR action to the new flow's actions, that outputs to | |
935 | the OpenFlow port taken from \fIfield\fB[\fIstart\fB..\fIend\fB]\fR, | |
936 | which must be an NXM field as described above. | |
937 | .RE | |
938 | .IP | |
939 | For best performance, segregate learned flows into a table (using | |
940 | \fBtable=\fInumber\fR) that is not used for any other flows except | |
941 | possibly for a lowest-priority ``catch-all'' flow, that is, a flow | |
942 | with no match criteria. (This is why the default \fBtable\fR is 1, to | |
943 | keep the learned flows separate from the primary flow table 0.) | |
064af421 | 944 | .RE |
a9b4a41a | 945 | . |
848e8809 EJ |
946 | .IP "\fBexit\fR" |
947 | This action causes Open vSwitch to immediately halt execution of further | |
948 | actions. Those actions which have already been executed are unaffected. Any | |
949 | further actions, including those which may be in other tables, or different | |
950 | levels of the \fBresubmit\fR call stack, are ignored. | |
951 | . | |
064af421 | 952 | .PP |
e729e793 JP |
953 | An opaque identifier called a cookie can be used as a handle to identify |
954 | a set of flows: | |
955 | . | |
956 | .IP \fBcookie=\fIvalue\fR[\fB/\fImask\fR] | |
957 | . | |
958 | A cookie can be associated with a flow using the \fBadd-flow\fR and | |
959 | \fBadd-flows\fR commands. \fIvalue\fR can be any 64-bit number and need | |
960 | not be unique among flows. If this field is omitted, a default cookie | |
961 | value of 0 is used. | |
962 | .IP | |
963 | When using NXM, the cookie can be used as a handle for querying, | |
964 | modifying, and deleting flows. In addition to \fIvalue\fR, an optional | |
965 | \fImask\fR may be supplied for the \fBdel-flows\fR, \fBmod-flows\fR, | |
966 | \fBdump-flows\fR, and \fBdump-aggregate\fR commands to limit matching | |
967 | cookies. A 1-bit in \fImask\fR indicates that the corresponding bit in | |
968 | \fIcookie\fR must match exactly, and a 0-bit wildcards that bit. | |
8cce2125 JP |
969 | . |
970 | .PP | |
4b6b46ce BP |
971 | The following additional field sets the priority for flows added by |
972 | the \fBadd\-flow\fR and \fBadd\-flows\fR commands. For | |
973 | \fBmod\-flows\fR and \fBdel\-flows\fR when \fB\-\-strict\fR is | |
974 | specified, priority must match along with the rest of the flow | |
c821124b | 975 | specification. Other commands do not allow priority to be specified. |
a9b4a41a | 976 | . |
064af421 BP |
977 | .IP \fBpriority=\fIvalue\fR |
978 | The priority at which a wildcarded entry will match in comparison to | |
979 | others. \fIvalue\fR is a number between 0 and 65535, inclusive. A higher | |
980 | \fIvalue\fR will match before a lower one. An exact-match entry will always | |
981 | have priority over an entry containing wildcards, so it has an implicit | |
982 | priority value of 65535. When adding a flow, if the field is not specified, | |
983 | the flow's priority will default to 32768. | |
a9b4a41a | 984 | . |
064af421 | 985 | .PP |
4e312e69 | 986 | The \fBadd\-flow\fR and \fBadd\-flows\fR commands support additional |
064af421 | 987 | optional fields: |
a9b4a41a | 988 | . |
064af421 BP |
989 | .TP |
990 | \fBidle_timeout=\fIseconds\fR | |
991 | Causes the flow to expire after the given number of seconds of | |
a1545337 BP |
992 | inactivity. A value of 0 (the default) prevents a flow from expiring due to |
993 | inactivity. | |
a9b4a41a | 994 | . |
064af421 BP |
995 | .IP \fBhard_timeout=\fIseconds\fR |
996 | Causes the flow to expire after the given number of seconds, | |
997 | regardless of activity. A value of 0 (the default) gives the flow no | |
998 | hard expiration deadline. | |
a9b4a41a | 999 | . |
064af421 | 1000 | .PP |
4e312e69 BP |
1001 | The \fBdump\-flows\fR, \fBdump\-aggregate\fR, \fBdel\-flow\fR |
1002 | and \fBdel\-flows\fR commands support one additional optional field: | |
a9b4a41a | 1003 | . |
064af421 BP |
1004 | .TP |
1005 | \fBout_port=\fIport\fR | |
1006 | If set, a matching flow must include an output action to \fIport\fR. | |
a9b4a41a | 1007 | . |
064af421 | 1008 | .SS "Table Entry Output" |
a9b4a41a | 1009 | . |
4e312e69 | 1010 | The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information |
064af421 BP |
1011 | about the entries in a datapath's tables. Each line of output is a |
1012 | unique flow entry, which begins with some common information: | |
a9b4a41a | 1013 | . |
064af421 BP |
1014 | .IP \fBduration\fR |
1015 | The number of seconds the entry has been in the table. | |
a9b4a41a | 1016 | . |
064af421 BP |
1017 | .IP \fBtable_id\fR |
1018 | The table that contains the flow. When a packet arrives, the switch | |
1019 | begins searching for an entry at the lowest numbered table. Tables are | |
4e312e69 | 1020 | numbered as shown by the \fBdump\-tables\fR command. |
a9b4a41a | 1021 | . |
064af421 BP |
1022 | .IP \fBpriority\fR |
1023 | The priority of the entry in relation to other entries within the same | |
1024 | table. A higher value will match before a lower one. | |
a9b4a41a | 1025 | . |
064af421 BP |
1026 | .IP \fBn_packets\fR |
1027 | The number of packets that have matched the entry. | |
a9b4a41a | 1028 | . |
064af421 BP |
1029 | .IP \fBn_bytes\fR |
1030 | The total number of bytes from packets that have matched the entry. | |
a9b4a41a | 1031 | . |
064af421 BP |
1032 | .PP |
1033 | The rest of the line consists of a description of the flow entry as | |
1034 | described in \fBFlow Syntax\fR, above. | |
a9b4a41a BP |
1035 | . |
1036 | . | |
064af421 BP |
1037 | .SH OPTIONS |
1038 | .TP | |
4e312e69 | 1039 | \fB\-\-strict\fR |
064af421 | 1040 | Uses strict matching when running flow modification commands. |
a9b4a41a | 1041 | . |
88ca35ee BP |
1042 | .IP "\fB\-F \fIformat\fR" |
1043 | .IQ "\fB\-\-flow\-format=\fIformat\fR" | |
1044 | \fBovs\-ofctl\fR supports the following flow formats, in order of | |
1045 | increasing capability: | |
1046 | .RS | |
1047 | .IP "\fBopenflow10\fR" | |
1048 | This is the standard OpenFlow 1.0 flow format. It should be supported | |
1049 | by all OpenFlow switches. | |
1050 | . | |
88ca35ee BP |
1051 | .IP "\fBnxm\fR (Nicira Extended Match)" |
1052 | This Nicira extension to OpenFlow is flexible and extensible. It | |
1053 | supports all of the Nicira flow extensions, such as \fBtun_id\fR and | |
1054 | registers. | |
1055 | .RE | |
1056 | .IP | |
1057 | Usually, \fBovs\-ofctl\fR picks the correct format automatically. For | |
1058 | commands that modify the flow table, \fBovs\-ofctl\fR by default uses | |
1059 | the most widely supported flow format that supports the flows being | |
1060 | added. For commands that query the flow table, \fBovs\-ofctl\fR by | |
1061 | default queries and uses the most advanced format supported by the | |
1062 | switch. | |
1063 | .IP | |
1064 | This option, where \fIformat\fR is one of the formats listed in the | |
1065 | above table, overrides \fBovs\-ofctl\fR's default choice of flow | |
1066 | format. If a command cannot work as requested using the requested | |
1067 | flow format, \fBovs\-ofctl\fR will report a fatal error. | |
4f564f8d | 1068 | . |
54834960 EJ |
1069 | . |
1070 | .IP "\fB\-P \fIformat\fR" | |
1071 | .IQ "\fB\-\-packet\-in\-format=\fIformat\fR" | |
1072 | \fBovs\-ofctl\fR supports the following packet_in formats, in order of | |
1073 | increasing capability: | |
1074 | .RS | |
1075 | .IP "\fBopenflow10\fR" | |
1076 | This is the standard OpenFlow 1.0 packet in format. It should be supported by | |
1077 | all OpenFlow switches. | |
1078 | . | |
1079 | .IP "\fBnxm\fR (Nicira Extended Match)" | |
1080 | This packet_in format includes flow metadata encoded using the NXM format. | |
1081 | . | |
1082 | .RE | |
1083 | .IP | |
1084 | Usually, \fBovs\-ofctl\fR prefers the \fBnxm\fR packet_in format, but will | |
1085 | allow the switch to choose its default if \fBnxm\fR is unsupported. When | |
1086 | \fIformat\fR is one of the formats listed in the above table, \fBovs\-ofctl\fR | |
1087 | will insist on the selected format. If the switch does not support the | |
1088 | requested format, \fBovs\-ofctl\fR will report a fatal error. This option only | |
1089 | affects the \fBmonitor\fR and \fBsnoop\fR commands. | |
1090 | . | |
4f564f8d BP |
1091 | .IP "\fB\-m\fR" |
1092 | .IQ "\fB\-\-more\fR" | |
1093 | Increases the verbosity of OpenFlow messages printed and logged by | |
1094 | \fBovs\-ofctl\fR commands. Specify this option more than once to | |
1095 | increase verbosity further. | |
1eb85ef5 EJ |
1096 | . |
1097 | .ds DD \ | |
1098 | \fBovs\-ofctl\fR detaches only when executing the \fBmonitor\fR or \ | |
1099 | \fBsnoop\fR commands. | |
1100 | .so lib/daemon.man | |
ac300505 | 1101 | .SS "Public Key Infrastructure Options" |
84ee7bcf | 1102 | .so lib/ssl.man |
064af421 BP |
1103 | .so lib/vlog.man |
1104 | .so lib/common.man | |
a9b4a41a | 1105 | . |
1eb85ef5 EJ |
1106 | .SH "RUNTIME MANAGEMENT COMMANDS" |
1107 | \fBovs\-appctl\fR(8) can send commands to a running \fBovs\-ofctl\fR process. | |
1108 | The currently supported commands only apply when executing the \fBmonitor\fR or | |
1109 | \fBsnoop\fR commands and are described below. | |
1110 | .IP "\fBexit\fR" | |
1111 | Causes \fBovs\-ofctl\fR to gracefully terminate. | |
064af421 | 1112 | .SH EXAMPLES |
a9b4a41a | 1113 | . |
045b2e5c BP |
1114 | The following examples assume that \fBovs\-vswitchd\fR has a bridge |
1115 | named \fBbr0\fR configured. | |
a9b4a41a | 1116 | . |
064af421 | 1117 | .TP |
045b2e5c | 1118 | \fBovs\-ofctl dump\-tables br0\fR |
064af421 BP |
1119 | Prints out the switch's table stats. (This is more interesting after |
1120 | some traffic has passed through.) | |
a9b4a41a | 1121 | . |
064af421 | 1122 | .TP |
045b2e5c | 1123 | \fBovs\-ofctl dump\-flows br0\fR |
064af421 | 1124 | Prints the flow entries in the switch. |
a9b4a41a | 1125 | . |
064af421 | 1126 | .SH "SEE ALSO" |
a9b4a41a | 1127 | . |
064af421 BP |
1128 | .BR ovs\-appctl (8), |
1129 | .BR ovs\-controller (8), | |
1130 | .BR ovs\-vswitchd (8) |