]>
Commit | Line | Data |
---|---|---|
1 | .\" -*- nroff -*- | |
2 | .so lib/ovs.tmac | |
3 | .TH ovs\-ofctl 8 "@VERSION@" "Open vSwitch" "Open vSwitch Manual" | |
4 | .ds PN ovs\-ofctl | |
5 | . | |
6 | .SH NAME | |
7 | ovs\-ofctl \- administer OpenFlow switches | |
8 | . | |
9 | .SH SYNOPSIS | |
10 | .B ovs\-ofctl | |
11 | [\fIoptions\fR] \fIcommand \fR[\fIswitch\fR] [\fIargs\fR\&...] | |
12 | . | |
13 | .SH DESCRIPTION | |
14 | The | |
15 | .B ovs\-ofctl | |
16 | program is a command line tool for monitoring and administering | |
17 | OpenFlow switches. It can also show the current state of an OpenFlow | |
18 | switch, including features, configuration, and table entries. | |
19 | It should work with any OpenFlow switch, not just Open vSwitch. | |
20 | . | |
21 | .SS "OpenFlow Switch Management Commands" | |
22 | .PP | |
23 | These commands allow \fBovs\-ofctl\fR to monitor and administer an OpenFlow | |
24 | switch. It is able to show the current state of a switch, including | |
25 | features, configuration, and table entries. | |
26 | .PP | |
27 | Most of these commands take an argument that specifies the method for | |
28 | connecting to an OpenFlow switch. The following connection methods | |
29 | are supported: | |
30 | . | |
31 | .RS | |
32 | .so lib/vconn-active.man | |
33 | . | |
34 | .IP "\fIfile\fR" | |
35 | This is short for \fBunix:\fIfile\fR, as long as \fIfile\fR does not | |
36 | contain a colon. | |
37 | . | |
38 | .IP \fIbridge\fR | |
39 | This is short for \fBunix:@RUNDIR@/\fIbridge\fB.mgmt\fR, as long as | |
40 | \fIbridge\fR does not contain a colon. | |
41 | . | |
42 | .IP [\fItype\fB@\fR]\fIdp\fR | |
43 | Attempts to look up the bridge associated with \fIdp\fR and open as | |
44 | above. If \fItype\fR is given, it specifies the datapath provider of | |
45 | \fIdp\fR, otherwise the default provider \fBsystem\fR is assumed. | |
46 | .RE | |
47 | . | |
48 | .TP | |
49 | \fBshow \fIswitch\fR | |
50 | Prints to the console information on \fIswitch\fR, including | |
51 | information on its flow tables and ports. | |
52 | . | |
53 | .TP | |
54 | \fBdump\-tables \fIswitch\fR | |
55 | Prints to the console statistics for each of the flow tables used by | |
56 | \fIswitch\fR. | |
57 | .TP | |
58 | \fBdump\-table\-features \fIswitch\fR | |
59 | Prints to the console features for each of the flow tables used by | |
60 | \fIswitch\fR. | |
61 | .TP | |
62 | \fBdump\-table\-desc \fIswitch\fR | |
63 | Prints to the console configuration for each of the flow tables used | |
64 | by \fIswitch\fR for OpenFlow 1.4+. | |
65 | .IP "\fBmod\-table \fIswitch\fR \fItable\fR \fIsetting\fR" | |
66 | This command configures flow table settings in \fIswitch\fR for | |
67 | OpenFlow table \fItable\fR, which may be expressed as a number or | |
68 | (unless \fB\-\-no\-names\fR is specified) a name. | |
69 | .IP | |
70 | The available settings depend on | |
71 | the OpenFlow version in use. In OpenFlow 1.1 and 1.2 (which must be | |
72 | enabled with the \fB\-O\fR option) only, \fBmod\-table\fR configures | |
73 | behavior when no flow is found when a packet is looked up in a flow | |
74 | table. The following \fIsetting\fR values are available: | |
75 | .RS | |
76 | .IP \fBdrop\fR | |
77 | Drop the packet. | |
78 | .IP \fBcontinue\fR | |
79 | Continue to the next table in the pipeline. (This is how an OpenFlow | |
80 | 1.0 switch always handles packets that do not match any flow, in | |
81 | tables other than the last one.) | |
82 | .IP \fBcontroller\fR | |
83 | Send to controller. (This is how an OpenFlow 1.0 switch always | |
84 | handles packets that do not match any flow in the last table.) | |
85 | .RE | |
86 | .IP | |
87 | In OpenFlow 1.3 and later (which must be enabled with the \fB\-O\fR | |
88 | option) and Open vSwitch 2.11 and later only, \fBmod\-table\fR can | |
89 | change the name of a table: | |
90 | .RS | |
91 | .IP \fBname:\fInew-name\fR | |
92 | Changes the name of the table to \fInew-name\fR. Use an empty | |
93 | \fInew-name\fR to clear the name. (This will be ineffective if the | |
94 | name is set via the \fBname\fR column in the \fBFlow_Table\fR table in | |
95 | the \fBOpen_vSwitch\fR database as described in | |
96 | \fBovs\-vswitchd.conf.db\fR(5).) | |
97 | .RE | |
98 | .IP | |
99 | In OpenFlow 1.4 and later (which must be enabled with the \fB\-O\fR | |
100 | option) only, \fBmod\-table\fR configures the behavior when a | |
101 | controller attempts to add a flow to a flow table that is full. The | |
102 | following \fIsetting\fR values are available: | |
103 | .RS | |
104 | .IP \fBevict\fR | |
105 | Delete some existing flow from the flow table, according to the | |
106 | algorithm described for the \fBFlow_Table\fR table in | |
107 | \fBovs-vswitchd.conf.db\fR(5). | |
108 | .IP \fBnoevict\fR | |
109 | Refuse to add the new flow. (Eviction might still be enabled through | |
110 | the \fBoverflow_policy\fR column in the \fBFlow_Table\fR table | |
111 | documented in \fBovs-vswitchd.conf.db\fR(5).) | |
112 | .IP \fBvacancy:\fIlow\fB,\fIhigh\fR | |
113 | Enables sending vacancy events to controllers using \fBTABLE_STATUS\fR | |
114 | messages, based on percentage thresholds \fIlow\fR and \fIhigh\fR. | |
115 | .IP \fBnovacancy\fR | |
116 | Disables vacancy events. | |
117 | .RE | |
118 | . | |
119 | .TP | |
120 | \fBdump\-ports \fIswitch\fR [\fInetdev\fR] | |
121 | Prints to the console statistics for network devices associated with | |
122 | \fIswitch\fR. If \fInetdev\fR is specified, only the statistics | |
123 | associated with that device will be printed. \fInetdev\fR can be an | |
124 | OpenFlow assigned port number or device name, e.g. \fBeth0\fR. | |
125 | . | |
126 | .IP "\fBdump\-ports\-desc \fIswitch\fR [\fIport\fR]" | |
127 | Prints to the console detailed information about network devices | |
128 | associated with \fIswitch\fR. To dump only a specific port, specify | |
129 | its number as \fIport\fR. Otherwise, if \fIport\fR is omitted, or if | |
130 | it is specified as \fBANY\fR, then all ports are printed. This is a | |
131 | subset of the information provided by the \fBshow\fR command. | |
132 | .IP | |
133 | If the connection to \fIswitch\fR negotiates OpenFlow 1.0, 1.2, or | |
134 | 1.2, this command uses an OpenFlow extension only implemented in Open | |
135 | vSwitch (version 1.7 and later). | |
136 | .IP | |
137 | Only OpenFlow 1.5 and later support dumping a specific port. Earlier | |
138 | versions of OpenFlow always dump all ports. | |
139 | . | |
140 | .IP "\fBmod\-port \fIswitch\fR \fIport\fR \fIaction\fR" | |
141 | Modify characteristics of port \fBport\fR in \fIswitch\fR. \fIport\fR | |
142 | may be an OpenFlow port number or name (unless \fB\-\-no\-names\fR is | |
143 | specified) or the keyword \fBLOCAL\fR (the | |
144 | preferred way to refer to the OpenFlow local port). The \fIaction\fR | |
145 | may be any one of the following: | |
146 | . | |
147 | .RS | |
148 | .IQ \fBup\fR | |
149 | .IQ \fBdown\fR | |
150 | Enable or disable the interface. This is equivalent to \fBip | |
151 | link set up\fR or \fBip link set down\fR on a Unix system. | |
152 | . | |
153 | .IP \fBstp\fR | |
154 | .IQ \fBno\-stp\fR | |
155 | Enable or disable 802.1D spanning tree protocol (STP) on the | |
156 | interface. OpenFlow implementations that don't support STP will | |
157 | refuse to enable it. | |
158 | . | |
159 | .IP \fBreceive\fR | |
160 | .IQ \fBno\-receive\fR | |
161 | .IQ \fBreceive\-stp\fR | |
162 | .IQ \fBno\-receive\-stp\fR | |
163 | Enable or disable OpenFlow processing of packets received on this | |
164 | interface. When packet processing is disabled, packets will be | |
165 | dropped instead of being processed through the OpenFlow table. The | |
166 | \fBreceive\fR or \fBno\-receive\fR setting applies to all packets | |
167 | except 802.1D spanning tree packets, which are separately controlled | |
168 | by \fBreceive\-stp\fR or \fBno\-receive\-stp\fR. | |
169 | . | |
170 | .IP \fBforward\fR | |
171 | .IQ \fBno\-forward\fR | |
172 | Allow or disallow forwarding of traffic to this interface. By | |
173 | default, forwarding is enabled. | |
174 | . | |
175 | .IP \fBflood\fR | |
176 | .IQ \fBno\-flood\fR | |
177 | Controls whether an OpenFlow \fBflood\fR action will send traffic out | |
178 | this interface. By default, flooding is enabled. Disabling flooding | |
179 | is primarily useful to prevent loops when a spanning tree protocol is | |
180 | not in use. | |
181 | . | |
182 | .IP \fBpacket\-in\fR | |
183 | .IQ \fBno\-packet\-in\fR | |
184 | Controls whether packets received on this interface that do not match | |
185 | a flow table entry generate a ``packet in'' message to the OpenFlow | |
186 | controller. By default, ``packet in'' messages are enabled. | |
187 | .RE | |
188 | .IP | |
189 | The \fBshow\fR command displays (among other information) the | |
190 | configuration that \fBmod\-port\fR changes. | |
191 | . | |
192 | .IP "\fBget\-frags \fIswitch\fR" | |
193 | Prints \fIswitch\fR's fragment handling mode. See \fBset\-frags\fR, | |
194 | below, for a description of each fragment handling mode. | |
195 | .IP | |
196 | The \fBshow\fR command also prints the fragment handling mode among | |
197 | its other output. | |
198 | . | |
199 | .IP "\fBset\-frags \fIswitch frag_mode\fR" | |
200 | Configures \fIswitch\fR's treatment of IPv4 and IPv6 fragments. The | |
201 | choices for \fIfrag_mode\fR are: | |
202 | .RS | |
203 | .IP "\fBnormal\fR" | |
204 | Fragments pass through the flow table like non-fragmented packets. | |
205 | The TCP ports, UDP ports, and ICMP type and code fields are always set | |
206 | to 0, even for fragments where that information would otherwise be | |
207 | available (fragments with offset 0). This is the default fragment | |
208 | handling mode for an OpenFlow switch. | |
209 | .IP "\fBdrop\fR" | |
210 | Fragments are dropped without passing through the flow table. | |
211 | .IP "\fBreassemble\fR" | |
212 | The switch reassembles fragments into full IP packets before passing | |
213 | them through the flow table. Open vSwitch does not implement this | |
214 | fragment handling mode. | |
215 | .IP "\fBnx\-match\fR" | |
216 | Fragments pass through the flow table like non-fragmented packets. | |
217 | The TCP ports, UDP ports, and ICMP type and code fields are available | |
218 | for matching for fragments with offset 0, and set to 0 in fragments | |
219 | with nonzero offset. This mode is a Nicira extension. | |
220 | .RE | |
221 | .IP | |
222 | See the description of \fBip_frag\fR, in \fBovs\-fields\fR(7), for a way to | |
223 | match on whether a packet is a fragment and on its fragment offset. | |
224 | . | |
225 | .TP | |
226 | \fBdump\-flows \fIswitch \fR[\fIflows\fR] | |
227 | Prints to the console all flow entries in \fIswitch\fR's | |
228 | tables that match \fIflows\fR. If \fIflows\fR is omitted, all flows | |
229 | in the switch are retrieved. See \fBFlow Syntax\fR, below, for the | |
230 | syntax of \fIflows\fR. The output format is described in | |
231 | \fBTable Entry Output\fR. | |
232 | . | |
233 | .IP | |
234 | By default, \fBovs\-ofctl\fR prints flow entries in the same order | |
235 | that the switch sends them, which is unlikely to be intuitive or | |
236 | consistent. Use \fB\-\-sort\fR and \fB\-\-rsort\fR to control display | |
237 | order. The \fB\-\-names\fR/\fB\-\-no\-names\fR and | |
238 | \fB\-\-stats\fR/\fB\-\-no\-stats\fR options also affect output | |
239 | formatting. See the descriptions of these options, under | |
240 | \fBOPTIONS\fR below, for more information | |
241 | . | |
242 | .TP | |
243 | \fBdump\-aggregate \fIswitch \fR[\fIflows\fR] | |
244 | Prints to the console aggregate statistics for flows in | |
245 | \fIswitch\fR's tables that match \fIflows\fR. If \fIflows\fR is omitted, | |
246 | the statistics are aggregated across all flows in the switch's flow | |
247 | tables. See \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR. | |
248 | The output format is described in \fBTable Entry Output\fR. | |
249 | . | |
250 | .IP "\fBqueue\-stats \fIswitch \fR[\fIport \fR[\fIqueue\fR]]" | |
251 | Prints to the console statistics for the specified \fIqueue\fR on | |
252 | \fIport\fR within \fIswitch\fR. \fIport\fR can be an OpenFlow port | |
253 | number or name, the keyword \fBLOCAL\fR (the preferred way to refer to | |
254 | the OpenFlow local port), or the keyword \fBALL\fR. Either of | |
255 | \fIport\fR or \fIqueue\fR or both may be omitted (or equivalently the | |
256 | keyword \fBALL\fR). If both are omitted, statistics are printed for | |
257 | all queues on all ports. If only \fIqueue\fR is omitted, then | |
258 | statistics are printed for all queues on \fIport\fR; if only | |
259 | \fIport\fR is omitted, then statistics are printed for \fIqueue\fR on | |
260 | every port where it exists. | |
261 | . | |
262 | .IP "\fBqueue\-get\-config \fIswitch [\fIport \fR[\fIqueue\fR]]" | |
263 | Prints to the console the configuration of \fIqueue\fR on \fIport\fR | |
264 | in \fIswitch\fR. If \fIport\fR is omitted or \fBANY\fR, reports | |
265 | queues for all port. If \fIqueue\fR is omitted or \fBANY\fR, reports | |
266 | all queues. For OpenFlow 1.3 and earlier, the output always includes | |
267 | all queues, ignoring \fIqueue\fR if specified. | |
268 | .IP | |
269 | This command has limited usefulness, because ports often have no | |
270 | configured queues and because the OpenFlow protocol provides only very | |
271 | limited information about the configuration of a queue. | |
272 | . | |
273 | .IP "\fBdump\-ipfix\-bridge \fIswitch\fR" | |
274 | Prints to the console the statistics of bridge IPFIX for \fIswitch\fR. | |
275 | If bridge IPFIX is configured on the \fIswitch\fR, IPFIX statistics | |
276 | can be retrieved. Otherwise, error message will be printed. | |
277 | .IP | |
278 | This command uses an Open vSwitch extension that is only in Open | |
279 | vSwitch 2.6 and later. | |
280 | . | |
281 | .IP "\fBdump\-ipfix\-flow \fIswitch\fR" | |
282 | Prints to the console the statistics of flow-based IPFIX for | |
283 | \fIswitch\fR. If flow-based IPFIX is configured on the \fIswitch\fR, | |
284 | statistics of all the collector set ids on the \fIswitch\fR will be | |
285 | printed. Otherwise, print error message. | |
286 | .IP | |
287 | Refer to \fBovs\-vswitchd.conf.db\fR(5) for more details on configuring | |
288 | flow based IPFIX and collector set ids. | |
289 | .IP | |
290 | This command uses an Open vSwitch extension that is only in Open | |
291 | vSwitch 2.6 and later. | |
292 | . | |
293 | .IP "\fBct\-flush\-zone \fIswitch zone\fR | |
294 | Flushes the connection tracking entries in \fIzone\fR on \fIswitch\fR. | |
295 | .IP | |
296 | This command uses an Open vSwitch extension that is only in Open | |
297 | vSwitch 2.6 and later. | |
298 | . | |
299 | .SS "OpenFlow Switch Flow Table Commands" | |
300 | . | |
301 | These commands manage the flow table in an OpenFlow switch. In each | |
302 | case, \fIflow\fR specifies a flow entry in the format described in | |
303 | \fBFlow Syntax\fR, below, \fIfile\fR is a text file that contains zero | |
304 | or more flows in the same syntax, one per line, and the optional | |
305 | \fB\-\-bundle\fR option operates the command as a single atomic | |
306 | transation, see option \fB\-\-bundle\fR, below. | |
307 | . | |
308 | .IP "[\fB\-\-bundle\fR] \fBadd\-flow \fIswitch flow\fR" | |
309 | .IQ "[\fB\-\-bundle\fR] \fBadd\-flow \fIswitch \fB\- < \fIfile\fR" | |
310 | .IQ "[\fB\-\-bundle\fR] \fBadd\-flows \fIswitch file\fR" | |
311 | Add each flow entry to \fIswitch\fR's tables. | |
312 | . | |
313 | Each flow specification (e.g., each line in \fIfile\fR) may start with | |
314 | \fBadd\fR, \fBmodify\fR, \fBdelete\fR, \fBmodify_strict\fR, or | |
315 | \fBdelete_strict\fR keyword to specify whether a flow is to be added, | |
316 | modified, or deleted, and whether the modify or delete is strict or | |
317 | not. For backwards compatibility a flow specification without one of | |
318 | these keywords is treated as a flow add. All flow mods are executed | |
319 | in the order specified. | |
320 | . | |
321 | .IP "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBmod\-flows \fIswitch flow\fR" | |
322 | .IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBmod\-flows \fIswitch \fB\- < \fIfile\fR" | |
323 | Modify the actions in entries from \fIswitch\fR's tables that match | |
324 | the specified flows. With \fB\-\-strict\fR, wildcards are not treated | |
325 | as active for matching purposes. | |
326 | . | |
327 | .IP "[\fB\-\-bundle\fR] \fBdel\-flows \fIswitch\fR" | |
328 | .IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fR[\fIflow\fR]" | |
329 | .IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fB\- < \fIfile\fR" | |
330 | Deletes entries from \fIswitch\fR's flow table. With only a | |
331 | \fIswitch\fR argument, deletes all flows. Otherwise, deletes flow | |
332 | entries that match the specified flows. With \fB\-\-strict\fR, | |
333 | wildcards are not treated as active for matching purposes. | |
334 | . | |
335 | .IP "[\fB\-\-bundle\fR] [\fB\-\-readd\fR] \fBreplace\-flows \fIswitch file\fR" | |
336 | Reads flow entries from \fIfile\fR (or \fBstdin\fR if \fIfile\fR is | |
337 | \fB\-\fR) and queries the flow table from \fIswitch\fR. Then it fixes | |
338 | up any differences, adding flows from \fIflow\fR that are missing on | |
339 | \fIswitch\fR, deleting flows from \fIswitch\fR that are not in | |
340 | \fIfile\fR, and updating flows in \fIswitch\fR whose actions, cookie, | |
341 | or timeouts differ in \fIfile\fR. | |
342 | . | |
343 | .IP | |
344 | With \fB\-\-readd\fR, \fBovs\-ofctl\fR adds all the flows from | |
345 | \fIfile\fR, even those that exist with the same actions, cookie, and | |
346 | timeout in \fIswitch\fR. In OpenFlow 1.0 and 1.1, re-adding a flow | |
347 | always resets the flow's packet and byte counters to 0, and in | |
348 | OpenFlow 1.2 and later, it does so only if the \fBreset_counts\fR flag | |
349 | is set. | |
350 | . | |
351 | .IP "\fBdiff\-flows \fIsource1 source2\fR" | |
352 | Reads flow entries from \fIsource1\fR and \fIsource2\fR and prints the | |
353 | differences. A flow that is in \fIsource1\fR but not in \fIsource2\fR | |
354 | is printed preceded by a \fB\-\fR, and a flow that is in \fIsource2\fR | |
355 | but not in \fIsource1\fR is printed preceded by a \fB+\fR. If a flow | |
356 | exists in both \fIsource1\fR and \fIsource2\fR with different actions, | |
357 | cookie, or timeouts, then both versions are printed preceded by | |
358 | \fB\-\fR and \fB+\fR, respectively. | |
359 | .IP | |
360 | \fIsource1\fR and \fIsource2\fR may each name a file or a switch. If | |
361 | a name begins with \fB/\fR or \fB.\fR, then it is considered to be a | |
362 | file name. A name that contains \fB:\fR is considered to be a switch. | |
363 | Otherwise, it is a file if a file by that name exists, a switch if | |
364 | not. | |
365 | .IP | |
366 | For this command, an exit status of 0 means that no differences were | |
367 | found, 1 means that an error occurred, and 2 means that some | |
368 | differences were found. | |
369 | . | |
370 | .IP "\fBpacket\-out \fIswitch\fR \fIpacket-out\fR" | |
371 | Connects to \fIswitch\fR and instructs it to execute the | |
372 | \fIpacket-out\fR OpenFlow message, specified as defined in | |
373 | \fBPacket\-Out Syntax\fR section. | |
374 | . | |
375 | .SS "Group Table Commands" | |
376 | . | |
377 | These commands manage the group table in an OpenFlow switch. In each | |
378 | case, \fIgroup\fR specifies a group entry in the format described in | |
379 | \fBGroup Syntax\fR, below, and \fIfile\fR is a text file that contains | |
380 | zero or more groups in the same syntax, one per line, and the optional | |
381 | \fB\-\-bundle\fR option operates the command as a single atomic | |
382 | transation, see option \fB\-\-bundle\fR, below. | |
383 | .PP | |
384 | The group commands work only with switches that support OpenFlow 1.1 | |
385 | or later or the Open vSwitch group extensions to OpenFlow 1.0 (added | |
386 | in Open vSwitch 2.9.90). For OpenFlow 1.1 or later, it is necessary | |
387 | to explicitly enable these protocol versions in \fBovs\-ofctl\fR | |
388 | (using \fB\-O\fR). For more information, see ``Q: What versions of | |
389 | OpenFlow does Open vSwitch support?'' in the Open vSwitch FAQ. | |
390 | . | |
391 | .IP "[\fB\-\-bundle\fR] \fBadd\-group \fIswitch group\fR" | |
392 | .IQ "[\fB\-\-bundle\fR] \fBadd\-group \fIswitch \fB\- < \fIfile\fR" | |
393 | .IQ "[\fB\-\-bundle\fR] \fBadd\-groups \fIswitch file\fR" | |
394 | Add each group entry to \fIswitch\fR's tables. | |
395 | . | |
396 | Each group specification (e.g., each line in \fIfile\fR) may start | |
397 | with \fBadd\fR, \fBmodify\fR, \fBadd_or_mod\fR, \fBdelete\fR, | |
398 | \fBinsert_bucket\fR, or \fBremove_bucket\fR keyword to specify whether | |
399 | a flow is to be added, modified, or deleted, or whether a group bucket | |
400 | is to be added or removed. For backwards compatibility a group | |
401 | specification without one of these keywords is treated as a group add. | |
402 | All group mods are executed in the order specified. | |
403 | . | |
404 | .IP "[\fB\-\-bundle\fR] [\fB\-\-may\-create\fR] \fBmod\-group \fIswitch group\fR" | |
405 | .IQ "[\fB\-\-bundle\fR] [\fB\-\-may\-create\fR] \fBmod\-group \fIswitch \fB\- < \fIfile\fR" | |
406 | Modify the action buckets in entries from \fIswitch\fR's tables for | |
407 | each group entry. If a specified group does not already exist, then | |
408 | without \fB\-\-may\-create\fR, this command has no effect; with | |
409 | \fB\-\-may\-create\fR, it creates a new group. The | |
410 | \fB\-\-may\-create\fR option uses an Open vSwitch extension to | |
411 | OpenFlow only implemented in Open vSwitch 2.6 and later. | |
412 | . | |
413 | .IP "[\fB\-\-bundle\fR] \fBdel\-groups \fIswitch\fR" | |
414 | .IQ "[\fB\-\-bundle\fR] \fBdel\-groups \fIswitch \fR[\fIgroup\fR]" | |
415 | .IQ "[\fB\-\-bundle\fR] \fBdel\-groups \fIswitch \fB\- < \fIfile\fR" | |
416 | Deletes entries from \fIswitch\fR's group table. With only a | |
417 | \fIswitch\fR argument, deletes all groups. Otherwise, deletes the group | |
418 | for each group entry. | |
419 | . | |
420 | .IP "[\fB\-\-bundle\fR] \fBinsert\-buckets \fIswitch group\fR" | |
421 | .IQ "[\fB\-\-bundle\fR] \fBinsert\-buckets \fIswitch \fB\- < \fIfile\fR" | |
422 | Add buckets to an existing group present in the \fIswitch\fR's group table. | |
423 | If no \fIcommand_bucket_id\fR is present in the group specification then all | |
424 | buckets of the group are removed. | |
425 | . | |
426 | .IP "[\fB\-\-bundle\fR] \fBremove\-buckets \fIswitch group\fR" | |
427 | .IQ "[\fB\-\-bundle\fR] \fBremove\-buckets \fIswitch \fB\- < \fIfile\fR" | |
428 | Remove buckets to an existing group present in the \fIswitch\fR's group table. | |
429 | If no \fIcommand_bucket_id\fR is present in the group specification then all | |
430 | buckets of the group are removed. | |
431 | . | |
432 | .IP "\fBdump\-groups \fIswitch\fR [\fIgroup\fR]" | |
433 | Prints group entries in \fIswitch\fR's tables to console. To dump | |
434 | only a specific group, specify its number as \fIgroup\fR. Otherwise, | |
435 | if \fIgroup\fR is omitted, or if it is specified as \fBALL\fR, then | |
436 | all groups are printed. | |
437 | .IP | |
438 | Only OpenFlow 1.5 and later support dumping a specific group. Earlier | |
439 | versions of OpenFlow always dump all groups. | |
440 | . | |
441 | .IP "\fBdump\-group\-features \fIswitch" | |
442 | Prints to the console the group features of the \fIswitch\fR. | |
443 | . | |
444 | .IP "\fBdump\-group\-stats \fIswitch \fR[\fIgroup\fR]" | |
445 | Prints to the console statistics for the specified \fIgroup\fR in | |
446 | \fIswitch\fR's tables. If \fIgroup\fR is omitted then statistics for all | |
447 | groups are printed. | |
448 | . | |
449 | .SS "OpenFlow 1.3+ Switch Meter Table Commands" | |
450 | . | |
451 | These commands manage the meter table in an OpenFlow switch. In each | |
452 | case, \fImeter\fR specifies a meter entry in the format described in | |
453 | \fBMeter Syntax\fR, below. | |
454 | . | |
455 | .PP | |
456 | OpenFlow 1.3 introduced support for meters, so these commands only work | |
457 | with switches that support OpenFlow 1.3 or later. It is necessary to | |
458 | explicitly enable these protocol versions in \fBovs\-ofctl\fR (using | |
459 | \fB\-O\fR) and in the switch itself (with the \fBprotocols\fR column in | |
460 | the \fBBridge\fR table). For more information, see ``Q: What versions | |
461 | of OpenFlow does Open vSwitch support?'' in the Open vSwitch FAQ. | |
462 | . | |
463 | .IP "\fBadd\-meter \fIswitch meter\fR" | |
464 | Add a meter entry to \fIswitch\fR's tables. The \fImeter\fR syntax is | |
465 | described in section \fBMeter Syntax\fR, below. | |
466 | . | |
467 | .IP "\fBmod\-meter \fIswitch meter\fR" | |
468 | Modify an existing meter. | |
469 | . | |
470 | .IP "\fBdel\-meters \fIswitch\fR [\fImeter\fR]" | |
471 | Delete entries from \fIswitch\fR's meter table. To delete only a | |
472 | specific meter, specify its number as \fImeter\fR. Otherwise, if | |
473 | \fImeter\fR is omitted, or if it is specified as \fBall\fR, then all | |
474 | meters are deleted. | |
475 | . | |
476 | .IP "\fBdump\-meters \fIswitch\fR [\fImeter\fR]" | |
477 | Print entries from \fIswitch\fR's meter table. To print only a | |
478 | specific meter, specify its number as \fImeter\fR. Otherwise, if | |
479 | \fImeter\fR is omitted, or if it is specified as \fBall\fR, then all | |
480 | meters are printed. | |
481 | . | |
482 | .IP "\fBmeter\-stats \fIswitch\fR [\fImeter\fR]" | |
483 | Print meter statistics. \fImeter\fR can specify a single meter with | |
484 | syntax \fBmeter=\fIid\fR, or all meters with syntax \fBmeter=all\fR. | |
485 | . | |
486 | .IP "\fBmeter\-features \fIswitch\fR" | |
487 | Print meter features. | |
488 | . | |
489 | .SS OpenFlow Switch Bundle Command | |
490 | . | |
491 | Transactional updates to both flow and group tables can be made with | |
492 | the \fBbundle\fR command. \fIfile\fR is a text file that contains | |
493 | zero or more flow mods, group mods, or packet-outs in \fBFlow | |
494 | Syntax\fR, \fBGroup Syntax\fR, or \fBPacket\-Out Syntax\fR, each line | |
495 | preceded by \fBflow\fR, \fBgroup\fR, or \fBpacket\-out\fR keyword, | |
496 | correspondingly. The \fBflow\fR keyword may be optionally followed by | |
497 | one of the keywords \fBadd\fR, \fBmodify\fR, \fBmodify_strict\fR, | |
498 | \fBdelete\fR, or \fBdelete_strict\fR, of which the \fBadd\fR is | |
499 | assumed if a bare \fBflow\fR is given. Similarly, the \fBgroup\fR | |
500 | keyword may be optionally followed by one of the keywords \fBadd\fR, | |
501 | \fBmodify\fR, \fBadd_or_mod\fR, \fBdelete\fR, \fBinsert_bucket\fR, or | |
502 | \fBremove_bucket\fR, of which the \fBadd\fR is assumed if a bare | |
503 | \fBgroup\fR is given. | |
504 | . | |
505 | .IP "\fBbundle \fIswitch file\fR" | |
506 | Execute all flow and group mods in \fIfile\fR as a single atomic | |
507 | transaction against \fIswitch\fR's tables. All bundled mods are | |
508 | executed in the order specified. | |
509 | . | |
510 | .SS "OpenFlow Switch Tunnel TLV Table Commands" | |
511 | . | |
512 | Open vSwitch maintains a mapping table between tunnel option TLVs (defined | |
513 | by <class, type, length>) and NXM fields \fBtun_metadata\fIn\fR, | |
514 | where \fIn\fR ranges from 0 to 63, that can be operated on for the | |
515 | purposes of matches, actions, etc. This TLV table can be used for | |
516 | Geneve option TLVs or other protocols with options in same TLV format | |
517 | as Geneve options. This mapping must be explicitly specified by the user | |
518 | through the following commands. | |
519 | ||
520 | A TLV mapping is specified with the syntax | |
521 | \fB{class=\fIclass\fB,type=\fItype\fB,len=\fIlength\fB}->tun_metadata\fIn\fR. | |
522 | When an option mapping exists for a given \fBtun_metadata\fIn\fR, | |
523 | matching on the defined field becomes possible, e.g.: | |
524 | ||
525 | .RS | |
526 | ovs-ofctl add-tlv-map br0 "{class=0xffff,type=0,len=4}->tun_metadata0" | |
527 | .PP | |
528 | ovs-ofctl add-flow br0 tun_metadata0=1234,actions=controller | |
529 | .RE | |
530 | ||
531 | A mapping should not be changed while it is in active | |
532 | use by a flow. The result of doing so is undefined. | |
533 | ||
534 | These commands are Nicira extensions to OpenFlow and require Open vSwitch | |
535 | 2.5 or later. | |
536 | ||
537 | .IP "\fBadd\-tlv\-map \fIswitch option\fR[\fB,\fIoption\fR]..." | |
538 | Add each \fIoption\fR to \fIswitch\fR's tables. Duplicate fields are | |
539 | rejected. | |
540 | . | |
541 | .IP "\fBdel\-tlv\-map \fIswitch \fR[\fIoption\fR[\fB,\fIoption\fR]]..." | |
542 | Delete each \fIoption\fR from \fIswitch\fR's table, or all option TLV | |
543 | mapping if no \fIoption\fR is specified. | |
544 | Fields that aren't mapped are ignored. | |
545 | . | |
546 | .IP "\fBdump\-tlv\-map \fIswitch\fR" | |
547 | Show the currently mapped fields in the switch's option table as well | |
548 | as switch capabilities. | |
549 | . | |
550 | .SS "OpenFlow Switch Monitoring Commands" | |
551 | . | |
552 | .IP "\fBsnoop \fIswitch\fR" | |
553 | Connects to \fIswitch\fR and prints to the console all OpenFlow | |
554 | messages received. Unlike other \fBovs\-ofctl\fR commands, if | |
555 | \fIswitch\fR is the name of a bridge, then the \fBsnoop\fR command | |
556 | connects to a Unix domain socket named | |
557 | \fB@RUNDIR@/\fIswitch\fB.snoop\fR. \fBovs\-vswitchd\fR listens on | |
558 | such a socket for each bridge and sends to it all of the OpenFlow | |
559 | messages sent to or received from its configured OpenFlow controller. | |
560 | Thus, this command can be used to view OpenFlow protocol activity | |
561 | between a switch and its controller. | |
562 | .IP | |
563 | When a switch has more than one controller configured, only the | |
564 | traffic to and from a single controller is output. If none of the | |
565 | controllers is configured as a master or a slave (using a Nicira | |
566 | extension to OpenFlow 1.0 or 1.1, or a standard request in OpenFlow | |
567 | 1.2 or later), then a controller is chosen arbitrarily among | |
568 | them. If there is a master controller, it is chosen; otherwise, if | |
569 | there are any controllers that are not masters or slaves, one is | |
570 | chosen arbitrarily; otherwise, a slave controller is chosen | |
571 | arbitrarily. This choice is made once at connection time and does not | |
572 | change as controllers reconfigure their roles. | |
573 | .IP | |
574 | If a switch has no controller configured, or if | |
575 | the configured controller is disconnected, no traffic is sent, so | |
576 | monitoring will not show any traffic. | |
577 | . | |
578 | .IP "\fBmonitor \fIswitch\fR [\fImiss-len\fR] [\fBinvalid_ttl\fR] [\fBwatch:\fR[\fIspec\fR...]]" | |
579 | Connects to \fIswitch\fR and prints to the console all OpenFlow | |
580 | messages received. Usually, \fIswitch\fR should specify the name of a | |
581 | bridge in the \fBovs\-vswitchd\fR database. | |
582 | .IP | |
583 | If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set | |
584 | configuration'' message at connection setup time that requests | |
585 | \fImiss-len\fR bytes of each packet that misses the flow table. Open vSwitch | |
586 | does not send these and other asynchronous messages to an | |
587 | \fBovs\-ofctl monitor\fR client connection unless a nonzero value is | |
588 | specified on this argument. (Thus, if \fImiss\-len\fR is not | |
589 | specified, very little traffic will ordinarily be printed.) | |
590 | .IP | |
591 | If \fBinvalid_ttl\fR is passed, \fBovs\-ofctl\fR sends an OpenFlow ``set | |
592 | configuration'' message at connection setup time that requests | |
593 | \fBINVALID_TTL_TO_CONTROLLER\fR, so that \fBovs\-ofctl monitor\fR can | |
594 | receive ``packet-in'' messages when TTL reaches zero on \fBdec_ttl\fR action. | |
595 | Only OpenFlow 1.1 and 1.2 support \fBinvalid_ttl\fR; Open vSwitch also | |
596 | implements it for OpenFlow 1.0 as an extension. | |
597 | .IP | |
598 | \fBwatch:\fR[\fB\fIspec\fR...] causes \fBovs\-ofctl\fR to send a | |
599 | ``monitor request'' Nicira extension message to the switch at | |
600 | connection setup time. This message causes the switch to send | |
601 | information about flow table changes as they occur. The following | |
602 | comma-separated \fIspec\fR syntax is available: | |
603 | .RS | |
604 | .IP "\fB!initial\fR" | |
605 | Do not report the switch's initial flow table contents. | |
606 | .IP "\fB!add\fR" | |
607 | Do not report newly added flows. | |
608 | .IP "\fB!delete\fR" | |
609 | Do not report deleted flows. | |
610 | .IP "\fB!modify\fR" | |
611 | Do not report modifications to existing flows. | |
612 | .IP "\fB!own\fR" | |
613 | Abbreviate changes made to the flow table by \fBovs\-ofctl\fR's own | |
614 | connection to the switch. (These could only occur using the | |
615 | \fBofctl/send\fR command described below under \fBRUNTIME MANAGEMENT | |
616 | COMMANDS\fR.) | |
617 | .IP "\fB!actions\fR" | |
618 | Do not report actions as part of flow updates. | |
619 | .IP "\fBtable=\fItable\fR" | |
620 | Limits the monitoring to the table with the given \fItable\fR, which | |
621 | may be expressed as a number between 0 and 254 or (unless | |
622 | \fB\-\-no\-names\fR is specified) a name. By default, all tables are | |
623 | monitored. | |
624 | .IP "\fBout_port=\fIport\fR" | |
625 | If set, only flows that output to \fIport\fR are monitored. The | |
626 | \fIport\fR may be an OpenFlow port number or keyword | |
627 | (e.g. \fBLOCAL\fR). | |
628 | .IP "\fIfield\fB=\fIvalue\fR" | |
629 | Monitors only flows that have \fIfield\fR specified as the given | |
630 | \fIvalue\fR. Any syntax valid for matching on \fBdump\-flows\fR may | |
631 | be used. | |
632 | .RE | |
633 | .IP | |
634 | This command may be useful for debugging switch or controller | |
635 | implementations. With \fBwatch:\fR, it is particularly useful for | |
636 | observing how a controller updates flow tables. | |
637 | . | |
638 | .SS "OpenFlow Switch and Controller Commands" | |
639 | . | |
640 | The following commands, like those in the previous section, may be | |
641 | applied to OpenFlow switches, using any of the connection methods | |
642 | described in that section. Unlike those commands, these may also be | |
643 | applied to OpenFlow controllers. | |
644 | . | |
645 | .TP | |
646 | \fBprobe \fItarget\fR | |
647 | Sends a single OpenFlow echo-request message to \fItarget\fR and waits | |
648 | for the response. With the \fB\-t\fR or \fB\-\-timeout\fR option, this | |
649 | command can test whether an OpenFlow switch or controller is up and | |
650 | running. | |
651 | . | |
652 | .TP | |
653 | \fBping \fItarget \fR[\fIn\fR] | |
654 | Sends a series of 10 echo request packets to \fItarget\fR and times | |
655 | each reply. The echo request packets consist of an OpenFlow header | |
656 | plus \fIn\fR bytes (default: 64) of randomly generated payload. This | |
657 | measures the latency of individual requests. | |
658 | . | |
659 | .TP | |
660 | \fBbenchmark \fItarget n count\fR | |
661 | Sends \fIcount\fR echo request packets that each consist of an | |
662 | OpenFlow header plus \fIn\fR bytes of payload and waits for each | |
663 | response. Reports the total time required. This is a measure of the | |
664 | maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte | |
665 | messages. | |
666 | . | |
667 | .SS "Other Commands" | |
668 | . | |
669 | .IP "\fBofp\-parse\fR \fIfile\fR" | |
670 | Reads \fIfile\fR (or \fBstdin\fR if \fIfile\fR is \fB\-\fR) as a | |
671 | series of OpenFlow messages in the binary format used on an OpenFlow | |
672 | connection, and prints them to the console. This can be useful for | |
673 | printing OpenFlow messages captured from a TCP stream. | |
674 | . | |
675 | .IP "\fBofp\-parse\-pcap\fR \fIfile\fR [\fIport\fR...]" | |
676 | Reads \fIfile\fR, which must be in the PCAP format used by network | |
677 | capture tools such as \fBtcpdump\fR or \fBwireshark\fR, extracts all | |
678 | the TCP streams for OpenFlow connections, and prints the OpenFlow | |
679 | messages in those connections in human-readable format on | |
680 | \fBstdout\fR. | |
681 | .IP | |
682 | OpenFlow connections are distinguished by TCP port number. | |
683 | Non-OpenFlow packets are ignored. By default, data on TCP ports 6633 | |
684 | and 6653 are considered to be OpenFlow. Specify one or more | |
685 | \fIport\fR arguments to override the default. | |
686 | .IP | |
687 | This command cannot usefully print SSL encrypted traffic. It does not | |
688 | understand IPv6. | |
689 | . | |
690 | .SS "Flow Syntax" | |
691 | .PP | |
692 | Some \fBovs\-ofctl\fR commands accept an argument that describes a flow or | |
693 | flows. Such flow descriptions comprise a series of | |
694 | \fIfield\fB=\fIvalue\fR assignments, separated by commas or white | |
695 | space. (Embedding spaces into a flow description normally requires | |
696 | quoting to prevent the shell from breaking the description into | |
697 | multiple arguments.) | |
698 | .PP | |
699 | Flow descriptions should be in \fBnormal form\fR. This means that a | |
700 | flow may only specify a value for an L3 field if it also specifies a | |
701 | particular L2 protocol, and that a flow may only specify an L4 field | |
702 | if it also specifies particular L2 and L3 protocol types. For | |
703 | example, if the L2 protocol type \fBdl_type\fR is wildcarded, then L3 | |
704 | fields \fBnw_src\fR, \fBnw_dst\fR, and \fBnw_proto\fR must also be | |
705 | wildcarded. Similarly, if \fBdl_type\fR or \fBnw_proto\fR (the L3 | |
706 | protocol type) is wildcarded, so must be the L4 fields \fBtcp_dst\fR and | |
707 | \fBtcp_src\fR. \fBovs\-ofctl\fR will warn about | |
708 | flows not in normal form. | |
709 | .PP | |
710 | \fBovs\-fields\fR(7) describes the supported fields and how to match | |
711 | them. In addition to match fields, commands that operate on flows | |
712 | accept a few additional key-value pairs: | |
713 | . | |
714 | .IP \fBtable=\fItable\fR | |
715 | For flow dump commands, limits the flows dumped to those in | |
716 | \fItable\fR, which may be expressed as a number between 0 and 255 or | |
717 | (unless \fB\-\-no\-names\fR is specified) a name. If not specified | |
718 | (or if 255 is specified as \fItable\fR), then flows in all tables are | |
719 | dumped. | |
720 | . | |
721 | .IP | |
722 | For flow table modification commands, behavior varies based on the | |
723 | OpenFlow version used to connect to the switch: | |
724 | . | |
725 | .RS | |
726 | .IP "OpenFlow 1.0" | |
727 | OpenFlow 1.0 does not support \fBtable\fR for modifying flows. | |
728 | \fBovs\-ofctl\fR will exit with an error if \fBtable\fR (other than | |
729 | \fBtable=255\fR) is specified for a switch that only supports OpenFlow | |
730 | 1.0. | |
731 | .IP | |
732 | In OpenFlow 1.0, the switch chooses the table into which to insert a | |
733 | new flow. The Open vSwitch software switch always chooses table 0. | |
734 | Other Open vSwitch datapaths and other OpenFlow implementations may | |
735 | choose different tables. | |
736 | .IP | |
737 | The OpenFlow 1.0 behavior in Open vSwitch for modifying or removing | |
738 | flows depends on whether \fB\-\-strict\fR is used. Without | |
739 | \fB\-\-strict\fR, the command applies to matching flows in all tables. | |
740 | With \fB\-\-strict\fR, the command will operate on any single matching | |
741 | flow in any table; it will do nothing if there are matches in more | |
742 | than one table. (The distinction between these behaviors only matters | |
743 | if non-OpenFlow 1.0 commands were also used, because OpenFlow 1.0 | |
744 | alone cannot add flows with the same matching criteria to multiple | |
745 | tables.) | |
746 | . | |
747 | .IP "OpenFlow 1.0 with table_id extension" | |
748 | Open vSwitch implements an OpenFlow extension that allows the | |
749 | controller to specify the table on which to operate. \fBovs\-ofctl\fR | |
750 | automatically enables the extension when \fBtable\fR is specified and | |
751 | OpenFlow 1.0 is used. \fBovs\-ofctl\fR automatically detects whether | |
752 | the switch supports the extension. As of this writing, this extension | |
753 | is only known to be implemented by Open vSwitch. | |
754 | . | |
755 | .IP | |
756 | With this extension, \fBovs\-ofctl\fR operates on the requested table | |
757 | when \fBtable\fR is specified, and acts as described for OpenFlow 1.0 | |
758 | above when no \fBtable\fR is specified (or for \fBtable=255\fR). | |
759 | . | |
760 | .IP "OpenFlow 1.1" | |
761 | OpenFlow 1.1 requires flow table modification commands to specify a | |
762 | table. When \fBtable\fR is not specified (or \fBtable=255\fR is | |
763 | specified), \fBovs\-ofctl\fR defaults to table 0. | |
764 | . | |
765 | .IP "OpenFlow 1.2 and later" | |
766 | OpenFlow 1.2 and later allow flow deletion commands, but not other | |
767 | flow table modification commands, to operate on all flow tables, with | |
768 | the behavior described above for OpenFlow 1.0. | |
769 | .RE | |
770 | .IP "\fBduration=\fR..." | |
771 | .IQ "\fBn_packet=\fR..." | |
772 | .IQ "\fBn_bytes=\fR..." | |
773 | \fBovs\-ofctl\fR ignores assignments to these ``fields'' to allow | |
774 | output from the \fBdump\-flows\fR command to be used as input for | |
775 | other commands that parse flows. | |
776 | . | |
777 | .PP | |
778 | The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands | |
779 | require an additional field, which must be the final field specified: | |
780 | . | |
781 | .IP \fBactions=\fR[\fIaction\fR][\fB,\fIaction\fR...]\fR | |
782 | Specifies a comma-separated list of actions to take on a packet when | |
783 | the flow entry matches. If no \fIaction\fR is specified, then packets | |
784 | matching the flow are dropped. See \fBovs\-actions\fR(7) for details | |
785 | on the syntax and semantics of actions. | |
786 | K | |
787 | .PP | |
788 | An opaque identifier called a cookie can be used as a handle to identify | |
789 | a set of flows: | |
790 | . | |
791 | .IP \fBcookie=\fIvalue\fR | |
792 | . | |
793 | A cookie can be associated with a flow using the \fBadd\-flow\fR, | |
794 | \fBadd\-flows\fR, and \fBmod\-flows\fR commands. \fIvalue\fR can be any | |
795 | 64-bit number and need not be unique among flows. If this field is | |
796 | omitted, a default cookie value of 0 is used. | |
797 | . | |
798 | .IP \fBcookie=\fIvalue\fR\fB/\fImask\fR | |
799 | . | |
800 | When using NXM, the cookie can be used as a handle for querying, | |
801 | modifying, and deleting flows. \fIvalue\fR and \fImask\fR may be | |
802 | supplied for the \fBdel\-flows\fR, \fBmod\-flows\fR, \fBdump\-flows\fR, and | |
803 | \fBdump\-aggregate\fR commands to limit matching cookies. A 1-bit in | |
804 | \fImask\fR indicates that the corresponding bit in \fIcookie\fR must | |
805 | match exactly, and a 0-bit wildcards that bit. A mask of \-1 may be used | |
806 | to exactly match a cookie. | |
807 | .IP | |
808 | The \fBmod\-flows\fR command can update the cookies of flows that | |
809 | match a cookie by specifying the \fIcookie\fR field twice (once with a | |
810 | mask for matching and once without to indicate the new value): | |
811 | .RS | |
812 | .IP "\fBovs\-ofctl mod\-flows br0 cookie=1,actions=normal\fR" | |
813 | Change all flows' cookies to 1 and change their actions to \fBnormal\fR. | |
814 | .IP "\fBovs\-ofctl mod\-flows br0 cookie=1/\-1,cookie=2,actions=normal\fR" | |
815 | Update cookies with a value of 1 to 2 and change their actions to | |
816 | \fBnormal\fR. | |
817 | .RE | |
818 | .IP | |
819 | The ability to match on cookies was added in Open vSwitch 1.5.0. | |
820 | . | |
821 | .PP | |
822 | The following additional field sets the priority for flows added by | |
823 | the \fBadd\-flow\fR and \fBadd\-flows\fR commands. For | |
824 | \fBmod\-flows\fR and \fBdel\-flows\fR when \fB\-\-strict\fR is | |
825 | specified, priority must match along with the rest of the flow | |
826 | specification. For \fBmod-flows\fR without \fB\-\-strict\fR, | |
827 | priority is only significant if the command creates a new flow, that | |
828 | is, non-strict \fBmod\-flows\fR does not match on priority and will | |
829 | not change the priority of existing flows. Other commands do not | |
830 | allow priority to be specified. | |
831 | . | |
832 | .IP \fBpriority=\fIvalue\fR | |
833 | The priority at which a wildcarded entry will match in comparison to | |
834 | others. \fIvalue\fR is a number between 0 and 65535, inclusive. A higher | |
835 | \fIvalue\fR will match before a lower one. An exact-match entry will always | |
836 | have priority over an entry containing wildcards, so it has an implicit | |
837 | priority value of 65535. When adding a flow, if the field is not specified, | |
838 | the flow's priority will default to 32768. | |
839 | .IP | |
840 | OpenFlow leaves behavior undefined when two or more flows with the | |
841 | same priority can match a single packet. Some users expect | |
842 | ``sensible'' behavior, such as more specific flows taking precedence | |
843 | over less specific flows, but OpenFlow does not specify this and Open | |
844 | vSwitch does not implement it. Users should therefore take care to | |
845 | use priorities to ensure the behavior that they expect. | |
846 | . | |
847 | .PP | |
848 | The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands | |
849 | support the following additional options. These options affect only | |
850 | new flows. Thus, for \fBadd\-flow\fR and \fBadd\-flows\fR, these | |
851 | options are always significant, but for \fBmod\-flows\fR they are | |
852 | significant only if the command creates a new flow, that is, their | |
853 | values do not update or affect existing flows. | |
854 | . | |
855 | .IP "\fBidle_timeout=\fIseconds\fR" | |
856 | Causes the flow to expire after the given number of seconds of | |
857 | inactivity. A value of 0 (the default) prevents a flow from expiring | |
858 | due to inactivity. | |
859 | . | |
860 | .IP \fBhard_timeout=\fIseconds\fR | |
861 | Causes the flow to expire after the given number of seconds, | |
862 | regardless of activity. A value of 0 (the default) gives the flow no | |
863 | hard expiration deadline. | |
864 | . | |
865 | .IP "\fBimportance=\fIvalue\fR" | |
866 | Sets the importance of a flow. The flow entry eviction mechanism can | |
867 | use importance as a factor in deciding which flow to evict. A value | |
868 | of 0 (the default) makes the flow non-evictable on the basis of | |
869 | importance. Specify a value between 0 and 65535. | |
870 | .IP | |
871 | Only OpenFlow 1.4 and later support \fBimportance\fR. | |
872 | . | |
873 | .IP "\fBsend_flow_rem\fR" | |
874 | Marks the flow with a flag that causes the switch to generate a ``flow | |
875 | removed'' message and send it to interested controllers when the flow | |
876 | later expires or is removed. | |
877 | . | |
878 | .IP "\fBcheck_overlap\fR" | |
879 | Forces the switch to check that the flow match does not overlap that | |
880 | of any different flow with the same priority in the same table. (This | |
881 | check is expensive so it is best to avoid it.) | |
882 | . | |
883 | .IP "\fBreset_counts\fR" | |
884 | When this flag is specified on a flow being added to a switch, and the | |
885 | switch already has a flow with an identical match, an OpenFlow 1.2 (or | |
886 | later) switch resets the flow's packet and byte counters to 0. | |
887 | Without the flag, the packet and byte counters are preserved. | |
888 | .IP | |
889 | OpenFlow 1.0 and 1.1 switches always reset counters in this situation, | |
890 | as if \fBreset_counts\fR were always specified. | |
891 | .IP | |
892 | Open vSwitch 1.10 added support for \fBreset_counts\fR. | |
893 | . | |
894 | .IP "\fBno_packet_counts\fR" | |
895 | .IQ "\fBno_byte_counts\fR" | |
896 | Adding these flags to a flow advises an OpenFlow 1.3 (or later) switch | |
897 | that the controller does not need packet or byte counters, | |
898 | respectively, for the flow. Some switch implementations might achieve | |
899 | higher performance or reduce resource consumption when these flags are | |
900 | used. These flags provide no benefit to the Open vSwitch software | |
901 | switch implementation. | |
902 | .IP | |
903 | OpenFlow 1.2 and earlier do not support these flags. | |
904 | .IP | |
905 | Open vSwitch 1.10 added support for \fBno_packet_counts\fR and | |
906 | \fBno_byte_counts\fR. | |
907 | . | |
908 | .PP | |
909 | The \fBdump\-flows\fR, \fBdump\-aggregate\fR, \fBdel\-flow\fR | |
910 | and \fBdel\-flows\fR commands support these additional optional fields: | |
911 | . | |
912 | .TP | |
913 | \fBout_port=\fIport\fR | |
914 | If set, a matching flow must include an output action to \fIport\fR, | |
915 | which must be an OpenFlow port number or name (e.g. \fBlocal\fR). | |
916 | . | |
917 | .TP | |
918 | \fBout_group=\fIgroup\fR | |
919 | If set, a matching flow must include an \fBgroup\fR action naming | |
920 | \fIgroup\fR, which must be an OpenFlow group number. This field | |
921 | is supported in Open vSwitch 2.5 and later and requires OpenFlow 1.1 | |
922 | or later. | |
923 | . | |
924 | .SS "Table Entry Output" | |
925 | . | |
926 | The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information | |
927 | about the entries in a datapath's tables. Each line of output is a | |
928 | flow entry as described in \fBFlow Syntax\fR, above, plus some | |
929 | additional fields: | |
930 | . | |
931 | .IP \fBduration=\fIsecs\fR | |
932 | The time, in seconds, that the entry has been in the table. | |
933 | \fIsecs\fR includes as much precision as the switch provides, possibly | |
934 | to nanosecond resolution. | |
935 | . | |
936 | .IP \fBn_packets\fR | |
937 | The number of packets that have matched the entry. | |
938 | . | |
939 | .IP \fBn_bytes\fR | |
940 | The total number of bytes from packets that have matched the entry. | |
941 | . | |
942 | .PP | |
943 | The following additional fields are included only if the switch is | |
944 | Open vSwitch 1.6 or later and the NXM flow format is used to dump the | |
945 | flow (see the description of the \fB\-\-flow-format\fR option below). | |
946 | The values of these additional fields are approximations only and in | |
947 | particular \fBidle_age\fR will sometimes become nonzero even for busy | |
948 | flows. | |
949 | . | |
950 | .IP \fBhard_age=\fIsecs\fR | |
951 | The integer number of seconds since the flow was added or modified. | |
952 | \fBhard_age\fR is displayed only if it differs from the integer part | |
953 | of \fBduration\fR. (This is separate from \fBduration\fR because | |
954 | \fBmod\-flows\fR restarts the \fBhard_timeout\fR timer without zeroing | |
955 | \fBduration\fR.) | |
956 | . | |
957 | .IP \fBidle_age=\fIsecs\fR | |
958 | The integer number of seconds that have passed without any packets | |
959 | passing through the flow. | |
960 | . | |
961 | .SS "Packet\-Out Syntax" | |
962 | .PP | |
963 | \fBovs\-ofctl bundle\fR command accepts packet-outs to be specified in | |
964 | the bundle file. Each packet-out comprises of a series of | |
965 | \fIfield\fB=\fIvalue\fR assignments, separated by commas or white | |
966 | space. (Embedding spaces into a packet-out description normally | |
967 | requires quoting to prevent the shell from breaking the description | |
968 | into multiple arguments.). Unless noted otherwise only the last | |
969 | instance of each field is honoured. This same syntax is also | |
970 | supported by the \fBovs\-ofctl packet-out\fR command. | |
971 | .PP | |
972 | .IP \fBin_port=\fIport\fR | |
973 | The port number to be considered the in_port when processing actions. | |
974 | This can be any valid OpenFlow port number, or any of the \fBLOCAL\fR, | |
975 | \fBCONTROLLER\fR, or \fBNONE\fR. | |
976 | . | |
977 | This field is required. | |
978 | ||
979 | .IP \fIpipeline_field\fR=\fIvalue\fR | |
980 | Optionally, user can specify a list of pipeline fields for a packet-out | |
981 | message. The supported pipeline fields includes \fBtunnel fields\fR and | |
982 | \fBregister fields\fR as defined in \fBovs\-fields\fR(7). | |
983 | ||
984 | .IP \fBpacket=\fIhex-string\fR | |
985 | The actual packet to send, expressed as a string of hexadecimal bytes. | |
986 | . | |
987 | This field is required. | |
988 | ||
989 | .IP \fBactions=\fR[\fIaction\fR][\fB,\fIaction\fR...]\fR | |
990 | The syntax of actions are identical to the \fBactions=\fR field | |
991 | described in \fBFlow Syntax\fR above. Specifying \fBactions=\fR is | |
992 | optional, but omitting actions is interpreted as a drop, so the packet | |
993 | will not be sent anywhere from the switch. | |
994 | . | |
995 | \fBactions\fR must be specified at the end of each line, like for flow mods. | |
996 | .RE | |
997 | . | |
998 | .SS "Group Syntax" | |
999 | .PP | |
1000 | Some \fBovs\-ofctl\fR commands accept an argument that describes a group or | |
1001 | groups. Such flow descriptions comprise a series | |
1002 | \fIfield\fB=\fIvalue\fR assignments, separated by commas or white | |
1003 | space. (Embedding spaces into a group description normally requires | |
1004 | quoting to prevent the shell from breaking the description into | |
1005 | multiple arguments.). Unless noted otherwise only the last instance | |
1006 | of each field is honoured. | |
1007 | .PP | |
1008 | .IP \fBgroup_id=\fIid\fR | |
1009 | The integer group id of group. | |
1010 | When this field is specified in \fBdel\-groups\fR or \fBdump\-groups\fR, | |
1011 | the keyword "all" may be used to designate all groups. | |
1012 | . | |
1013 | This field is required. | |
1014 | ||
1015 | ||
1016 | .IP \fBtype=\fItype\fR | |
1017 | The type of the group. The \fBadd-group\fR, \fBadd-groups\fR and | |
1018 | \fBmod-groups\fR commands require this field. It is prohibited for | |
1019 | other commands. The following keywords designated the allowed types: | |
1020 | .RS | |
1021 | .IP \fBall\fR | |
1022 | Execute all buckets in the group. | |
1023 | .IP \fBselect\fR | |
1024 | Execute one bucket in the group, balancing across the buckets | |
1025 | according to their weights. To select a bucket, for each live bucket, | |
1026 | Open vSwitch hashes flow data with the bucket ID and multiplies by the | |
1027 | bucket weight to obtain a ``score,'' and then selects the bucket with | |
1028 | the highest score. Use \fBselection_method\fR to control the flow | |
1029 | data used for selection. | |
1030 | .IP \fBindirect\fR | |
1031 | Executes the one bucket in the group. | |
1032 | .IP \fBff\fR | |
1033 | .IQ \fBfast_failover\fR | |
1034 | Executes the first live bucket in the group which is associated with | |
1035 | a live port or group. | |
1036 | .RE | |
1037 | ||
1038 | .IP \fBcommand_bucket_id=\fIid\fR | |
1039 | The bucket to operate on. The \fBinsert-buckets\fR and \fBremove-buckets\fR | |
1040 | commands require this field. It is prohibited for other commands. | |
1041 | \fIid\fR may be an integer or one of the following keywords: | |
1042 | .RS | |
1043 | .IP \fBall\fR | |
1044 | Operate on all buckets in the group. | |
1045 | Only valid when used with the \fBremove-buckets\fR command in which | |
1046 | case the effect is to remove all buckets from the group. | |
1047 | .IP \fBfirst\fR | |
1048 | Operate on the first bucket present in the group. | |
1049 | In the case of the \fBinsert-buckets\fR command the effect is to | |
1050 | insert new bucets just before the first bucket already present in the group; | |
1051 | or to replace the buckets of the group if there are no buckets already present | |
1052 | in the group. | |
1053 | In the case of the \fBremove-buckets\fR command the effect is to | |
1054 | remove the first bucket of the group; or do nothing if there are no | |
1055 | buckets present in the group. | |
1056 | .IP \fBlast\fR | |
1057 | Operate on the last bucket present in the group. | |
1058 | In the case of the \fBinsert-buckets\fR command the effect is to | |
1059 | insert new bucets just after the last bucket already present in the group; | |
1060 | or to replace the buckets of the group if there are no buckets already present | |
1061 | in the group. | |
1062 | In the case of the \fBremove-buckets\fR command the effect is to | |
1063 | remove the last bucket of the group; or do nothing if there are no | |
1064 | buckets present in the group. | |
1065 | .RE | |
1066 | .IP | |
1067 | If \fIid\fR is an integer then it should correspond to the \fBbucket_id\fR | |
1068 | of a bucket present in the group. | |
1069 | In case of the \fBinsert-buckets\fR command the effect is to | |
1070 | insert buckets just before the bucket in the group whose \fBbucket_id\fR is | |
1071 | \fIid\fR. | |
1072 | In case of the \fBiremove-buckets\fR command the effect is to | |
1073 | remove the in the group whose \fBbucket_id\fR is \fIid\fR. | |
1074 | It is an error if there is no bucket persent group in whose \fBbucket_id\fR is | |
1075 | \fIid\fR. | |
1076 | ||
1077 | .IP \fBselection_method\fR=\fImethod\fR | |
1078 | The selection method used to select a bucket for a select group. | |
1079 | This is a string of 1 to 15 bytes in length known to lower layers. | |
1080 | This field is optional for \fBadd\-group\fR, \fBadd\-groups\fR and | |
1081 | \fBmod\-group\fR commands on groups of type \fBselect\fR. Prohibited | |
1082 | otherwise. If no selection method is specified, Open vSwitch up to | |
1083 | release 2.9 applies the \fBhash\fR method with default fields. From | |
1084 | 2.10 onwards Open vSwitch defaults to the \fBdp_hash\fR method with symmetric | |
1085 | L3/L4 hash algorithm, unless the weighted group buckets cannot be mapped to | |
1086 | a maximum of 64 dp_hash values with sufficient accuracy. | |
1087 | In those rare cases Open vSwitch 2.10 and later fall back to the \fBhash\fR | |
1088 | method with the default set of hash fields. | |
1089 | .RS | |
1090 | .IP \fBdp_hash\fR | |
1091 | Use a datapath computed hash value. The hash algorithm varies accross | |
1092 | different datapath implementations. \fBdp_hash\fR uses the upper 32 | |
1093 | bits of the \fBselection_method_param\fR as the datapath hash | |
1094 | algorithm selector. The supported values are \fB0\fR (corresponding to | |
1095 | hash computation over the IP 5-tuple) and \fB1\fR (corresponding to a | |
1096 | \fIsymmetric\fR hash computation over the IP 5-tuple). Selecting specific | |
1097 | fields with the \fBfields\fR option is not supported with \fBdp_hash\fR). | |
1098 | The lower 32 bits are used as the hash basis. | |
1099 | .IP | |
1100 | Using \fBdp_hash\fR has the advantage that it does not require the | |
1101 | generated datapath flows to exact match any additional packet header | |
1102 | fields. For example, even if multiple TCP connections thus hashed to | |
1103 | different select group buckets have different source port numbers, | |
1104 | generally all of them would be handled with a small set of already | |
1105 | established datapath flows, resulting in less latency for TCP SYN | |
1106 | packets. The downside is that the shared datapath flows must match | |
1107 | each packet twice, as the datapath hash value calculation happens only | |
1108 | when needed, and a second match is required to match some bits of its | |
1109 | value. This double-matching incurs a small additional latency cost | |
1110 | for each packet, but this latency is orders of magnitude less than the | |
1111 | latency of creating new datapath flows for new TCP connections. | |
1112 | .IP \fBhash\fR | |
1113 | Use a hash computed over the fields specified with the \fBfields\fR | |
1114 | option, see below. If no hash fields are specified, \fBhash\fR defaults | |
1115 | to a symmetric hash over the combination of MAC addresses, VLAN tags, | |
1116 | Ether type, IP addresses and L4 port numbers. \fBhash\fR uses the | |
1117 | \fBselection_method_param\fR as the hash basis. | |
1118 | .IP | |
1119 | Note that the hashed fields become exact matched by the datapath | |
1120 | flows. For example, if the TCP source port is hashed, the created | |
1121 | datapath flows will match the specific TCP source port value present | |
1122 | in the packet received. Since each TCP connection generally has a | |
1123 | different source port value, a separate datapath flow will be need to | |
1124 | be inserted for each TCP connection thus hashed to a select group | |
1125 | bucket. | |
1126 | .RE | |
1127 | .IP | |
1128 | This option uses a Netronome OpenFlow extension which is only supported | |
1129 | when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later. | |
1130 | ||
1131 | .IP \fBselection_method_param\fR=\fIparam\fR | |
1132 | 64-bit integer parameter to the selection method selected by the | |
1133 | \fBselection_method\fR field. The parameter's use is defined by the | |
1134 | lower-layer that implements the \fBselection_method\fR. It is optional if | |
1135 | the \fBselection_method\fR field is specified as a non-empty string. | |
1136 | Prohibited otherwise. The default value is zero. | |
1137 | .IP | |
1138 | This option uses a Netronome OpenFlow extension which is only supported | |
1139 | when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later. | |
1140 | ||
1141 | .IP \fBfields\fR=\fIfield\fR | |
1142 | .IQ \fBfields(\fIfield\fR[\fB=\fImask\fR]\fR...\fB)\fR | |
1143 | The field parameters to selection method selected by the | |
1144 | \fBselection_method\fR field. The syntax is described in \fBFlow | |
1145 | Syntax\fR with the additional restrictions that if a value is provided | |
1146 | it is treated as a wildcard mask and wildcard masks following a slash | |
1147 | are prohibited. The pre-requisites of fields must be provided by any | |
1148 | flows that output to the group. The use of the fields is defined by | |
1149 | the lower-layer that implements the \fBselection_method\fR. They are | |
1150 | optional if the \fBselection_method\fR field is specified as ``hash', | |
1151 | prohibited otherwise. The default is no fields. | |
1152 | .IP | |
1153 | This option will use a Netronome OpenFlow extension which is only supported | |
1154 | when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later. | |
1155 | ||
1156 | .IP \fBbucket\fR=\fIbucket_parameters\fR | |
1157 | The \fBadd-group\fR, \fBadd-groups\fR and \fBmod-group\fR commands | |
1158 | require at least one bucket field. Bucket fields must appear after | |
1159 | all other fields. | |
1160 | . | |
1161 | Multiple bucket fields to specify multiple buckets. | |
1162 | The order in which buckets are specified corresponds to their order in | |
1163 | the group. If the type of the group is "indirect" then only one group may | |
1164 | be specified. | |
1165 | . | |
1166 | \fIbucket_parameters\fR consists of a list of \fIfield\fB=\fIvalue\fR | |
1167 | assignments, separated by commas or white space followed by a | |
1168 | comma-separated list of actions. | |
1169 | The fields for \fIbucket_parameters\fR are: | |
1170 | . | |
1171 | .RS | |
1172 | .IP \fBbucket_id=\fIid\fR | |
1173 | The 32-bit integer group id of the bucket. Values greater than | |
1174 | 0xffffff00 are reserved. | |
1175 | . | |
1176 | This field was added in Open vSwitch 2.4 to conform with the OpenFlow | |
1177 | 1.5 specification. It is not supported when earlier versions | |
1178 | of OpenFlow are used. Open vSwitch will automatically allocate bucket | |
1179 | ids when they are not specified. | |
1180 | .IP \fBactions=\fR[\fIaction\fR][\fB,\fIaction\fR...]\fR | |
1181 | The syntax of actions are identical to the \fBactions=\fR field described in | |
1182 | \fBFlow Syntax\fR above. Specifying \fBactions=\fR is optional, any unknown | |
1183 | bucket parameter will be interpreted as an action. | |
1184 | .IP \fBweight=\fIvalue\fR | |
1185 | The relative weight of the bucket as an integer. This may be used by the switch | |
1186 | during bucket select for groups whose \fBtype\fR is \fBselect\fR. | |
1187 | .IP \fBwatch_port=\fIport\fR | |
1188 | Port used to determine liveness of group. | |
1189 | This or the \fBwatch_group\fR field is required | |
1190 | for groups whose \fBtype\fR is \fBff\fR or \fBfast_failover\fR. | |
1191 | This or the \fBwatch_group\fR field can also be used | |
1192 | for groups whose \fBtype\fR is \fBselect\fR. | |
1193 | .IP \fBwatch_group=\fIgroup_id\fR | |
1194 | Group identifier of group used to determine liveness of group. | |
1195 | This or the \fBwatch_port\fR field is required | |
1196 | for groups whose \fBtype\fR is \fBff\fR or \fBfast_failover\fR. | |
1197 | This or the \fBwatch_port\fR field can also be used | |
1198 | for groups whose \fBtype\fR is \fBselect\fR. | |
1199 | .RE | |
1200 | . | |
1201 | .SS "Meter Syntax" | |
1202 | .PP | |
1203 | The meter table commands accept an argument that describes a meter. | |
1204 | Such meter descriptions comprise a series \fIfield\fB=\fIvalue\fR | |
1205 | assignments, separated by commas or white space. | |
1206 | (Embedding spaces into a group description normally requires | |
1207 | quoting to prevent the shell from breaking the description into | |
1208 | multiple arguments.). Unless noted otherwise only the last instance | |
1209 | of each field is honoured. | |
1210 | .PP | |
1211 | .IP \fBmeter=\fIid\fR | |
1212 | The identifier for the meter. An integer is used to specify a | |
1213 | user-defined meter. In addition, the keywords "all", "controller", and | |
1214 | "slowpath", are also supported as virtual meters. The "controller" and | |
1215 | "slowpath" virtual meters apply to packets sent to the controller and to | |
1216 | the OVS userspace, respectively. | |
1217 | .IP | |
1218 | When this field is specified in \fBdel-meter\fR, \fBdump-meter\fR, or | |
1219 | \fBmeter-stats\fR, the keyword "all" may be used to designate all | |
1220 | meters. This field is required, except for \fBmeter-stats\fR, which | |
1221 | dumps all stats when this field is not specified. | |
1222 | .IP \fBkbps\fR | |
1223 | .IQ \fBpktps\fR | |
1224 | The unit for the \fBrate\fR and \fBburst_size\fR band parameters. | |
1225 | \fBkbps\fR specifies kilobits per second, and \fBpktps\fR specifies | |
1226 | packets per second. A unit is required for the \fBadd-meter\fR and | |
1227 | \fBmod-meter\fR commands. | |
1228 | ||
1229 | .IP \fBburst\fR | |
1230 | If set, enables burst support for meter bands through the \fBburst_size\fR | |
1231 | parameter. | |
1232 | ||
1233 | .IP \fBstats\fR | |
1234 | If set, enables the collection of meter and band statistics. | |
1235 | ||
1236 | .IP \fBbands\fR=\fIband_parameters\fR | |
1237 | The \fBadd-meter\fR and \fBmod-meter\fR commands require at least one | |
1238 | band specification. Bands must appear after all other fields. | |
1239 | .RS | |
1240 | .IP \fBtype=\fItype\fR | |
1241 | The type of the meter band. This keyword starts a new band specification. | |
1242 | Each band specifies a rate above which the band is to take some action. The | |
1243 | action depends on the band type. If multiple bands' rate is exceeded, then | |
1244 | the band with the highest rate among the exceeded bands is selected. | |
1245 | The following keywords designate the allowed | |
1246 | meter band types: | |
1247 | .RS | |
1248 | .IP \fBdrop\fR | |
1249 | Drop packets exceeding the band's rate limit. | |
1250 | .RE | |
1251 | . | |
1252 | .IP "The other \fIband_parameters\fR are:" | |
1253 | .IP \fBrate=\fIvalue\fR | |
1254 | The relative rate limit for this band, in kilobits per second or packets per | |
1255 | second, depending on whether \fBkbps\fR or \fBpktps\fR was specified. | |
1256 | .IP \fBburst_size=\fIsize\fR | |
1257 | If \fBburst\fR is specified for the meter entry, configures the maximum | |
1258 | burst allowed for the band in kilobits or packets, depending on whether | |
1259 | \fBkbps\fR or \fBpktps\fR was specified. If unspecified, the switch is | |
1260 | free to select some reasonable value depending on its configuration. | |
1261 | .RE | |
1262 | . | |
1263 | .SH OPTIONS | |
1264 | .TP | |
1265 | \fB\-\-strict\fR | |
1266 | Uses strict matching when running flow modification commands. | |
1267 | . | |
1268 | .IP "\fB\-\-names\fR" | |
1269 | .IQ "\fB\-\-no\-names\fR" | |
1270 | Every OpenFlow port has a name and a number, and every OpenFlow flow | |
1271 | table has a number and sometimes a name. By default, \fBovs\-ofctl\fR | |
1272 | commands accept both port and table names and numbers, and they | |
1273 | display port and table names if \fBovs\-ofctl\fR is running on an | |
1274 | interactive console, numbers otherwise. With \fB\-\-names\fR, | |
1275 | \fBovs\-ofctl\fR commands both accept and display port and table | |
1276 | names; with \fB\-\-no\-names\fR, commands neither accept nor display | |
1277 | port and table names. | |
1278 | .IP | |
1279 | If a port or table name contains special characters or might be | |
1280 | confused with a keyword within a flow, it may be enclosed in double | |
1281 | quotes (escaped from the shell). If necessary, JSON-style escape | |
1282 | sequences may be used inside quotes, as specified in RFC 7159. When | |
1283 | it displays port and table names, \fBovs\-ofctl\fR quotes any name | |
1284 | that does not start with a letter followed by letters or digits. | |
1285 | .IP | |
1286 | Open vSwitch added support for port names and these options. Open | |
1287 | vSwitch 2.10 added support for table names. Earlier versions always | |
1288 | behaved as if \fB\-\-no\-names\fR were specified. | |
1289 | .IP | |
1290 | Open vSwitch does not place its own limit on the length of port names, | |
1291 | but OpenFlow 1.0 to 1.5 limit port names to 15 bytes and OpenFlow 1.6 | |
1292 | limits them to 63 bytes. Because \fRovs\-ofctl\fR uses OpenFlow to | |
1293 | retrieve the mapping between port names and numbers, names longer than | |
1294 | this limit will be truncated for both display and acceptance. | |
1295 | Truncation can also cause long names that are different to appear to | |
1296 | be the same; when a switch has two ports with the same (truncated) | |
1297 | name, \fBovs\-ofctl\fR refuses to display or accept the name, using | |
1298 | the number instead. | |
1299 | .IP | |
1300 | OpenFlow and Open vSwitch limit table names to 32 bytes. | |
1301 | . | |
1302 | .IP "\fB\-\-stats\fR" | |
1303 | .IQ "\fB\-\-no\-stats\fR" | |
1304 | The \fBdump\-flows\fR command by default, or with \fB\-\-stats\fR, | |
1305 | includes flow duration, packet and byte counts, and idle and hard age | |
1306 | in its output. With \fB\-\-no\-stats\fR, it omits all of these, as | |
1307 | well as cookie values and table IDs if they are zero. | |
1308 | . | |
1309 | .IP "\fB\-\-read-only\fR" | |
1310 | Do not execute read/write commands. | |
1311 | . | |
1312 | .IP "\fB\-\-bundle\fR" | |
1313 | Execute flow mods as an OpenFlow 1.4 atomic bundle transaction. | |
1314 | .RS | |
1315 | .IP \(bu | |
1316 | Within a bundle, all flow mods are processed in the order they appear | |
1317 | and as a single atomic transaction, meaning that if one of them fails, | |
1318 | the whole transaction fails and none of the changes are made to the | |
1319 | \fIswitch\fR's flow table, and that each given datapath packet | |
1320 | traversing the OpenFlow tables sees the flow tables either as before | |
1321 | the transaction, or after all the flow mods in the bundle have been | |
1322 | successfully applied. | |
1323 | .IP \(bu | |
1324 | The beginning and the end of the flow table modification commands in a | |
1325 | bundle are delimited with OpenFlow 1.4 bundle control messages, which | |
1326 | makes it possible to stream the included commands without explicit | |
1327 | OpenFlow barriers, which are otherwise used after each flow table | |
1328 | modification command. This may make large modifications execute | |
1329 | faster as a bundle. | |
1330 | .IP \(bu | |
1331 | Bundles require OpenFlow 1.4 or higher. An explicit \fB-O | |
1332 | OpenFlow14\fR option is not needed, but you may need to enable | |
1333 | OpenFlow 1.4 support for OVS by setting the OVSDB \fIprotocols\fR | |
1334 | column in the \fIbridge\fR table. | |
1335 | .RE | |
1336 | . | |
1337 | .so lib/ofp-version.man | |
1338 | . | |
1339 | .IP "\fB\-F \fIformat\fR[\fB,\fIformat\fR...]" | |
1340 | .IQ "\fB\-\-flow\-format=\fIformat\fR[\fB,\fIformat\fR...]" | |
1341 | \fBovs\-ofctl\fR supports the following individual flow formats, any | |
1342 | number of which may be listed as \fIformat\fR: | |
1343 | .RS | |
1344 | .IP "\fBOpenFlow10\-table_id\fR" | |
1345 | This is the standard OpenFlow 1.0 flow format. All OpenFlow switches | |
1346 | and all versions of Open vSwitch support this flow format. | |
1347 | . | |
1348 | .IP "\fBOpenFlow10+table_id\fR" | |
1349 | This is the standard OpenFlow 1.0 flow format plus a Nicira extension | |
1350 | that allows \fBovs\-ofctl\fR to specify the flow table in which a | |
1351 | particular flow should be placed. Open vSwitch 1.2 and later supports | |
1352 | this flow format. | |
1353 | . | |
1354 | .IP "\fBNXM\-table_id\fR (Nicira Extended Match)" | |
1355 | This Nicira extension to OpenFlow is flexible and extensible. It | |
1356 | supports all of the Nicira flow extensions, such as \fBtun_id\fR and | |
1357 | registers. Open vSwitch 1.1 and later supports this flow format. | |
1358 | . | |
1359 | .IP "\fBNXM+table_id\fR (Nicira Extended Match)" | |
1360 | This combines Nicira Extended match with the ability to place a flow | |
1361 | in a specific table. Open vSwitch 1.2 and later supports this flow | |
1362 | format. | |
1363 | . | |
1364 | .IP "\fBOXM-OpenFlow12\fR" | |
1365 | .IQ "\fBOXM-OpenFlow13\fR" | |
1366 | .IQ "\fBOXM-OpenFlow14\fR" | |
1367 | .IQ "\fBOXM-OpenFlow15\fR" | |
1368 | .IQ "\fBOXM-OpenFlow16\fR" | |
1369 | These are the standard OXM (OpenFlow Extensible Match) flow format in | |
1370 | OpenFlow 1.2 and later. | |
1371 | .RE | |
1372 | . | |
1373 | .IP | |
1374 | \fBovs\-ofctl\fR also supports the following abbreviations for | |
1375 | collections of flow formats: | |
1376 | .RS | |
1377 | .IP "\fBany\fR" | |
1378 | Any supported flow format. | |
1379 | .IP "\fBOpenFlow10\fR" | |
1380 | \fBOpenFlow10\-table_id\fR or \fBOpenFlow10+table_id\fR. | |
1381 | .IP "\fBNXM\fR" | |
1382 | \fBNXM\-table_id\fR or \fBNXM+table_id\fR. | |
1383 | .IP "\fBOXM\fR" | |
1384 | \fBOXM-OpenFlow12\fR, \fBOXM-OpenFlow13\fR, or \fBOXM-OpenFlow14\fR. | |
1385 | .RE | |
1386 | . | |
1387 | .IP | |
1388 | For commands that modify the flow table, \fBovs\-ofctl\fR by default | |
1389 | negotiates the most widely supported flow format that supports the | |
1390 | flows being added. For commands that query the flow table, | |
1391 | \fBovs\-ofctl\fR by default uses the most advanced format supported by | |
1392 | the switch. | |
1393 | .IP | |
1394 | This option, where \fIformat\fR is a comma-separated list of one or | |
1395 | more of the formats listed above, limits \fBovs\-ofctl\fR's choice of | |
1396 | flow format. If a command cannot work as requested using one of the | |
1397 | specified flow formats, \fBovs\-ofctl\fR will report a fatal error. | |
1398 | . | |
1399 | .IP "\fB\-P \fIformat\fR" | |
1400 | .IQ "\fB\-\-packet\-in\-format=\fIformat\fR" | |
1401 | \fBovs\-ofctl\fR supports the following ``packet-in'' formats, in order of | |
1402 | increasing capability: | |
1403 | .RS | |
1404 | .IP "\fBstandard\fR" | |
1405 | This uses the \fBOFPT_PACKET_IN\fR message, the standard ``packet-in'' | |
1406 | message for any given OpenFlow version. Every OpenFlow switch that | |
1407 | supports a given OpenFlow version supports this format. | |
1408 | . | |
1409 | .IP "\fBnxt_packet_in\fR" | |
1410 | This uses the \fBNXT_PACKET_IN\fR message, which adds many of the | |
1411 | capabilities of the OpenFlow 1.1 and later ``packet-in'' messages | |
1412 | before those OpenFlow versions were available in Open vSwitch. Open | |
1413 | vSwitch 1.1 and later support this format. Only Open vSwitch 2.6 and | |
1414 | later, however, support it for OpenFlow 1.1 and later (but there is | |
1415 | little reason to use it with those versions of OpenFlow). | |
1416 | . | |
1417 | .IP "\fBnxt_packet_in2\fR" | |
1418 | This uses the \fBNXT_PACKET_IN2\fR message, which is extensible and | |
1419 | should avoid the need to define new formats later. In particular, | |
1420 | this format supports passing arbitrary user-provided data to a | |
1421 | controller using the \fBuserdata\fB option on the \fBcontroller\fR | |
1422 | action. Open vSwitch 2.6 and later support this format. | |
1423 | . | |
1424 | .RE | |
1425 | .IP | |
1426 | Without this option, \fBovs\-ofctl\fR prefers \fBnxt_packet_in2\fR if | |
1427 | the switch supports it. Otherwise, if OpenFlow 1.0 is in use, | |
1428 | \fBovs\-ofctl\fR prefers \fBnxt_packet_in\fR if the switch supports | |
1429 | it. Otherwise, \fBovs\-ofctl\fR falls back to the \fBstandard\fR | |
1430 | packet-in format. When this option is specified, \fBovs\-ofctl\fR | |
1431 | insists on the selected format. If the switch does not support the | |
1432 | requested format, \fBovs\-ofctl\fR will report a fatal error. | |
1433 | .IP | |
1434 | Before version 2.6, Open vSwitch called \fBstandard\fR format | |
1435 | \fBopenflow10\fR and \fBnxt_packet_in\fR format \fBnxm\fR, and | |
1436 | \fBovs\-ofctl\fR still accepts these names as synonyms. (The name | |
1437 | \fBopenflow10\fR was a misnomer because this format actually varies | |
1438 | from one OpenFlow version to another; it is not consistently OpenFlow | |
1439 | 1.0 format. Similarly, when \fBnxt_packet_in2\fR was introduced, the | |
1440 | name \fBnxm\fR became confusing because it also uses OXM/NXM.) | |
1441 | . | |
1442 | .IP | |
1443 | This option affects only the \fBmonitor\fR command. | |
1444 | . | |
1445 | .IP "\fB\-\-timestamp\fR" | |
1446 | Print a timestamp before each received packet. This option only | |
1447 | affects the \fBmonitor\fR, \fBsnoop\fR, and \fBofp\-parse\-pcap\fR | |
1448 | commands. | |
1449 | . | |
1450 | .IP "\fB\-m\fR" | |
1451 | .IQ "\fB\-\-more\fR" | |
1452 | Increases the verbosity of OpenFlow messages printed and logged by | |
1453 | \fBovs\-ofctl\fR commands. Specify this option more than once to | |
1454 | increase verbosity further. | |
1455 | . | |
1456 | .IP \fB\-\-sort\fR[\fB=\fIfield\fR] | |
1457 | .IQ \fB\-\-rsort\fR[\fB=\fIfield\fR] | |
1458 | Display output sorted by flow \fIfield\fR in ascending | |
1459 | (\fB\-\-sort\fR) or descending (\fB\-\-rsort\fR) order, where | |
1460 | \fIfield\fR is any of the fields that are allowed for matching or | |
1461 | \fBpriority\fR to sort by priority. When \fIfield\fR is omitted, the | |
1462 | output is sorted by priority. Specify these options multiple times to | |
1463 | sort by multiple fields. | |
1464 | .IP | |
1465 | Any given flow will not necessarily specify a value for a given | |
1466 | field. This requires special treatement: | |
1467 | .RS | |
1468 | .IP \(bu | |
1469 | A flow that does not specify any part of a field that is used for sorting is | |
1470 | sorted after all the flows that do specify the field. For example, | |
1471 | \fB\-\-sort=tcp_src\fR will sort all the flows that specify a TCP | |
1472 | source port in ascending order, followed by the flows that do not | |
1473 | specify a TCP source port at all. | |
1474 | .IP \(bu | |
1475 | A flow that only specifies some bits in a field is sorted as if the | |
1476 | wildcarded bits were zero. For example, \fB\-\-sort=nw_src\fR would | |
1477 | sort a flow that specifies \fBnw_src=192.168.0.0/24\fR the same as | |
1478 | \fBnw_src=192.168.0.0\fR. | |
1479 | .RE | |
1480 | .IP | |
1481 | These options currently affect only \fBdump\-flows\fR output. | |
1482 | . | |
1483 | .SS "Daemon Options" | |
1484 | .ds DD \ | |
1485 | \fBovs\-ofctl\fR detaches only when executing the \fBmonitor\fR or \ | |
1486 | \fBsnoop\fR commands. | |
1487 | .so lib/daemon.man | |
1488 | .so lib/unixctl.man | |
1489 | .SS "Public Key Infrastructure Options" | |
1490 | .so lib/ssl.man | |
1491 | .so lib/vlog.man | |
1492 | .so lib/colors.man | |
1493 | .so lib/common.man | |
1494 | . | |
1495 | .SH "RUNTIME MANAGEMENT COMMANDS" | |
1496 | \fBovs\-appctl\fR(8) can send commands to a running \fBovs\-ofctl\fR | |
1497 | process. The supported commands are listed below. | |
1498 | . | |
1499 | .IP "\fBexit\fR" | |
1500 | Causes \fBovs\-ofctl\fR to gracefully terminate. This command applies | |
1501 | only when executing the \fBmonitor\fR or \fBsnoop\fR commands. | |
1502 | . | |
1503 | .IP "\fBofctl/set\-output\-file \fIfile\fR" | |
1504 | Causes all subsequent output to go to \fIfile\fR instead of stderr. | |
1505 | This command applies only when executing the \fBmonitor\fR or | |
1506 | \fBsnoop\fR commands. | |
1507 | . | |
1508 | .IP "\fBofctl/send \fIofmsg\fR..." | |
1509 | Sends each \fIofmsg\fR, specified as a sequence of hex digits that | |
1510 | express an OpenFlow message, on the OpenFlow connection. This command | |
1511 | is useful only when executing the \fBmonitor\fR command. | |
1512 | . | |
1513 | .IP "\fBofctl/packet\-out \fIpacket-out\fR" | |
1514 | Sends an OpenFlow PACKET_OUT message specified in \fBPacket\-Out | |
1515 | Syntax\fR, on the OpenFlow connection. See \fBPacket\-Out Syntax\fR | |
1516 | section for more information. This command is useful only when | |
1517 | executing the \fBmonitor\fR command. | |
1518 | . | |
1519 | .IP "\fBofctl/barrier\fR" | |
1520 | Sends an OpenFlow barrier request on the OpenFlow connection and waits | |
1521 | for a reply. This command is useful only for the \fBmonitor\fR | |
1522 | command. | |
1523 | . | |
1524 | .SH EXAMPLES | |
1525 | . | |
1526 | The following examples assume that \fBovs\-vswitchd\fR has a bridge | |
1527 | named \fBbr0\fR configured. | |
1528 | . | |
1529 | .TP | |
1530 | \fBovs\-ofctl dump\-tables br0\fR | |
1531 | Prints out the switch's table stats. (This is more interesting after | |
1532 | some traffic has passed through.) | |
1533 | . | |
1534 | .TP | |
1535 | \fBovs\-ofctl dump\-flows br0\fR | |
1536 | Prints the flow entries in the switch. | |
1537 | . | |
1538 | .TP | |
1539 | \fBovs\-ofctl add\-flow table=0 actions=learn(table=1,hard_timeout=10, NXM_OF_VLAN_TCI[0..11],output:NXM_OF_IN_PORT[]), resubmit(,1)\fR | |
1540 | \fBovs\-ofctl add\-flow table=1 priority=0 actions=flood\fR | |
1541 | Implements a level 2 MAC learning switch using the learn. | |
1542 | . | |
1543 | .TP | |
1544 | \fBovs\-ofctl add\-flow br0 'table=0,priority=0 actions=load:3->NXM_NX_REG0[0..15],learn(table=0,priority=1,idle_timeout=10,NXM_OF_ETH_SRC[],NXM_OF_VLAN_TCI[0..11],output:NXM_NX_REG0[0..15]),output:2\fR | |
1545 | In this use of a learn action, the first packet from each source MAC | |
1546 | will be sent to port 2. Subsequent packets will be output to port 3, | |
1547 | with an idle timeout of 10 seconds. NXM field names and match field | |
1548 | names are both accepted, e.g. \fBNXM_NX_REG0\fR or \fBreg0\fR for the | |
1549 | first register, and empty brackets may be omitted. | |
1550 | .IP | |
1551 | Additional examples may be found documented as part of related sections. | |
1552 | . | |
1553 | .SH "SEE ALSO" | |
1554 | . | |
1555 | .BR ovs\-fields (7), | |
1556 | .BR ovs\-actions (7), | |
1557 | .BR ovs\-appctl (8), | |
1558 | .BR ovs\-vswitchd (8), | |
1559 | .BR ovs\-vswitchd.conf.db (8) |