]>
Commit | Line | Data |
---|---|---|
a9b4a41a BP |
1 | .\" -*- nroff -*- |
2 | .de IQ | |
3 | . br | |
4 | . ns | |
5 | . IP "\\$1" | |
6 | .. | |
834377ea | 7 | .TH ovs\-ofctl 8 "January 2010" "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 BP |
56 | .TP |
57 | \fBstatus \fIswitch\fR [\fIkey\fR] | |
58 | Prints to the console a series of key-value pairs that report the | |
59 | status of \fIswitch\fR. If \fIkey\fR is specified, only the key-value | |
60 | pairs whose key names begin with \fIkey\fR are printed. If \fIkey\fR is | |
61 | omitted, all key-value pairs are printed. | |
a9b4a41a | 62 | . |
064af421 | 63 | .TP |
4e312e69 | 64 | \fBdump\-tables \fIswitch\fR |
064af421 BP |
65 | Prints to the console statistics for each of the flow tables used by |
66 | \fIswitch\fR. | |
a9b4a41a | 67 | . |
064af421 | 68 | .TP |
4e312e69 | 69 | \fBdump\-ports \fIswitch\fR [\fInetdev\fR] |
abaad8cf JP |
70 | Prints to the console statistics for network devices associated with |
71 | \fIswitch\fR. If \fInetdev\fR is specified, only the statistics | |
72 | associated with that device will be printed. \fInetdev\fR can be an | |
73 | OpenFlow assigned port number or device name, e.g. \fBeth0\fR. | |
a9b4a41a | 74 | . |
064af421 | 75 | .TP |
4e312e69 | 76 | \fBmod\-port \fIswitch\fR \fInetdev\fR \fIaction\fR |
064af421 BP |
77 | Modify characteristics of an interface monitored by \fIswitch\fR. |
78 | \fInetdev\fR can be referred to by its OpenFlow assigned port number or | |
79 | the device name, e.g. \fBeth0\fR. The \fIaction\fR may be any one of the | |
80 | following: | |
a9b4a41a | 81 | . |
064af421 BP |
82 | .RS |
83 | .IP \fBup\fR | |
84 | Enables the interface. This is equivalent to ``ifconfig up'' on a Unix | |
85 | system. | |
a9b4a41a | 86 | . |
064af421 BP |
87 | .IP \fBdown\fR |
88 | Disables the interface. This is equivalent to ``ifconfig down'' on a Unix | |
89 | system. | |
a9b4a41a | 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 | . |
064af421 | 102 | .TP |
4e312e69 | 103 | \fBdump\-flows \fIswitch \fR[\fIflows\fR] |
064af421 BP |
104 | Prints to the console all flow entries in \fIswitch\fR's |
105 | tables that match \fIflows\fR. If \fIflows\fR is omitted, all flows | |
106 | in the switch are retrieved. See \fBFlow Syntax\fR, below, for the | |
107 | syntax of \fIflows\fR. The output format is described in | |
108 | \fBTable Entry Output\fR. | |
a9b4a41a | 109 | . |
064af421 | 110 | .TP |
4e312e69 | 111 | \fBdump\-aggregate \fIswitch \fR[\fIflows\fR] |
064af421 BP |
112 | Prints to the console aggregate statistics for flows in |
113 | \fIswitch\fR's tables that match \fIflows\fR. If \fIflows\fR is omitted, | |
114 | the statistics are aggregated across all flows in the switch's flow | |
115 | tables. See \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR. | |
116 | The output format is descrbed in \fBTable Entry Output\fR. | |
a9b4a41a | 117 | . |
d2805da2 BP |
118 | .IP "\fBqueue\-stats \fIswitch \fR[\fIport \fR[\fIqueue\fR]]" |
119 | Prints to the console statistics for the specified \fIqueue\fR on | |
120 | \fIport\fR within \fIswitch\fR. Either of \fIport\fR or \fIqueue\fR | |
121 | or both may be omitted (or equivalently specified as \fBALL\fR). If | |
122 | both are omitted, statistics are printed for all queues on all ports. | |
123 | If only \fIqueue\fR is omitted, then statistics are printed for all | |
124 | queues on \fIport\fR; if only \fIport\fR is omitted, then statistics | |
125 | are printed for \fIqueue\fR on every port where it exists. | |
126 | . | |
064af421 | 127 | .TP |
4e312e69 | 128 | \fBadd\-flow \fIswitch flow\fR |
064af421 BP |
129 | Add the flow entry as described by \fIflow\fR to the \fIswitch\fR's |
130 | tables. The flow entry is in the format described in \fBFlow Syntax\fR, | |
131 | below. | |
a9b4a41a | 132 | . |
064af421 | 133 | .TP |
4e312e69 | 134 | \fBadd\-flows \fIswitch file\fR |
064af421 BP |
135 | Add flow entries as described in \fIfile\fR to \fIswitch\fR's |
136 | tables. Each line in \fIfile\fR is a flow entry in the format | |
137 | described in \fBFlow Syntax\fR, below. | |
a9b4a41a | 138 | . |
064af421 | 139 | .TP |
4e312e69 | 140 | \fBmod\-flows \fIswitch flow\fR |
064af421 | 141 | Modify the actions in entries from the \fIswitch\fR's tables |
4e312e69 | 142 | that match \fIflow\fR. When invoked with the \fB\-\-strict\fR option, |
064af421 BP |
143 | wildcards are not treated as active for matching purposes. See |
144 | \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR. | |
a9b4a41a | 145 | . |
064af421 | 146 | .TP |
4e312e69 | 147 | \fBdel\-flows \fIswitch \fR[\fIflow\fR] |
064af421 | 148 | Deletes entries from the \fIswitch\fR's tables that match |
4e312e69 | 149 | \fIflow\fR. When invoked with the \fB\-\-strict\fR option, wildcards are |
064af421 | 150 | not treated as active for matching purposes. If \fIflow\fR is |
4e312e69 | 151 | omitted and the \fB\-\-strict\fR option is not used, all flows in the |
064af421 BP |
152 | switch's tables are removed. See \fBFlow Syntax\fR, below, for the |
153 | syntax of \fIflows\fR. | |
a9b4a41a | 154 | . |
0caf6bde BP |
155 | .IP "\fBsnoop \fIswitch\fR" |
156 | Connects to \fIswitch\fR and prints to the console all OpenFlow | |
157 | messages received. Unlike other \fBovs\-ofctl\fR commands, if | |
158 | \fIswitch\fR is the name of a bridge, then the \fBsnoop\fR command | |
159 | connects to a Unix domain socket named | |
160 | \fB@RUNDIR@/\fIbridge\fB.snoop\fR. \fBovs\-vswitchd\fR listens on | |
161 | such a socket for each bridge and sends to it all of the OpenFlow | |
162 | messages sent to or received from its configured OpenFlow controller. | |
163 | Thus, this command can be used to view OpenFlow protocol activity | |
164 | between a switch and its controller. | |
165 | .IP | |
166 | When a switch has more than one controller configured, only the | |
e2bfacb6 BP |
167 | traffic to and from a single controller is output. If none of the |
168 | controllers is configured as a master or a slave (using a Nicira | |
169 | extension to OpenFlow), then a controller is chosen arbitrarily among | |
170 | them. If there is a master controller, it is chosen; otherwise, if | |
171 | there are any controllers that are not masters or slaves, one is | |
172 | chosen arbitrarily; otherwise, a slave controller is chosen | |
173 | arbitrarily. This choice is made once at connection time and does not | |
174 | change as controllers reconfigure their roles. | |
175 | .IP | |
176 | If a switch has no controller configured, or if | |
0caf6bde BP |
177 | the configured controller is disconnected, no traffic is sent, so |
178 | monitoring will not show any traffic. | |
179 | . | |
180 | .IQ "\fBmonitor \fIswitch\fR [\fImiss-len\fR]" | |
064af421 BP |
181 | Connects to \fIswitch\fR and prints to the console all OpenFlow |
182 | messages received. Usually, \fIswitch\fR should specify a connection | |
4e312e69 | 183 | named on \fBovs\-openflowd\fR(8)'s \fB\-l\fR or \fB\-\-listen\fR command line |
064af421 | 184 | option. |
a9b4a41a | 185 | .IP |
064af421 BP |
186 | If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set |
187 | configuration'' message at connection setup time that requests | |
0caf6bde BP |
188 | \fImiss-len\fR bytes of each packet that misses the flow table. Open vSwitch |
189 | does not send these and other asynchronous messages to an | |
064af421 | 190 | \fBovs\-ofctl monitor\fR client connection unless a nonzero value is |
0caf6bde BP |
191 | specified on this argument. (Thus, if \fImiss\-len\fR is not |
192 | specified, very little traffic will ordinarily be printed.) | |
a9b4a41a | 193 | .IP |
064af421 BP |
194 | This command may be useful for debugging switch or controller |
195 | implementations. | |
a9b4a41a | 196 | . |
064af421 | 197 | .SS "OpenFlow Switch and Controller Commands" |
a9b4a41a | 198 | . |
064af421 BP |
199 | The following commands, like those in the previous section, may be |
200 | applied to OpenFlow switches, using any of the connection methods | |
201 | described in that section. Unlike those commands, these may also be | |
202 | applied to OpenFlow controllers. | |
a9b4a41a | 203 | . |
064af421 BP |
204 | .TP |
205 | \fBprobe \fItarget\fR | |
206 | Sends a single OpenFlow echo-request message to \fItarget\fR and waits | |
4e312e69 | 207 | for the response. With the \fB\-t\fR or \fB\-\-timeout\fR option, this |
064af421 BP |
208 | command can test whether an OpenFlow switch or controller is up and |
209 | running. | |
a9b4a41a | 210 | . |
064af421 BP |
211 | .TP |
212 | \fBping \fItarget \fR[\fIn\fR] | |
213 | Sends a series of 10 echo request packets to \fItarget\fR and times | |
214 | each reply. The echo request packets consist of an OpenFlow header | |
215 | plus \fIn\fR bytes (default: 64) of randomly generated payload. This | |
216 | measures the latency of individual requests. | |
a9b4a41a | 217 | . |
064af421 BP |
218 | .TP |
219 | \fBbenchmark \fItarget n count\fR | |
220 | Sends \fIcount\fR echo request packets that each consist of an | |
221 | OpenFlow header plus \fIn\fR bytes of payload and waits for each | |
222 | response. Reports the total time required. This is a measure of the | |
223 | maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte | |
224 | messages. | |
a9b4a41a | 225 | . |
064af421 | 226 | .SS "Flow Syntax" |
a9b4a41a | 227 | .PP |
064af421 BP |
228 | Some \fBovs\-ofctl\fR commands accept an argument that describes a flow or |
229 | flows. Such flow descriptions comprise a series | |
230 | \fIfield\fB=\fIvalue\fR assignments, separated by commas or white | |
231 | space. (Embedding spaces into a flow description normally requires | |
232 | quoting to prevent the shell from breaking the description into | |
233 | multiple arguments.) | |
a9b4a41a | 234 | .PP |
0b3f2725 BP |
235 | Flow descriptions should be in \fBnormal form\fR. This means that a |
236 | flow may only specify a value for an L3 field if it also specifies a | |
237 | particular L2 protocol, and that a flow may only specify an L4 field | |
238 | if it also specifies particular L2 and L3 protocol types. For | |
239 | example, if the L2 protocol type \fBdl_type\fR is wildcarded, then L3 | |
240 | fields \fBnw_src\fR, \fBnw_dst\fR, and \fBnw_proto\fR must also be | |
241 | wildcarded. Similarly, if \fBdl_type\fR or \fBnw_proto\fR (the L3 | |
242 | protocol type) is wildcarded, so must be \fBtp_dst\fR and | |
243 | \fBtp_src\fR, which are L4 fields. \fBovs\-ofctl\fR will warn about | |
244 | flows not in normal form. | |
245 | .PP | |
064af421 BP |
246 | The following field assignments describe how a flow matches a packet. |
247 | If any of these assignments is omitted from the flow syntax, the field | |
248 | is treated as a wildcard; thus, if all of them are omitted, the | |
249 | resulting flow matches all packets. The string \fB*\fR or \fBANY\fR | |
250 | may be specified to explicitly mark any of these fields as a wildcard. | |
251 | (\fB*\fR should be quoted to protect it from shell expansion.) | |
a9b4a41a | 252 | . |
064af421 BP |
253 | .IP \fBin_port=\fIport_no\fR |
254 | Matches physical port \fIport_no\fR. Switch ports are numbered as | |
255 | displayed by \fBovs\-ofctl show\fR. | |
a9b4a41a | 256 | . |
064af421 | 257 | .IP \fBdl_vlan=\fIvlan\fR |
f30f26be JP |
258 | Matches IEEE 802.1q Virtual LAN tag \fIvlan\fR. Specify \fB0xffff\fR |
259 | as \fIvlan\fR to match packets that are not tagged with a Virtual LAN; | |
064af421 BP |
260 | otherwise, specify a number between 0 and 4095, inclusive, as the |
261 | 12-bit VLAN ID to match. | |
a9b4a41a | 262 | . |
959a2ecd JP |
263 | .IP \fBdl_vlan_pcp=\fIpriority\fR |
264 | Matches IEEE 802.1q Priority Code Point (PCP) \fIpriority\fR, which is | |
265 | specified as a value between 0 and 7, inclusive. A higher value | |
266 | indicates a higher frame priority level. | |
a9b4a41a | 267 | . |
ed951f15 BP |
268 | .IP \fBdl_src=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR |
269 | .IQ \fBdl_dst=\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fB:\fIxx\fR | |
270 | Matches an Ethernet source (or destination) address specified as 6 | |
271 | pairs of hexadecimal digits delimited by colons | |
272 | (e.g. \fB00:0A:E4:25:6B:B0\fR). | |
273 | . | |
064af421 BP |
274 | .IP \fBdl_type=\fIethertype\fR |
275 | Matches Ethernet protocol type \fIethertype\fR, which is specified as an | |
276 | integer between 0 and 65535, inclusive, either in decimal or as a | |
277 | hexadecimal number prefixed by \fB0x\fR (e.g. \fB0x0806\fR to match ARP | |
278 | packets). | |
a9b4a41a | 279 | . |
064af421 | 280 | .IP \fBnw_src=\fIip\fR[\fB/\fInetmask\fR] |
ed951f15 BP |
281 | .IQ \fBnw_dst=\fIip\fR[\fB/\fInetmask\fR] |
282 | When \fBdl_type\fR is 0x0800 (possibly via shorthand, e.g. \fBip\fR | |
283 | or \fBtcp\fR), matches IPv4 source (or destination) address \fIip\fR, | |
284 | which may be specified as an IP address or host name | |
285 | (e.g. \fB192.168.1.1\fR or \fBwww.example.com\fR). The optional | |
286 | \fInetmask\fR allows restricting a match to an IPv4 address prefix. | |
287 | The netmask may be specified as a dotted quad | |
288 | (e.g. \fB192.168.1.0/255.255.255.0\fR) or as a CIDR block | |
064af421 | 289 | (e.g. \fB192.168.1.0/24\fR). |
ed951f15 BP |
290 | .IP |
291 | When \fBdl_type=0x0806\fR or \fBarp\fR is specified, matches the | |
292 | \fBar_spa\fR or \fBar_tpa\fR field, respectively, in ARP packets for | |
293 | IPv4 and Ethernet. | |
294 | .IP | |
295 | When \fBdl_type\fR is wildcarded or set to a value other than 0x0800 | |
0b3f2725 BP |
296 | or 0x0806, the values of \fBnw_src\fR and \fBnw_dst\fR are ignored |
297 | (see \fBFlow Syntax\fR above). | |
a9b4a41a | 298 | . |
064af421 | 299 | .IP \fBnw_proto=\fIproto\fR |
ed951f15 BP |
300 | When \fBip\fR or \fBdl_type=0x0800\fR is specified, matches IP |
301 | protocol type \fIproto\fR, which is specified as a decimal number | |
302 | between 0 and 255, inclusive (e.g. 6 to match TCP packets). | |
303 | .IP | |
304 | When \fBarp\fR or \fBdl_type=0x0806\fR is specified, matches the lower | |
305 | 8 bits of the ARP opcode. ARP opcodes greater than 255 are treated as | |
306 | 0. | |
307 | .IP | |
308 | When \fBdl_type\fR is wildcarded or set to a value other than 0x0800 | |
0b3f2725 BP |
309 | or 0x0806, the value of \fBnw_proto\fR is ignored (see \fBFlow |
310 | Syntax\fR above). | |
a9b4a41a | 311 | . |
834377ea JP |
312 | .IP \fBnw_tos=\fItos\fR |
313 | Matches IP ToS/DSCP field \fItos\fR, which is specified as a decimal | |
314 | number between 0 and 255, inclusive. Note that the two lower reserved | |
315 | bits are ignored for matching purposes. | |
ed951f15 | 316 | .IP |
0b3f2725 BP |
317 | The value of \fBnw_proto\fR is ignored unless \fBdl_type=0x0800\fR, |
318 | \fBip\fR, \fBicmp\fR, \fBtcp\fR, or \fBudp\fR is also specified (see | |
319 | \fBFlow Syntax\fR above). | |
a9b4a41a | 320 | . |
064af421 | 321 | .IP \fBtp_src=\fIport\fR |
ed951f15 BP |
322 | .IQ \fBtp_dst=\fIport\fR |
323 | When \fBdl_type\fR and \fBnw_proto\fR specify TCP or UDP, \fBtp_src\fR | |
324 | and \fBtp_dst\fR match the UDP or TCP source or destination port | |
325 | \fIport\fR, respectively. which is specified as a decimal number | |
326 | between 0 and 65535, inclusive (e.g. 80 to match packets originating | |
064af421 | 327 | from a HTTP server). |
ed951f15 BP |
328 | .IP |
329 | When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of | |
0b3f2725 | 330 | these settings are ignored (see \fBFlow Syntax\fR above). |
a9b4a41a | 331 | . |
064af421 | 332 | .IP \fBicmp_type=\fItype\fR |
ed951f15 BP |
333 | .IQ \fBicmp_code=\fIcode\fR |
334 | When \fBdl_type\fR and \fBnw_proto\fR specify ICMP, \fItype\fR matches | |
335 | the ICMP type and \fIcode\fR matches the ICMP code. Each is specified | |
336 | as a decimal number between 0 and 255, inclusive. | |
337 | .IP | |
338 | When \fBdl_type\fR and \fBnw_proto\fR take other values, the values of | |
0b3f2725 | 339 | these settings are ignored (see \fBFlow Syntax\fR above). |
4c5df7f7 BP |
340 | .IP \fBtun_id=\fItunnel\-id\fR |
341 | Matches tunnel identifier \fItunnel\-id\fR. Only packets that arrive | |
342 | over a tunnel that carries a key (e.g. GRE with the RFC 2890 key | |
343 | extension) will have a nonzero tunnel ID. | |
344 | .IP | |
345 | \fBtun_id\fR requires use of one of two Nicira extensions to OpenFlow: | |
346 | .RS | |
347 | .IP "NXM (Nicira Extended Match)" | |
348 | This extension fully supports \fBtun_id\fR. | |
349 | .IP "Tunnel ID from Cookie" | |
350 | This extension supports \fBtun_id\fR with two caveats: the top 32 bits | |
351 | of the \fBcookie\fR (see below) are used for \fItunnel\-id\fR and thus | |
352 | unavailable for other use, and specifying \fBtun_id\fR on | |
353 | \fBdump\-flows\fR or \fBdump\-aggregate\fR has no effect. | |
354 | .RE | |
355 | .IP | |
356 | When \fBtun_id\fR is specified, \fBovs\-ofctl\fR will automatically | |
88ca35ee BP |
357 | attempt to negotiate use of one of these extensions. It will use the |
358 | ``tunnel ID from cookie'' extension if neither caveat applies and NXM | |
359 | otherwise. If the switch does not support the needed extension, then | |
360 | \fBovs\-ofctl\fR will report a fatal error. | |
00b1c62f BP |
361 | .IP "\fBreg\fIidx\fB=\fIvalue\fR[\fB/\fImask\fR]" |
362 | Matches \fIvalue\fR either exactly or with optional \fImask\fR in | |
363 | register number \fIidx\fR. The valid range of \fIidx\fR depends on | |
364 | the switch. \fIvalue\fR and \fImask\fR are 32-bit integers, by | |
365 | default in decimal (use a \fB0x\fR prefix to specify hexadecimal). | |
366 | Arbitrary \fImask\fR values are allowed: a 1-bit in \fImask\fR | |
367 | indicates that the corresponding bit in \fIvalue\fR must match | |
368 | exactly, and a 0-bit wildcards that bit. | |
369 | .IP | |
370 | When a packet enters an OpenFlow switch, all of the registers are set | |
371 | to 0. Only explicit Nicira extension actions change register values. | |
372 | .IP | |
373 | Register matches require support for the NXM (Nicira Extended Match) | |
374 | extension to OpenFlow. When a register match is specified, | |
375 | \fBovs\-ofctl\fR will automatically attempt to negotiate use of this | |
376 | extension. If the switch does not support NXM, then \fBovs\-ofctl\fR | |
377 | will report a fatal error. | |
a9b4a41a | 378 | . |
064af421 BP |
379 | .PP |
380 | The following shorthand notations are also available: | |
a9b4a41a | 381 | . |
064af421 BP |
382 | .IP \fBip\fR |
383 | Same as \fBdl_type=0x0800\fR. | |
a9b4a41a | 384 | . |
064af421 BP |
385 | .IP \fBicmp\fR |
386 | Same as \fBdl_type=0x0800,nw_proto=1\fR. | |
a9b4a41a | 387 | . |
064af421 BP |
388 | .IP \fBtcp\fR |
389 | Same as \fBdl_type=0x0800,nw_proto=6\fR. | |
a9b4a41a | 390 | . |
064af421 BP |
391 | .IP \fBudp\fR |
392 | Same as \fBdl_type=0x0800,nw_proto=17\fR. | |
a9b4a41a | 393 | . |
064af421 BP |
394 | .IP \fBarp\fR |
395 | Same as \fBdl_type=0x0806\fR. | |
a9b4a41a | 396 | . |
064af421 | 397 | .PP |
4e312e69 | 398 | The \fBadd\-flow\fR and \fBadd\-flows\fR commands require an additional |
537eeb9c | 399 | field, which must be the final field specified: |
a9b4a41a | 400 | . |
064af421 BP |
401 | .IP \fBactions=\fR[\fItarget\fR][\fB,\fItarget\fR...]\fR |
402 | Specifies a comma-separated list of actions to take on a packet when the | |
403 | flow entry matches. If no \fItarget\fR is specified, then packets | |
404 | matching the flow are dropped. The \fItarget\fR may be a decimal port | |
405 | number designating the physical port on which to output the packet, or one | |
406 | of the following keywords: | |
a9b4a41a | 407 | . |
064af421 BP |
408 | .RS |
409 | .IP \fBoutput\fR:\fIport\fR | |
410 | Outputs the packet on the port specified by \fIport\fR. | |
a9b4a41a | 411 | . |
5682f723 BP |
412 | .IP \fBenqueue\fR:\fIport\fB:\fIqueue\fR |
413 | Enqueues the packet on the specified \fIqueue\fR within port | |
414 | \fIport\fR. The number of supported queues depends on the switch; | |
415 | some OpenFlow implementations do not support queuing at all. | |
416 | . | |
064af421 BP |
417 | .IP \fBnormal\fR |
418 | Subjects the packet to the device's normal L2/L3 processing. (This | |
419 | action is not implemented by all OpenFlow switches.) | |
a9b4a41a | 420 | . |
064af421 BP |
421 | .IP \fBflood\fR |
422 | Outputs the packet on all switch physical ports other than the port on | |
423 | which it was received and any ports on which flooding is disabled | |
424 | (typically, these would be ports disabled by the IEEE 802.1D spanning | |
425 | tree protocol). | |
a9b4a41a | 426 | . |
064af421 BP |
427 | .IP \fBall\fR |
428 | Outputs the packet on all switch physical ports other than the port on | |
429 | which it was received. | |
a9b4a41a | 430 | . |
064af421 BP |
431 | .IP \fBcontroller\fR:\fImax_len\fR |
432 | Sends the packet to the OpenFlow controller as a ``packet in'' | |
433 | message. If \fImax_len\fR is a number, then it specifies the maximum | |
434 | number of bytes that should be sent. If \fImax_len\fR is \fBALL\fR or | |
435 | omitted, then the entire packet is sent. | |
a9b4a41a | 436 | . |
064af421 BP |
437 | .IP \fBlocal\fR |
438 | Outputs the packet on the ``local port,'' which corresponds to the | |
439 | \fBof\fIn\fR network device (see \fBCONTACTING THE CONTROLLER\fR in | |
8cd4882f | 440 | \fBovs\-openflowd\fR(8) for information on the \fBof\fIn\fR network device). |
a9b4a41a | 441 | . |
064af421 BP |
442 | .IP \fBdrop\fR |
443 | Discards the packet, so no further processing or forwarding takes place. | |
444 | If a drop action is used, no other actions may be specified. | |
a9b4a41a | 445 | . |
064af421 BP |
446 | .IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR |
447 | Modifies the VLAN id on a packet. The VLAN tag is added or modified | |
448 | as necessary to match the value specified. If the VLAN tag is added, | |
449 | a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set | |
450 | this). | |
a9b4a41a | 451 | . |
064af421 BP |
452 | .IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR |
453 | Modifies the VLAN priority on a packet. The VLAN tag is added or modified | |
454 | as necessary to match the value specified. Valid values are between 0 | |
455 | (lowest) and 7 (highest). If the VLAN tag is added, a vid of zero is used | |
456 | (see the \fBmod_vlan_vid\fR action to set this). | |
a9b4a41a | 457 | . |
064af421 BP |
458 | .IP \fBstrip_vlan\fR |
459 | Strips the VLAN tag from a packet if it is present. | |
a9b4a41a | 460 | . |
064af421 BP |
461 | .IP \fBmod_dl_src\fB:\fImac\fR |
462 | Sets the source Ethernet address to \fImac\fR. | |
a9b4a41a | 463 | . |
064af421 BP |
464 | .IP \fBmod_dl_dst\fB:\fImac\fR |
465 | Sets the destination Ethernet address to \fImac\fR. | |
a9b4a41a | 466 | . |
e423eca6 JP |
467 | .IP \fBmod_nw_src\fB:\fIip\fR |
468 | Sets the IPv4 source address to \fIip\fR. | |
a9b4a41a | 469 | . |
e423eca6 JP |
470 | .IP \fBmod_nw_dst\fB:\fIip\fR |
471 | Sets the IPv4 destination address to \fIip\fR. | |
a9b4a41a | 472 | . |
e423eca6 JP |
473 | .IP \fBmod_tp_src\fB:\fIport\fR |
474 | Sets the TCP or UDP source port to \fIport\fR. | |
a9b4a41a | 475 | . |
e423eca6 JP |
476 | .IP \fBmod_tp_dst\fB:\fIport\fR |
477 | Sets the TCP or UDP destination port to \fIport\fR. | |
a9b4a41a | 478 | . |
959a2ecd JP |
479 | .IP \fBmod_nw_tos\fB:\fItos\fR |
480 | Sets the IP ToS/DSCP field to \fItos\fR. Valid values are between 0 and | |
481 | 255, inclusive. Note that the two lower reserved bits are never | |
482 | modified. | |
a9b4a41a | 483 | . |
659586ef JG |
484 | .RE |
485 | .IP | |
486 | The following actions are Nicira vendor extensions that, as of this writing, are | |
487 | only known to be implemented by Open vSwitch: | |
488 | . | |
489 | .RS | |
490 | . | |
3a2fe1f3 BP |
491 | .IP \fBresubmit\fB:\fIport\fR |
492 | Re-searches the OpenFlow flow table with the \fBin_port\fR field | |
493 | replaced by \fIport\fR and executes the actions found, if any, in | |
494 | addition to any other actions in this flow entry. Recursive | |
495 | \fBresubmit\fR actions are ignored. | |
659586ef JG |
496 | . |
497 | .IP \fBset_tunnel\fB:\fIid\fR | |
498 | If outputting to a port that encapsulates the packet in a tunnel and supports | |
499 | an identifier (such as GRE), sets the identifier to \fBid\fR. | |
3a2fe1f3 | 500 | . |
933df876 BP |
501 | .IP \fBdrop_spoofed_arp\fR |
502 | Stops processing further actions, if the packet being processed is an | |
503 | Ethernet+IPv4 ARP packet for which the source Ethernet address inside | |
504 | the ARP packet differs from the source Ethernet address in the | |
505 | Ethernet header. | |
506 | . | |
507 | This is useful because OpenFlow does not provide a way to match on the | |
508 | Ethernet addresses inside ARP packets, so there is no other way to | |
509 | drop spoofed ARPs other than sending every ARP packet to a controller. | |
eedc0097 JP |
510 | . |
511 | .IP \fBset_queue\fB:\fIqueue\fR | |
512 | Sets the queue that should be used to \fIqueue\fR when packets are | |
513 | output. The number of supported queues depends on the switch; some | |
514 | OpenFlow implementations do not support queuing at all. | |
515 | . | |
516 | .IP \fBpop_queue\fR | |
517 | Restores the queue to the value it was before any \fBset_queue\fR | |
518 | actions were applied. | |
519 | . | |
96fc46e8 BP |
520 | .IP \fBnote:\fR[\fIhh\fR]... |
521 | Does nothing at all. Any number of bytes represented as hex digits | |
522 | \fIhh\fR may be included. Pairs of hex digits may be separated by | |
523 | periods for readability. | |
064af421 | 524 | .RE |
a9b4a41a | 525 | . |
064af421 BP |
526 | .IP |
527 | (The OpenFlow protocol supports other actions that \fBovs\-ofctl\fR does | |
528 | not yet expose to the user.) | |
a9b4a41a | 529 | . |
064af421 | 530 | .PP |
8cce2125 JP |
531 | The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands |
532 | support an additional optional field: | |
533 | . | |
534 | .IP \fBcookie=\fIvalue\fR | |
535 | . | |
536 | A cookie is an opaque identifier that can be associated with the flow. | |
537 | \fIvalue\fR can be any 64-bit number and need not be unique among | |
538 | flows. | |
539 | . | |
540 | .PP | |
4b6b46ce BP |
541 | The following additional field sets the priority for flows added by |
542 | the \fBadd\-flow\fR and \fBadd\-flows\fR commands. For | |
543 | \fBmod\-flows\fR and \fBdel\-flows\fR when \fB\-\-strict\fR is | |
544 | specified, priority must match along with the rest of the flow | |
545 | specification. Other commands ignore the priority value. | |
a9b4a41a | 546 | . |
064af421 BP |
547 | .IP \fBpriority=\fIvalue\fR |
548 | The priority at which a wildcarded entry will match in comparison to | |
549 | others. \fIvalue\fR is a number between 0 and 65535, inclusive. A higher | |
550 | \fIvalue\fR will match before a lower one. An exact-match entry will always | |
551 | have priority over an entry containing wildcards, so it has an implicit | |
552 | priority value of 65535. When adding a flow, if the field is not specified, | |
553 | the flow's priority will default to 32768. | |
a9b4a41a | 554 | . |
064af421 | 555 | .PP |
4e312e69 | 556 | The \fBadd\-flow\fR and \fBadd\-flows\fR commands support additional |
064af421 | 557 | optional fields: |
a9b4a41a | 558 | . |
064af421 BP |
559 | .TP |
560 | \fBidle_timeout=\fIseconds\fR | |
561 | Causes the flow to expire after the given number of seconds of | |
a1545337 BP |
562 | inactivity. A value of 0 (the default) prevents a flow from expiring due to |
563 | inactivity. | |
a9b4a41a | 564 | . |
064af421 BP |
565 | .IP \fBhard_timeout=\fIseconds\fR |
566 | Causes the flow to expire after the given number of seconds, | |
567 | regardless of activity. A value of 0 (the default) gives the flow no | |
568 | hard expiration deadline. | |
a9b4a41a | 569 | . |
064af421 | 570 | .PP |
4e312e69 BP |
571 | The \fBdump\-flows\fR, \fBdump\-aggregate\fR, \fBdel\-flow\fR |
572 | and \fBdel\-flows\fR commands support one additional optional field: | |
a9b4a41a | 573 | . |
064af421 BP |
574 | .TP |
575 | \fBout_port=\fIport\fR | |
576 | If set, a matching flow must include an output action to \fIport\fR. | |
a9b4a41a | 577 | . |
064af421 | 578 | .PP |
4e312e69 | 579 | The \fBdump\-flows\fR and \fBdump\-aggregate\fR commands support an |
064af421 | 580 | additional optional field: |
a9b4a41a | 581 | . |
064af421 BP |
582 | .IP \fBtable=\fInumber\fR |
583 | If specified, limits the flows about which statistics are gathered to | |
584 | those in the table with the given \fInumber\fR. Tables are numbered | |
4e312e69 | 585 | as shown by the \fBdump\-tables\fR command. |
a9b4a41a | 586 | . |
064af421 BP |
587 | If this field is not specified, or if \fInumber\fR is given as |
588 | \fB255\fR, statistics are gathered about flows from all tables. | |
a9b4a41a | 589 | . |
064af421 | 590 | .SS "Table Entry Output" |
a9b4a41a | 591 | . |
4e312e69 | 592 | The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information |
064af421 BP |
593 | about the entries in a datapath's tables. Each line of output is a |
594 | unique flow entry, which begins with some common information: | |
a9b4a41a | 595 | . |
064af421 BP |
596 | .IP \fBduration\fR |
597 | The number of seconds the entry has been in the table. | |
a9b4a41a | 598 | . |
064af421 BP |
599 | .IP \fBtable_id\fR |
600 | The table that contains the flow. When a packet arrives, the switch | |
601 | begins searching for an entry at the lowest numbered table. Tables are | |
4e312e69 | 602 | numbered as shown by the \fBdump\-tables\fR command. |
a9b4a41a | 603 | . |
064af421 BP |
604 | .IP \fBpriority\fR |
605 | The priority of the entry in relation to other entries within the same | |
606 | table. A higher value will match before a lower one. | |
a9b4a41a | 607 | . |
064af421 BP |
608 | .IP \fBn_packets\fR |
609 | The number of packets that have matched the entry. | |
a9b4a41a | 610 | . |
064af421 BP |
611 | .IP \fBn_bytes\fR |
612 | The total number of bytes from packets that have matched the entry. | |
a9b4a41a | 613 | . |
064af421 BP |
614 | .PP |
615 | The rest of the line consists of a description of the flow entry as | |
616 | described in \fBFlow Syntax\fR, above. | |
a9b4a41a BP |
617 | . |
618 | . | |
064af421 BP |
619 | .SH OPTIONS |
620 | .TP | |
4e312e69 | 621 | \fB\-\-strict\fR |
064af421 | 622 | Uses strict matching when running flow modification commands. |
a9b4a41a | 623 | . |
88ca35ee BP |
624 | .IP "\fB\-F \fIformat\fR" |
625 | .IQ "\fB\-\-flow\-format=\fIformat\fR" | |
626 | \fBovs\-ofctl\fR supports the following flow formats, in order of | |
627 | increasing capability: | |
628 | .RS | |
629 | .IP "\fBopenflow10\fR" | |
630 | This is the standard OpenFlow 1.0 flow format. It should be supported | |
631 | by all OpenFlow switches. | |
632 | . | |
633 | .IP "\fBtun_id_from_cookie\fR" | |
634 | This Nicira extension to OpenFlow adds minimal and limited support for | |
635 | \fBtun_id\fR, but it does not support any other Nicira flow | |
636 | extensions. (This flow format is deprecated.) | |
637 | . | |
638 | .IP "\fBnxm\fR (Nicira Extended Match)" | |
639 | This Nicira extension to OpenFlow is flexible and extensible. It | |
640 | supports all of the Nicira flow extensions, such as \fBtun_id\fR and | |
641 | registers. | |
642 | .RE | |
643 | .IP | |
644 | Usually, \fBovs\-ofctl\fR picks the correct format automatically. For | |
645 | commands that modify the flow table, \fBovs\-ofctl\fR by default uses | |
646 | the most widely supported flow format that supports the flows being | |
647 | added. For commands that query the flow table, \fBovs\-ofctl\fR by | |
648 | default queries and uses the most advanced format supported by the | |
649 | switch. | |
650 | .IP | |
651 | This option, where \fIformat\fR is one of the formats listed in the | |
652 | above table, overrides \fBovs\-ofctl\fR's default choice of flow | |
653 | format. If a command cannot work as requested using the requested | |
654 | flow format, \fBovs\-ofctl\fR will report a fatal error. | |
4f564f8d BP |
655 | . |
656 | .IP "\fB\-m\fR" | |
657 | .IQ "\fB\-\-more\fR" | |
658 | Increases the verbosity of OpenFlow messages printed and logged by | |
659 | \fBovs\-ofctl\fR commands. Specify this option more than once to | |
660 | increase verbosity further. | |
ac300505 | 661 | .SS "Public Key Infrastructure Options" |
84ee7bcf | 662 | .so lib/ssl.man |
064af421 BP |
663 | .so lib/vlog.man |
664 | .so lib/common.man | |
a9b4a41a | 665 | . |
064af421 | 666 | .SH EXAMPLES |
a9b4a41a | 667 | . |
064af421 BP |
668 | The following examples assume that an OpenFlow switch on the local |
669 | host has been configured to listen for management connections on a | |
670 | Unix domain socket named \fB@RUNDIR@/openflow.sock\fR, e.g. by | |
4e312e69 | 671 | specifying \fB\-\-listen=punix:@RUNDIR@/openflow.sock\fR on the |
8cd4882f | 672 | \fBovs\-openflowd\fR(8) command line. |
a9b4a41a | 673 | . |
064af421 | 674 | .TP |
4e312e69 | 675 | \fBovs\-ofctl dump\-tables unix:@RUNDIR@/openflow.sock\fR |
064af421 BP |
676 | Prints out the switch's table stats. (This is more interesting after |
677 | some traffic has passed through.) | |
a9b4a41a | 678 | . |
064af421 | 679 | .TP |
4e312e69 | 680 | \fBovs\-ofctl dump\-flows unix:@RUNDIR@/openflow.sock\fR |
064af421 | 681 | Prints the flow entries in the switch. |
a9b4a41a | 682 | . |
064af421 | 683 | .SH "SEE ALSO" |
a9b4a41a | 684 | . |
064af421 BP |
685 | .BR ovs\-appctl (8), |
686 | .BR ovs\-controller (8), | |
687 | .BR ovs\-vswitchd (8) |