]>
Commit | Line | Data |
---|---|---|
a9b4a41a BP |
1 | .\" -*- nroff -*- |
2 | .de IQ | |
3 | . br | |
4 | . ns | |
5 | . IP "\\$1" | |
6 | .. | |
d2cb6c95 | 7 | .TH ovs\-ofctl 8 "@VERSION@" "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. | |
0d8e9638 | 23 | It should work with any OpenFlow switch, not just Open vSwitch. |
a9b4a41a | 24 | . |
064af421 | 25 | .SS "OpenFlow Switch Management Commands" |
a9b4a41a | 26 | .PP |
064af421 BP |
27 | These commands allow \fBovs\-ofctl\fR to monitor and administer an OpenFlow |
28 | switch. It is able to show the current state of a switch, including | |
29 | features, configuration, and table entries. | |
a9b4a41a | 30 | .PP |
064af421 BP |
31 | Most of these commands take an argument that specifies the method for |
32 | connecting to an OpenFlow switch. The following connection methods | |
33 | are supported: | |
a9b4a41a | 34 | . |
064af421 | 35 | .RS |
84ee7bcf BP |
36 | .so lib/vconn-active.man |
37 | . | |
064af421 BP |
38 | .IP "\fIfile\fR" |
39 | This is short for \fBunix:\fIfile\fR, as long as \fIfile\fR does not | |
40 | contain a colon. | |
84ee7bcf | 41 | . |
1a6f1e2a JG |
42 | .IP \fIbridge\fR |
43 | This is short for \fBunix:@RUNDIR@/\fIbridge\fB.mgmt\fR, as long as | |
44 | \fIbridge\fR does not contain a colon. | |
45 | . | |
46 | .IP [\fItype\fB@\fR]\fIdp\fR | |
47 | Attempts to look up the bridge associated with \fIdp\fR and open as | |
48 | above. If \fItype\fR is given, it specifies the datapath provider of | |
49 | \fIdp\fR, otherwise the default provider \fBsystem\fR is assumed. | |
064af421 | 50 | .RE |
a9b4a41a | 51 | . |
064af421 BP |
52 | .TP |
53 | \fBshow \fIswitch\fR | |
54 | Prints to the console information on \fIswitch\fR, including | |
55 | information on its flow tables and ports. | |
a9b4a41a | 56 | . |
064af421 | 57 | .TP |
4e312e69 | 58 | \fBdump\-tables \fIswitch\fR |
064af421 BP |
59 | Prints to the console statistics for each of the flow tables used by |
60 | \fIswitch\fR. | |
5deff5aa AW |
61 | .TP |
62 | \fBdump\-table\-features \fIswitch\fR | |
63 | Prints to the console features for each of the flow tables used by | |
64 | \fIswitch\fR. | |
03c72922 BP |
65 | .TP |
66 | \fBdump\-table\-desc \fIswitch\fR | |
67 | Prints to the console configuration for each of the flow tables used | |
68 | by \fIswitch\fR for OpenFlow 1.4+. | |
4bc938cc BP |
69 | .IP "\fBmod\-table \fIswitch\fR \fItable\fR \fIsetting\fR" |
70 | This command configures flow table settings in \fIswitch\fR for | |
71 | OpenFlow table \fItable\fR, which may be expressed as a number or | |
72 | (unless \fB\-\-no\-names\fR is specified) a name. | |
73 | .IP | |
74 | The available settings depend on | |
82c22d34 BP |
75 | the OpenFlow version in use. In OpenFlow 1.1 and 1.2 (which must be |
76 | enabled with the \fB\-O\fR option) only, \fBmod\-table\fR configures | |
77 | behavior when no flow is found when a packet is looked up in a flow | |
78 | table. The following \fIsetting\fR values are available: | |
c354fcc5 TG |
79 | .RS |
80 | .IP \fBdrop\fR | |
81 | Drop the packet. | |
82 | .IP \fBcontinue\fR | |
83 | Continue to the next table in the pipeline. (This is how an OpenFlow | |
84 | 1.0 switch always handles packets that do not match any flow, in | |
85 | tables other than the last one.) | |
86 | .IP \fBcontroller\fR | |
87 | Send to controller. (This is how an OpenFlow 1.0 switch always | |
88 | handles packets that do not match any flow in the last table.) | |
89 | .RE | |
82c22d34 BP |
90 | .IP |
91 | In OpenFlow 1.4 and later (which must be enabled with the \fB\-O\fR | |
92 | option) only, \fBmod\-table\fR configures the behavior when a | |
93 | controller attempts to add a flow to a flow table that is full. The | |
94 | following \fIsetting\fR values are available: | |
95 | .RS | |
96 | .IP \fBevict\fR | |
97 | Delete some existing flow from the flow table, according to the | |
98 | algorithm described for the \fBFlow_Table\fR table in | |
99 | \fBovs-vswitchd.conf.db\fR(5). | |
100 | .IP \fBnoevict\fR | |
101 | Refuse to add the new flow. (Eviction might still be enabled through | |
de7d3c07 | 102 | the \fBoverflow_policy\fR column in the \fBFlow_Table\fR table |
82c22d34 | 103 | documented in \fBovs-vswitchd.conf.db\fR(5).) |
de7d3c07 SJ |
104 | .IP \fBvacancy:\fIlow\fB,\fIhigh\fR |
105 | Enables sending vacancy events to controllers using \fBTABLE_STATUS\fR | |
106 | messages, based on percentage thresholds \fIlow\fR and \fIhigh\fR. | |
107 | .IP \fBnovacancy\fR | |
108 | Disables vacancy events. | |
82c22d34 | 109 | .RE |
c354fcc5 | 110 | . |
064af421 | 111 | .TP |
4e312e69 | 112 | \fBdump\-ports \fIswitch\fR [\fInetdev\fR] |
abaad8cf JP |
113 | Prints to the console statistics for network devices associated with |
114 | \fIswitch\fR. If \fInetdev\fR is specified, only the statistics | |
115 | associated with that device will be printed. \fInetdev\fR can be an | |
116 | OpenFlow assigned port number or device name, e.g. \fBeth0\fR. | |
a9b4a41a | 117 | . |
70ae4f93 | 118 | .IP "\fBdump\-ports\-desc \fIswitch\fR [\fIport\fR]" |
2be393ed | 119 | Prints to the console detailed information about network devices |
70ae4f93 BP |
120 | associated with \fIswitch\fR. To dump only a specific port, specify |
121 | its number as \fIport\fR. Otherwise, if \fIport\fR is omitted, or if | |
122 | it is specified as \fBANY\fR, then all ports are printed. This is a | |
123 | subset of the information provided by the \fBshow\fR command. | |
124 | .IP | |
125 | If the connection to \fIswitch\fR negotiates OpenFlow 1.0, 1.2, or | |
126 | 1.2, this command uses an OpenFlow extension only implemented in Open | |
127 | vSwitch (version 1.7 and later). | |
128 | .IP | |
129 | Only OpenFlow 1.5 and later support dumping a specific port. Earlier | |
130 | versions of OpenFlow always dump all ports. | |
2be393ed | 131 | . |
c6100d92 BP |
132 | .IP "\fBmod\-port \fIswitch\fR \fIport\fR \fIaction\fR" |
133 | Modify characteristics of port \fBport\fR in \fIswitch\fR. \fIport\fR | |
50f96b10 BP |
134 | may be an OpenFlow port number or name (unless \fB\-\-no\-names\fR is |
135 | specified) or the keyword \fBLOCAL\fR (the | |
c6100d92 BP |
136 | preferred way to refer to the OpenFlow local port). The \fIaction\fR |
137 | may be any one of the following: | |
a9b4a41a | 138 | . |
064af421 | 139 | .RS |
28124950 BP |
140 | .IQ \fBup\fR |
141 | .IQ \fBdown\fR | |
0b2c7e69 BP |
142 | Enable or disable the interface. This is equivalent to \fBip |
143 | link set up\fR or \fBip link set down\fR on a Unix system. | |
28124950 BP |
144 | . |
145 | .IP \fBstp\fR | |
146 | .IQ \fBno\-stp\fR | |
147 | Enable or disable 802.1D spanning tree protocol (STP) on the | |
148 | interface. OpenFlow implementations that don't support STP will | |
149 | refuse to enable it. | |
150 | . | |
151 | .IP \fBreceive\fR | |
152 | .IQ \fBno\-receive\fR | |
153 | .IQ \fBreceive\-stp\fR | |
154 | .IQ \fBno\-receive\-stp\fR | |
155 | Enable or disable OpenFlow processing of packets received on this | |
156 | interface. When packet processing is disabled, packets will be | |
157 | dropped instead of being processed through the OpenFlow table. The | |
158 | \fBreceive\fR or \fBno\-receive\fR setting applies to all packets | |
159 | except 802.1D spanning tree packets, which are separately controlled | |
160 | by \fBreceive\-stp\fR or \fBno\-receive\-stp\fR. | |
a9b4a41a | 161 | . |
451256f6 | 162 | .IP \fBforward\fR |
28124950 BP |
163 | .IQ \fBno\-forward\fR |
164 | Allow or disallow forwarding of traffic to this interface. By | |
165 | default, forwarding is enabled. | |
451256f6 | 166 | . |
064af421 | 167 | .IP \fBflood\fR |
28124950 BP |
168 | .IQ \fBno\-flood\fR |
169 | Controls whether an OpenFlow \fBflood\fR action will send traffic out | |
170 | this interface. By default, flooding is enabled. Disabling flooding | |
171 | is primarily useful to prevent loops when a spanning tree protocol is | |
172 | not in use. | |
173 | . | |
174 | .IP \fBpacket\-in\fR | |
175 | .IQ \fBno\-packet\-in\fR | |
176 | Controls whether packets received on this interface that do not match | |
177 | a flow table entry generate a ``packet in'' message to the OpenFlow | |
178 | controller. By default, ``packet in'' messages are enabled. | |
064af421 | 179 | .RE |
28124950 BP |
180 | .IP |
181 | The \fBshow\fR command displays (among other information) the | |
182 | configuration that \fBmod\-port\fR changes. | |
a9b4a41a | 183 | . |
7257b535 BP |
184 | .IP "\fBget\-frags \fIswitch\fR" |
185 | Prints \fIswitch\fR's fragment handling mode. See \fBset\-frags\fR, | |
186 | below, for a description of each fragment handling mode. | |
187 | .IP | |
188 | The \fBshow\fR command also prints the fragment handling mode among | |
189 | its other output. | |
190 | . | |
191 | .IP "\fBset\-frags \fIswitch frag_mode\fR" | |
192 | Configures \fIswitch\fR's treatment of IPv4 and IPv6 fragments. The | |
193 | choices for \fIfrag_mode\fR are: | |
194 | .RS | |
195 | .IP "\fBnormal\fR" | |
196 | Fragments pass through the flow table like non-fragmented packets. | |
197 | The TCP ports, UDP ports, and ICMP type and code fields are always set | |
198 | to 0, even for fragments where that information would otherwise be | |
199 | available (fragments with offset 0). This is the default fragment | |
200 | handling mode for an OpenFlow switch. | |
201 | .IP "\fBdrop\fR" | |
202 | Fragments are dropped without passing through the flow table. | |
203 | .IP "\fBreassemble\fR" | |
204 | The switch reassembles fragments into full IP packets before passing | |
205 | them through the flow table. Open vSwitch does not implement this | |
206 | fragment handling mode. | |
207 | .IP "\fBnx\-match\fR" | |
208 | Fragments pass through the flow table like non-fragmented packets. | |
209 | The TCP ports, UDP ports, and ICMP type and code fields are available | |
210 | for matching for fragments with offset 0, and set to 0 in fragments | |
211 | with nonzero offset. This mode is a Nicira extension. | |
212 | .RE | |
213 | .IP | |
214 | See the description of \fBip_frag\fR, below, for a way to match on | |
215 | whether a packet is a fragment and on its fragment offset. | |
216 | . | |
064af421 | 217 | .TP |
4e312e69 | 218 | \fBdump\-flows \fIswitch \fR[\fIflows\fR] |
064af421 BP |
219 | Prints to the console all flow entries in \fIswitch\fR's |
220 | tables that match \fIflows\fR. If \fIflows\fR is omitted, all flows | |
221 | in the switch are retrieved. See \fBFlow Syntax\fR, below, for the | |
bdcc5925 | 222 | syntax of \fIflows\fR. The output format is described in |
064af421 | 223 | \fBTable Entry Output\fR. |
a9b4a41a | 224 | . |
bdcc5925 BP |
225 | .IP |
226 | By default, \fBovs\-ofctl\fR prints flow entries in the same order | |
227 | that the switch sends them, which is unlikely to be intuitive or | |
1b3758c3 BP |
228 | consistent. Use \fB\-\-sort\fR and \fB\-\-rsort\fR to control display |
229 | order. The \fB\-\-names\fR/\fB\-\-no\-names\fR and | |
230 | \fB\-\-stats\fR/\fB\-\-no\-stats\fR options also affect output | |
231 | formatting. See the descriptions of these options, under | |
232 | \fBOPTIONS\fR below, for more information | |
bdcc5925 | 233 | . |
064af421 | 234 | .TP |
4e312e69 | 235 | \fBdump\-aggregate \fIswitch \fR[\fIflows\fR] |
bdcc5925 | 236 | Prints to the console aggregate statistics for flows in |
064af421 BP |
237 | \fIswitch\fR's tables that match \fIflows\fR. If \fIflows\fR is omitted, |
238 | the statistics are aggregated across all flows in the switch's flow | |
239 | tables. See \fBFlow Syntax\fR, below, for the syntax of \fIflows\fR. | |
3845a3fd | 240 | The output format is described in \fBTable Entry Output\fR. |
a9b4a41a | 241 | . |
d2805da2 BP |
242 | .IP "\fBqueue\-stats \fIswitch \fR[\fIport \fR[\fIqueue\fR]]" |
243 | Prints to the console statistics for the specified \fIqueue\fR on | |
c6100d92 BP |
244 | \fIport\fR within \fIswitch\fR. \fIport\fR can be an OpenFlow port |
245 | number or name, the keyword \fBLOCAL\fR (the preferred way to refer to | |
246 | the OpenFlow local port), or the keyword \fBALL\fR. Either of | |
247 | \fIport\fR or \fIqueue\fR or both may be omitted (or equivalently the | |
248 | keyword \fBALL\fR). If both are omitted, statistics are printed for | |
249 | all queues on all ports. If only \fIqueue\fR is omitted, then | |
250 | statistics are printed for all queues on \fIport\fR; if only | |
251 | \fIport\fR is omitted, then statistics are printed for \fIqueue\fR on | |
252 | every port where it exists. | |
d2805da2 | 253 | . |
e016fb63 BP |
254 | .IP "\fBqueue\-get\-config \fIswitch [\fIport \fR[\fIqueue\fR]]" |
255 | Prints to the console the configuration of \fIqueue\fR on \fIport\fR | |
256 | in \fIswitch\fR. If \fIport\fR is omitted or \fBANY\fR, reports | |
257 | queues for all port. If \fIqueue\fR is omitted or \fBANY\fR, reports | |
258 | all queues. For OpenFlow 1.3 and earlier, the output always includes | |
259 | all queues, ignoring \fIqueue\fR if specified. | |
56085be5 BP |
260 | .IP |
261 | This command has limited usefulness, because ports often have no | |
262 | configured queues and because the OpenFlow protocol provides only very | |
263 | limited information about the configuration of a queue. | |
264 | . | |
56fb20c4 | 265 | .IP "\fBdump\-ipfix\-bridge \fIswitch\fR" |
fb8f22c1 BY |
266 | Prints to the console the statistics of bridge IPFIX for \fIswitch\fR. |
267 | If bridge IPFIX is configured on the \fIswitch\fR, IPFIX statistics | |
268 | can be retrieved. Otherwise, error message will be printed. | |
269 | .IP | |
270 | This command uses an Open vSwitch extension that is only in Open | |
271 | vSwitch 2.6 and later. | |
272 | . | |
56fb20c4 | 273 | .IP "\fBdump\-ipfix\-flow \fIswitch\fR" |
fb8f22c1 BY |
274 | Prints to the console the statistics of flow-based IPFIX for |
275 | \fIswitch\fR. If flow-based IPFIX is configured on the \fIswitch\fR, | |
276 | statistics of all the collector set ids on the \fIswitch\fR will be | |
277 | printed. Otherwise, print error message. | |
278 | .IP | |
56fb20c4 | 279 | Refer to \fBovs\-vswitchd.conf.db\fR(5) for more details on configuring |
fb8f22c1 BY |
280 | flow based IPFIX and collector set ids. |
281 | .IP | |
282 | This command uses an Open vSwitch extension that is only in Open | |
283 | vSwitch 2.6 and later. | |
284 | . | |
2a7c4805 JP |
285 | .IP "\fBct\-flush\-zone \fIswitch zone\fR |
286 | Flushes the connection tracking entries in \fIzone\fR on \fIswitch\fR. | |
287 | .IP | |
288 | This command uses an Open vSwitch extension that is only in Open | |
289 | vSwitch 2.6 and later. | |
290 | . | |
4989c59f BP |
291 | .SS "OpenFlow Switch Flow Table Commands" |
292 | . | |
293 | These commands manage the flow table in an OpenFlow switch. In each | |
294 | case, \fIflow\fR specifies a flow entry in the format described in | |
db5076ee JR |
295 | \fBFlow Syntax\fR, below, \fIfile\fR is a text file that contains zero |
296 | or more flows in the same syntax, one per line, and the optional | |
39c94593 JR |
297 | \fB\-\-bundle\fR option operates the command as a single atomic |
298 | transation, see option \fB\-\-bundle\fR, below. | |
db5076ee JR |
299 | . |
300 | .IP "[\fB\-\-bundle\fR] \fBadd\-flow \fIswitch flow\fR" | |
301 | .IQ "[\fB\-\-bundle\fR] \fBadd\-flow \fIswitch \fB\- < \fIfile\fR" | |
302 | .IQ "[\fB\-\-bundle\fR] \fBadd\-flows \fIswitch file\fR" | |
4989c59f BP |
303 | Add each flow entry to \fIswitch\fR's tables. |
304 | . | |
db5076ee JR |
305 | Each flow specification (e.g., each line in \fIfile\fR) may start with |
306 | \fBadd\fR, \fBmodify\fR, \fBdelete\fR, \fBmodify_strict\fR, or | |
307 | \fBdelete_strict\fR keyword to specify whether a flow is to be added, | |
308 | modified, or deleted, and whether the modify or delete is strict or | |
309 | not. For backwards compatibility a flow specification without one of | |
310 | these keywords is treated as a flow add. All flow mods are executed | |
311 | in the order specified. | |
312 | . | |
313 | .IP "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBmod\-flows \fIswitch flow\fR" | |
314 | .IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBmod\-flows \fIswitch \fB\- < \fIfile\fR" | |
4989c59f BP |
315 | Modify the actions in entries from \fIswitch\fR's tables that match |
316 | the specified flows. With \fB\-\-strict\fR, wildcards are not treated | |
317 | as active for matching purposes. | |
318 | . | |
db5076ee JR |
319 | .IP "[\fB\-\-bundle\fR] \fBdel\-flows \fIswitch\fR" |
320 | .IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fR[\fIflow\fR]" | |
321 | .IQ "[\fB\-\-bundle\fR] [\fB\-\-strict\fR] \fBdel\-flows \fIswitch \fB\- < \fIfile\fR" | |
4989c59f BP |
322 | Deletes entries from \fIswitch\fR's flow table. With only a |
323 | \fIswitch\fR argument, deletes all flows. Otherwise, deletes flow | |
324 | entries that match the specified flows. With \fB\-\-strict\fR, | |
325 | wildcards are not treated as active for matching purposes. | |
a9b4a41a | 326 | . |
db5076ee | 327 | .IP "[\fB\-\-bundle\fR] [\fB\-\-readd\fR] \fBreplace\-flows \fIswitch file\fR" |
0199c526 BP |
328 | Reads flow entries from \fIfile\fR (or \fBstdin\fR if \fIfile\fR is |
329 | \fB\-\fR) and queries the flow table from \fIswitch\fR. Then it fixes | |
330 | up any differences, adding flows from \fIflow\fR that are missing on | |
331 | \fIswitch\fR, deleting flows from \fIswitch\fR that are not in | |
332 | \fIfile\fR, and updating flows in \fIswitch\fR whose actions, cookie, | |
333 | or timeouts differ in \fIfile\fR. | |
334 | . | |
c4ea79bf BP |
335 | .IP |
336 | With \fB\-\-readd\fR, \fBovs\-ofctl\fR adds all the flows from | |
337 | \fIfile\fR, even those that exist with the same actions, cookie, and | |
b6dc6b93 BP |
338 | timeout in \fIswitch\fR. In OpenFlow 1.0 and 1.1, re-adding a flow |
339 | always resets the flow's packet and byte counters to 0, and in | |
340 | OpenFlow 1.2 and later, it does so only if the \fBreset_counts\fR flag | |
341 | is set. | |
c4ea79bf | 342 | . |
0199c526 BP |
343 | .IP "\fBdiff\-flows \fIsource1 source2\fR" |
344 | Reads flow entries from \fIsource1\fR and \fIsource2\fR and prints the | |
345 | differences. A flow that is in \fIsource1\fR but not in \fIsource2\fR | |
346 | is printed preceded by a \fB\-\fR, and a flow that is in \fIsource2\fR | |
347 | but not in \fIsource1\fR is printed preceded by a \fB+\fR. If a flow | |
348 | exists in both \fIsource1\fR and \fIsource2\fR with different actions, | |
349 | cookie, or timeouts, then both versions are printed preceded by | |
350 | \fB\-\fR and \fB+\fR, respectively. | |
351 | .IP | |
352 | \fIsource1\fR and \fIsource2\fR may each name a file or a switch. If | |
353 | a name begins with \fB/\fR or \fB.\fR, then it is considered to be a | |
354 | file name. A name that contains \fB:\fR is considered to be a switch. | |
355 | Otherwise, it is a file if a file by that name exists, a switch if | |
356 | not. | |
357 | .IP | |
358 | For this command, an exit status of 0 means that no differences were | |
359 | found, 1 means that an error occurred, and 2 means that some | |
360 | differences were found. | |
361 | . | |
6dd3c787 JR |
362 | .IP "\fBpacket\-out \fIswitch\fR \fIpacket-out\fR" |
363 | Connects to \fIswitch\fR and instructs it to execute the | |
364 | \fIpacket-out\fR OpenFlow message, specified as defined in | |
365 | \fBPacket\-Out Syntax\fR section. | |
0c3d5fc8 | 366 | . |
7b809df9 | 367 | .SS "Group Table Commands" |
7395c052 NZ |
368 | . |
369 | These commands manage the group table in an OpenFlow switch. In each | |
370 | case, \fIgroup\fR specifies a group entry in the format described in | |
371 | \fBGroup Syntax\fR, below, and \fIfile\fR is a text file that contains | |
25070e04 JR |
372 | zero or more groups in the same syntax, one per line, and the optional |
373 | \fB\-\-bundle\fR option operates the command as a single atomic | |
374 | transation, see option \fB\-\-bundle\fR, below. | |
481bde49 | 375 | .PP |
7b809df9 BP |
376 | The group commands work only with switches that support OpenFlow 1.1 |
377 | or later or the Open vSwitch group extensions to OpenFlow 1.0 (added | |
378 | in Open vSwitch 2.9.90). For OpenFlow 1.1 or later, it is necessary | |
379 | to explicitly enable these protocol versions in \fBovs\-ofctl\fR | |
380 | (using \fB\-O\fR). For more information, see ``Q: What versions of | |
381 | OpenFlow does Open vSwitch support?'' in the Open vSwitch FAQ. | |
481bde49 | 382 | . |
25070e04 JR |
383 | .IP "[\fB\-\-bundle\fR] \fBadd\-group \fIswitch group\fR" |
384 | .IQ "[\fB\-\-bundle\fR] \fBadd\-group \fIswitch \fB\- < \fIfile\fR" | |
385 | .IQ "[\fB\-\-bundle\fR] \fBadd\-groups \fIswitch file\fR" | |
7395c052 NZ |
386 | Add each group entry to \fIswitch\fR's tables. |
387 | . | |
25070e04 JR |
388 | Each group specification (e.g., each line in \fIfile\fR) may start |
389 | with \fBadd\fR, \fBmodify\fR, \fBadd_or_mod\fR, \fBdelete\fR, | |
390 | \fBinsert_bucket\fR, or \fBremove_bucket\fR keyword to specify whether | |
391 | a flow is to be added, modified, or deleted, or whether a group bucket | |
392 | is to be added or removed. For backwards compatibility a group | |
393 | specification without one of these keywords is treated as a group add. | |
394 | All group mods are executed in the order specified. | |
395 | . | |
396 | .IP "[\fB\-\-bundle\fR] [\fB\-\-may\-create\fR] \fBmod\-group \fIswitch group\fR" | |
397 | .IQ "[\fB\-\-bundle\fR] [\fB\-\-may\-create\fR] \fBmod\-group \fIswitch \fB\- < \fIfile\fR" | |
7395c052 | 398 | Modify the action buckets in entries from \fIswitch\fR's tables for |
88b87a36 JS |
399 | each group entry. If a specified group does not already exist, then |
400 | without \fB\-\-may\-create\fR, this command has no effect; with | |
401 | \fB\-\-may\-create\fR, it creates a new group. The | |
402 | \fB\-\-may\-create\fR option uses an Open vSwitch extension to | |
403 | OpenFlow only implemented in Open vSwitch 2.6 and later. | |
7395c052 | 404 | . |
25070e04 JR |
405 | .IP "[\fB\-\-bundle\fR] \fBdel\-groups \fIswitch\fR" |
406 | .IQ "[\fB\-\-bundle\fR] \fBdel\-groups \fIswitch \fR[\fIgroup\fR]" | |
407 | .IQ "[\fB\-\-bundle\fR] \fBdel\-groups \fIswitch \fB\- < \fIfile\fR" | |
7395c052 NZ |
408 | Deletes entries from \fIswitch\fR's group table. With only a |
409 | \fIswitch\fR argument, deletes all groups. Otherwise, deletes the group | |
410 | for each group entry. | |
411 | . | |
25070e04 JR |
412 | .IP "[\fB\-\-bundle\fR] \fBinsert\-buckets \fIswitch group\fR" |
413 | .IQ "[\fB\-\-bundle\fR] \fBinsert\-buckets \fIswitch \fB\- < \fIfile\fR" | |
bdbb8426 SH |
414 | Add buckets to an existing group present in the \fIswitch\fR's group table. |
415 | If no \fIcommand_bucket_id\fR is present in the group specification then all | |
416 | buckets of the group are removed. | |
417 | . | |
25070e04 JR |
418 | .IP "[\fB\-\-bundle\fR] \fBremove\-buckets \fIswitch group\fR" |
419 | .IQ "[\fB\-\-bundle\fR] \fBremove\-buckets \fIswitch \fB\- < \fIfile\fR" | |
bdbb8426 SH |
420 | Remove buckets to an existing group present in the \fIswitch\fR's group table. |
421 | If no \fIcommand_bucket_id\fR is present in the group specification then all | |
422 | buckets of the group are removed. | |
423 | . | |
481bde49 JP |
424 | .IP "\fBdump\-groups \fIswitch\fR [\fIgroup\fR]" |
425 | Prints group entries in \fIswitch\fR's tables to console. To dump | |
426 | only a specific group, specify its number as \fIgroup\fR. Otherwise, | |
427 | if \fIgroup\fR is omitted, or if it is specified as \fBALL\fR, then | |
428 | all groups are printed. | |
429 | .IP | |
430 | Only OpenFlow 1.5 and later support dumping a specific group. Earlier | |
431 | versions of OpenFlow always dump all groups. | |
432 | . | |
433 | .IP "\fBdump\-group\-features \fIswitch" | |
434 | Prints to the console the group features of the \fIswitch\fR. | |
435 | . | |
436 | .IP "\fBdump\-group\-stats \fIswitch \fR[\fIgroup\fR]" | |
437 | Prints to the console statistics for the specified \fIgroup\fR in | |
438 | \fIswitch\fR's tables. If \fIgroup\fR is omitted then statistics for all | |
439 | groups are printed. | |
440 | . | |
441 | .SS "OpenFlow 1.3+ Switch Meter Table Commands" | |
442 | . | |
443 | These commands manage the meter table in an OpenFlow switch. In each | |
444 | case, \fImeter\fR specifies a meter entry in the format described in | |
445 | \fBMeter Syntax\fR, below. | |
446 | . | |
447 | .PP | |
448 | OpenFlow 1.3 introduced support for meters, so these commands only work | |
449 | with switches that support OpenFlow 1.3 or later. It is necessary to | |
450 | explicitly enable these protocol versions in \fBovs\-ofctl\fR (using | |
451 | \fB\-O\fR) and in the switch itself (with the \fBprotocols\fR column in | |
452 | the \fBBridge\fR table). For more information, see ``Q: What versions | |
453 | of OpenFlow does Open vSwitch support?'' in the Open vSwitch FAQ. | |
454 | . | |
455 | .IP "\fBadd\-meter \fIswitch meter\fR" | |
456 | Add a meter entry to \fIswitch\fR's tables. The \fImeter\fR syntax is | |
457 | described in section \fBMeter Syntax\fR, below. | |
458 | . | |
459 | .IP "\fBmod\-meter \fIswitch meter\fR" | |
460 | Modify an existing meter. | |
461 | . | |
04f803fd JP |
462 | .IP "\fBdel\-meters \fIswitch\fR [\fImeter\fR]" |
463 | Delete entries from \fIswitch\fR's meter table. To delete only a | |
464 | specific meter, specify its number as \fImeter\fR. Otherwise, if | |
465 | \fImeter\fR is omitted, or if it is specified as \fBall\fR, then all | |
466 | meters are deleted. | |
467 | . | |
468 | .IP "\fBdump\-meters \fIswitch\fR [\fImeter\fR]" | |
469 | Print entries from \fIswitch\fR's meter table. To print only a | |
470 | specific meter, specify its number as \fImeter\fR. Otherwise, if | |
471 | \fImeter\fR is omitted, or if it is specified as \fBall\fR, then all | |
472 | meters are printed. | |
481bde49 JP |
473 | . |
474 | .IP "\fBmeter\-stats \fIswitch\fR [\fImeter\fR]" | |
475 | Print meter statistics. \fImeter\fR can specify a single meter with | |
476 | syntax \fBmeter=\fIid\fR, or all meters with syntax \fBmeter=all\fR. | |
477 | . | |
478 | .IP "\fBmeter\-features \fIswitch\fR" | |
479 | Print meter features. | |
480 | . | |
25070e04 JR |
481 | .SS OpenFlow Switch Bundle Command |
482 | . | |
483 | Transactional updates to both flow and group tables can be made with | |
484 | the \fBbundle\fR command. \fIfile\fR is a text file that contains | |
6dd3c787 JR |
485 | zero or more flow mods, group mods, or packet-outs in \fBFlow |
486 | Syntax\fR, \fBGroup Syntax\fR, or \fBPacket\-Out Syntax\fR, each line | |
487 | preceded by \fBflow\fR, \fBgroup\fR, or \fBpacket\-out\fR keyword, | |
488 | correspondingly. The \fBflow\fR keyword may be optionally followed by | |
489 | one of the keywords \fBadd\fR, \fBmodify\fR, \fBmodify_strict\fR, | |
25070e04 JR |
490 | \fBdelete\fR, or \fBdelete_strict\fR, of which the \fBadd\fR is |
491 | assumed if a bare \fBflow\fR is given. Similarly, the \fBgroup\fR | |
492 | keyword may be optionally followed by one of the keywords \fBadd\fR, | |
493 | \fBmodify\fR, \fBadd_or_mod\fR, \fBdelete\fR, \fBinsert_bucket\fR, or | |
494 | \fBremove_bucket\fR, of which the \fBadd\fR is assumed if a bare | |
495 | \fBgroup\fR is given. | |
496 | . | |
497 | .IP "\fBbundle \fIswitch file\fR" | |
498 | Execute all flow and group mods in \fIfile\fR as a single atomic | |
499 | transaction against \fIswitch\fR's tables. All bundled mods are | |
500 | executed in the order specified. | |
501 | . | |
4e548ad9 | 502 | .SS "OpenFlow Switch Tunnel TLV Table Commands" |
6159c531 | 503 | . |
4e548ad9 ML |
504 | Open vSwitch maintains a mapping table between tunnel option TLVs (defined |
505 | by <class, type, length>) and NXM fields \fBtun_metadata\fIn\fR, | |
1e71b944 | 506 | where \fIn\fR ranges from 0 to 63, that can be operated on for the |
4e548ad9 ML |
507 | purposes of matches, actions, etc. This TLV table can be used for |
508 | Geneve option TLVs or other protocols with options in same TLV format | |
509 | as Geneve options. This mapping must be explicitly specified by the user | |
510 | through the following commands. | |
6159c531 | 511 | |
4e548ad9 | 512 | A TLV mapping is specified with the syntax |
1e71b944 BP |
513 | \fB{class=\fIclass\fB,type=\fItype\fB,len=\fIlength\fB}->tun_metadata\fIn\fR. |
514 | When an option mapping exists for a given \fBtun_metadata\fIn\fR, | |
515 | matching on the defined field becomes possible, e.g.: | |
516 | ||
517 | .RS | |
4e548ad9 | 518 | ovs-ofctl add-tlv-map br0 "{class=0xffff,type=0,len=4}->tun_metadata0" |
1e71b944 BP |
519 | .PP |
520 | ovs-ofctl add-flow br0 tun_metadata0=1234,actions=controller | |
521 | .RE | |
522 | ||
523 | A mapping should not be changed while it is in active | |
524 | use by a flow. The result of doing so is undefined. | |
6159c531 JG |
525 | |
526 | These commands are Nicira extensions to OpenFlow and require Open vSwitch | |
527 | 2.5 or later. | |
528 | ||
b8e2f655 | 529 | .IP "\fBadd\-tlv\-map \fIswitch option\fR[\fB,\fIoption\fR]..." |
1e71b944 | 530 | Add each \fIoption\fR to \fIswitch\fR's tables. Duplicate fields are |
6159c531 JG |
531 | rejected. |
532 | . | |
b8e2f655 | 533 | .IP "\fBdel\-tlv\-map \fIswitch \fR[\fIoption\fR[\fB,\fIoption\fR]]..." |
4e548ad9 | 534 | Delete each \fIoption\fR from \fIswitch\fR's table, or all option TLV |
1e71b944 BP |
535 | mapping if no \fIoption\fR is specified. |
536 | Fields that aren't mapped are ignored. | |
6159c531 | 537 | . |
b8e2f655 | 538 | .IP "\fBdump\-tlv\-map \fIswitch\fR" |
6159c531 JG |
539 | Show the currently mapped fields in the switch's option table as well |
540 | as switch capabilities. | |
541 | . | |
4989c59f BP |
542 | .SS "OpenFlow Switch Monitoring Commands" |
543 | . | |
0caf6bde BP |
544 | .IP "\fBsnoop \fIswitch\fR" |
545 | Connects to \fIswitch\fR and prints to the console all OpenFlow | |
546 | messages received. Unlike other \fBovs\-ofctl\fR commands, if | |
547 | \fIswitch\fR is the name of a bridge, then the \fBsnoop\fR command | |
548 | connects to a Unix domain socket named | |
421e818c | 549 | \fB@RUNDIR@/\fIswitch\fB.snoop\fR. \fBovs\-vswitchd\fR listens on |
0caf6bde BP |
550 | such a socket for each bridge and sends to it all of the OpenFlow |
551 | messages sent to or received from its configured OpenFlow controller. | |
552 | Thus, this command can be used to view OpenFlow protocol activity | |
553 | between a switch and its controller. | |
554 | .IP | |
555 | When a switch has more than one controller configured, only the | |
e2bfacb6 BP |
556 | traffic to and from a single controller is output. If none of the |
557 | controllers is configured as a master or a slave (using a Nicira | |
70d0aed3 BP |
558 | extension to OpenFlow 1.0 or 1.1, or a standard request in OpenFlow |
559 | 1.2 or later), then a controller is chosen arbitrarily among | |
e2bfacb6 BP |
560 | them. If there is a master controller, it is chosen; otherwise, if |
561 | there are any controllers that are not masters or slaves, one is | |
562 | chosen arbitrarily; otherwise, a slave controller is chosen | |
563 | arbitrarily. This choice is made once at connection time and does not | |
564 | change as controllers reconfigure their roles. | |
565 | .IP | |
566 | If a switch has no controller configured, or if | |
0caf6bde BP |
567 | the configured controller is disconnected, no traffic is sent, so |
568 | monitoring will not show any traffic. | |
569 | . | |
2b07c8b1 | 570 | .IP "\fBmonitor \fIswitch\fR [\fImiss-len\fR] [\fBinvalid_ttl\fR] [\fBwatch:\fR[\fIspec\fR...]]" |
064af421 | 571 | Connects to \fIswitch\fR and prints to the console all OpenFlow |
045b2e5c BP |
572 | messages received. Usually, \fIswitch\fR should specify the name of a |
573 | bridge in the \fBovs\-vswitchd\fR database. | |
a9b4a41a | 574 | .IP |
064af421 BP |
575 | If \fImiss-len\fR is provided, \fBovs\-ofctl\fR sends an OpenFlow ``set |
576 | configuration'' message at connection setup time that requests | |
0caf6bde BP |
577 | \fImiss-len\fR bytes of each packet that misses the flow table. Open vSwitch |
578 | does not send these and other asynchronous messages to an | |
064af421 | 579 | \fBovs\-ofctl monitor\fR client connection unless a nonzero value is |
0caf6bde BP |
580 | specified on this argument. (Thus, if \fImiss\-len\fR is not |
581 | specified, very little traffic will ordinarily be printed.) | |
a9b4a41a | 582 | .IP |
f0fd1a17 PS |
583 | If \fBinvalid_ttl\fR is passed, \fBovs\-ofctl\fR sends an OpenFlow ``set |
584 | configuration'' message at connection setup time that requests | |
5484c47a BP |
585 | \fBINVALID_TTL_TO_CONTROLLER\fR, so that \fBovs\-ofctl monitor\fR can |
586 | receive ``packet-in'' messages when TTL reaches zero on \fBdec_ttl\fR action. | |
ad99e2ed BP |
587 | Only OpenFlow 1.1 and 1.2 support \fBinvalid_ttl\fR; Open vSwitch also |
588 | implements it for OpenFlow 1.0 as an extension. | |
f0fd1a17 | 589 | .IP |
2b07c8b1 BP |
590 | \fBwatch:\fR[\fB\fIspec\fR...] causes \fBovs\-ofctl\fR to send a |
591 | ``monitor request'' Nicira extension message to the switch at | |
592 | connection setup time. This message causes the switch to send | |
593 | information about flow table changes as they occur. The following | |
594 | comma-separated \fIspec\fR syntax is available: | |
595 | .RS | |
596 | .IP "\fB!initial\fR" | |
597 | Do not report the switch's initial flow table contents. | |
598 | .IP "\fB!add\fR" | |
599 | Do not report newly added flows. | |
600 | .IP "\fB!delete\fR" | |
601 | Do not report deleted flows. | |
602 | .IP "\fB!modify\fR" | |
603 | Do not report modifications to existing flows. | |
604 | .IP "\fB!own\fR" | |
605 | Abbreviate changes made to the flow table by \fBovs\-ofctl\fR's own | |
606 | connection to the switch. (These could only occur using the | |
607 | \fBofctl/send\fR command described below under \fBRUNTIME MANAGEMENT | |
608 | COMMANDS\fR.) | |
609 | .IP "\fB!actions\fR" | |
610 | Do not report actions as part of flow updates. | |
4bc938cc BP |
611 | .IP "\fBtable=\fItable\fR" |
612 | Limits the monitoring to the table with the given \fItable\fR, which | |
613 | may be expressed as a number between 0 and 254 or (unless | |
614 | \fB\-\-no\-names\fR is specified) a name. By default, all tables are | |
615 | monitored. | |
2b07c8b1 | 616 | .IP "\fBout_port=\fIport\fR" |
c6100d92 BP |
617 | If set, only flows that output to \fIport\fR are monitored. The |
618 | \fIport\fR may be an OpenFlow port number or keyword | |
619 | (e.g. \fBLOCAL\fR). | |
2b07c8b1 BP |
620 | .IP "\fIfield\fB=\fIvalue\fR" |
621 | Monitors only flows that have \fIfield\fR specified as the given | |
622 | \fIvalue\fR. Any syntax valid for matching on \fBdump\-flows\fR may | |
623 | be used. | |
624 | .RE | |
625 | .IP | |
064af421 | 626 | This command may be useful for debugging switch or controller |
2b07c8b1 BP |
627 | implementations. With \fBwatch:\fR, it is particularly useful for |
628 | observing how a controller updates flow tables. | |
a9b4a41a | 629 | . |
064af421 | 630 | .SS "OpenFlow Switch and Controller Commands" |
a9b4a41a | 631 | . |
064af421 BP |
632 | The following commands, like those in the previous section, may be |
633 | applied to OpenFlow switches, using any of the connection methods | |
634 | described in that section. Unlike those commands, these may also be | |
635 | applied to OpenFlow controllers. | |
a9b4a41a | 636 | . |
064af421 BP |
637 | .TP |
638 | \fBprobe \fItarget\fR | |
639 | Sends a single OpenFlow echo-request message to \fItarget\fR and waits | |
4e312e69 | 640 | for the response. With the \fB\-t\fR or \fB\-\-timeout\fR option, this |
064af421 BP |
641 | command can test whether an OpenFlow switch or controller is up and |
642 | running. | |
a9b4a41a | 643 | . |
064af421 BP |
644 | .TP |
645 | \fBping \fItarget \fR[\fIn\fR] | |
646 | Sends a series of 10 echo request packets to \fItarget\fR and times | |
647 | each reply. The echo request packets consist of an OpenFlow header | |
648 | plus \fIn\fR bytes (default: 64) of randomly generated payload. This | |
649 | measures the latency of individual requests. | |
a9b4a41a | 650 | . |
064af421 BP |
651 | .TP |
652 | \fBbenchmark \fItarget n count\fR | |
653 | Sends \fIcount\fR echo request packets that each consist of an | |
654 | OpenFlow header plus \fIn\fR bytes of payload and waits for each | |
655 | response. Reports the total time required. This is a measure of the | |
656 | maximum bandwidth to \fItarget\fR for round-trips of \fIn\fR-byte | |
657 | messages. | |
a9b4a41a | 658 | . |
1ac0e975 BP |
659 | .SS "Other Commands" |
660 | . | |
661 | .IP "\fBofp\-parse\fR \fIfile\fR" | |
662 | Reads \fIfile\fR (or \fBstdin\fR if \fIfile\fR is \fB\-\fR) as a | |
663 | series of OpenFlow messages in the binary format used on an OpenFlow | |
664 | connection, and prints them to the console. This can be useful for | |
665 | printing OpenFlow messages captured from a TCP stream. | |
666 | . | |
f3dd1419 BP |
667 | .IP "\fBofp\-parse\-pcap\fR \fIfile\fR [\fIport\fR...]" |
668 | Reads \fIfile\fR, which must be in the PCAP format used by network | |
669 | capture tools such as \fBtcpdump\fR or \fBwireshark\fR, extracts all | |
670 | the TCP streams for OpenFlow connections, and prints the OpenFlow | |
671 | messages in those connections in human-readable format on | |
672 | \fBstdout\fR. | |
673 | .IP | |
674 | OpenFlow connections are distinguished by TCP port number. | |
675 | Non-OpenFlow packets are ignored. By default, data on TCP ports 6633 | |
676 | and 6653 are considered to be OpenFlow. Specify one or more | |
677 | \fIport\fR arguments to override the default. | |
678 | .IP | |
679 | This command cannot usefully print SSL encrypted traffic. It does not | |
680 | understand IPv6. | |
681 | . | |
064af421 | 682 | .SS "Flow Syntax" |
a9b4a41a | 683 | .PP |
064af421 | 684 | Some \fBovs\-ofctl\fR commands accept an argument that describes a flow or |
96fee5e0 | 685 | flows. Such flow descriptions comprise a series of |
064af421 BP |
686 | \fIfield\fB=\fIvalue\fR assignments, separated by commas or white |
687 | space. (Embedding spaces into a flow description normally requires | |
688 | quoting to prevent the shell from breaking the description into | |
689 | multiple arguments.) | |
a9b4a41a | 690 | .PP |
0b3f2725 BP |
691 | Flow descriptions should be in \fBnormal form\fR. This means that a |
692 | flow may only specify a value for an L3 field if it also specifies a | |
693 | particular L2 protocol, and that a flow may only specify an L4 field | |
694 | if it also specifies particular L2 and L3 protocol types. For | |
695 | example, if the L2 protocol type \fBdl_type\fR is wildcarded, then L3 | |
696 | fields \fBnw_src\fR, \fBnw_dst\fR, and \fBnw_proto\fR must also be | |
697 | wildcarded. Similarly, if \fBdl_type\fR or \fBnw_proto\fR (the L3 | |
1c58a78b BP |
698 | protocol type) is wildcarded, so must be the L4 fields \fBtcp_dst\fR and |
699 | \fBtcp_src\fR. \fBovs\-ofctl\fR will warn about | |
0b3f2725 BP |
700 | flows not in normal form. |
701 | .PP | |
96fee5e0 BP |
702 | \fBovs\-fields\fR(7) describes the supported fields and how to match |
703 | them. In addition to match fields, commands that operate on flows | |
704 | accept a few additional key-value pairs: | |
71e17a7a | 705 | . |
4bc938cc BP |
706 | .IP \fBtable=\fItable\fR |
707 | For flow dump commands, limits the flows dumped to those in | |
708 | \fItable\fR, which may be expressed as a number between 0 and 255 or | |
709 | (unless \fB\-\-no\-names\fR is specified) a name. If not specified | |
710 | (or if 255 is specified as \fItable\fR), then flows in all tables are | |
0e197060 BP |
711 | dumped. |
712 | . | |
713 | .IP | |
714 | For flow table modification commands, behavior varies based on the | |
715 | OpenFlow version used to connect to the switch: | |
716 | . | |
717 | .RS | |
718 | .IP "OpenFlow 1.0" | |
719 | OpenFlow 1.0 does not support \fBtable\fR for modifying flows. | |
720 | \fBovs\-ofctl\fR will exit with an error if \fBtable\fR (other than | |
721 | \fBtable=255\fR) is specified for a switch that only supports OpenFlow | |
722 | 1.0. | |
723 | .IP | |
724 | In OpenFlow 1.0, the switch chooses the table into which to insert a | |
725 | new flow. The Open vSwitch software switch always chooses table 0. | |
726 | Other Open vSwitch datapaths and other OpenFlow implementations may | |
727 | choose different tables. | |
728 | .IP | |
729 | The OpenFlow 1.0 behavior in Open vSwitch for modifying or removing | |
730 | flows depends on whether \fB\-\-strict\fR is used. Without | |
731 | \fB\-\-strict\fR, the command applies to matching flows in all tables. | |
732 | With \fB\-\-strict\fR, the command will operate on any single matching | |
733 | flow in any table; it will do nothing if there are matches in more | |
734 | than one table. (The distinction between these behaviors only matters | |
735 | if non-OpenFlow 1.0 commands were also used, because OpenFlow 1.0 | |
736 | alone cannot add flows with the same matching criteria to multiple | |
737 | tables.) | |
738 | . | |
739 | .IP "OpenFlow 1.0 with table_id extension" | |
740 | Open vSwitch implements an OpenFlow extension that allows the | |
741 | controller to specify the table on which to operate. \fBovs\-ofctl\fR | |
742 | automatically enables the extension when \fBtable\fR is specified and | |
743 | OpenFlow 1.0 is used. \fBovs\-ofctl\fR automatically detects whether | |
744 | the switch supports the extension. As of this writing, this extension | |
745 | is only known to be implemented by Open vSwitch. | |
746 | . | |
747 | .IP | |
748 | With this extension, \fBovs\-ofctl\fR operates on the requested table | |
749 | when \fBtable\fR is specified, and acts as described for OpenFlow 1.0 | |
750 | above when no \fBtable\fR is specified (or for \fBtable=255\fR). | |
751 | . | |
752 | .IP "OpenFlow 1.1" | |
753 | OpenFlow 1.1 requires flow table modification commands to specify a | |
754 | table. When \fBtable\fR is not specified (or \fBtable=255\fR is | |
755 | specified), \fBovs\-ofctl\fR defaults to table 0. | |
756 | . | |
757 | .IP "OpenFlow 1.2 and later" | |
758 | OpenFlow 1.2 and later allow flow deletion commands, but not other | |
759 | flow table modification commands, to operate on all flow tables, with | |
760 | the behavior described above for OpenFlow 1.0. | |
761 | .RE | |
96fee5e0 BP |
762 | .IP "\fBduration=\fR..." |
763 | .IQ "\fBn_packet=\fR..." | |
764 | .IQ "\fBn_bytes=\fR..." | |
765 | \fBovs\-ofctl\fR ignores assignments to these ``fields'' to allow | |
766 | output from the \fBdump\-flows\fR command to be used as input for | |
767 | other commands that parse flows. | |
2c6d8411 BP |
768 | . |
769 | .PP | |
c821124b BP |
770 | The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands |
771 | require an additional field, which must be the final field specified: | |
a9b4a41a | 772 | . |
d1ba66e9 | 773 | .IP \fBactions=\fR[\fIaction\fR][\fB,\fIaction\fR...]\fR |
064af421 | 774 | Specifies a comma-separated list of actions to take on a packet when the |
d1ba66e9 BP |
775 | flow entry matches. If no \fIaction\fR is specified, then packets |
776 | matching the flow are dropped. The following forms of \fIaction\fR | |
777 | are supported: | |
a9b4a41a | 778 | . |
064af421 | 779 | .RS |
d1ba66e9 BP |
780 | .IP \fIport\fR |
781 | .IQ \fBoutput:\fIport\fR | |
782 | Outputs the packet to OpenFlow port number \fIport\fR. If \fIport\fR | |
783 | is the packet's input port, the packet is not output. | |
c6100d92 BP |
784 | . |
785 | .IP \fBoutput:\fIsrc\fB[\fIstart\fB..\fIend\fB] | |
786 | Outputs the packet to the OpenFlow port number read from \fIsrc\fR, | |
21b2fa61 JR |
787 | which may be an NXM field name, as described above, or a match field name. |
788 | \fBoutput:reg0[16..31]\fR outputs to the OpenFlow port number | |
d1ba66e9 BP |
789 | written in the upper half of register 0. If the port number is the |
790 | packet's input port, the packet is not output. | |
791 | .IP | |
792 | This form of \fBoutput\fR was added in Open vSwitch 1.3.0. This form | |
793 | of \fBoutput\fR uses an OpenFlow extension that is not supported by | |
794 | standard OpenFlow switches. | |
5682f723 | 795 | . |
aaca4fe0 WT |
796 | .IP \fBoutput(port=\fIport\fR\fB,max_len=\fInbytes\fR) |
797 | Outputs the packet to the OpenFlow port number read from \fIport\fR, | |
798 | with maximum packet size set to \fInbytes\fR. \fIport\fR may be OpenFlow | |
799 | port number, \fBlocal\fR, or \fBin_port\fR. Patch port is not supported. | |
800 | Packets larger than \fInbytes\fR will be trimmed to \fInbytes\fR while | |
801 | packets smaller than \fInbytes\fR remains the original size. | |
802 | . | |
b47e67c4 | 803 | .IP \fBgroup:\fIgroup_id\fR |
88c8ca26 BP |
804 | Outputs the packet to the OpenFlow group \fIgroup_id\fR. OpenFlow 1.1 |
805 | introduced support for groups; Open vSwitch 2.6 and later also | |
806 | supports output to groups as an extension to OpenFlow 1.0. See | |
807 | \fBGroup Syntax\fR for more details. | |
b47e67c4 | 808 | . |
064af421 BP |
809 | .IP \fBnormal\fR |
810 | Subjects the packet to the device's normal L2/L3 processing. (This | |
811 | action is not implemented by all OpenFlow switches.) | |
a9b4a41a | 812 | . |
064af421 BP |
813 | .IP \fBflood\fR |
814 | Outputs the packet on all switch physical ports other than the port on | |
815 | which it was received and any ports on which flooding is disabled | |
816 | (typically, these would be ports disabled by the IEEE 802.1D spanning | |
817 | tree protocol). | |
a9b4a41a | 818 | . |
064af421 BP |
819 | .IP \fBall\fR |
820 | Outputs the packet on all switch physical ports other than the port on | |
821 | which it was received. | |
a9b4a41a | 822 | . |
d1ba66e9 BP |
823 | .IP \fBlocal\fR |
824 | Outputs the packet on the ``local port,'' which corresponds to the | |
825 | network device that has the same name as the bridge. | |
826 | . | |
827 | .IP \fBin_port\fR | |
828 | Outputs the packet on the port from which it was received. | |
829 | . | |
a7349929 | 830 | .IP \fBcontroller(\fIkey\fB=\fIvalue\fR...\fB) |
77ab5fd2 | 831 | Sends the packet and its metadata to the OpenFlow controller as a ``packet in'' |
a7349929 BP |
832 | message. The supported key-value pairs are: |
833 | .RS | |
834 | .IP "\fBmax_len=\fInbytes\fR" | |
835 | Limit to \fInbytes\fR the number of bytes of the packet to send to | |
836 | the controller. By default the entire packet is sent. | |
837 | .IP "\fBreason=\fIreason\fR" | |
838 | Specify \fIreason\fR as the reason for sending the message in the | |
839 | ``packet in'' message. The supported reasons are \fBaction\fR (the | |
840 | default), \fBno_match\fR, and \fBinvalid_ttl\fR. | |
841 | .IP "\fBid=\fIcontroller-id\fR" | |
842 | Specify \fIcontroller-id\fR, a 16-bit integer, as the connection ID of | |
843 | the OpenFlow controller or controllers to which the ``packet in'' | |
844 | message should be sent. The default is zero. Zero is also the | |
845 | default connection ID for each controller connection, and a given | |
846 | controller connection will only have a nonzero connection ID if its | |
847 | controller uses the \fBNXT_SET_CONTROLLER_ID\fR Nicira extension to | |
848 | OpenFlow. | |
bdcad671 BP |
849 | .IP "\fBuserdata=\fIhh\fR...\fR" |
850 | Supplies the bytes represented as hex digits \fIhh\fR as additional | |
851 | data to the controller in the packet-in message. Pairs of hex digits | |
852 | may be separated by periods for readability. | |
77ab5fd2 BP |
853 | .IP "\fBpause\fR" |
854 | Causes the switch to freeze the packet's trip through Open vSwitch | |
855 | flow tables and serializes that state into the packet-in message as a | |
856 | ``continuation,'' an additional property in the \fBNXT_PACKET_IN2\fR | |
857 | message. The controller can later send the continuation back to the | |
858 | switch in an \fBNXT_RESUME\fR message, which will restart the packet's | |
859 | traversal from the point where it was interrupted. This permits an | |
860 | OpenFlow controller to interpose on a packet midway through processing | |
861 | in Open vSwitch. | |
bdcad671 | 862 | . |
a7349929 | 863 | .RE |
d1ba66e9 | 864 | .IP |
bdcad671 BP |
865 | If any \fIreason\fR other than \fBaction\fR or any nonzero |
866 | \fIcontroller-id\fR is supplied, Open vSwitch extension | |
867 | \fBNXAST_CONTROLLER\fR, supported by Open vSwitch 1.6 and later, is | |
868 | used. If \fBuserdata\fR is supplied, then \fBNXAST_CONTROLLER2\fR, | |
869 | supported by Open vSwitch 2.6 and later, is used. | |
a7349929 BP |
870 | . |
871 | .IP \fBcontroller\fR | |
872 | .IQ \fBcontroller\fR[\fB:\fInbytes\fR] | |
873 | Shorthand for \fBcontroller()\fR or | |
874 | \fBcontroller(max_len=\fInbytes\fB)\fR, respectively. | |
a9b4a41a | 875 | . |
d1ba66e9 BP |
876 | .IP \fBenqueue(\fIport\fB,\fIqueue\fB)\fR |
877 | Enqueues the packet on the specified \fIqueue\fR within port | |
878 | \fIport\fR, which must be an OpenFlow port number or keyword | |
879 | (e.g. \fBLOCAL\fR). The number of supported queues depends on the | |
880 | switch; some OpenFlow implementations do not support queuing at all. | |
64c1e8af | 881 | . |
064af421 BP |
882 | .IP \fBdrop\fR |
883 | Discards the packet, so no further processing or forwarding takes place. | |
884 | If a drop action is used, no other actions may be specified. | |
a9b4a41a | 885 | . |
064af421 BP |
886 | .IP \fBmod_vlan_vid\fR:\fIvlan_vid\fR |
887 | Modifies the VLAN id on a packet. The VLAN tag is added or modified | |
888 | as necessary to match the value specified. If the VLAN tag is added, | |
889 | a priority of zero is used (see the \fBmod_vlan_pcp\fR action to set | |
890 | this). | |
a9b4a41a | 891 | . |
064af421 BP |
892 | .IP \fBmod_vlan_pcp\fR:\fIvlan_pcp\fR |
893 | Modifies the VLAN priority on a packet. The VLAN tag is added or modified | |
894 | as necessary to match the value specified. Valid values are between 0 | |
895 | (lowest) and 7 (highest). If the VLAN tag is added, a vid of zero is used | |
896 | (see the \fBmod_vlan_vid\fR action to set this). | |
a9b4a41a | 897 | . |
064af421 BP |
898 | .IP \fBstrip_vlan\fR |
899 | Strips the VLAN tag from a packet if it is present. | |
a9b4a41a | 900 | . |
3e34fbdd | 901 | .IP \fBpush_vlan\fR:\fIethertype\fR |
898dcef1 | 902 | Push a new VLAN tag onto the packet. Ethertype is used as the Ethertype |
3e34fbdd IY |
903 | for the tag. Only ethertype 0x8100 should be used. (0x88a8 which the spec |
904 | allows isn't supported at the moment.) | |
905 | A priority of zero and the tag of zero are used for the new tag. | |
906 | . | |
b02475c5 | 907 | .IP \fBpush_mpls\fR:\fIethertype\fR |
912c1938 SH |
908 | Changes the packet's Ethertype to \fIethertype\fR, which must be either |
909 | \fB0x8847\fR or \fB0x8848\fR, and pushes an MPLS LSE. | |
910 | .IP | |
911 | If the packet does not already contain any MPLS labels then an initial | |
912 | label stack entry is pushed. The label stack entry's label is 2 if the | |
913 | packet contains IPv6 and 0 otherwise, its default traffic control value is | |
914 | the low 3 bits of the packet's DSCP value (0 if the packet is not IP), and | |
915 | its TTL is copied from the IP TTL (64 if the packet is not IP). | |
b02475c5 SH |
916 | .IP |
917 | If the packet does already contain an MPLS label, pushes a new | |
918 | outermost label as a copy of the existing outermost label. | |
919 | .IP | |
b0a17866 SH |
920 | A limitation of the implementation is that processing of actions will stop |
921 | if \fBpush_mpls\fR follows another \fBpush_mpls\fR unless there is a | |
922 | \fBpop_mpls\fR in between. | |
b02475c5 SH |
923 | . |
924 | .IP \fBpop_mpls\fR:\fIethertype\fR | |
799a91bb SH |
925 | Strips the outermost MPLS label stack entry. |
926 | Currently the implementation restricts \fIethertype\fR to a non-MPLS Ethertype | |
927 | and thus \fBpop_mpls\fR should only be applied to packets with | |
b0a17866 SH |
928 | an MPLS label stack depth of one. A further limitation is that processing of |
929 | actions will stop if \fBpop_mpls\fR follows another \fBpop_mpls\fR unless | |
930 | there is a \fBpush_mpls\fR in between. | |
b02475c5 | 931 | . |
064af421 BP |
932 | .IP \fBmod_dl_src\fB:\fImac\fR |
933 | Sets the source Ethernet address to \fImac\fR. | |
a9b4a41a | 934 | . |
064af421 BP |
935 | .IP \fBmod_dl_dst\fB:\fImac\fR |
936 | Sets the destination Ethernet address to \fImac\fR. | |
a9b4a41a | 937 | . |
e423eca6 JP |
938 | .IP \fBmod_nw_src\fB:\fIip\fR |
939 | Sets the IPv4 source address to \fIip\fR. | |
a9b4a41a | 940 | . |
e423eca6 JP |
941 | .IP \fBmod_nw_dst\fB:\fIip\fR |
942 | Sets the IPv4 destination address to \fIip\fR. | |
a9b4a41a | 943 | . |
e423eca6 | 944 | .IP \fBmod_tp_src\fB:\fIport\fR |
0d56eaf2 | 945 | Sets the TCP or UDP or SCTP source port to \fIport\fR. |
a9b4a41a | 946 | . |
e423eca6 | 947 | .IP \fBmod_tp_dst\fB:\fIport\fR |
0d56eaf2 | 948 | Sets the TCP or UDP or SCTP destination port to \fIport\fR. |
a9b4a41a | 949 | . |
959a2ecd | 950 | .IP \fBmod_nw_tos\fB:\fItos\fR |
04f01c24 BP |
951 | Sets the DSCP bits in the IPv4 ToS/DSCP or IPv6 traffic class field to |
952 | \fItos\fR, which must be a multiple of 4 between 0 and 255. This action | |
953 | does not modify the two least significant bits of the ToS field (the ECN bits). | |
ff14eb7a JR |
954 | . |
955 | .IP \fBmod_nw_ecn\fB:\fIecn\fR | |
956 | Sets the ECN bits in the IPv4 ToS or IPv6 traffic class field to \fIecn\fR, | |
957 | which must be a value between 0 and 3, inclusive. This action does not modify | |
958 | the six most significant bits of the field (the DSCP bits). | |
959 | .IP | |
960 | Requires OpenFlow 1.1 or later. | |
0c20dbe4 JR |
961 | . |
962 | .IP \fBmod_nw_ttl\fB:\fIttl\fR | |
963 | Sets the IPv4 TTL or IPv6 hop limit field to \fIttl\fR, which is specified as | |
964 | a decimal number between 0 and 255, inclusive. Switch behavior when setting | |
965 | \fIttl\fR to zero is not well specified, though. | |
966 | .IP | |
967 | Requires OpenFlow 1.1 or later. | |
659586ef JG |
968 | .RE |
969 | .IP | |
970 | The following actions are Nicira vendor extensions that, as of this writing, are | |
971 | only known to be implemented by Open vSwitch: | |
972 | . | |
973 | .RS | |
974 | . | |
3a2fe1f3 | 975 | .IP \fBresubmit\fB:\fIport\fR |
29901626 | 976 | .IQ \fBresubmit\fB(\fR[\fIport\fR]\fB,\fR[\fItable\fR]\fB) |
2cd20955 | 977 | .IQ \fBresubmit\fB(\fR[\fIport\fR]\fB,\fR[\fItable\fR]\fB,ct) |
4bc938cc BP |
978 | Re-searches this OpenFlow flow table (or table \fItable\fR, if |
979 | specified) with the \fBin_port\fR field replaced by | |
2cd20955 JR |
980 | \fIport\fR (if \fIport\fR is specified) and the packet 5-tuple fields |
981 | swapped with the corresponding conntrack original direction tuple | |
982 | fields (if \fBct\fR is specified, see \fBct_nw_src\fR above), and | |
983 | executes the actions found, if any, in addition to any other actions | |
984 | in this flow entry. The \fBin_port\fR and swapped 5-tuple fields are | |
985 | restored immediately after the search, before any actions are | |
986 | executed. | |
987 | .IP | |
4bc938cc BP |
988 | The \fItable\fR may be expressed as a number between 0 and 254 or |
989 | (unless \fB\-\-no\-names\fR is specified) a name. | |
990 | .IP | |
2cd20955 JR |
991 | The \fBct\fR option requires a valid connection tracking state as a |
992 | match prerequisite in the flow where this action is placed. Examples | |
993 | of valid connection tracking state matches include | |
994 | \fBct_state=+new\fR, \fBct_state=+est\fR, \fBct_state=+rel\fR, and | |
995 | \fBct_state=+trk-inv\fR. | |
29901626 | 996 | .IP |
790c5d26 BP |
997 | Recursive \fBresubmit\fR actions are obeyed up to |
998 | implementation-defined limits: | |
999 | .RS | |
1000 | .IP \(bu | |
1001 | Open vSwitch 1.0.1 and earlier did not support recursion. | |
1002 | .IP \(bu | |
1003 | Open vSwitch 1.0.2 and 1.0.3 limited recursion to 8 levels. | |
1004 | .IP \(bu | |
1005 | Open vSwitch 1.1 and 1.2 limited recursion to 16 levels. | |
1006 | .IP \(bu | |
1007 | Open vSwitch 1.2 through 1.8 limited recursion to 32 levels. | |
1008 | .IP \(bu | |
1009 | Open vSwitch 1.9 through 2.0 limited recursion to 64 levels. | |
1010 | .IP \(bu | |
1011 | Open vSwitch 2.1 through 2.5 limited recursion to 64 levels and impose | |
1012 | a total limit of 4,096 resubmits per flow translation (earlier versions | |
1013 | did not impose any total limit). | |
1014 | .IP \(bu | |
1015 | Open vSwitch 2.6 and later imposes the same limits as 2.5, with one | |
1016 | exception: \fBresubmit\fR from table \fIx\fR to any table \fIy\fR > | |
1017 | \fIx\fR does not count against the recursion limit. | |
1018 | .RE | |
1019 | .IP | |
2cd20955 JR |
1020 | Open vSwitch before 1.2.90 did not support \fItable\fR. Open vSwitch |
1021 | before 2.7 did not support \fBct\fR. | |
659586ef JG |
1022 | . |
1023 | .IP \fBset_tunnel\fB:\fIid\fR | |
b9298d3f BP |
1024 | .IQ \fBset_tunnel64\fB:\fIid\fR |
1025 | If outputting to a port that encapsulates the packet in a tunnel and | |
5a6861aa | 1026 | supports an identifier (such as GRE), sets the identifier to \fIid\fR. |
b9298d3f BP |
1027 | If the \fBset_tunnel\fR form is used and \fIid\fR fits in 32 bits, |
1028 | then this uses an action extension that is supported by Open vSwitch | |
1029 | 1.0 and later. Otherwise, if \fIid\fR is a 64-bit value, it requires | |
1030 | Open vSwitch 1.1 or later. | |
3a2fe1f3 | 1031 | . |
eedc0097 JP |
1032 | .IP \fBset_queue\fB:\fIqueue\fR |
1033 | Sets the queue that should be used to \fIqueue\fR when packets are | |
1034 | output. The number of supported queues depends on the switch; some | |
1035 | OpenFlow implementations do not support queuing at all. | |
1036 | . | |
1037 | .IP \fBpop_queue\fR | |
1038 | Restores the queue to the value it was before any \fBset_queue\fR | |
1039 | actions were applied. | |
1040 | . | |
07659514 | 1041 | .IP \fBct\fR |
f6fabcc6 | 1042 | .IQ \fBct(\fR[\fIargument\fR][\fB,\fIargument\fR...]\fB) |
07659514 | 1043 | Send the packet through the connection tracker. Refer to the \fBct_state\fR |
f6fabcc6 JP |
1044 | documentation above for possible packet and connection states. A \fBct\fR |
1045 | action always sets the packet to an untracked state and clears out the | |
1046 | \fBct_state\fR fields for the current processing path. Those fields are | |
1047 | only available for the processing path pointed to by the \fBtable\fR | |
1048 | argument. The following arguments are supported: | |
07659514 JS |
1049 | .RS |
1050 | .IP \fBcommit\fR | |
1051 | .RS | |
1052 | Commit the connection to the connection tracking module. Information about the | |
1053 | connection will be stored beyond the lifetime of the packet in the pipeline. | |
1054 | Some \fBct_state\fR flags are only available for committed connections. | |
1055 | .RE | |
a76a37ef JR |
1056 | .IP \fBforce\fR |
1057 | .RS | |
1058 | A committed connection always has the directionality of the packet | |
1059 | that caused the connection to be committed in the first place. This | |
1060 | is the ``original direction'' of the connection, and the opposite | |
1061 | direction is the ``reply direction''. If a connection is already | |
1062 | committed, but it is in the wrong direction, \fBforce\fR flag may be | |
1063 | used in addition to \fBcommit\fR flag to effectively terminate the | |
1064 | existing connection and start a new one in the current direction. | |
1065 | This flag has no effect if the original direction of the connection is | |
1066 | already the same as that of the current packet. | |
1067 | .RE | |
4bc938cc | 1068 | .IP \fBtable=\fItable\fR |
07659514 JS |
1069 | Fork pipeline processing in two. The original instance of the packet will |
1070 | continue processing the current actions list as an untracked packet. An | |
1071 | additional instance of the packet will be sent to the connection tracker, which | |
1072 | will be re-injected into the OpenFlow pipeline to resume processing in table | |
4bc938cc BP |
1073 | \fInumber\fR (which may be specified as a number between 0 and 254 or, |
1074 | unless \fB\-\-no\-names\fR is specified, a name), with the | |
1075 | \fBct_state\fR and other ct match fields set. If | |
54da48f4 JS |
1076 | \fBtable\fR is not specified, then the packet which is submitted to the |
1077 | connection tracker is not re-injected into the OpenFlow pipeline. It is | |
1078 | strongly recommended to specify a table later than the current table to prevent | |
1079 | loops. | |
07659514 JS |
1080 | .IP \fBzone=\fIvalue\fR |
1081 | .IQ \fBzone=\fIsrc\fB[\fIstart\fB..\fIend\fB]\fR | |
1082 | A 16-bit context id that can be used to isolate connections into separate | |
1083 | domains, allowing overlapping network addresses in different zones. If a zone | |
1084 | is not provided, then the default is to use zone zero. The \fBzone\fR may be | |
1085 | specified either as an immediate 16-bit \fIvalue\fR, or may be provided from an | |
8e53fe8c | 1086 | NXM field \fIsrc\fR. The \fIstart\fR and \fIend\fR pair are inclusive, and must |
54da48f4 JS |
1087 | specify a 16-bit range within the field. This value is copied to the |
1088 | \fBct_zone\fR match field for packets which are re-injected into the pipeline | |
1089 | using the \fBtable\fR option. | |
8e53fe8c | 1090 | .IP \fBexec\fB(\fR[\fIaction\fR][\fB,\fIaction\fR...]\fB)\fR |
54da48f4 JS |
1091 | Perform actions within the context of connection tracking. This is a restricted |
1092 | set of actions which are in the same format as their specifications as part | |
1093 | of a flow. Only actions which modify the \fBct_mark\fR or \fBct_label\fR | |
1094 | fields are accepted within the \fBexec\fR action, and these fields may only be | |
1095 | modified with this option. For example: | |
8e53fe8c JS |
1096 | . |
1097 | .RS | |
96f46bfc | 1098 | .IP \fBset_field:\fIvalue\fR[\fB/\fImask\fR]->ct_mark\fR |
91440329 JR |
1099 | Store a 32-bit metadata value with the connection. Subsequent lookups |
1100 | for packets in this connection will populate the \fBct_mark\fR flow | |
1101 | field when the packet is sent to the connection tracker with the | |
1102 | \fBtable\fR specified. | |
96f46bfc | 1103 | .IP \fBset_field:\fIvalue\fR[\fB/\fImask\fR]->ct_label\fR |
91440329 JR |
1104 | Store a 128-bit metadata value with the connection. Subsequent |
1105 | lookups for packets in this connection will populate the | |
1106 | \fBct_label\fR flow field when the packet is sent to the connection | |
1107 | tracker with the \fBtable\fR specified. | |
8e53fe8c JS |
1108 | .RE |
1109 | .IP | |
3a103e4a | 1110 | The \fBcommit\fR parameter must be specified to use \fBexec(...)\fR. |
8e53fe8c | 1111 | . |
d787ad39 JS |
1112 | .IP \fBalg=\fIalg\fR |
1113 | Specify application layer gateway \fIalg\fR to track specific connection | |
40c7b2fc JS |
1114 | types. If subsequent related connections are sent through the \fBct\fR |
1115 | action, then the \fBrel\fR flag in the \fBct_state\fR field will be set. | |
1116 | Supported types include: | |
d787ad39 JS |
1117 | .RS |
1118 | .IP \fBftp\fR | |
40c7b2fc JS |
1119 | Look for negotiation of FTP data connections. Specify this option for FTP |
1120 | control connections to detect related data connections and populate the | |
1121 | \fBrel\fR flag for the data connections. | |
1122 | . | |
1123 | .IP \fBtftp\fR | |
1124 | Look for negotiation of TFTP data connections. Specify this option for TFTP | |
1125 | control connections to detect related data connections and populate the | |
1126 | \fBrel\fR flag for the data connections. | |
d787ad39 JS |
1127 | .RE |
1128 | . | |
54da48f4 | 1129 | .IP |
3a103e4a RB |
1130 | The \fBcommit\fR parameter must be specified to use \fBalg=\fIalg\fR. |
1131 | . | |
1132 | .IP | |
54da48f4 JS |
1133 | When committing related connections, the \fBct_mark\fR for that connection is |
1134 | inherited from the current \fBct_mark\fR stored with the original connection | |
1135 | (ie, the connection created by \fBct(alg=...)\fR). | |
ae8b9260 | 1136 | . |
8c019a41 JS |
1137 | .IP |
1138 | Note that with the Linux datapath, global sysctl options affect the usage of | |
1139 | the \fBct\fR action. In particular, if \fBnet.netfilter.nf_conntrack_helper\fR | |
1140 | is enabled then application layer gateway helpers may be executed even if the | |
1141 | \fBalg\fR option is not specified. This is the default setting until Linux 4.7. | |
1142 | For security reasons, the netfilter team recommends users to disable this | |
1143 | option. See this blog post for further details: | |
1144 | . | |
1145 | http://www.netfilter.org/news.html#2012-04-03 | |
1146 | . | |
ae8b9260 JR |
1147 | .IP \fBnat\fR[\fB(\fR(\fBsrc\fR|\fBdst\fR)\fB=\fIaddr1\fR[\fB-\fIaddr2\fR][\fB:\fIport1\fR[\fB-\fIport2\fR]][\fB,\fIflags\fR]\fB)\fR] |
1148 | . | |
1149 | Specify address and port translation for the connection being tracked. | |
1150 | For new connections either \fBsrc\fR or \fBdst\fR argument must be | |
1151 | provided to set up either source address/port translation (SNAT) or | |
1152 | destination address/port translation (DNAT), respectively. Setting up | |
1153 | address translation for a new connection takes effect only if the | |
1154 | \fBcommit\fR flag is also provided for the enclosing \fBct\fR action. | |
1155 | A bare \fBnat\fR action will only translate the packet being processed | |
1156 | in the way the connection has been set up with an earlier \fBct\fR | |
1157 | action. Also a \fBnat\fR action with \fBsrc\fR or \fBdst\fR, when | |
1158 | applied to a packet belonging to an established (rather than new) | |
1159 | connection, will behave the same as a bare \fBnat\fR. | |
1160 | .IP | |
1161 | \fBsrc\fR and \fBdst\fR options take the following arguments: | |
1162 | .RS | |
1163 | .IP \fIaddr1\fR[\fB-\fIaddr2\fR] | |
1164 | The address range from which the translated address should be | |
1165 | selected. If only one address is given, then that address will always | |
1166 | be selected, otherwise the address selection can be informed by the | |
1167 | optional \fBpersistent\fR flag as described below. Either IPv4 or | |
1168 | IPv6 addresses can be provided, but both addresses must be of the same | |
1169 | type, and the datapath behavior is undefined in case of providing IPv4 | |
1170 | address range for an IPv6 packet, or IPv6 address range for an IPv4 | |
1171 | packet. IPv6 addresses must be bracketed with '[' and ']' if a port | |
1172 | range is also given. | |
1173 | .RE | |
1174 | . | |
1175 | .RS | |
1176 | .IP \fIport1\fR[\fB-\fIport2\fR] | |
1177 | The port range from which the translated port should be selected. If | |
1178 | only one port number is provided, then that should be selected. In | |
1179 | case of a mapping conflict the datapath may choose any other | |
1180 | non-conflicting port number instead, even when no port range is | |
1181 | specified. The port number selection can be informed by the optional | |
1182 | \fBrandom\fR and \fBhash\fR flags as described below. | |
1183 | .RE | |
1184 | .IP | |
1185 | The optional flags are: | |
1186 | .RS | |
1187 | .IP \fBrandom\fR | |
1188 | The selection of the port from the given range should be done using a | |
1189 | fresh random number. This flag is mutually exclusive with \fBhash\fR. | |
1190 | .RE | |
1191 | . | |
1192 | .RS | |
1193 | .IP \fBhash\fR | |
1194 | The selection of the port from the given range should be done using a | |
1195 | datapath specific hash of the packet's IP addresses and the other, | |
1196 | non-mapped port number. This flag is mutually exclusive with | |
1197 | \fBrandom\fR. | |
1198 | .RE | |
1199 | . | |
1200 | .RS | |
1201 | .IP \fBpersistent\fR | |
1202 | The selection of the IP address from the given range should be done so | |
1203 | that the same mapping can be provided after the system restarts. | |
1204 | .RE | |
1205 | .IP | |
1206 | If an \fBalg\fR is specified for the committing \fBct\fR action that | |
1207 | also includes \fBnat\fR with a \fBsrc\fR or \fBdst\fR attribute, | |
1208 | then the datapath tries to set up the helper to be NAT aware. This | |
1209 | functionality is datapath specific and may not be supported by all | |
1210 | datapaths. | |
1211 | .IP | |
1212 | \fBnat\fR was introduced in Open vSwitch 2.6. The first datapath that | |
1213 | implements \fBct nat\fR support is the one that ships with Linux 4.6. | |
07659514 JS |
1214 | .RE |
1215 | .IP | |
1216 | The \fBct\fR action may be used as a primitive to construct stateful firewalls | |
1217 | by selectively committing some traffic, then matching the \fBct_state\fR to | |
1218 | allow established connections while denying new connections. The following | |
1219 | flows provide an example of how to implement a simple firewall that allows new | |
1220 | connections from port 1 to port 2, and only allows established connections to | |
1221 | send traffic from port 2 to port 1: | |
1222 | \fBtable=0,priority=1,action=drop | |
1223 | table=0,priority=10,arp,action=normal | |
1224 | table=0,priority=100,ip,ct_state=-trk,action=ct(table=1) | |
1225 | table=1,in_port=1,ip,ct_state=+trk+new,action=ct(commit),2 | |
1226 | table=1,in_port=1,ip,ct_state=+trk+est,action=2 | |
1227 | table=1,in_port=2,ip,ct_state=+trk+new,action=drop | |
1228 | table=1,in_port=2,ip,ct_state=+trk+est,action=1\fR | |
1229 | .IP | |
1230 | If \fBct\fR is executed on IP (or IPv6) fragments, then the message is | |
1231 | implicitly reassembled before sending to the connection tracker and | |
1232 | refragmented upon \fBoutput\fR, to the original maximum received fragment size. | |
54da48f4 JS |
1233 | Reassembly occurs within the context of the \fBzone\fR, meaning that IP |
1234 | fragments in different zones are not assembled together. Pipeline processing | |
1235 | for the initial fragments is halted; When the final fragment is received, the | |
1236 | message is assembled and pipeline processing will continue for that flow. | |
07659514 JS |
1237 | Because packet ordering is not guaranteed by IP protocols, it is not possible |
1238 | to determine which IP fragment will cause message reassembly (and therefore | |
1239 | continue pipeline processing). As such, it is strongly recommended that | |
1240 | multiple flows should not execute \fBct\fR to reassemble fragments from the | |
1241 | same IP message. | |
1242 | .IP | |
de759da2 | 1243 | The \fBct\fR action was introduced in Open vSwitch 2.5. |
07659514 | 1244 | . |
72fe7578 BP |
1245 | .IP \fBct_clear\fR |
1246 | Clears connection tracking state from the flow, zeroing | |
1247 | \fBct_state\fR, \fBct_zone\fR, \fBct_mark\fR, and \fBct_label\fR. | |
1248 | .IP | |
1249 | This action was introduced in Open vSwitch 2.6.90. | |
1250 | . | |
f0fd1a17 | 1251 | .IP \fBdec_ttl\fR |
ef6d1b11 | 1252 | .IQ \fBdec_ttl(\fIid1\fR[\fB,\fIid2\fR]...\fB)\fR |
f0fd1a17 | 1253 | Decrement TTL of IPv4 packet or hop limit of IPv6 packet. If the |
972b5f38 JR |
1254 | TTL or hop limit is initially zero or decrementing would make it so, no |
1255 | decrement occurs, as packets reaching TTL zero must be rejected. Instead, | |
f0fd1a17 PS |
1256 | a ``packet-in'' message with reason code \fBOFPR_INVALID_TTL\fR is |
1257 | sent to each connected controller that has enabled receiving them, | |
c2d967a5 MM |
1258 | if any. Processing the current set of actions then stops. However, |
1259 | if the current set of actions was reached through ``resubmit'' then | |
ef6d1b11 JP |
1260 | remaining actions in outer levels resume processing. |
1261 | .IP | |
1262 | This action also optionally supports the ability to specify a list of | |
1263 | valid controller ids. Each of the controllers in the list will receive | |
1264 | the ``packet_in'' message only if they have registered to receive the | |
c2d967a5 MM |
1265 | invalid ttl packets. If controller ids are not specified, the |
1266 | ``packet_in'' message will be sent only to the controllers having | |
1267 | controller id zero which have registered for the invalid ttl packets. | |
f0fd1a17 | 1268 | . |
afd5ac06 SH |
1269 | .IP \fBset_mpls_label\fR:\fIlabel\fR |
1270 | Set the label of the outer MPLS label stack entry of a packet. | |
1271 | \fIlabel\fR should be a 20-bit value that is decimal by default; | |
1272 | use a \fB0x\fR prefix to specify them in hexadecimal. | |
1273 | . | |
1274 | .IP \fBset_mpls_tc\fR:\fItc\fR | |
1275 | Set the traffic-class of the outer MPLS label stack entry of a packet. | |
1276 | \fItc\fR should be a in the range 0 to 7 inclusive. | |
1277 | . | |
0f3f3c3d SH |
1278 | .IP \fBset_mpls_ttl\fR:\fIttl\fR |
1279 | Set the TTL of the outer MPLS label stack entry of a packet. | |
1280 | \fIttl\fR should be in the range 0 to 255 inclusive. | |
1281 | . | |
b676167a SH |
1282 | .IP \fBdec_mpls_ttl\fR |
1283 | Decrement TTL of the outer MPLS label stack entry of a packet. If the TTL | |
972b5f38 JR |
1284 | is initially zero or decrementing would make it so, no decrement occurs. |
1285 | Instead, a ``packet-in'' message with reason code \fBOFPR_INVALID_TTL\fR | |
1286 | is sent to the main controller (id zero), if it has enabled receiving them. | |
b676167a SH |
1287 | Processing the current set of actions then stops. However, if the current |
1288 | set of actions was reached through ``resubmit'' then remaining actions in | |
1289 | outer levels resume processing. | |
1290 | . | |
491e05c2 YY |
1291 | .IP \fBdec_nsh_ttl\fR |
1292 | Decrement TTL of the outer NSH header of a packet. If the TTL | |
1293 | is initially zero or decrementing would make it so, no decrement occurs. | |
1294 | Instead, a ``packet-in'' message with reason code \fBOFPR_INVALID_TTL\fR | |
1295 | is sent to the main controller (id zero), if it has enabled receiving them. | |
1296 | Processing the current set of actions then stops. However, if the current | |
1297 | set of actions was reached through ``resubmit'' then remaining actions in | |
1298 | outer levels resume processing. | |
1299 | . | |
96fc46e8 BP |
1300 | .IP \fBnote:\fR[\fIhh\fR]... |
1301 | Does nothing at all. Any number of bytes represented as hex digits | |
1302 | \fIhh\fR may be included. Pairs of hex digits may be separated by | |
1303 | periods for readability. | |
e0631927 BP |
1304 | The \fBnote\fR action's format doesn't include an exact length for its |
1305 | payload, so the provided bytes will be padded on the right by enough | |
1306 | bytes with value 0 to make the total number 6 more than a multiple of | |
1307 | 8. | |
f393f81e | 1308 | . |
5a6861aa | 1309 | .IP "\fBmove:\fIsrc\fB[\fIstart\fB..\fIend\fB]\->\fIdst\fB[\fIstart\fB..\fIend\fB]\fR" |
f393f81e | 1310 | Copies the named bits from field \fIsrc\fR to field \fIdst\fR. |
21b2fa61 JR |
1311 | \fIsrc\fR and \fIdst\fR may be NXM field names as defined in |
1312 | \fBnicira\-ext.h\fR, e.g. \fBNXM_OF_UDP_SRC\fR or \fBNXM_NX_REG0\fR, | |
1313 | or a match field name, e.g. \fBreg0\fR. Each | |
1314 | \fIstart\fR and \fIend\fR pair, which are inclusive, must specify the | |
1315 | same number of bits and must fit within its respective field. | |
f393f81e BP |
1316 | Shorthands for \fB[\fIstart\fB..\fIend\fB]\fR exist: use |
1317 | \fB[\fIbit\fB]\fR to specify a single bit or \fB[]\fR to specify an | |
21b2fa61 | 1318 | entire field (in the latter case the brackets can also be left off). |
f393f81e BP |
1319 | .IP |
1320 | Examples: \fBmove:NXM_NX_REG0[0..5]\->NXM_NX_REG1[26..31]\fR copies the | |
1321 | six bits numbered 0 through 5, inclusive, in register 0 into bits 26 | |
1322 | through 31, inclusive; | |
21b2fa61 | 1323 | \fBmove:reg0[0..15]\->vlan_tci\fR copies the least |
f393f81e | 1324 | significant 16 bits of register 0 into the VLAN TCI field. |
1a12c419 | 1325 | .IP |
914624f8 BP |
1326 | In OpenFlow 1.0 through 1.4, \fBmove\fR ordinarily uses an Open |
1327 | vSwitch extension to OpenFlow. In OpenFlow 1.5, \fBmove\fR uses the | |
d3cb080e | 1328 | OpenFlow 1.5 standard \fBcopy_field\fR action. The ONF has |
914624f8 BP |
1329 | also made \fBcopy_field\fR available as an extension to OpenFlow 1.3. |
1330 | Open vSwitch 2.4 and later understands this extension and uses it if a | |
1331 | controller uses it, but for backward compatibility with older versions | |
1332 | of Open vSwitch, \fBovs\-ofctl\fR does not use it. | |
f393f81e | 1333 | . |
7eb4b1f1 BP |
1334 | .IP "\fBset_field:\fIvalue\fR[/\fImask\fR]\fB\->\fIdst" |
1335 | .IQ "\fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB]" | |
1336 | Loads a literal value into a field or part of a field. With | |
1337 | \fBset_field\fR, \fBvalue\fR and the optional \fBmask\fR are given in | |
1338 | the customary syntax for field \fIdst\fR, which is expressed as a | |
1339 | field name. For example, \fBset_field:00:11:22:33:44:55->eth_src\fR | |
1340 | sets the Ethernet source address to 00:11:22:33:44:55. With | |
1341 | \fBload\fR, \fIvalue\fR must be an integer value (in decimal or | |
21b2fa61 JR |
1342 | prefixed by \fB0x\fR for hexadecimal) and \fIdst\fR can also be the |
1343 | NXM or OXM name for the field. For example, | |
1344 | \fBload:0x001122334455->OXM_OF_ETH_SRC[]\fR has the same effect as the | |
7eb4b1f1 BP |
1345 | prior \fBset_field\fR example. |
1346 | .IP | |
1347 | The two forms exist for historical reasons. Open vSwitch 1.1 | |
1348 | introduced \fBNXAST_REG_LOAD\fR as a Nicira extension to OpenFlow 1.0 | |
1349 | and used \fBload\fR to express it. Later, OpenFlow 1.2 introduced a | |
1350 | standard \fBOFPAT_SET_FIELD\fR action that was restricted to loading | |
1351 | entire fields, so Open vSwitch added the form \fBset_field\fR with | |
1352 | this restriction. OpenFlow 1.5 extended \fBOFPAT_SET_FIELD\fR to the | |
1353 | point that it became a superset of \fBNXAST_REG_LOAD\fR. Open vSwitch | |
1354 | translates either syntax as necessary for the OpenFlow version in use: | |
1355 | in OpenFlow 1.0 and 1.1, \fBNXAST_REG_LOAD\fR; in OpenFlow 1.2, 1.3, | |
1356 | and 1.4, \fBNXAST_REG_LOAD\fR for \fBload\fR or for loading a | |
1357 | subfield, \fBOFPAT_SET_FIELD\fR otherwise; and OpenFlow 1.5 and later, | |
1358 | \fBOFPAT_SET_FIELD\fR. | |
53ddd40a | 1359 | . |
bd85dac1 | 1360 | .IP "\fBpush:\fIsrc\fB[\fIstart\fB..\fIend\fB]" |
81ce8036 BP |
1361 | .IQ "\fBpop:\fIdst\fB[\fIstart\fB..\fIend\fB]" |
1362 | These Open vSwitch extension actions act on bits \fIstart\fR to | |
1363 | \fIend\fR, inclusive, in the named field, pushing or popping the bits | |
1364 | on a general-purpose stack of fields or subfields. Controllers can | |
1365 | use this stack for saving and restoring data or metadata around | |
1366 | \fBresubmit\fR actions, for swapping or rearranging data and metadata, | |
1367 | or for other purposes. Any data or metadata field, or part of one, | |
1368 | may be pushed, and any modifiable field or subfield may be popped. | |
bd85dac1 | 1369 | .IP |
81ce8036 BP |
1370 | The number of bits pushed in a stack entry do not have to match the |
1371 | number of bits later popped from that entry. If more bits are popped | |
1372 | from an entry than were pushed, then the entry is conceptually | |
1373 | left-padded with 0-bits as needed. If fewer bits are popped than | |
1374 | pushed, then bits are conceptually trimmed from the left side of the | |
1375 | entry. | |
bd85dac1 | 1376 | .IP |
81ce8036 BP |
1377 | The stack's size is intended to have a large enough limit that |
1378 | ``normal'' use will not pose problems. Stack overflow or underflow is | |
1379 | an error that causes action execution to stop. | |
1380 | .IP | |
1381 | Example: \fBpush:NXM_NX_REG2[0..5]\fR or \fBpush:reg2[0..5]\fR push | |
1382 | the value stored in register 2 bits 0 through 5, inclusive, on the | |
1383 | internal stack, and \fBpop:NXM_NX_REG2[0..5]\fR or | |
1384 | \fBpop:reg2[0..5]\fR pops the value from top of the stack and sets | |
1385 | register 2 bits 0 through 5, inclusive, based on bits 0 through 5 from | |
1386 | the value just popped. | |
f5c45121 | 1387 | . |
53ddd40a BP |
1388 | .IP "\fBmultipath(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIn_links\fB, \fIarg\fB, \fIdst\fB[\fIstart\fB..\fIend\fB])\fR" |
1389 | Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter, | |
1390 | then the applies multipath link selection \fIalgorithm\fR (with | |
1391 | parameter \fIarg\fR) to choose one of \fIn_links\fR output links | |
1392 | numbered 0 through \fIn_links\fR minus 1, and stores the link into | |
43edca57 | 1393 | \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as |
53ddd40a BP |
1394 | described above. |
1395 | .IP | |
4249b547 JB |
1396 | \fIfields\fR must be one of the following: |
1397 | .RS | |
1398 | .IP \fBeth_src\fR | |
1399 | Hashes Ethernet source address only. | |
1400 | .IP \fBsymmetric_l4\fR | |
1401 | Hashes Ethernet source, destination, and type, VLAN ID, IPv4/IPv6 | |
1402 | source, destination, and protocol, and TCP or SCTP (but not UDP) | |
1403 | ports. The hash is computed so that pairs of corresponding flows in | |
1404 | each direction hash to the same value, in environments where L2 paths | |
1405 | are the same in each direction. UDP ports are not included in the | |
1406 | hash to support protocols such as VXLAN that use asymmetric ports in | |
1407 | each direction. | |
1408 | .IP \fBsymmetric_l3l4\fR | |
1409 | Hashes IPv4/IPv6 source, destination, and protocol, and TCP or SCTP | |
1410 | (but not UDP) ports. Like \fBsymmetric_l4\fR, this is a symmetric | |
1411 | hash, but by excluding L2 headers it is more effective in environments | |
1412 | with asymmetric L2 paths (e.g. paths involving VRRP IP addresses on a | |
1413 | router). Not an effective hash function for protocols other than IPv4 | |
1414 | and IPv6, which hash to a constant zero. | |
1415 | .IP \fBsymmetric_l3l4+udp\fR | |
1416 | Like \fBsymmetric_l3l4+udp\fR, but UDP ports are included in the hash. | |
1417 | This is a more effective hash when asymmetric UDP protocols such as | |
1418 | VXLAN are not a consideration. | |
417cfdb6 | 1419 | .IP \fBnw_src\fR |
1420 | Hashes Network source address only. | |
1421 | .IP \fBnw_dst\fR | |
1422 | Hashes Network destination address only. | |
4249b547 JB |
1423 | .RE |
1424 | .IP | |
1425 | \fIalgorithm\fR must be one of \fBmodulo_n\fR, | |
53ddd40a BP |
1426 | \fBhash_threshold\fR, \fBhrw\fR, and \fBiter_hash\fR. Only |
1427 | the \fBiter_hash\fR algorithm uses \fIarg\fR. | |
1428 | .IP | |
1429 | Refer to \fBnicira\-ext.h\fR for more details. | |
3b6a2571 | 1430 | . |
daff3353 EJ |
1431 | .IP "\fBbundle(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, slaves:[\fIs1\fB, \fIs2\fB, ...])\fR" |
1432 | Hashes \fIfields\fR using \fIbasis\fR as a universal hash parameter, then | |
1433 | applies the bundle link selection \fIalgorithm\fR to choose one of the listed | |
1434 | slaves represented as \fIslave_type\fR. Currently the only supported | |
1435 | \fIslave_type\fR is \fBofport\fR. Thus, each \fIs1\fR through \fIsN\fR should | |
1436 | be an OpenFlow port number. Outputs to the selected slave. | |
1437 | .IP | |
417cfdb6 | 1438 | Currently, \fIfields\fR must be either \fBeth_src\fR, \fBsymmetric_l4\fR, \fBsymmetric_l3l4\fR, \fBsymmetric_l3l4+udp\fR, |
1439 | \fBnw_src\fR, or \fBnw_dst\fR, and \fIalgorithm\fR must be one of \fBhrw\fR and \fBactive_backup\fR. | |
daff3353 EJ |
1440 | .IP |
1441 | Example: \fBbundle(eth_src,0,hrw,ofport,slaves:4,8)\fR uses an Ethernet source | |
1442 | hash with basis 0, to select between OpenFlow ports 4 and 8 using the Highest | |
1443 | Random Weight algorithm. | |
1444 | .IP | |
1445 | Refer to \fBnicira\-ext.h\fR for more details. | |
a368bb53 EJ |
1446 | . |
1447 | .IP "\fBbundle_load(\fIfields\fB, \fIbasis\fB, \fIalgorithm\fB, \fIslave_type\fB, \fIdst\fB[\fIstart\fB..\fIend\fB], slaves:[\fIs1\fB, \fIs2\fB, ...])\fR" | |
1448 | Has the same behavior as the \fBbundle\fR action, with one exception. Instead | |
1449 | of outputting to the selected slave, it writes its selection to | |
1450 | \fIdst\fB[\fIstart\fB..\fIend\fB]\fR, which must be an NXM field as described | |
1451 | above. | |
1452 | .IP | |
2638c6dc BP |
1453 | Example: \fBbundle_load(eth_src, 0, hrw, ofport, NXM_NX_REG0[], |
1454 | slaves:4, 8)\fR uses an Ethernet source hash with basis 0, to select | |
1455 | between OpenFlow ports 4 and 8 using the Highest Random Weight | |
21b2fa61 JR |
1456 | algorithm, and writes the selection to \fBNXM_NX_REG0[]\fR. Also the |
1457 | match field name can be used, for example, instead of 'NXM_NX_REG0' | |
1458 | the name 'reg0' can be used. When the while field is indicated the | |
1459 | empty brackets can also be left off. | |
a368bb53 EJ |
1460 | .IP |
1461 | Refer to \fBnicira\-ext.h\fR for more details. | |
75a75043 BP |
1462 | . |
1463 | .IP "\fBlearn(\fIargument\fR[\fB,\fIargument\fR]...\fB)\fR" | |
1464 | This action adds or modifies a flow in an OpenFlow table, similar to | |
1465 | \fBovs\-ofctl \-\-strict mod\-flows\fR. The arguments specify the | |
1466 | flow's match fields, actions, and other properties, as follows. At | |
1467 | least one match criterion and one action argument should ordinarily be | |
1468 | specified. | |
1469 | .RS | |
1470 | .IP \fBidle_timeout=\fIseconds\fR | |
1471 | .IQ \fBhard_timeout=\fIseconds\fR | |
1472 | .IQ \fBpriority=\fIvalue\fR | |
45d77538 | 1473 | .IQ \fBcookie=\fIvalue\fR |
3d6832c2 BP |
1474 | .IQ \fBsend_flow_rem\fR |
1475 | These arguments have the same meaning as in the usual \fBovs\-ofctl\fR | |
1476 | flow syntax. | |
75a75043 | 1477 | . |
0e553d9c BP |
1478 | .IP \fBfin_idle_timeout=\fIseconds\fR |
1479 | .IQ \fBfin_hard_timeout=\fIseconds\fR | |
1480 | Adds a \fBfin_timeout\fR action with the specified arguments to the | |
1481 | new flow. This feature was added in Open vSwitch 1.5.90. | |
1482 | . | |
4bc938cc | 1483 | .IP \fBtable=\fItable\fR |
75a75043 | 1484 | The table in which the new flow should be inserted. Specify a decimal |
4bc938cc BP |
1485 | number between 0 and 254 or (unless \fB\-\-no\-names\fR is specified) |
1486 | a name. The default, if \fBtable\fR is unspecified, is table 1. | |
75a75043 | 1487 | . |
35f48b8b BP |
1488 | .IP \fBdelete_learned\fR |
1489 | This flag enables deletion of the learned flows when the flow with the | |
1490 | \fBlearn\fR action is removed. Specifically, when the last | |
1491 | \fBlearn\fR action with this flag and particular \fBtable\fR and | |
1492 | \fBcookie\fR values is removed, the switch deletes all of the flows in | |
1493 | the specified table with the specified cookie. | |
1494 | . | |
1495 | .IP | |
1496 | This flag was added in Open vSwitch 2.4. | |
1497 | . | |
4c71600d DDP |
1498 | .IP \fBlimit=\fInumber\fR |
1499 | If the number of flows in table \fBtable\fR with cookie id \fBcookie\fR exceeds | |
1500 | \fInumber\fR, a new flow will not be learned by this action. By default | |
1746822c | 1501 | there's no limit. limit=0 is a long-hand for no limit. |
4c71600d DDP |
1502 | . |
1503 | .IP | |
1504 | This flag was added in Open vSwitch 2.8. | |
1505 | . | |
1506 | .IP \fBresult_dst=\fIfield\fB[\fIbit\fB]\fR | |
1507 | If learning failed (because the number of flows exceeds \fBlimit\fR), | |
1508 | the action sets \fIfield\fB[\fIbit\fB]\fR to 0, otherwise it will be set to 1. | |
1509 | \fIfield\fB[\fIbit\fB]\fR must be a single bit. | |
1510 | . | |
1511 | .IP | |
1512 | This flag was added in Open vSwitch 2.8. | |
1513 | . | |
75a75043 BP |
1514 | .IP \fIfield\fB=\fIvalue\fR |
1515 | .IQ \fIfield\fB[\fIstart\fB..\fIend\fB]=\fIsrc\fB[\fIstart\fB..\fIend\fB]\fR | |
1516 | .IQ \fIfield\fB[\fIstart\fB..\fIend\fB]\fR | |
1517 | Adds a match criterion to the new flow. | |
1518 | .IP | |
1519 | The first form specifies that \fIfield\fR must match the literal | |
1520 | \fIvalue\fR, e.g. \fBdl_type=0x0800\fR. All of the fields and values | |
1521 | for \fBovs\-ofctl\fR flow syntax are available with their usual | |
5b10f305 OS |
1522 | meanings. Shorthand notation matchers (e.g. \fBip\fR in place of |
1523 | \fBdl_type=0x0800\fR) are not currently implemented. | |
75a75043 BP |
1524 | .IP |
1525 | The second form specifies that \fIfield\fB[\fIstart\fB..\fIend\fB]\fR | |
1526 | in the new flow must match \fIsrc\fB[\fIstart\fB..\fIend\fB]\fR taken | |
1527 | from the flow currently being processed. | |
5b10f305 OS |
1528 | For example, \fINXM_OF_UDP_DST\fB[]\fR=\fINXM_OF_UDP_SRC\fB[]\fR on a |
1529 | TCP packet for which the UDP src port is \fB53\fR, creates a flow which | |
1530 | matches \fINXM_OF_UDP_DST\fB[]\fR=\fB53\fR. | |
75a75043 BP |
1531 | .IP |
1532 | The third form is a shorthand for the second form. It specifies that | |
5b10f305 | 1533 | \fIfield\fB[\fIstart\fB..\fIend\fB]\fR in the new flow must match the same |
75a75043 BP |
1534 | \fIfield\fB[\fIstart\fB..\fIend\fB]\fR taken from the flow currently |
1535 | being processed. | |
5b10f305 OS |
1536 | For example, \fINXM_OF_TCP_DST\fB[]\fR on a TCP packet |
1537 | for which the TCP dst port is \fB80\fR, creates a flow which | |
1538 | matches \fINXM_OF_TCP_DST\fB[]\fR=\fB80\fR. | |
75a75043 BP |
1539 | . |
1540 | .IP \fBload:\fIvalue\fB\->\fIdst\fB[\fIstart\fB..\fIend\fB] | |
1541 | .IQ \fBload:\fIsrc\fB[\fIstart\fB..\fIend\fB]\->\fIdst\fB[\fIstart\fB..\fIend\fB] | |
1542 | . | |
1543 | Adds a \fBload\fR action to the new flow. | |
1544 | .IP | |
1545 | The first form loads the literal \fIvalue\fR into bits \fIstart\fR | |
1546 | through \fIend\fR, inclusive, in field \fIdst\fR. Its syntax is the | |
1547 | same as the \fBload\fR action described earlier in this section. | |
1548 | .IP | |
1549 | The second form loads \fIsrc\fB[\fIstart\fB..\fIend\fB]\fR, a value | |
1550 | from the flow currently being processed, into bits \fIstart\fR | |
1551 | through \fIend\fR, inclusive, in field \fIdst\fR. | |
1552 | . | |
1553 | .IP \fBoutput:\fIfield\fB[\fIstart\fB..\fIend\fB]\fR | |
1554 | Add an \fBoutput\fR action to the new flow's actions, that outputs to | |
1555 | the OpenFlow port taken from \fIfield\fB[\fIstart\fB..\fIend\fB]\fR, | |
1556 | which must be an NXM field as described above. | |
1557 | .RE | |
c4f5d00b | 1558 | .RE |
a9b4a41a | 1559 | . |
8dd54666 | 1560 | .RS |
8dd54666 | 1561 | . |
b19e8793 IY |
1562 | .IP \fBclear_actions\fR |
1563 | Clears all the actions in the action set immediately. | |
1564 | . | |
7fdb60a7 SH |
1565 | .IP \fBwrite_actions(\fR[\fIaction\fR][\fB,\fIaction\fR...]\fB) |
1566 | Add the specific actions to the action set. The syntax of | |
1567 | \fIactions\fR is the same as in the \fBactions=\fR field. The action | |
1568 | set is carried between flow tables and then executed at the end of the | |
1569 | pipeline. | |
1570 | . | |
1571 | .IP | |
1572 | The actions in the action set are applied in the following order, as | |
1573 | required by the OpenFlow specification, regardless of the order in | |
1574 | which they were added to the action set. Except as specified | |
1575 | otherwise below, the action set only holds at most a single action of | |
1576 | each type. When more than one action of a single type is written to | |
1577 | the action set, the one written later replaces the earlier action: | |
1578 | . | |
1579 | .RS | |
1580 | .IP 1. | |
1581 | \fBstrip_vlan\fR | |
1582 | .IQ | |
1583 | \fBpop_mpls\fR | |
1584 | . | |
1585 | .IP 2. | |
f839892a | 1586 | \fBdecap\fR |
7fdb60a7 SH |
1587 | . |
1588 | .IP 3. | |
f839892a | 1589 | \fBencap\fR |
7fdb60a7 SH |
1590 | . |
1591 | .IP 4. | |
f839892a JS |
1592 | \fBpush_mpls\fR |
1593 | . | |
1594 | .IP 5. | |
1595 | \fBpush_vlan\fR | |
1596 | . | |
1597 | .IP 6. | |
7fdb60a7 SH |
1598 | \fBdec_ttl\fR |
1599 | .IQ | |
1600 | \fBdec_mpls_ttl\fR | |
491e05c2 YY |
1601 | .IQ |
1602 | \fBdec_nsh_ttl\fR | |
7fdb60a7 | 1603 | . |
f839892a | 1604 | .IP 7. |
7fdb60a7 SH |
1605 | \fBload\fR |
1606 | .IQ | |
1b0ee636 TG |
1607 | \fBmove\fR |
1608 | .IQ | |
7fdb60a7 SH |
1609 | \fBmod_dl_dst\fR |
1610 | .IQ | |
1611 | \fBmod_dl_src\fR | |
1612 | .IQ | |
1613 | \fBmod_nw_dst\fR | |
1614 | .IQ | |
1615 | \fBmod_nw_src\fR | |
1616 | .IQ | |
1617 | \fBmod_nw_tos\fR | |
1618 | .IQ | |
ff14eb7a JR |
1619 | \fBmod_nw_ecn\fR |
1620 | .IQ | |
0c20dbe4 JR |
1621 | \fBmod_nw_ttl\fR |
1622 | .IQ | |
7fdb60a7 SH |
1623 | \fBmod_tp_dst\fR |
1624 | .IQ | |
1625 | \fBmod_tp_src\fR | |
1626 | .IQ | |
1627 | \fBmod_vlan_pcp\fR | |
1628 | .IQ | |
1629 | \fBmod_vlan_vid\fR | |
1630 | .IQ | |
1631 | \fBset_field\fR | |
1632 | .IQ | |
1633 | \fBset_tunnel\fR | |
1634 | .IQ | |
1635 | \fBset_tunnel64\fR | |
1636 | .IQ | |
1637 | The action set can contain any number of these actions, with | |
1b0ee636 TG |
1638 | cumulative effect. They will be applied in the order as added. |
1639 | That is, when multiple actions modify the same part of a field, | |
1640 | the later modification takes effect, and when they modify | |
1641 | different parts of a field (or different fields), then both | |
7fdb60a7 SH |
1642 | modifications are applied. |
1643 | . | |
f839892a | 1644 | .IP 8. |
7fdb60a7 SH |
1645 | \fBset_queue\fR |
1646 | . | |
f839892a | 1647 | .IP 9. |
7fdb60a7 SH |
1648 | \fBgroup\fR |
1649 | .IQ | |
1650 | \fBoutput\fR | |
1651 | .IQ | |
2e34a6a3 SS |
1652 | \fBresubmit\fR |
1653 | .IQ | |
1654 | If more than one of these actions is present, then the one listed | |
1655 | earliest above is executed and the others are ignored, regardless of | |
1656 | the order in which they were added to the action set. (If none of these | |
1657 | actions is present, the action set has no real effect, because the | |
1658 | modified packet is not sent anywhere and thus the modifications are | |
1659 | not visible.) | |
7fdb60a7 SH |
1660 | .RE |
1661 | .IP | |
1662 | Only the actions listed above may be written to the action set. | |
491e05c2 | 1663 | \fBencap\fR, \fBdecap\fR and \fBdec_nsh_ttl\fR actions are nonstandard. |
7fdb60a7 | 1664 | . |
4cceacb9 JS |
1665 | .IP \fBwrite_metadata\fB:\fIvalue\fR[/\fImask\fR] |
1666 | Updates the metadata field for the flow. If \fImask\fR is omitted, the | |
1667 | metadata field is set exactly to \fIvalue\fR; if \fImask\fR is specified, then | |
1668 | a 1-bit in \fImask\fR indicates that the corresponding bit in the metadata | |
1669 | field will be replaced with the corresponding bit from \fIvalue\fR. Both | |
1670 | \fIvalue\fR and \fImask\fR are 64-bit values that are decimal by default; use | |
1671 | a \fB0x\fR prefix to specify them in hexadecimal. | |
1672 | . | |
3200ed58 JR |
1673 | .IP \fBmeter\fR:\fImeter_id\fR |
1674 | Apply the \fImeter_id\fR before any other actions. If a meter band rate is | |
1675 | exceeded, the packet may be dropped, or modified, depending on the meter | |
1676 | band type. See the description of the \fBMeter Table Commands\fR, above, | |
1677 | for more details. | |
1678 | . | |
8dd54666 | 1679 | .IP \fBgoto_table\fR:\fItable\fR |
4bc938cc BP |
1680 | Jumps to \fItable\Fr as the next table in the process pipeline. The |
1681 | \fItable\fR may be a number between 0 and 254 or (unless | |
1682 | \fB\-\-no\-names\fR is specified) a name. | |
8dd54666 | 1683 | . |
0e553d9c BP |
1684 | .IP "\fBfin_timeout(\fIargument\fR[\fB,\fIargument\fR]\fB)" |
1685 | This action changes the idle timeout or hard timeout, or both, of this | |
1686 | OpenFlow rule when the rule matches a TCP packet with the FIN or RST | |
1687 | flag. When such a packet is observed, the action reduces the rule's | |
1688 | timeouts to those specified on the action. If the rule's existing | |
1689 | timeout is already shorter than the one that the action specifies, | |
1690 | then that timeout is unaffected. | |
1691 | .IP | |
1692 | \fIargument\fR takes the following forms: | |
1693 | .RS | |
1694 | .IP "\fBidle_timeout=\fIseconds\fR" | |
1695 | Causes the flow to expire after the given number of seconds of | |
1696 | inactivity. | |
1697 | . | |
1698 | .IP "\fBhard_timeout=\fIseconds\fR" | |
1699 | Causes the flow to expire after the given number of seconds, | |
1700 | regardless of activity. (\fIseconds\fR specifies time since the | |
1701 | flow's creation, not since the receipt of the FIN or RST.) | |
1702 | .RE | |
1703 | .IP | |
1704 | This action was added in Open vSwitch 1.5.90. | |
29089a54 RL |
1705 | . |
1706 | .IP "\fBsample(\fIargument\fR[\fB,\fIargument\fR]...\fB)\fR" | |
1707 | Samples packets and sends one sample for every sampled packet. | |
1708 | .IP | |
1709 | \fIargument\fR takes the following forms: | |
1710 | .RS | |
1711 | .IP "\fBprobability=\fIpackets\fR" | |
1712 | The number of sampled packets out of 65535. Must be greater or equal to 1. | |
1713 | .IP "\fBcollector_set_id=\fIid\fR" | |
1714 | The unsigned 32-bit integer identifier of the set of sample collectors | |
1715 | to send sampled packets to. Defaults to 0. | |
1716 | .IP "\fBobs_domain_id=\fIid\fR" | |
1717 | When sending samples to IPFIX collectors, the unsigned 32-bit integer | |
1718 | Observation Domain ID sent in every IPFIX flow record. Defaults to 0. | |
1719 | .IP "\fBobs_point_id=\fIid\fR" | |
1720 | When sending samples to IPFIX collectors, the unsigned 32-bit integer | |
1721 | Observation Point ID sent in every IPFIX flow record. Defaults to 0. | |
f69f713b | 1722 | .IP "\fBsampling_port=\fIport\fR" |
4930ea56 BP |
1723 | Sample packets on \fIport\fR, which should be the ingress or egress |
1724 | port. This option, which was added in Open vSwitch 2.5.90, allows the | |
1725 | IPFIX implementation to export egress tunnel information. | |
1726 | .IP "\fBingress\fR" | |
1727 | .IQ "\fBegress\fR" | |
1728 | Specifies explicitly that the packet is being sampled on ingress to or | |
1729 | egress from the switch. IPFIX reports sent by Open vSwitch before | |
1730 | version 2.5.90 did not include a direction. From 2.5.90 until 2.6.90, | |
1731 | IPFIX reports inferred a direction from \fBsampling_port\fR: if it was | |
1732 | the packet's output port, then the direction was reported as egress, | |
1733 | otherwise as ingress. Open vSwitch 2.6.90 introduced these options, | |
1734 | which allow the inferred direction to be overridden. This is | |
1735 | particularly useful when the ingress (or egress) port is not a tunnel. | |
29089a54 RL |
1736 | .RE |
1737 | .IP | |
fb8f22c1 | 1738 | Refer to \fBovs\-vswitchd.conf.db\fR(5) for more details on |
29089a54 RL |
1739 | configuring sample collector sets. |
1740 | .IP | |
1741 | This action was added in Open vSwitch 1.10.90. | |
1742 | . | |
848e8809 | 1743 | .IP "\fBexit\fR" |
7fdb60a7 SH |
1744 | This action causes Open vSwitch to immediately halt execution of |
1745 | further actions. Those actions which have already been executed are | |
1746 | unaffected. Any further actions, including those which may be in | |
1747 | other tables, or different levels of the \fBresubmit\fR call stack, | |
1748 | are ignored. Actions in the action set is still executed (specify | |
1749 | \fBclear_actions\fR before \fBexit\fR to discard them). | |
18080541 BP |
1750 | . |
1751 | .IP "\fBconjunction(\fIid\fB, \fIk\fB/\fIn\fR\fB)\fR" | |
96fee5e0 BP |
1752 | This action allows for sophisticated ``conjunctive match'' flows. |
1753 | Refer to \fBCONJUNCTIVE MATCH FIELDS\fR in \fBovs\-fields\fR(7) for details. | |
18080541 BP |
1754 | .IP |
1755 | The \fBconjunction\fR action and \fBconj_id\fR field were introduced | |
1756 | in Open vSwitch 2.4. | |
e8035fc0 BP |
1757 | . |
1758 | .IP "\fBclone(\fR[\fIaction\fR][\fB,\fIaction\fR...]\fB)\fR" | |
1759 | Executes each nested \fIaction\fR, saving much of the packet and | |
1760 | pipeline state beforehand and then restoring it afterward. The state | |
1761 | that is saved and restored includes all flow data and metadata | |
b827b231 BP |
1762 | (including, for example, \fBct_state\fR), the stack accessed by |
1763 | \fBpush\fR and \fBpop\fR actions, and the OpenFlow action set. | |
e8035fc0 BP |
1764 | .IP |
1765 | This action was added in Open vSwitch 2.6.90. | |
f839892a JS |
1766 | . |
1767 | .IP "\fBencap(\fR\fIheader\fR[\fB(\fR\fIprop\fR\fB=\fR\fIvalue\fR,\fItlv\fR\fB(\fR\fIclass\fR,\fItype\fR,\fIvalue\fB)\fR,...\fB)\fR]\fB)\fR" | |
1768 | Encapsulates the packet with a new packet header, e.g., ethernet | |
1769 | or nsh. | |
1770 | . | |
1771 | .RS | |
1772 | .IP "\fIheader\fR" | |
1773 | Used to specify encapsulation header type. | |
1774 | . | |
1775 | .IP "\fIprop\fR\fB=\fR\fIvalue\fR" | |
1776 | Used to specify the initial value for the property in the encapsulation header. | |
1777 | . | |
1778 | .IP "\fItlv\fR\fB(\fR\fIclass\fR,\fItype\fR,\fIvalue\fB)\fR" | |
1779 | Used to specify the initial value for the TLV (Type Length Value) | |
1780 | in the encapsulation header. | |
1781 | .RE | |
1782 | .IP | |
1783 | For example, \fBencap(ethernet)\fR will encapsulate the L3 packet with | |
1784 | Ethernet header. | |
1785 | .IP | |
1786 | \fBencap(nsh(md_type=1))\fR will encapsulate the packet with nsh header | |
1787 | and nsh metadata type 1. | |
1788 | .IP | |
1789 | \fBencap(nsh(md_type=2,tlv(0x1000,10,0x12345678)))\fR will encapsulate | |
1790 | the packet with nsh header and nsh metadata type 2, and the nsh TLV with | |
1791 | class 0x1000 and type 10 is set to 0x12345678. | |
1792 | .IP | |
1793 | \fIprop\fR\fB=\fR\fIvalue\fR is just used to set some | |
1794 | necessary fields for encapsulation header initialization. Other fields | |
1795 | in the encapsulation header must be set by \fBset_field\fR action. New | |
1796 | encapsulation header implementation must add new match fields and | |
1797 | corresponding \fBset\fR action in order that \fBset_field\fR action can | |
1798 | change the fields in the encapsulation header on demand. | |
1799 | .IP | |
1800 | \fBencap(nsh(md_type=1)),\fR | |
1801 | \fBset_field:0x1234->nsh_spi,set_field:0x11223344->nsh_c1\fR | |
1802 | is an example to encapsulate nsh header and set nsh spi and c1. | |
1803 | .IP | |
1804 | This action was added in Open vSwitch 2.8. | |
1805 | . | |
1806 | .IP "\fBdecap(\fR[\fBpacket_type(ns=\fR\fInamespace\fR\fB,type=\fR\fItype\fR\fB)\fR]\fB)\fR" | |
1807 | Decapsulates the outer packet header. | |
1808 | . | |
1809 | .RS | |
1810 | .IP "\fBpacket_type(ns=\fR\fInamespace\fR\fB,type=\fR\fItype\fR\fB)\fR" | |
1811 | It is optional and used to specify the outer header type of the | |
1812 | decapsulated packet. \fInamespace\fR is 0 for Ethernet packet, | |
1813 | 1 for L3 packet, \fItype\fR\ is L3 protocol type, e.g., | |
1814 | 0x894f for nsh, 0x0 for Ethernet. | |
1815 | .RE | |
1816 | .IP | |
1817 | By default, \fBdecap()\fR will decapsulate the outer packet header | |
1818 | according to the packet header type, if | |
1819 | \fBpacket_type(ns=\fR\fInamespace\fR\fB,type=\fR\fItype\fR\fB)\fR | |
1820 | is given, it will decapsulate the given packet header, it will fail | |
1821 | if the actual outer packet header type is not of | |
1822 | \fBpacket_type(ns=\fR\fInamespace\fR\fB,type=\fR\fItype\fR\fB)\fR. | |
1823 | .IP | |
1824 | This action was added in Open vSwitch 2.8. | |
24362cd6 | 1825 | .RE |
848e8809 | 1826 | . |
064af421 | 1827 | .PP |
e729e793 JP |
1828 | An opaque identifier called a cookie can be used as a handle to identify |
1829 | a set of flows: | |
1830 | . | |
623e1caf JP |
1831 | .IP \fBcookie=\fIvalue\fR |
1832 | . | |
1833 | A cookie can be associated with a flow using the \fBadd\-flow\fR, | |
1834 | \fBadd\-flows\fR, and \fBmod\-flows\fR commands. \fIvalue\fR can be any | |
1835 | 64-bit number and need not be unique among flows. If this field is | |
1836 | omitted, a default cookie value of 0 is used. | |
1837 | . | |
1838 | .IP \fBcookie=\fIvalue\fR\fB/\fImask\fR | |
e729e793 | 1839 | . |
e729e793 | 1840 | When using NXM, the cookie can be used as a handle for querying, |
623e1caf JP |
1841 | modifying, and deleting flows. \fIvalue\fR and \fImask\fR may be |
1842 | supplied for the \fBdel\-flows\fR, \fBmod\-flows\fR, \fBdump\-flows\fR, and | |
1843 | \fBdump\-aggregate\fR commands to limit matching cookies. A 1-bit in | |
1844 | \fImask\fR indicates that the corresponding bit in \fIcookie\fR must | |
1845 | match exactly, and a 0-bit wildcards that bit. A mask of \-1 may be used | |
1846 | to exactly match a cookie. | |
1847 | .IP | |
1848 | The \fBmod\-flows\fR command can update the cookies of flows that | |
1849 | match a cookie by specifying the \fIcookie\fR field twice (once with a | |
1850 | mask for matching and once without to indicate the new value): | |
1851 | .RS | |
1852 | .IP "\fBovs\-ofctl mod\-flows br0 cookie=1,actions=normal\fR" | |
1853 | Change all flows' cookies to 1 and change their actions to \fBnormal\fR. | |
1854 | .IP "\fBovs\-ofctl mod\-flows br0 cookie=1/\-1,cookie=2,actions=normal\fR" | |
1855 | Update cookies with a value of 1 to 2 and change their actions to | |
1856 | \fBnormal\fR. | |
1857 | .RE | |
1858 | .IP | |
1859 | The ability to match on cookies was added in Open vSwitch 1.5.0. | |
8cce2125 JP |
1860 | . |
1861 | .PP | |
4b6b46ce BP |
1862 | The following additional field sets the priority for flows added by |
1863 | the \fBadd\-flow\fR and \fBadd\-flows\fR commands. For | |
1864 | \fBmod\-flows\fR and \fBdel\-flows\fR when \fB\-\-strict\fR is | |
1865 | specified, priority must match along with the rest of the flow | |
623e1caf | 1866 | specification. For \fBmod-flows\fR without \fB\-\-strict\fR, |
fdb3539e BP |
1867 | priority is only significant if the command creates a new flow, that |
1868 | is, non-strict \fBmod\-flows\fR does not match on priority and will | |
1869 | not change the priority of existing flows. Other commands do not | |
1870 | allow priority to be specified. | |
a9b4a41a | 1871 | . |
064af421 BP |
1872 | .IP \fBpriority=\fIvalue\fR |
1873 | The priority at which a wildcarded entry will match in comparison to | |
1874 | others. \fIvalue\fR is a number between 0 and 65535, inclusive. A higher | |
1875 | \fIvalue\fR will match before a lower one. An exact-match entry will always | |
1876 | have priority over an entry containing wildcards, so it has an implicit | |
1877 | priority value of 65535. When adding a flow, if the field is not specified, | |
1878 | the flow's priority will default to 32768. | |
4530afba BP |
1879 | .IP |
1880 | OpenFlow leaves behavior undefined when two or more flows with the | |
1881 | same priority can match a single packet. Some users expect | |
1882 | ``sensible'' behavior, such as more specific flows taking precedence | |
1883 | over less specific flows, but OpenFlow does not specify this and Open | |
1884 | vSwitch does not implement it. Users should therefore take care to | |
1885 | use priorities to ensure the behavior that they expect. | |
a9b4a41a | 1886 | . |
064af421 | 1887 | .PP |
fdb3539e BP |
1888 | The \fBadd\-flow\fR, \fBadd\-flows\fR, and \fBmod\-flows\fR commands |
1889 | support the following additional options. These options affect only | |
1890 | new flows. Thus, for \fBadd\-flow\fR and \fBadd\-flows\fR, these | |
1891 | options are always significant, but for \fBmod\-flows\fR they are | |
1892 | significant only if the command creates a new flow, that is, their | |
a993007b | 1893 | values do not update or affect existing flows. |
a9b4a41a | 1894 | . |
fdb3539e | 1895 | .IP "\fBidle_timeout=\fIseconds\fR" |
064af421 | 1896 | Causes the flow to expire after the given number of seconds of |
fdb3539e BP |
1897 | inactivity. A value of 0 (the default) prevents a flow from expiring |
1898 | due to inactivity. | |
a9b4a41a | 1899 | . |
064af421 BP |
1900 | .IP \fBhard_timeout=\fIseconds\fR |
1901 | Causes the flow to expire after the given number of seconds, | |
1902 | regardless of activity. A value of 0 (the default) gives the flow no | |
1903 | hard expiration deadline. | |
a9b4a41a | 1904 | . |
ca26eb44 RB |
1905 | .IP "\fBimportance=\fIvalue\fR" |
1906 | Sets the importance of a flow. The flow entry eviction mechanism can | |
1907 | use importance as a factor in deciding which flow to evict. A value | |
1908 | of 0 (the default) makes the flow non-evictable on the basis of | |
1909 | importance. Specify a value between 0 and 65535. | |
1910 | .IP | |
1911 | Only OpenFlow 1.4 and later support \fBimportance\fR. | |
1912 | . | |
a993007b BP |
1913 | .IP "\fBsend_flow_rem\fR" |
1914 | Marks the flow with a flag that causes the switch to generate a ``flow | |
1915 | removed'' message and send it to interested controllers when the flow | |
1916 | later expires or is removed. | |
1917 | . | |
1918 | .IP "\fBcheck_overlap\fR" | |
1919 | Forces the switch to check that the flow match does not overlap that | |
1920 | of any different flow with the same priority in the same table. (This | |
1921 | check is expensive so it is best to avoid it.) | |
1922 | . | |
b6dc6b93 BP |
1923 | .IP "\fBreset_counts\fR" |
1924 | When this flag is specified on a flow being added to a switch, and the | |
1925 | switch already has a flow with an identical match, an OpenFlow 1.2 (or | |
1926 | later) switch resets the flow's packet and byte counters to 0. | |
1927 | Without the flag, the packet and byte counters are preserved. | |
1928 | .IP | |
1929 | OpenFlow 1.0 and 1.1 switches always reset counters in this situation, | |
1930 | as if \fBreset_counts\fR were always specified. | |
1931 | .IP | |
1932 | Open vSwitch 1.10 added support for \fBreset_counts\fR. | |
1933 | . | |
1934 | .IP "\fBno_packet_counts\fR" | |
1935 | .IQ "\fBno_byte_counts\fR" | |
1936 | Adding these flags to a flow advises an OpenFlow 1.3 (or later) switch | |
1937 | that the controller does not need packet or byte counters, | |
1938 | respectively, for the flow. Some switch implementations might achieve | |
1939 | higher performance or reduce resource consumption when these flags are | |
1940 | used. These flags provide no benefit to the Open vSwitch software | |
1941 | switch implementation. | |
1942 | .IP | |
1943 | OpenFlow 1.2 and earlier do not support these flags. | |
1944 | .IP | |
1945 | Open vSwitch 1.10 added support for \fBno_packet_counts\fR and | |
1946 | \fBno_byte_counts\fR. | |
1947 | . | |
064af421 | 1948 | .PP |
4e312e69 | 1949 | The \fBdump\-flows\fR, \fBdump\-aggregate\fR, \fBdel\-flow\fR |
6d5d1f3b | 1950 | and \fBdel\-flows\fR commands support these additional optional fields: |
a9b4a41a | 1951 | . |
064af421 BP |
1952 | .TP |
1953 | \fBout_port=\fIport\fR | |
c6100d92 | 1954 | If set, a matching flow must include an output action to \fIport\fR, |
60a0b9e5 | 1955 | which must be an OpenFlow port number or name (e.g. \fBlocal\fR). |
a9b4a41a | 1956 | . |
6d5d1f3b BP |
1957 | .TP |
1958 | \fBout_group=\fIport\fR | |
1959 | If set, a matching flow must include an \fBgroup\fR action naming | |
1960 | \fIgroup\fR, which must be an OpenFlow group number. This field | |
1961 | is supported in Open vSwitch 2.5 and later and requires OpenFlow 1.1 | |
1962 | or later. | |
1963 | . | |
064af421 | 1964 | .SS "Table Entry Output" |
a9b4a41a | 1965 | . |
4e312e69 | 1966 | The \fBdump\-tables\fR and \fBdump\-aggregate\fR commands print information |
064af421 | 1967 | about the entries in a datapath's tables. Each line of output is a |
f27f2134 BP |
1968 | flow entry as described in \fBFlow Syntax\fR, above, plus some |
1969 | additional fields: | |
a9b4a41a | 1970 | . |
f27f2134 BP |
1971 | .IP \fBduration=\fIsecs\fR |
1972 | The time, in seconds, that the entry has been in the table. | |
1973 | \fIsecs\fR includes as much precision as the switch provides, possibly | |
1974 | to nanosecond resolution. | |
a9b4a41a | 1975 | . |
064af421 BP |
1976 | .IP \fBn_packets\fR |
1977 | The number of packets that have matched the entry. | |
a9b4a41a | 1978 | . |
064af421 BP |
1979 | .IP \fBn_bytes\fR |
1980 | The total number of bytes from packets that have matched the entry. | |
a9b4a41a | 1981 | . |
064af421 | 1982 | .PP |
f27f2134 BP |
1983 | The following additional fields are included only if the switch is |
1984 | Open vSwitch 1.6 or later and the NXM flow format is used to dump the | |
1985 | flow (see the description of the \fB\-\-flow-format\fR option below). | |
1986 | The values of these additional fields are approximations only and in | |
1987 | particular \fBidle_age\fR will sometimes become nonzero even for busy | |
1988 | flows. | |
1989 | . | |
1990 | .IP \fBhard_age=\fIsecs\fR | |
1991 | The integer number of seconds since the flow was added or modified. | |
1992 | \fBhard_age\fR is displayed only if it differs from the integer part | |
1993 | of \fBduration\fR. (This is separate from \fBduration\fR because | |
1994 | \fBmod\-flows\fR restarts the \fBhard_timeout\fR timer without zeroing | |
1995 | \fBduration\fR.) | |
1996 | . | |
1997 | .IP \fBidle_age=\fIsecs\fR | |
1998 | The integer number of seconds that have passed without any packets | |
1999 | passing through the flow. | |
a9b4a41a | 2000 | . |
6dd3c787 JR |
2001 | .SS "Packet\-Out Syntax" |
2002 | .PP | |
2003 | \fBovs\-ofctl bundle\fR command accepts packet-outs to be specified in | |
2004 | the bundle file. Each packet-out comprises of a series of | |
2005 | \fIfield\fB=\fIvalue\fR assignments, separated by commas or white | |
2006 | space. (Embedding spaces into a packet-out description normally | |
2007 | requires quoting to prevent the shell from breaking the description | |
2008 | into multiple arguments.). Unless noted otherwise only the last | |
2009 | instance of each field is honoured. This same syntax is also | |
2010 | supported by the \fBovs\-ofctl packet-out\fR command. | |
2011 | .PP | |
2012 | .IP \fBin_port=\fIport\fR | |
2013 | The port number to be considered the in_port when processing actions. | |
2014 | This can be any valid OpenFlow port number, or any of the \fBLOCAL\fR, | |
2015 | \fBCONTROLLER\fR, or \fBNONE\fR. | |
2016 | . | |
2017 | This field is required. | |
2018 | ||
880b1458 YHW |
2019 | .IP \fIpipeline_field\fR=\fIvalue\fR |
2020 | Optionally, user can specify a list of pipeline fields for a packet-out | |
2021 | message. The supported pipeline fields includes \fBtunnel fields\fR and | |
2022 | \fBregister fields\fR as defined in \fBovs\-fields\fR(7). | |
2023 | ||
6dd3c787 JR |
2024 | .IP \fBpacket=\fIhex-string\fR |
2025 | The actual packet to send, expressed as a string of hexadecimal bytes. | |
2026 | . | |
2027 | This field is required. | |
2028 | ||
2029 | .IP \fBactions=\fR[\fIaction\fR][\fB,\fIaction\fR...]\fR | |
2030 | The syntax of actions are identical to the \fBactions=\fR field | |
2031 | described in \fBFlow Syntax\fR above. Specifying \fBactions=\fR is | |
2032 | optional, but omitting actions is interpreted as a drop, so the packet | |
2033 | will not be sent anywhere from the switch. | |
2034 | . | |
2035 | \fBactions\fR must be specified at the end of each line, like for flow mods. | |
2036 | .RE | |
2037 | . | |
7395c052 NZ |
2038 | .SS "Group Syntax" |
2039 | .PP | |
2040 | Some \fBovs\-ofctl\fR commands accept an argument that describes a group or | |
2041 | groups. Such flow descriptions comprise a series | |
2042 | \fIfield\fB=\fIvalue\fR assignments, separated by commas or white | |
2043 | space. (Embedding spaces into a group description normally requires | |
2044 | quoting to prevent the shell from breaking the description into | |
2045 | multiple arguments.). Unless noted otherwise only the last instance | |
2046 | of each field is honoured. | |
2047 | .PP | |
2048 | .IP \fBgroup_id=\fIid\fR | |
2049 | The integer group id of group. | |
19187a71 | 2050 | When this field is specified in \fBdel\-groups\fR or \fBdump\-groups\fR, |
7395c052 NZ |
2051 | the keyword "all" may be used to designate all groups. |
2052 | . | |
2053 | This field is required. | |
2054 | ||
2055 | ||
2056 | .IP \fBtype=\fItype\fR | |
bdbb8426 | 2057 | The type of the group. The \fBadd-group\fR, \fBadd-groups\fR and |
ed1d5ef3 | 2058 | \fBmod-groups\fR commands require this field. It is prohibited for |
bdbb8426 | 2059 | other commands. The following keywords designated the allowed types: |
7395c052 NZ |
2060 | .RS |
2061 | .IP \fBall\fR | |
2062 | Execute all buckets in the group. | |
2063 | .IP \fBselect\fR | |
9a84f468 BP |
2064 | Execute one bucket in the group, balancing across the buckets |
2065 | according to their weights. To select a bucket, for each live bucket, | |
2066 | Open vSwitch hashes flow data with the bucket ID and multiplies by the | |
2067 | bucket weight to obtain a ``score,'' and then selects the bucket with | |
2068 | the highest score. Use \fBselection_method\fR to control the flow | |
2069 | data used for selection. | |
7395c052 NZ |
2070 | .IP \fBindirect\fR |
2071 | Executes the one bucket in the group. | |
2072 | .IP \fBff\fR | |
2073 | .IQ \fBfast_failover\fR | |
2074 | Executes the first live bucket in the group which is associated with | |
2075 | a live port or group. | |
2076 | .RE | |
2077 | ||
bdbb8426 SH |
2078 | .IP \fBcommand_bucket_id=\fIid\fR |
2079 | The bucket to operate on. The \fBinsert-buckets\fR and \fBremove-buckets\fR | |
2080 | commands require this field. It is prohibited for other commands. | |
2081 | \fIid\fR may be an integer or one of the following keywords: | |
2082 | .RS | |
2083 | .IP \fBall\fR | |
2084 | Operate on all buckets in the group. | |
2085 | Only valid when used with the \fBremove-buckets\fR command in which | |
2086 | case the effect is to remove all buckets from the group. | |
2087 | .IP \fBfirst\fR | |
2088 | Operate on the first bucket present in the group. | |
2089 | In the case of the \fBinsert-buckets\fR command the effect is to | |
2090 | insert new bucets just before the first bucket already present in the group; | |
2091 | or to replace the buckets of the group if there are no buckets already present | |
2092 | in the group. | |
2093 | In the case of the \fBremove-buckets\fR command the effect is to | |
2094 | remove the first bucket of the group; or do nothing if there are no | |
2095 | buckets present in the group. | |
2096 | .IP \fBlast\fR | |
2097 | Operate on the last bucket present in the group. | |
2098 | In the case of the \fBinsert-buckets\fR command the effect is to | |
2099 | insert new bucets just after the last bucket already present in the group; | |
2100 | or to replace the buckets of the group if there are no buckets already present | |
2101 | in the group. | |
2102 | In the case of the \fBremove-buckets\fR command the effect is to | |
2103 | remove the last bucket of the group; or do nothing if there are no | |
2104 | buckets present in the group. | |
2105 | .RE | |
2106 | .IP | |
2107 | If \fIid\fR is an integer then it should correspond to the \fBbucket_id\fR | |
2108 | of a bucket present in the group. | |
2109 | In case of the \fBinsert-buckets\fR command the effect is to | |
2110 | insert buckets just before the bucket in the group whose \fBbucket_id\fR is | |
2111 | \fIid\fR. | |
2112 | In case of the \fBiremove-buckets\fR command the effect is to | |
2113 | remove the in the group whose \fBbucket_id\fR is \fIid\fR. | |
2114 | It is an error if there is no bucket persent group in whose \fBbucket_id\fR is | |
2115 | \fIid\fR. | |
2116 | ||
b879391e SH |
2117 | .IP \fBselection_method\fR=\fImethod\fR |
2118 | The selection method used to select a bucket for a select group. | |
2119 | This is a string of 1 to 15 bytes in length known to lower layers. | |
2120 | This field is optional for \fBadd\-group\fR, \fBadd\-groups\fR and | |
2121 | \fBmod\-group\fR commands on groups of type \fBselect\fR. Prohibited | |
06db81cc JS |
2122 | otherwise. If no selection method is specified, Open vSwitch up to |
2123 | release 2.9 applies the \fBhash\fR method with default fields. From | |
2124 | 2.10 onwards Open vSwitch defaults to the \fBdp_hash\fR method with symmetric | |
2125 | L3/L4 hash algorithm, unless the weighted group buckets cannot be mapped to | |
2126 | a maximum of 64 dp_hash values with sufficient accuracy. | |
2127 | In those rare cases Open vSwitch 2.10 and later fall back to the \fBhash\fR | |
2128 | method with the default set of hash fields. | |
53cc166a | 2129 | .RS |
53cc166a JR |
2130 | .IP \fBdp_hash\fR |
2131 | Use a datapath computed hash value. The hash algorithm varies accross | |
2132 | different datapath implementations. \fBdp_hash\fR uses the upper 32 | |
2133 | bits of the \fBselection_method_param\fR as the datapath hash | |
06db81cc JS |
2134 | algorithm selector. The supported values are \fB0\fR (corresponding to |
2135 | hash computation over the IP 5-tuple) and \fB1\fR (corresponding to a | |
2136 | \fIsymmetric\fR hash computation over the IP 5-tuple). Selecting specific | |
2137 | fields with the \fBfields\fR option is not supported with \fBdp_hash\fR). | |
2138 | The lower 32 bits are used as the hash basis. | |
53cc166a JR |
2139 | .IP |
2140 | Using \fBdp_hash\fR has the advantage that it does not require the | |
2141 | generated datapath flows to exact match any additional packet header | |
2142 | fields. For example, even if multiple TCP connections thus hashed to | |
2143 | different select group buckets have different source port numbers, | |
2144 | generally all of them would be handled with a small set of already | |
2145 | established datapath flows, resulting in less latency for TCP SYN | |
2146 | packets. The downside is that the shared datapath flows must match | |
2147 | each packet twice, as the datapath hash value calculation happens only | |
2148 | when needed, and a second match is required to match some bits of its | |
2149 | value. This double-matching incurs a small additional latency cost | |
2150 | for each packet, but this latency is orders of magnitude less than the | |
2151 | latency of creating new datapath flows for new TCP connections. | |
06db81cc JS |
2152 | .IP \fBhash\fR |
2153 | Use a hash computed over the fields specified with the \fBfields\fR | |
2154 | option, see below. If no hash fields are specified, \fBhash\fR defaults | |
2155 | to a symmetric hash over the combination of MAC addresses, VLAN tags, | |
2156 | Ether type, IP addresses and L4 port numbers. \fBhash\fR uses the | |
2157 | \fBselection_method_param\fR as the hash basis. | |
2158 | .IP | |
2159 | Note that the hashed fields become exact matched by the datapath | |
2160 | flows. For example, if the TCP source port is hashed, the created | |
2161 | datapath flows will match the specific TCP source port value present | |
2162 | in the packet received. Since each TCP connection generally has a | |
2163 | different source port value, a separate datapath flow will be need to | |
2164 | be inserted for each TCP connection thus hashed to a select group | |
2165 | bucket. | |
53cc166a | 2166 | .RE |
68dfc25b | 2167 | .IP |
06db81cc | 2168 | This option uses a Netronome OpenFlow extension which is only supported |
b879391e SH |
2169 | when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later. |
2170 | ||
2171 | .IP \fBselection_method_param\fR=\fIparam\fR | |
2172 | 64-bit integer parameter to the selection method selected by the | |
2173 | \fBselection_method\fR field. The parameter's use is defined by the | |
2174 | lower-layer that implements the \fBselection_method\fR. It is optional if | |
2175 | the \fBselection_method\fR field is specified as a non-empty string. | |
2176 | Prohibited otherwise. The default value is zero. | |
2177 | .IP | |
06db81cc | 2178 | This option uses a Netronome OpenFlow extension which is only supported |
b879391e SH |
2179 | when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later. |
2180 | ||
68dfc25b BP |
2181 | .IP \fBfields\fR=\fIfield\fR |
2182 | .IQ \fBfields(\fIfield\fR[\fB=\fImask\fR]\fR...\fB)\fR | |
b879391e | 2183 | The field parameters to selection method selected by the |
60dfb5ed JR |
2184 | \fBselection_method\fR field. The syntax is described in \fBFlow |
2185 | Syntax\fR with the additional restrictions that if a value is provided | |
2186 | it is treated as a wildcard mask and wildcard masks following a slash | |
2187 | are prohibited. The pre-requisites of fields must be provided by any | |
2188 | flows that output to the group. The use of the fields is defined by | |
2189 | the lower-layer that implements the \fBselection_method\fR. They are | |
2190 | optional if the \fBselection_method\fR field is specified as ``hash', | |
2191 | prohibited otherwise. The default is no fields. | |
b879391e SH |
2192 | .IP |
2193 | This option will use a Netronome OpenFlow extension which is only supported | |
2194 | when using Open vSwitch 2.4 and later with OpenFlow 1.5 and later. | |
2195 | ||
7395c052 NZ |
2196 | .IP \fBbucket\fR=\fIbucket_parameters\fR |
2197 | The \fBadd-group\fR, \fBadd-groups\fR and \fBmod-group\fR commands | |
2198 | require at least one bucket field. Bucket fields must appear after | |
2199 | all other fields. | |
2200 | . | |
2201 | Multiple bucket fields to specify multiple buckets. | |
2202 | The order in which buckets are specified corresponds to their order in | |
2203 | the group. If the type of the group is "indirect" then only one group may | |
2204 | be specified. | |
2205 | . | |
2206 | \fIbucket_parameters\fR consists of a list of \fIfield\fB=\fIvalue\fR | |
2207 | assignments, separated by commas or white space followed by a | |
2208 | comma-separated list of actions. | |
7395c052 NZ |
2209 | The fields for \fIbucket_parameters\fR are: |
2210 | . | |
2211 | .RS | |
2d5d050c SH |
2212 | .IP \fBbucket_id=\fIid\fR |
2213 | The 32-bit integer group id of the bucket. Values greater than | |
2214 | 0xffffff00 are reserved. | |
2215 | . | |
2216 | This field was added in Open vSwitch 2.4 to conform with the OpenFlow | |
d3cb080e | 2217 | 1.5 specification. It is not supported when earlier versions |
2d5d050c SH |
2218 | of OpenFlow are used. Open vSwitch will automatically allocate bucket |
2219 | ids when they are not specified. | |
f1457c26 TG |
2220 | .IP \fBactions=\fR[\fIaction\fR][\fB,\fIaction\fR...]\fR |
2221 | The syntax of actions are identical to the \fBactions=\fR field described in | |
6dd3c787 | 2222 | \fBFlow Syntax\fR above. Specifying \fBactions=\fR is optional, any unknown |
f1457c26 | 2223 | bucket parameter will be interpreted as an action. |
7395c052 NZ |
2224 | .IP \fBweight=\fIvalue\fR |
2225 | The relative weight of the bucket as an integer. This may be used by the switch | |
2226 | during bucket select for groups whose \fBtype\fR is \fBselect\fR. | |
2227 | .IP \fBwatch_port=\fIport\fR | |
2228 | Port used to determine liveness of group. | |
2229 | This or the \fBwatch_group\fR field is required | |
2230 | for groups whose \fBtype\fR is \fBff\fR or \fBfast_failover\fR. | |
2231 | .IP \fBwatch_group=\fIgroup_id\fR | |
2232 | Group identifier of group used to determine liveness of group. | |
2233 | This or the \fBwatch_port\fR field is required | |
2234 | for groups whose \fBtype\fR is \fBff\fR or \fBfast_failover\fR. | |
2235 | .RE | |
2236 | . | |
3200ed58 JR |
2237 | .SS "Meter Syntax" |
2238 | .PP | |
2239 | The meter table commands accept an argument that describes a meter. | |
2240 | Such meter descriptions comprise a series \fIfield\fB=\fIvalue\fR | |
2241 | assignments, separated by commas or white space. | |
2242 | (Embedding spaces into a group description normally requires | |
2243 | quoting to prevent the shell from breaking the description into | |
2244 | multiple arguments.). Unless noted otherwise only the last instance | |
2245 | of each field is honoured. | |
2246 | .PP | |
2247 | .IP \fBmeter=\fIid\fR | |
76b05258 JP |
2248 | The identifier for the meter. An integer is used to specify a |
2249 | user-defined meter. In addition, the keywords "all", "controller", and | |
2250 | "slowpath", are also supported as virtual meters. The "controller" and | |
2251 | "slowpath" virtual meters apply to packets sent to the controller and to | |
2252 | the OVS userspace, respectively. | |
2253 | .IP | |
3200ed58 | 2254 | When this field is specified in \fBdel-meter\fR, \fBdump-meter\fR, or |
76b05258 JP |
2255 | \fBmeter-stats\fR, the keyword "all" may be used to designate all |
2256 | meters. This field is required, except for \fBmeter-stats\fR, which | |
2257 | dumps all stats when this field is not specified. | |
3200ed58 JR |
2258 | .IP \fBkbps\fR |
2259 | .IQ \fBpktps\fR | |
330f6f53 JP |
2260 | The unit for the \fBrate\fR and \fBburst_size\fR band parameters. |
2261 | \fBkbps\fR specifies kilobits per second, and \fBpktps\fR specifies | |
2262 | packets per second. A unit is required for the \fBadd-meter\fR and | |
2263 | \fBmod-meter\fR commands. | |
3200ed58 JR |
2264 | |
2265 | .IP \fBburst\fR | |
330f6f53 JP |
2266 | If set, enables burst support for meter bands through the \fBburst_size\fR |
2267 | parameter. | |
3200ed58 JR |
2268 | |
2269 | .IP \fBstats\fR | |
330f6f53 | 2270 | If set, enables the collection of meter and band statistics. |
3200ed58 JR |
2271 | |
2272 | .IP \fBbands\fR=\fIband_parameters\fR | |
2273 | The \fBadd-meter\fR and \fBmod-meter\fR commands require at least one | |
2274 | band specification. Bands must appear after all other fields. | |
2275 | .RS | |
2276 | .IP \fBtype=\fItype\fR | |
2277 | The type of the meter band. This keyword starts a new band specification. | |
2278 | Each band specifies a rate above which the band is to take some action. The | |
2279 | action depends on the band type. If multiple bands' rate is exceeded, then | |
2280 | the band with the highest rate among the exceeded bands is selected. | |
2281 | The following keywords designate the allowed | |
2282 | meter band types: | |
2283 | .RS | |
2284 | .IP \fBdrop\fR | |
2285 | Drop packets exceeding the band's rate limit. | |
2286 | .RE | |
2287 | . | |
2288 | .IP "The other \fIband_parameters\fR are:" | |
2289 | .IP \fBrate=\fIvalue\fR | |
2290 | The relative rate limit for this band, in kilobits per second or packets per | |
330f6f53 | 2291 | second, depending on whether \fBkbps\fR or \fBpktps\fR was specified. |
96660ed1 | 2292 | .IP \fBburst_size=\fIsize\fR |
330f6f53 JP |
2293 | If \fBburst\fR is specified for the meter entry, configures the maximum |
2294 | burst allowed for the band in kilobits or packets, depending on whether | |
2295 | \fBkbps\fR or \fBpktps\fR was specified. If unspecified, the switch is | |
2296 | free to select some reasonable value depending on its configuration. | |
3200ed58 JR |
2297 | .RE |
2298 | . | |
064af421 BP |
2299 | .SH OPTIONS |
2300 | .TP | |
4e312e69 | 2301 | \fB\-\-strict\fR |
064af421 | 2302 | Uses strict matching when running flow modification commands. |
a9b4a41a | 2303 | . |
50f96b10 BP |
2304 | .IP "\fB\-\-names\fR" |
2305 | .IQ "\fB\-\-no\-names\fR" | |
4bc938cc BP |
2306 | Every OpenFlow port has a name and a number, and every OpenFlow flow |
2307 | table has a number and sometimes a name. By default, \fBovs\-ofctl\fR | |
2308 | commands accept both port and table names and numbers, and they | |
2309 | display port and table names if \fBovs\-ofctl\fR is running on an | |
2310 | interactive console, numbers otherwise. With \fB\-\-names\fR, | |
2311 | \fBovs\-ofctl\fR commands both accept and display port and table | |
2312 | names; with \fB\-\-no\-names\fR, commands neither accept nor display | |
2313 | port and table names. | |
2314 | .IP | |
2315 | If a port or table name contains special characters or might be | |
2316 | confused with a keyword within a flow, it may be enclosed in double | |
2317 | quotes (escaped from the shell). If necessary, JSON-style escape | |
2318 | sequences may be used inside quotes, as specified in RFC 7159. When | |
2319 | it displays port and table names, \fBovs\-ofctl\fR quotes any name | |
2320 | that does not start with a letter followed by letters or digits. | |
2321 | .IP | |
2322 | Open vSwitch added support for port names and these options. Open | |
2323 | vSwitch 2.10 added support for table names. Earlier versions always | |
50f96b10 BP |
2324 | behaved as if \fB\-\-no\-names\fR were specified. |
2325 | .IP | |
2326 | Open vSwitch does not place its own limit on the length of port names, | |
2327 | but OpenFlow 1.0 to 1.5 limit port names to 15 bytes and OpenFlow 1.6 | |
2328 | limits them to 63 bytes. Because \fRovs\-ofctl\fR uses OpenFlow to | |
2329 | retrieve the mapping between port names and numbers, names longer than | |
2330 | this limit will be truncated for both display and acceptance. | |
2331 | Truncation can also cause long names that are different to appear to | |
2332 | be the same; when a switch has two ports with the same (truncated) | |
2333 | name, \fBovs\-ofctl\fR refuses to display or accept the name, using | |
2334 | the number instead. | |
4bc938cc BP |
2335 | .IP |
2336 | OpenFlow and Open vSwitch limit table names to 32 bytes. | |
50f96b10 | 2337 | . |
1b3758c3 BP |
2338 | .IP "\fB\-\-stats\fR" |
2339 | .IQ "\fB\-\-no\-stats\fR" | |
2340 | The \fBdump\-flows\fR command by default, or with \fB\-\-stats\fR, | |
2341 | includes flow duration, packet and byte counts, and idle and hard age | |
2342 | in its output. With \fB\-\-no\-stats\fR, it omits all of these, as | |
2343 | well as cookie values and table IDs if they are zero. | |
2344 | . | |
1f4a7252 RM |
2345 | .IP "\fB\-\-read-only\fR" |
2346 | Do not execute read/write commands. | |
2347 | . | |
db5076ee | 2348 | .IP "\fB\-\-bundle\fR" |
39c94593 | 2349 | Execute flow mods as an OpenFlow 1.4 atomic bundle transaction. |
db5076ee JR |
2350 | .RS |
2351 | .IP \(bu | |
2352 | Within a bundle, all flow mods are processed in the order they appear | |
39c94593 JR |
2353 | and as a single atomic transaction, meaning that if one of them fails, |
2354 | the whole transaction fails and none of the changes are made to the | |
2355 | \fIswitch\fR's flow table, and that each given datapath packet | |
2356 | traversing the OpenFlow tables sees the flow tables either as before | |
2357 | the transaction, or after all the flow mods in the bundle have been | |
2358 | successfully applied. | |
db5076ee JR |
2359 | .IP \(bu |
2360 | The beginning and the end of the flow table modification commands in a | |
2361 | bundle are delimited with OpenFlow 1.4 bundle control messages, which | |
2362 | makes it possible to stream the included commands without explicit | |
2363 | OpenFlow barriers, which are otherwise used after each flow table | |
2364 | modification command. This may make large modifications execute | |
2365 | faster as a bundle. | |
2366 | .IP \(bu | |
2367 | Bundles require OpenFlow 1.4 or higher. An explicit \fB-O | |
2368 | OpenFlow14\fR option is not needed, but you may need to enable | |
2369 | OpenFlow 1.4 support for OVS by setting the OVSDB \fIprotocols\fR | |
2370 | column in the \fIbridge\fR table. | |
db5076ee JR |
2371 | .RE |
2372 | . | |
a53a8efa SH |
2373 | .so lib/ofp-version.man |
2374 | . | |
27527aa0 BP |
2375 | .IP "\fB\-F \fIformat\fR[\fB,\fIformat\fR...]" |
2376 | .IQ "\fB\-\-flow\-format=\fIformat\fR[\fB,\fIformat\fR...]" | |
2377 | \fBovs\-ofctl\fR supports the following individual flow formats, any | |
2378 | number of which may be listed as \fIformat\fR: | |
88ca35ee | 2379 | .RS |
27527aa0 BP |
2380 | .IP "\fBOpenFlow10\-table_id\fR" |
2381 | This is the standard OpenFlow 1.0 flow format. All OpenFlow switches | |
2382 | and all versions of Open vSwitch support this flow format. | |
88ca35ee | 2383 | . |
27527aa0 BP |
2384 | .IP "\fBOpenFlow10+table_id\fR" |
2385 | This is the standard OpenFlow 1.0 flow format plus a Nicira extension | |
2386 | that allows \fBovs\-ofctl\fR to specify the flow table in which a | |
2387 | particular flow should be placed. Open vSwitch 1.2 and later supports | |
2388 | this flow format. | |
2389 | . | |
2390 | .IP "\fBNXM\-table_id\fR (Nicira Extended Match)" | |
88ca35ee BP |
2391 | This Nicira extension to OpenFlow is flexible and extensible. It |
2392 | supports all of the Nicira flow extensions, such as \fBtun_id\fR and | |
27527aa0 BP |
2393 | registers. Open vSwitch 1.1 and later supports this flow format. |
2394 | . | |
2395 | .IP "\fBNXM+table_id\fR (Nicira Extended Match)" | |
2396 | This combines Nicira Extended match with the ability to place a flow | |
2397 | in a specific table. Open vSwitch 1.2 and later supports this flow | |
2398 | format. | |
e71bff1b BP |
2399 | . |
2400 | .IP "\fBOXM-OpenFlow12\fR" | |
2401 | .IQ "\fBOXM-OpenFlow13\fR" | |
aa233d57 | 2402 | .IQ "\fBOXM-OpenFlow14\fR" |
8d348579 BP |
2403 | .IQ "\fBOXM-OpenFlow15\fR" |
2404 | .IQ "\fBOXM-OpenFlow16\fR" | |
e71bff1b | 2405 | These are the standard OXM (OpenFlow Extensible Match) flow format in |
8d348579 | 2406 | OpenFlow 1.2 and later. |
88ca35ee | 2407 | .RE |
27527aa0 | 2408 | . |
88ca35ee | 2409 | .IP |
27527aa0 BP |
2410 | \fBovs\-ofctl\fR also supports the following abbreviations for |
2411 | collections of flow formats: | |
2412 | .RS | |
2413 | .IP "\fBany\fR" | |
aa233d57 | 2414 | Any supported flow format. |
27527aa0 BP |
2415 | .IP "\fBOpenFlow10\fR" |
2416 | \fBOpenFlow10\-table_id\fR or \fBOpenFlow10+table_id\fR. | |
2417 | .IP "\fBNXM\fR" | |
2418 | \fBNXM\-table_id\fR or \fBNXM+table_id\fR. | |
e71bff1b | 2419 | .IP "\fBOXM\fR" |
aa233d57 | 2420 | \fBOXM-OpenFlow12\fR, \fBOXM-OpenFlow13\fR, or \fBOXM-OpenFlow14\fR. |
27527aa0 | 2421 | .RE |
4f564f8d | 2422 | . |
27527aa0 BP |
2423 | .IP |
2424 | For commands that modify the flow table, \fBovs\-ofctl\fR by default | |
2425 | negotiates the most widely supported flow format that supports the | |
2426 | flows being added. For commands that query the flow table, | |
2427 | \fBovs\-ofctl\fR by default uses the most advanced format supported by | |
2428 | the switch. | |
2429 | .IP | |
2430 | This option, where \fIformat\fR is a comma-separated list of one or | |
2431 | more of the formats listed above, limits \fBovs\-ofctl\fR's choice of | |
2432 | flow format. If a command cannot work as requested using one of the | |
2433 | specified flow formats, \fBovs\-ofctl\fR will report a fatal error. | |
54834960 EJ |
2434 | . |
2435 | .IP "\fB\-P \fIformat\fR" | |
2436 | .IQ "\fB\-\-packet\-in\-format=\fIformat\fR" | |
6409e008 | 2437 | \fBovs\-ofctl\fR supports the following ``packet-in'' formats, in order of |
54834960 EJ |
2438 | increasing capability: |
2439 | .RS | |
6409e008 BP |
2440 | .IP "\fBstandard\fR" |
2441 | This uses the \fBOFPT_PACKET_IN\fR message, the standard ``packet-in'' | |
2442 | message for any given OpenFlow version. Every OpenFlow switch that | |
2443 | supports a given OpenFlow version supports this format. | |
2444 | . | |
2445 | .IP "\fBnxt_packet_in\fR" | |
2446 | This uses the \fBNXT_PACKET_IN\fR message, which adds many of the | |
2447 | capabilities of the OpenFlow 1.1 and later ``packet-in'' messages | |
2448 | before those OpenFlow versions were available in Open vSwitch. Open | |
2449 | vSwitch 1.1 and later support this format. Only Open vSwitch 2.6 and | |
2450 | later, however, support it for OpenFlow 1.1 and later (but there is | |
2451 | little reason to use it with those versions of OpenFlow). | |
2452 | . | |
2453 | .IP "\fBnxt_packet_in2\fR" | |
2454 | This uses the \fBNXT_PACKET_IN2\fR message, which is extensible and | |
bdcad671 BP |
2455 | should avoid the need to define new formats later. In particular, |
2456 | this format supports passing arbitrary user-provided data to a | |
2457 | controller using the \fBuserdata\fB option on the \fBcontroller\fR | |
2458 | action. Open vSwitch 2.6 and later support this format. | |
54834960 EJ |
2459 | . |
2460 | .RE | |
2461 | .IP | |
6409e008 BP |
2462 | Without this option, \fBovs\-ofctl\fR prefers \fBnxt_packet_in2\fR if |
2463 | the switch supports it. Otherwise, if OpenFlow 1.0 is in use, | |
2464 | \fBovs\-ofctl\fR prefers \fBnxt_packet_in\fR if the switch supports | |
2465 | it. Otherwise, \fBovs\-ofctl\fR falls back to the \fBstandard\fR | |
2466 | packet-in format. When this option is specified, \fBovs\-ofctl\fR | |
2467 | insists on the selected format. If the switch does not support the | |
2468 | requested format, \fBovs\-ofctl\fR will report a fatal error. | |
2469 | .IP | |
2470 | Before version 2.6, Open vSwitch called \fBstandard\fR format | |
2471 | \fBopenflow10\fR and \fBnxt_packet_in\fR format \fBnxm\fR, and | |
2472 | \fBovs\-ofctl\fR still accepts these names as synonyms. (The name | |
2473 | \fBopenflow10\fR was a misnomer because this format actually varies | |
2474 | from one OpenFlow version to another; it is not consistently OpenFlow | |
2475 | 1.0 format. Similarly, when \fBnxt_packet_in2\fR was introduced, the | |
2476 | name \fBnxm\fR became confusing because it also uses OXM/NXM.) | |
2477 | . | |
2478 | .IP | |
2479 | This option affects only the \fBmonitor\fR command. | |
54834960 | 2480 | . |
0c9560b7 BP |
2481 | .IP "\fB\-\-timestamp\fR" |
2482 | Print a timestamp before each received packet. This option only | |
f3dd1419 BP |
2483 | affects the \fBmonitor\fR, \fBsnoop\fR, and \fBofp\-parse\-pcap\fR |
2484 | commands. | |
0c9560b7 | 2485 | . |
4f564f8d BP |
2486 | .IP "\fB\-m\fR" |
2487 | .IQ "\fB\-\-more\fR" | |
2488 | Increases the verbosity of OpenFlow messages printed and logged by | |
2489 | \fBovs\-ofctl\fR commands. Specify this option more than once to | |
2490 | increase verbosity further. | |
1eb85ef5 | 2491 | . |
bdcc5925 BP |
2492 | .IP \fB\-\-sort\fR[\fB=\fIfield\fR] |
2493 | .IQ \fB\-\-rsort\fR[\fB=\fIfield\fR] | |
2494 | Display output sorted by flow \fIfield\fR in ascending | |
2495 | (\fB\-\-sort\fR) or descending (\fB\-\-rsort\fR) order, where | |
2496 | \fIfield\fR is any of the fields that are allowed for matching or | |
2497 | \fBpriority\fR to sort by priority. When \fIfield\fR is omitted, the | |
2498 | output is sorted by priority. Specify these options multiple times to | |
2499 | sort by multiple fields. | |
2500 | .IP | |
2501 | Any given flow will not necessarily specify a value for a given | |
2502 | field. This requires special treatement: | |
2503 | .RS | |
2504 | .IP \(bu | |
2505 | A flow that does not specify any part of a field that is used for sorting is | |
2506 | sorted after all the flows that do specify the field. For example, | |
2507 | \fB\-\-sort=tcp_src\fR will sort all the flows that specify a TCP | |
2508 | source port in ascending order, followed by the flows that do not | |
0d56eaf2 | 2509 | specify a TCP source port at all. |
bdcc5925 BP |
2510 | .IP \(bu |
2511 | A flow that only specifies some bits in a field is sorted as if the | |
2512 | wildcarded bits were zero. For example, \fB\-\-sort=nw_src\fR would | |
2513 | sort a flow that specifies \fBnw_src=192.168.0.0/24\fR the same as | |
2514 | \fBnw_src=192.168.0.0\fR. | |
2515 | .RE | |
2516 | .IP | |
2517 | These options currently affect only \fBdump\-flows\fR output. | |
2518 | . | |
679d3475 | 2519 | .SS "Daemon Options" |
1eb85ef5 EJ |
2520 | .ds DD \ |
2521 | \fBovs\-ofctl\fR detaches only when executing the \fBmonitor\fR or \ | |
2522 | \fBsnoop\fR commands. | |
2523 | .so lib/daemon.man | |
19945013 | 2524 | .so lib/unixctl.man |
ac300505 | 2525 | .SS "Public Key Infrastructure Options" |
84ee7bcf | 2526 | .so lib/ssl.man |
064af421 | 2527 | .so lib/vlog.man |
e7019d99 | 2528 | .so lib/colors.man |
064af421 | 2529 | .so lib/common.man |
a9b4a41a | 2530 | . |
1eb85ef5 | 2531 | .SH "RUNTIME MANAGEMENT COMMANDS" |
96761f58 BP |
2532 | \fBovs\-appctl\fR(8) can send commands to a running \fBovs\-ofctl\fR |
2533 | process. The supported commands are listed below. | |
2534 | . | |
1eb85ef5 | 2535 | .IP "\fBexit\fR" |
96761f58 BP |
2536 | Causes \fBovs\-ofctl\fR to gracefully terminate. This command applies |
2537 | only when executing the \fBmonitor\fR or \fBsnoop\fR commands. | |
2538 | . | |
1e1d00a5 BP |
2539 | .IP "\fBofctl/set\-output\-file \fIfile\fR" |
2540 | Causes all subsequent output to go to \fIfile\fR instead of stderr. | |
2541 | This command applies only when executing the \fBmonitor\fR or | |
2542 | \fBsnoop\fR commands. | |
2543 | . | |
96761f58 BP |
2544 | .IP "\fBofctl/send \fIofmsg\fR..." |
2545 | Sends each \fIofmsg\fR, specified as a sequence of hex digits that | |
2546 | express an OpenFlow message, on the OpenFlow connection. This command | |
2547 | is useful only when executing the \fBmonitor\fR command. | |
2548 | . | |
6dd3c787 JR |
2549 | .IP "\fBofctl/packet\-out \fIpacket-out\fR" |
2550 | Sends an OpenFlow PACKET_OUT message specified in \fBPacket\-Out | |
2551 | Syntax\fR, on the OpenFlow connection. See \fBPacket\-Out Syntax\fR | |
2552 | section for more information. This command is useful only when | |
2553 | executing the \fBmonitor\fR command. | |
2554 | . | |
bb638b9a BP |
2555 | .IP "\fBofctl/barrier\fR" |
2556 | Sends an OpenFlow barrier request on the OpenFlow connection and waits | |
2557 | for a reply. This command is useful only for the \fBmonitor\fR | |
2558 | command. | |
2559 | . | |
064af421 | 2560 | .SH EXAMPLES |
a9b4a41a | 2561 | . |
045b2e5c BP |
2562 | The following examples assume that \fBovs\-vswitchd\fR has a bridge |
2563 | named \fBbr0\fR configured. | |
a9b4a41a | 2564 | . |
064af421 | 2565 | .TP |
045b2e5c | 2566 | \fBovs\-ofctl dump\-tables br0\fR |
064af421 BP |
2567 | Prints out the switch's table stats. (This is more interesting after |
2568 | some traffic has passed through.) | |
a9b4a41a | 2569 | . |
064af421 | 2570 | .TP |
045b2e5c | 2571 | \fBovs\-ofctl dump\-flows br0\fR |
064af421 | 2572 | Prints the flow entries in the switch. |
a9b4a41a | 2573 | . |
5b10f305 OS |
2574 | .TP |
2575 | \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 | |
2576 | \fBovs\-ofctl add\-flow table=1 priority=0 actions=flood\fR | |
2577 | Implements a level 2 MAC learning switch using the learn. | |
2578 | . | |
2579 | .TP | |
2580 | \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 | |
2581 | In this use of a learn action, the first packet from each source MAC | |
2582 | will be sent to port 2. Subsequent packets will be output to port 3, | |
21b2fa61 JR |
2583 | with an idle timeout of 10 seconds. NXM field names and match field |
2584 | names are both accepted, e.g. \fBNXM_NX_REG0\fR or \fBreg0\fR for the | |
2585 | first register, and empty brackets may be omitted. | |
2586 | .IP | |
5b10f305 OS |
2587 | Additional examples may be found documented as part of related sections. |
2588 | . | |
064af421 | 2589 | .SH "SEE ALSO" |
a9b4a41a | 2590 | . |
96fee5e0 | 2591 | .BR ovs\-fields (7), |
064af421 | 2592 | .BR ovs\-appctl (8), |
96fee5e0 | 2593 | .BR ovs\-vswitchd (8), |
29089a54 | 2594 | .BR ovs\-vswitchd.conf.db (8) |