]>
Commit | Line | Data |
---|---|---|
be51cd41 BP |
1 | <?xml version="1.0" encoding="utf-8"?> |
2 | <actions> | |
3 | <h1>Introduction</h1> | |
4 | ||
5 | <p> | |
6 | This document aims to comprehensively document all of the OpenFlow actions | |
7 | and instructions, both standard and non-standard, supported by Open | |
8 | vSwitch, regardless of origin. The document includes information of | |
9 | interest to Open vSwitch users, such as the semantics of each supported | |
10 | action and the syntax used by Open vSwitch tools, and to developers seeking | |
11 | to build controllers and switches compatible with Open vSwitch, such as the | |
12 | wire format for each supported message. | |
13 | </p> | |
14 | ||
15 | <h2>Actions</h2> | |
16 | ||
17 | <p> | |
18 | In this document, we define an <dfn>action</dfn> as an OpenFlow action, | |
19 | which is a kind of command that specifies what to do with a packet. | |
20 | Actions are used in OpenFlow flows to describe what to do when the flow | |
21 | matches a packet, and in a few other places in OpenFlow. Each version of | |
22 | the OpenFlow specification defines standard actions, and beyond that many | |
23 | OpenFlow switches, including Open vSwitch, implement extensions to the | |
24 | standard. | |
25 | </p> | |
26 | ||
27 | <p> | |
28 | OpenFlow groups actions in two ways: as an <dfn>action list</dfn> or an | |
29 | <dfn>action set</dfn>, described below. | |
30 | </p> | |
31 | ||
32 | <h3>Action Lists</h3> | |
33 | ||
34 | <p> | |
35 | An <dfn>action list</dfn>, a concept present in every version of OpenFlow, | |
36 | is simply an ordered sequence of actions. The OpenFlow specifications | |
37 | require a switch to execute actions within an action list in the order | |
38 | specified, and to refuse to execute an action list entirely if it cannot | |
39 | implement the actions in that order [OpenFlow 1.0, section 3.3], with one | |
40 | exception: when an action list outputs multiple packets, the switch may | |
41 | output the packets in an order different from that specified. Usually, | |
42 | this exception is not important, especially in the common case when the | |
43 | packets are output to different ports. | |
44 | </p> | |
45 | ||
46 | <h3>Action Sets</h3> | |
47 | ||
48 | <p> | |
49 | OpenFlow 1.1 introduced the concept of an <dfn>action set</dfn>. An action | |
50 | set is also a sequence of actions, but the switch reorders the actions and | |
51 | drops duplicates according to rules specified in the OpenFlow | |
52 | specifications. Because of these semantics, some standard OpenFlow actions | |
53 | cannot usefully be included in an action set. For some, but not all, Open | |
54 | vSwitch extension actions, Open vSwitch defines its own action set | |
55 | semantics and ordering. | |
56 | </p> | |
57 | ||
58 | <p> | |
59 | The OpenFlow pipeline has an action set associated with it as a packet is | |
60 | processed. After pipeline processing is otherwise complete, the switch | |
61 | executes the actions in the action set. | |
62 | </p> | |
63 | ||
64 | <p> | |
65 | Open vSwitch applies actions in an action set in the following order: | |
66 | Except as noted otherwise below, the action set only executes at most a | |
67 | single action of each type, and when more than one action of a given type | |
68 | is present, the one added to the set later replaces the earlier action: | |
69 | </p> | |
70 | ||
71 | <ol> | |
72 | <li><code>strip_vlan</code></li> | |
73 | <li><code>pop_mpls</code></li> | |
74 | <li><code>decap</code></li> | |
75 | <li><code>encap</code></li> | |
76 | <li><code>push_mpls</code></li> | |
77 | <li><code>push_vlan</code></li> | |
78 | <li><code>dec_ttl</code></li> | |
79 | <li><code>dec_mpls_ttl</code></li> | |
80 | <li><code>dec_nsh_ttl</code></li> | |
81 | <li> | |
82 | <p> | |
83 | All of the following actions are executed in the order added to the | |
84 | action set, with cumulative effect. That is, when multiple actions | |
85 | modify the same part of a field, the later modification takes effect, | |
86 | and when they modify different parts of a field (or different fields), | |
87 | then both modifications are applied: | |
88 | </p> | |
89 | ||
90 | <ul> | |
91 | <li><code>load</code></li> | |
92 | <li><code>move</code></li> | |
93 | <li><code>mod_dl_dst</code></li> | |
94 | <li><code>mod_dl_src</code></li> | |
95 | <li><code>mod_nw_dst</code></li> | |
96 | <li><code>mod_nw_src</code></li> | |
97 | <li><code>mod_nw_tos</code></li> | |
98 | <li><code>mod_nw_ecn</code></li> | |
99 | <li><code>mod_nw_ttl</code></li> | |
100 | <li><code>mod_tp_dst</code></li> | |
101 | <li><code>mod_tp_src</code></li> | |
102 | <li><code>mod_vlan_pcp</code></li> | |
103 | <li><code>mod_vlan_vid</code></li> | |
104 | <li><code>set_field</code></li> | |
105 | <li><code>set_tunnel</code></li> | |
106 | <li><code>set_tunnel64</code></li> | |
107 | </ul> | |
108 | </li> | |
109 | <li><code>set_queue</code></li> | |
110 | <li> | |
111 | <code>group</code>, <code>output</code>, <code>resubmit</code>, | |
112 | <code>ct_clear</code>, or <code>ct</code>. If more than one of these | |
113 | actions is present, then the one listed earliest above is executed and | |
114 | the others are ignored, regardless of the order in which they were added | |
115 | to the action set. (If none of these actions is present, the action set | |
116 | has no real effect, because the modified packet is not sent anywhere and | |
117 | thus the modifications are not visible.) | |
118 | </li> | |
119 | </ol> | |
120 | ||
121 | <p> | |
122 | An action set may only contain the actions listed above. | |
123 | </p> | |
124 | ||
125 | <h2>Error Handling</h2> | |
126 | ||
127 | <p> | |
128 | Packet processing can encounter a variety of errors: | |
129 | </p> | |
130 | ||
131 | <dl> | |
132 | <dt>Bridge not found</dt> | |
133 | <dd> | |
134 | <p> | |
135 | Open vSwitch supports an extension to the standard OpenFlow | |
136 | <code>controller</code> action called a ``continuation,'' which allows | |
137 | the controller to interrupt and later resume the processing of a packet | |
138 | through the switch pipeline. This error occurs when such a packet's | |
139 | processing cannot be resumed, e.g. because the bridge processing it has | |
140 | been destroyed. Open vSwitch reports this error to the controller as | |
141 | Open vSwitch extension error <code>NXR_STALE</code>. | |
142 | </p> | |
143 | ||
144 | <p> | |
145 | This error prevents packet processing entirely. | |
146 | </p> | |
147 | </dd> | |
148 | ||
149 | <dt>Recursion too deep</dt> | |
150 | <dd> | |
151 | <p> | |
152 | While processing a given packet, Open vSwitch limits the flow table | |
153 | recursion depth to 64, to ensure that packet processing uses a finite | |
154 | amount of time and space. Actions that count against the recursion | |
155 | limit include <code>resubmit</code> from a given OpenFlow table to the | |
156 | same or an earlier table, <code>group</code>, and <code>output</code> | |
157 | to patch ports. | |
158 | </p> | |
159 | ||
160 | <p> | |
161 | A <code>resubmit</code> from one table to a later one (or, | |
162 | equivalently. a <code>goto_table</code> instruction) does not count | |
163 | against the depth limit because resubmits to strictly monotonically | |
164 | increasing tables will eventually terminate. OpenFlow tables are most | |
165 | commonly traversed in numerically increasing order, so this limit has | |
166 | little effect on conventionally designed OpenFlow pipelines. | |
167 | </p> | |
168 | ||
169 | <p> | |
170 | This error terminates packet processing. Any previous side effects | |
171 | (e.g. output actions) are retained. | |
172 | </p> | |
173 | ||
174 | <p> | |
175 | Usually this error indicates a loop or other bug in the OpenFlow flow | |
176 | tables. To assist debugging, when this error occurs, Open vSwitch 2.10 | |
177 | and later logs a trace of the packet execution, as if by | |
178 | <code>ovs-appctl ofproto/trace</code>, rate-limited to one per minute | |
179 | to reduce the log volume. | |
180 | </p> | |
181 | </dd> | |
182 | ||
183 | <dt>Too many resubmits</dt> | |
184 | <dd> | |
185 | <p> | |
186 | Open vSwitch limits the total number of <code>resubmit</code> actions | |
187 | that a given packet can execute to 4,096. For this purpose, | |
188 | <code>goto_table</code> instructions and output to the | |
189 | <code>table</code> port are treated like <code>resubmit</code>. This | |
190 | limits the amount of time to process a single packet. | |
191 | </p> | |
192 | ||
193 | <p> | |
194 | Unlike the limit on recursion depth, the limit on resubmits counts all | |
195 | resubmits, regardless of direction. | |
196 | </p> | |
197 | ||
198 | <p> | |
199 | This error has the same effect, including logging, as exceeding the | |
200 | recursion depth limit. | |
201 | </p> | |
202 | </dd> | |
203 | ||
204 | <dt>Stack too deep</dt> | |
205 | <dd> | |
206 | <p> | |
207 | Open vSwitch limits the amount of data that the <code>push</code> | |
208 | action can put onto the stack at one time to 64 kB of data. | |
209 | </p> | |
210 | ||
211 | <p> | |
212 | This error terminates packet processing. Any previous side effects | |
213 | (e.g. output actions) are retained. | |
214 | </p> | |
215 | </dd> | |
216 | ||
217 | <dt>No recirculation context</dt> | |
218 | <dt>Recirculation conflict</dt> | |
219 | <dd> | |
220 | These errors indicate internal errors inside Open vSwitch and should | |
221 | generally not occur. If you notice recurring log messages about these | |
222 | errors, please report a bug. | |
223 | </dd> | |
224 | ||
225 | <dt>Too many MPLS labels</dt> | |
226 | <dd> | |
227 | <p> | |
228 | Open vSwitch can process packets with any number of MPLS labels, but | |
229 | its ability to push and pop MPLS labels is limited, currently to 3 | |
230 | labels. Attempting to push more than the supported number of labels | |
231 | onto a packet, or to pop any number of labels from a packet with more | |
232 | than the supported number, raises this error. | |
233 | </p> | |
234 | ||
235 | <p> | |
236 | This error terminates packet processing, retaining any previous side | |
237 | effects (e.g. output actions). When this error arises within the | |
238 | execution of a group bucket, it only terminates that bucket's | |
239 | execution, not packet processing overall. | |
240 | </p> | |
241 | </dd> | |
242 | ||
243 | <dt>Invalid tunnel metadata</dt> | |
244 | <dd> | |
245 | <p> | |
246 | Open vSwitch raises this error when it processes a Geneve packet that | |
247 | has TLV options with an invalid form, e.g. where the length in a TLV | |
248 | would extend past the end of the options. | |
249 | </p> | |
250 | ||
251 | <p> | |
252 | This error prevents packet processing entirely. | |
253 | </p> | |
254 | </dd> | |
255 | ||
256 | <dt>Unsupported packet type</dt> | |
257 | <dd> | |
258 | <p> | |
259 | When a <code>encap</code> action encapsulates a packet, Open vSwitch | |
260 | raises this error if it does not support the combination of the new | |
261 | encapsulation with the current packet. <code>encap(ethernet)</code> | |
262 | raises this error if the current packet is not an L3 packet, and | |
263 | <code>encap(nsh)</code> raises this error if the current packet is not | |
264 | Ethernet, IPv4, IPv6, or NSH. | |
265 | </p> | |
266 | ||
267 | <p> | |
268 | When a <code>decap</code> action decapsulates a packet, Open vSwitch | |
269 | raises this error if it does not support the type of inner packet. | |
270 | <code>decap</code> of an Ethernet header raises this error if a VLAN | |
271 | header is present, <code>decap</code> of a NSH packet raises this error | |
272 | if the NSH inner packet is not Ethernet, IPv4, IPv6, or NSH, and | |
273 | <code>decap</code> of other types of packets is unsupported and also | |
274 | raises this error. | |
275 | </p> | |
276 | ||
277 | <p> | |
278 | This error terminates packet processing, retaining any previous side | |
279 | effects (e.g. output actions). When this error arises within the | |
280 | execution of a group bucket, it only terminates that bucket's | |
281 | execution, not packet processing overall. | |
282 | </p> | |
283 | </dd> | |
284 | </dl> | |
285 | ||
286 | <h2>Inconsistencies</h2> | |
287 | ||
288 | <p> | |
289 | OpenFlow 1.0 allows any action to be part of any flow, regardless of the | |
290 | flow's match. Some combinations do not make sense, e.g. an | |
291 | <code>set_nw_tos</code> action in a flow that matches only ARP packets or | |
292 | <code>strip_vlan</code> in a flow that matches packets without VLAN tags. | |
293 | Other combinations have varying results depending on the kind of packet | |
294 | that the flow processes, e.g. a <code>set_nw_src</code> action in a flow | |
295 | that does not match on Ethertype will be treated as a no-op when it | |
296 | processes a non-IPv4 packet. Nevertheless OVS allows all of the above in | |
297 | conformance with OpenFlow 1.0, that is, the following will succeed: | |
298 | </p> | |
299 | ||
300 | <pre> | |
301 | $ ovs-ofctl -O OpenFlow10 add-flow br0 arp,actions=mod_nw_tos:12 | |
302 | $ ovs-ofctl -O OpenFlow10 add-flow br0 dl_vlan=0xffff,actions=strip_vlan | |
303 | $ ovs-ofctl -O OpenFlow10 add-flow br0 actions=mod_nw_src:1.2.3.4 | |
304 | </pre> | |
305 | ||
306 | <p> | |
307 | Open vSwitch calls these kinds of combinations <dfn>inconsistencies</dfn> | |
308 | between match and actions. OpenFlow 1.1 and later forbid inconsistencies, | |
309 | and disallow the examples described above by preventing such flows from | |
310 | being added. All of the above, for example, will fail with an error | |
311 | message if one replaces <code>OpenFlow10</code> by <code>OpenFlow11</code>. | |
312 | </p> | |
313 | ||
314 | <p> | |
315 | OpenFlow 1.1 and later cannot detect and disallow all inconsistencies. For | |
316 | example, the <code>write_actions</code> instruction arbitrarily delays | |
317 | execution of the actions inside it, which can even be canceled with | |
318 | <code>clear_actions</code>, so that there is no way to ensure that its | |
319 | actions are consistent with the packet at the time they execute. Thus, | |
320 | actions with <code>write_actions</code> and some other contexts are exempt | |
321 | from consistency requirements. | |
322 | </p> | |
323 | ||
324 | <p> | |
325 | When OVS executes an action inconsistent with the packet, it treats it as a | |
326 | no-op. | |
327 | </p> | |
328 | ||
329 | <h2>Inter-Version Compatibility</h2> | |
330 | ||
331 | <p> | |
332 | Open vSwitch supports multiple OpenFlow versions simultaneously on a single | |
333 | switch. When actions are added with one OpenFlow version and then | |
334 | retrieved with another, Open vSwitch does its best to translate between | |
335 | them. | |
336 | </p> | |
337 | ||
338 | <p> | |
339 | Inter-version compatibility issues can still arise when different | |
340 | connections use different OpenFlow versions. Backward compatibility is the | |
341 | most obvious case. Suppose, for example, that an OpenFlow 1.1 session adds | |
342 | a flow with a <code>push_vlan</code> action, for which there is no | |
343 | equivalent in OpenFlow 1.0. If an OpenFlow 1.0 session retrieves this | |
344 | flow, Open vSwitch must somehow represent the action. | |
345 | </p> | |
346 | ||
347 | <p> | |
348 | Forward compatibility can also be an issue, because later OpenFlow versions | |
349 | sometimes remove functionality. The best example is the | |
350 | <code>enqueue</code> action from OpenFlow 1.0, which OpenFlow 1.1 removed. | |
351 | </p> | |
352 | ||
353 | <p> | |
354 | In practice, Open vSwitch uses a variety of strategies for inter-version | |
355 | compatibility: | |
356 | </p> | |
357 | ||
358 | <ul> | |
359 | <li> | |
360 | Most standard OpenFlow actions, such as <code>output</code> actions, | |
361 | translate without compatibility issues. | |
362 | </li> | |
363 | ||
364 | <li> | |
365 | Open vSwitch supports its extension actions in every OpenFlow version, so | |
366 | they do not pose inter-version compatibility problems. | |
367 | </li> | |
368 | ||
369 | <li> | |
370 | Open vSwitch sometimes adds extension actions to ensure backward or | |
371 | forward compatibility. For example, for backward compatibility with the | |
372 | <code>group</code> action added in OpenFlow 1.1, Open vSwitch includes | |
373 | an OpenFlow 1.0 extension <code>group</code> action. | |
374 | </li> | |
375 | </ul> | |
376 | ||
377 | <p> | |
378 | Perfect inter-version compatibility is not possible, so best results | |
379 | require OpenFlow connections to use a consistent version. One may enforce | |
380 | use of a particular version by setting the <code>protocols</code> column | |
381 | for a bridge, e.g. to force <code>br0</code> to use only OpenFlow 1.3: | |
382 | </p> | |
383 | ||
384 | <pre> | |
385 | ovs-vsctl set bridge br0 protocols=OpenFlow13 | |
386 | </pre> | |
387 | ||
388 | <h2>Field Specifications</h2> | |
389 | ||
390 | <p> | |
391 | Many Open vSwitch actions refer to fields. In such cases, fields may | |
392 | usually be referred to by their common names, such as <code>eth_dst</code> | |
393 | for the Ethernet destination field, or by their full OXM or NXM names, such | |
394 | as <code>NXM_OF_ETH_DST</code> or <code>OXM_OF_ETH_DST</code>. Before Open | |
395 | vSwitch 2.7, only OXM or NXM field names were accepted. | |
396 | </p> | |
397 | ||
398 | <p> | |
399 | Many actions that act on fields can also act on <dfn>subfields</dfn>, that | |
400 | is, parts of fields, written as | |
401 | <code><var>field</var>[<var>start</var>..<var>end</var>]</code>, where | |
402 | <var>start</var> is the first bit and <var>end</var> is the last bit to use | |
403 | in <var>field</var>, e.g. <code>vlan_tci[13..15]</code> for the VLAN PCP. | |
404 | A single-bit subfield may also be written as | |
405 | <code><var>field</var>[<var>offset</var>]</code>, | |
406 | e.g. <code>vlan_tci[13]</code> for the least-significant bit of the VLAN | |
407 | PCP. Empty brackets may be used to explicitly designate an entire field, | |
408 | e.g. <code>vlan_tci[]</code> for the entire 16-bit VLAN TCI header. Before | |
409 | Open vSwitch 2.7, brackets were required in field specifications. | |
410 | </p> | |
411 | ||
412 | <p> | |
413 | See <code>ovs-fields</code>(7) for a list of fields and their names. | |
414 | </p> | |
415 | ||
416 | <h2>Port Specifications</h2> | |
417 | ||
418 | <p> | |
419 | Many Open vSwitch actions refer to OpenFlow ports. In such cases, the port | |
420 | may be specified as a numeric port number in the range 0 to 65,535, | |
421 | although Open vSwitch only assigns port numbers in the range 1 through | |
422 | 62,279 to ports. OpenFlow 1.1 and later use 32-bit port numbers, but Open | |
423 | vSwitch never assigns a port number that requires more than 16 bits. | |
424 | </p> | |
425 | ||
426 | <p> | |
427 | In most contexts, the name of a port may also be used. (The most obvious | |
428 | context where a port name may not be used is in an <code>ovs-ofctl</code> | |
429 | command along with the <code>--no-names</code> option.) When a port's name | |
430 | contains punctuation or could be ambiguous with other actions, the name may | |
431 | be enclosed in double quotes, with JSON-like string escapes supported (see | |
432 | [RFC 8259]). | |
433 | </p> | |
434 | ||
435 | <p> | |
436 | Open vSwitch also supports the following standard OpenFlow port names (even | |
437 | in contexts where port names are not otherwise supported). The | |
438 | corresponding OpenFlow 1.0 and 1.1+ port numbers are listed alongside them | |
439 | but should not be used in flow syntax: | |
440 | </p> | |
441 | ||
442 | <ul> | |
443 | <li><code>in_port</code> (65528 or 0xfff8; 0xfffffff8)</li> | |
444 | <li><code>table</code> (65529 or 0xfff9; 0xfffffff9)</li> | |
445 | <li><code>normal</code> (65530 or 0xfffa; 0xfffffffa)</li> | |
446 | <li><code>flood</code> (65531 or 0xfffb; 0xfffffffb)</li> | |
447 | <li><code>all</code> (65532 or 0xfffc; 0xfffffffc)</li> | |
448 | <li><code>controller</code> (65533 or 0xfffd; 0xfffffffd)</li> | |
449 | <li><code>local</code> (65534 or 0xfffe; 0xfffffffe)</li> | |
450 | <li><code>any</code> or <code>none</code> (65535 or 0xffff; 0xffffffff)</li> | |
451 | <li><code>unset</code> (not in OpenFlow 1.0; 0xfffffff7)</li> | |
452 | </ul> | |
453 | ||
454 | <!-- What about OVS version compatibility as opposed to OF version --> | |
455 | ||
456 | <group title="Output Actions"> | |
457 | <p> | |
458 | These actions send a packet to a physical port or a controller. A packet | |
459 | that never encounters an output action on its trip through the Open | |
460 | vSwitch pipeline is effectively dropped. Because actions are executed in | |
461 | order, a packet modification action that is not eventually followed by an | |
462 | output action will not have an externally visible effect. | |
463 | </p> | |
464 | ||
465 | <action name="OUTPUT, OUTPUT_REG, OUTPUT_TRUNC"> | |
466 | <h2>The <code>output</code> action</h2> | |
467 | <syntax><var>port</var></syntax> | |
468 | <syntax><code>output:</code><var>port</var></syntax> | |
469 | <syntax><code>output:<var>field</var></code></syntax> | |
470 | <syntax><code>output(port=<var>port</var>, max_len=<var>nbytes</var>)</code></syntax> | |
471 | ||
472 | <p> | |
473 | Outputs the packet to an OpenFlow port most commonly specified as | |
474 | <var>port</var>. Alternatively, the output port may be read from | |
475 | <var>field</var>, a field or subfield in the syntax described under | |
476 | ``Field Specifications'' above. Either way, if the port is the | |
477 | packet's input port, the packet is not output. | |
478 | </p> | |
479 | ||
480 | <p> | |
481 | The port may be one of the following standard OpenFlow ports: | |
482 | </p> | |
483 | ||
484 | <dl> | |
485 | <dt><code>local</code></dt> | |
486 | <dd> | |
487 | Outputs the packet on the ``local port'' that corresponds to the | |
488 | network device that has the same name as the bridge, unless the | |
489 | packet was received on the local port. OpenFlow switch | |
490 | implementations are not required to have a local port, but Open | |
491 | vSwitch bridges always do. | |
492 | </dd> | |
493 | ||
494 | <dt><code>in_port</code></dt> | |
495 | <dd> | |
496 | Outputs the packet on the port on which it was received. This is the | |
497 | only standard way to output the packet to the input port (but see | |
498 | ``Output to the Input port'', below). | |
499 | </dd> | |
500 | </dl> | |
501 | ||
502 | <p> | |
503 | The port may also be one of the following additional OpenFlow ports, | |
504 | unless <code>max_len</code> is specified: | |
505 | </p> | |
506 | ||
507 | <dl> | |
508 | <dt><code>normal</code></dt> | |
509 | <dd> | |
510 | Subjects the packet to the device's normal L2/L3 processing. This | |
511 | action is not implemented by all OpenFlow switches, and each switch | |
512 | implements it differently. | |
513 | </dd> | |
514 | ||
515 | <dt><code>flood</code></dt> | |
516 | <dd> | |
517 | Outputs the packet on all switch physical ports, except the port on | |
518 | which it was received and any ports on which flooding is disabled. | |
519 | Flooding can be disabled automatically on a port by Open vSwitch when | |
520 | IEEE 802.1D spanning tree (STP) or rapid spanning tree (RSTP) is | |
521 | enabled, or by a controller using an OpenFlow | |
522 | <code>OFPT_MOD_PORT</code> request to set the port's | |
523 | <code>OFPPC_NO_FLOOD</code> flag (<code>ovs-ofctl mod-port</code> | |
524 | provides a command-line interface to set this flag). | |
525 | </dd> | |
526 | ||
527 | <dt><code>all</code></dt> | |
528 | <dd> | |
529 | Outputs the packet on all switch physical ports except the port on | |
530 | which it was received. | |
531 | </dd> | |
532 | ||
533 | <dt><code>controller</code></dt> | |
534 | <dd> | |
4272c604 | 535 | Sends the packet and its metadata to an OpenFlow controller or |
be51cd41 BP |
536 | controllers encapsulated in an OpenFlow ``packet-in'' message. The |
537 | separate <code>controller</code> action, described below, provides | |
538 | more options for output to a controller. | |
539 | </dd> | |
540 | </dl> | |
541 | ||
542 | <p> | |
543 | Open vSwitch rejects output to other standard OpenFlow ports, including | |
544 | <code>none</code>, <code>unset</code>, and port numbers reserved for | |
545 | future use as standard ports, with the error | |
546 | <code>OFPBAC_BAD_OUT_PORT</code>. | |
547 | </p> | |
548 | ||
549 | <p> | |
550 | With <var>max_len</var>, the packet is truncated to at most | |
551 | <var>nbytes</var> bytes before being output. In this case, the output | |
552 | port may not be a patch port. Truncation is just for the single output | |
553 | action, so that later actions in the OpenFlow pipeline work with the | |
554 | complete packet. The truncation feature is meant for use in monitoring | |
555 | applications, e.g. for mirroring packets to a collector. | |
556 | </p> | |
557 | ||
558 | <p> | |
559 | When an <code>output</code> action specifies the number of a port that | |
560 | does not currently exist (and is not in the range for standard ports), | |
561 | the OpenFlow specification allows but does not require OVS to reject | |
562 | the action. All versions of Open vSwitch treat such an action as a | |
563 | no-op. If a port with the number is created later, then the action | |
564 | will be honored at that point. (OpenFlow requires OVS to reject output | |
565 | to a port number that will never be valid, with | |
566 | <code>OFPBAC_BAD_OUT_PORT</code>, but this situation does not arise | |
567 | when OVS is a software switch, since the user can add or renumber ports | |
568 | at any time.) | |
569 | </p> | |
570 | ||
571 | <p> | |
572 | A controller can suppress output to a port by setting its | |
573 | <code>OFPPC_NO_FORWARD</code> flag using an OpenFlow | |
574 | <code>OFPT_MOD_PORT</code> request (<code>ovs-ofctl mod-port</code> | |
575 | provides a command-line interface to set this flag). When output is | |
576 | disabled, <code>output</code> actions (and other actions that output to | |
577 | the port) are allowed but have no effect. | |
578 | </p> | |
579 | ||
580 | <p> | |
581 | Open vSwitch allows output to a port that does not exist, although | |
582 | OpenFlow allows switches to reject such actions. | |
583 | </p> | |
584 | ||
585 | <!-- XXX output to normal details --> | |
586 | <!-- XXX output to patch ports details --> | |
587 | ||
588 | <h3>Output to the Input Port</h3> | |
589 | ||
590 | <p> | |
591 | OpenFlow requires a switch to ignore attempts to send a packet out its | |
592 | ingress port in the most straightforward way. For example, | |
593 | <code>output:234</code> has no effect if the packet has ingress port | |
594 | 234. The rationale is that dropping these packets makes it harder to | |
595 | loop the network. Sometimes this behavior can even be convenient, | |
596 | e.g. it is often the desired behavior in a flow that forwards a packet | |
597 | to several ports (``floods'' the packet). | |
598 | </p> | |
599 | ||
600 | <p> | |
601 | Sometimes one really needs to send a packet out its ingress port | |
602 | (``hairpin''). In this case, use <code>in_port</code> to explicitly | |
603 | output the packet to its input port, e.g.: | |
604 | </p> | |
605 | ||
606 | <pre> | |
607 | $ ovs-ofctl add-flow br0 in_port=2,actions=in_port | |
608 | </pre> | |
609 | ||
610 | <p> | |
611 | This also works in some circumstances where the flow doesn't match on | |
612 | the input port. For example, if you know that your switch has five | |
613 | ports numbered 2 through 6, then the following will send every received | |
614 | packet out every port, even its ingress port: | |
615 | </p> | |
616 | ||
617 | <pre> | |
618 | $ ovs-ofctl add-flow br0 actions=2,3,4,5,6,in_port | |
619 | </pre> | |
620 | ||
621 | <p> | |
622 | or, equivalently: | |
623 | </p> | |
624 | ||
625 | <pre> | |
626 | $ ovs-ofctl add-flow br0 actions=all,in_port | |
627 | </pre> | |
628 | ||
629 | <p> | |
630 | Sometimes, in complicated flow tables with multiple levels of | |
631 | <code>resubmit</code> actions, a flow needs to output to a particular | |
632 | port that may or may not be the ingress port. It's difficult to take | |
633 | advantage of output to <code>in_port</code> in this situation. To | |
634 | help, Open vSwitch provides, as an OpenFlow extension, the ability to | |
635 | modify the <code>in_port</code> field. Whatever value is currently in | |
636 | the <code>in_port</code> field is both the port to which output will be | |
637 | dropped and the destination for <code>in_port</code>. This means that | |
638 | the following adds flows that reliably output to port 2 or to ports 2 | |
639 | through 6, respectively: | |
640 | </p> | |
641 | ||
642 | <pre> | |
643 | $ ovs-ofctl add-flow br0 "in_port=2,actions=load:0->in_port,2" | |
644 | $ ovs-ofctl add-flow br0 "actions=load:0->in_port,2,3,4,5,6" | |
645 | </pre> | |
646 | ||
647 | <p> | |
648 | If <code>in_port</code> is important for matching or other reasons, one | |
649 | may save and restore it on the stack: | |
650 | </p> | |
651 | ||
652 | <pre> | |
653 | $ ovs-ofctl add-flow br0 actions="push:in_port,\ | |
654 | load:0->in_port,\ | |
655 | 2,3,4,5,6,\ | |
656 | pop:in_port" | |
657 | </pre> | |
658 | ||
659 | <conformance> | |
660 | All versions of OpenFlow and Open vSwitch support <code>output</code> | |
661 | to a literal <var>port</var>. Output to a register is an OpenFlow | |
662 | extension introduced in Open vSwitch 1.3. Output with truncation is an | |
663 | OpenFlow extension introduced in Open vSwitch 2.6. | |
664 | </conformance> | |
665 | </action> | |
666 | ||
667 | <action name="CONTROLLER"> | |
668 | <h2>The <code>controller</code> action</h2> | |
669 | <syntax><code>controller</code></syntax> | |
670 | <syntax><code>controller:</code><var>max_len</var></syntax> | |
671 | <syntax><code>controller(</code><var>key</var>[<code>=</code><var>value</var>]<code>,</code> ...<code>)</code></syntax> | |
672 | ||
673 | <p> | |
674 | Sends the packet and its metadata to an OpenFlow controller or | |
675 | controllers encapsulated in an OpenFlow ``packet-in'' message. The | |
676 | supported options are: | |
677 | </p> | |
678 | ||
679 | <dl> | |
680 | <dt><code>max_len=</code><var>max_len</var></dt> | |
681 | <dd> | |
682 | <p> | |
683 | Limit to <var>max_len</var> the number of bytes of the packet to | |
684 | send in the ``packet-in.'' A <var>max_len</var> of 0 prevents any | |
685 | of the packet from being sent (thus, only metadata is included). | |
686 | By default, the entire packet is sent, equivalent to a | |
687 | <var>max_len</var> of 65535. | |
688 | </p> | |
689 | </dd> | |
690 | ||
691 | <dt><code>reason=</code><var>reason</var></dt> | |
692 | <dd> | |
693 | Specify <var>reason</var> as the reason for sending the message in | |
694 | the ``packet-in.'' The supported reasons are <code>no_match</code>, | |
695 | <code>action</code>, <code>invalid_ttl</code>, | |
696 | <code>action_set</code>, <code>group</code>, and | |
697 | <code>packet_out</code>. The default reason is <code>action</code>. | |
698 | </dd> | |
699 | ||
700 | <dt><code>id=</code><var>controller_id</var></dt> | |
701 | <dd> | |
1705b8b3 | 702 | Specify <var>controller_id</var>, a 16-bit integer, as the connection |
be51cd41 BP |
703 | ID of the OpenFlow controller or controllers to which the |
704 | ``packet-in'' message should be sent. The default is zero. Zero is | |
705 | also the default connection ID for each controller connection, and a | |
706 | given controller connection will only have a nonzero connection ID if | |
707 | its controller uses the <code>NXT_SET_CONTROLLER_ID</code> Open | |
708 | vSwitch extension to OpenFlow. | |
709 | </dd> | |
710 | ||
711 | <dt><code>userdata=</code><var>hh</var>...</dt> | |
712 | <dd> | |
713 | Supplies the bytes represented as hex digits <var>hh</var> as | |
714 | additional data to the controller in the ``packet-in'' message. | |
715 | Pairs of hex digits may be separated by periods for readability. | |
716 | </dd> | |
717 | ||
718 | <dt><code>pause</code></dt> | |
719 | <dd> | |
720 | Causes the switch to freeze the packet's trip through Open vSwitch | |
721 | flow tables and serializes that state into the packet-in message as a | |
722 | ``continuation,'' an additional property in the | |
723 | <code>NXT_PACKET_IN2</code> message. The controller can later send | |
724 | the continuation back to the switch in an <code>NXT_RESUME</code> | |
725 | message, which will restart the packet's traversal from the point | |
726 | where it was interrupted. This permits an OpenFlow controller to | |
727 | interpose on a packet midway through processing in Open vSwitch. | |
728 | </dd> | |
729 | </dl> | |
730 | ||
731 | <conformance> | |
732 | All versions of OpenFlow and Open vSwitch support | |
733 | <code>controller</code> action and its <code>max_len</code> option. | |
734 | The <code>userdata</code> and <code>pause</code> options require the | |
735 | Open vSwitch <code>NXAST_CONTROLLER2</code> extension action added in | |
736 | Open vSwitch 2.6. In the absence of these options, the | |
737 | <var>reason</var> (other than <code>reason=action</code>) and | |
738 | <var>controller_id</var> (option than <code>controller_id=0</code>) | |
739 | options require the Open vSwitch <code>NXAST_CONTROLLER</code> | |
740 | extension action added in Open vSwitch 1.6. | |
741 | </conformance> | |
742 | </action> | |
743 | ||
744 | <action name="ENQUEUE"> | |
745 | <h2>The <code>enqueue</code> action</h2> | |
746 | <syntax><code>enqueue(</code><var>port</var><code>,</code><var>queue</var><code>)</code></syntax> | |
747 | <syntax><code>enqueue:</code><var>port</var><code>:</code><var>queue</var></syntax> | |
748 | ||
749 | <p> | |
750 | Enqueues the packet on the specified <var>queue</var> within port | |
751 | <var>port</var>. | |
752 | </p> | |
753 | ||
754 | <p> | |
755 | <var>port</var> must be an OpenFlow port number or name as described | |
756 | under ``Port Specifications'' above. <var>port</var> may be | |
757 | <code>in_port</code> or <code>local</code> but the other standard | |
758 | OpenFlow ports are not allowed. | |
759 | </p> | |
760 | ||
761 | <p> | |
762 | <var>queue</var> must be a a number between 0 and 4294967294 | |
763 | (0xfffffffe), inclusive. The number of actually supported queues | |
764 | depends on the switch. Some OpenFlow implementations do not support | |
765 | queuing at all. In Open vSwitch, the supported queues vary depending | |
766 | on the operating system, datapath, and hardware in use. Use the | |
767 | <code>QoS</code> and <code>Queue</code> tables in the Open vSwitch | |
768 | database to configure queuing on individual OpenFlow ports (see | |
769 | <code>ovs-vswitchd.conf.db</code>(5) for more information). | |
770 | </p> | |
771 | ||
772 | <conformance> | |
773 | <p> | |
774 | Only OpenFlow 1.0 supports <code>enqueue</code>. OpenFlow 1.1 added | |
775 | the <code>set_queue</code> action to use in its place along with | |
776 | <code>output</code>. | |
777 | </p> | |
778 | ||
779 | <p> | |
780 | Open vSwitch translates <code>enqueue</code> to a sequence of three | |
781 | actions in OpenFlow 1.1 or later: <code>set_queue:<var>queue</var>, | |
782 | output:<var>port</var>, pop_queue</code>. This is equivalent in | |
783 | behavior as long as the flow table does not otherwise use | |
784 | <code>set_queue</code>, but it relies on the <code>pop_queue</code> | |
785 | Open vSwitch extension action. | |
786 | </p> | |
787 | </conformance> | |
788 | </action> | |
789 | ||
790 | <action name="BUNDLE,BUNDLE_LOAD"> | |
791 | <h2>The <code>bundle</code> and <code>bundle_load</code> actions</h2> | |
91fc374a BP |
792 | <syntax><code>bundle(</code><var>fields</var><code>, </code><var>basis</var><code>, </code><var>algorithm</var><code>, ofport, members:</code><var>port</var>...<code>)</code></syntax> |
793 | <syntax><code>bundle_load(</code><var>fields</var><code>, </code><var>basis</var><code>, </code><var>algorithm</var><code>, ofport, </code><var>dst</var><code>, members:</code><var>port</var>...<code>)</code></syntax> | |
be51cd41 BP |
794 | |
795 | <p> | |
91fc374a BP |
796 | These actions choose a port (a ``member'') from a |
797 | comma-separated OpenFlow <var>port</var> list. After selecting the | |
798 | port, <code>bundle</code> outputs to it, whereas | |
799 | <code>bundle_load</code> writes its port number to <var>dst</var>, | |
800 | which must be a 16-bit or wider field or subfield in the syntax | |
801 | described under ``Field Specifications'' above. | |
be51cd41 BP |
802 | </p> |
803 | ||
804 | <p> | |
805 | These actions hash a set of <var>fields</var> using <var>basis</var> as | |
806 | a universal hash parameter, then apply the bundle link selection | |
807 | <var>algorithm</var> to choose a <var>port</var>. | |
808 | </p> | |
809 | ||
810 | <p> | |
811 | <var>fields</var> must be one of the following. For the options with | |
812 | ``symmetric'' in the name, reversing source and destination addresses | |
813 | yields the same hash: | |
814 | </p> | |
815 | ||
816 | <dl> | |
817 | <dt><code>eth_src</code></dt> | |
818 | <dd> | |
819 | Ethernet source address. | |
820 | </dd> | |
821 | ||
822 | <dt><code>nw_src</code></dt> | |
823 | <dd> | |
824 | IPv4 or IPv6 source address. | |
825 | </dd> | |
826 | ||
827 | <dt><code>nw_dst</code></dt> | |
828 | <dd> | |
829 | IPv4 or IPv6 destination address. | |
830 | </dd> | |
831 | ||
832 | <dt><code>symmetric_l4</code></dt> | |
833 | <dd> | |
834 | Ethernet source and destination, Ethernet type, VLAN ID or IDs (if | |
835 | any), IPv4 or IPv6 source and destination, IP protocol, TCP or SCTP | |
836 | (but not UDP) source and destination. | |
837 | </dd> | |
838 | ||
839 | <dt><code>symmetric_l3l4</code></dt> | |
840 | <dd> | |
841 | IPv4 or IPv6 source and destination, IP protocol, TCP or SCTP (but | |
842 | not UDP) source and destination. | |
843 | </dd> | |
844 | ||
845 | <dt><code>symmetric_l3l4+udp</code></dt> | |
846 | <dd> | |
847 | Like <code>symmetric_l3l4</code> but include UDP ports. | |
848 | </dd> | |
849 | </dl> | |
850 | ||
5a7f15ab BP |
851 | <p> |
852 | <var>algorithm</var> must be one of the following: | |
853 | </p> | |
854 | ||
855 | <dl> | |
856 | <dt><code>active_backup</code></dt> | |
857 | <dd> | |
91fc374a | 858 | Chooses the first live port listed in <var>members</var>. |
5a7f15ab BP |
859 | </dd> |
860 | ||
861 | <dt><code>hrw</code> (Highest Random Weight)</dt> | |
862 | <dd> | |
863 | <p> | |
864 | Computes the following, considering only the live ports in | |
91fc374a | 865 | <var>members</var>: |
5a7f15ab BP |
866 | </p> |
867 | ||
868 | <pre> | |
91fc374a | 869 | for <var>i</var> in [1,<var>n_members</var>]: |
5a7f15ab | 870 | <var>weights</var>[<var>i</var>] = hash(<var>flow</var>, <var>i</var>) |
91fc374a | 871 | <var>member</var> = { <var>i</var> such that <var>weights</var>[<var>i</var>] >= <var>weights</var>[<var>j</var>] for all <var>j</var> != <var>i</var> } |
5a7f15ab BP |
872 | </pre> |
873 | ||
874 | <p> | |
875 | This algorithm is specified by RFC 2992. | |
876 | </p> | |
877 | </dd> | |
878 | </dl> | |
879 | ||
880 | <p> | |
91fc374a BP |
881 | The algorithms take port liveness into account when selecting |
882 | members. The definition of whether a port is live is subject to | |
883 | change. It currently takes into account carrier status and link | |
884 | monitoring protocols such as BFD and CFM. If none of the members is | |
885 | live, <code>bundle</code> does not output the packet and | |
5a7f15ab BP |
886 | <code>bundle_load</code> stores <code>OFPP_NONE</code> (65535) in the |
887 | output field. | |
888 | </p> | |
889 | ||
890 | <p> | |
91fc374a | 891 | Example: <code>bundle(eth_src,0,hrw,ofport,members:4,8)</code> uses an |
5a7f15ab BP |
892 | Ethernet source hash with basis 0, to select between OpenFlow ports 4 |
893 | and 8 using the Highest Random Weight algorithm. | |
894 | </p> | |
895 | ||
be51cd41 BP |
896 | <conformance> |
897 | Open vSwitch 1.2 introduced the <code>bundle</code> and | |
898 | <code>bundle_load</code> OpenFlow extension actions. | |
899 | </conformance> | |
900 | </action> | |
901 | ||
902 | <action name="GROUP"> | |
903 | <h2>The <code>group</code> action</h2> | |
904 | <syntax><code>group:</code><var>group</var></syntax> | |
905 | <p> | |
906 | Outputs the packet to the OpenFlow group <var>group</var>, which must | |
907 | be a number in the range 0 to 4294967040 (0xffffff00). The group must | |
908 | exist or Open vSwitch will refuse to add the flow. When a group is | |
909 | deleted, Open vSwitch also deletes all of the flows that output to it. | |
910 | </p> | |
911 | ||
912 | <p> | |
913 | Groups contain action sets, whose semantics are described above in the | |
914 | section ``Action Sets''. The semantics of action sets can be | |
915 | surprising to users who expect action list semantics, since action sets | |
916 | reorder and sometimes ignore actions. | |
917 | </p> | |
918 | ||
919 | <p> | |
920 | A <code>group</code> action usually executes the action set or sets in | |
921 | one or more group buckets. Open vSwitch saves the packet and metadata | |
922 | before it executes each bucket, and then restores it afterward. Thus, | |
923 | when a group executes more than one bucket, this means that each bucket | |
924 | executes on the same packet and metadata. Moreover, regardless of the | |
925 | number of buckets executed, the packet and metadata are the same before | |
926 | and after executing the group. | |
927 | </p> | |
928 | ||
929 | <p> | |
930 | Sometimes saving and restoring the packet and metadata can be | |
931 | undesirable. In these situations, workarounds are possible. For | |
932 | example, consider a pipeline design in which a <code>select</code> | |
933 | group bucket is to communicate to a later stage of processing a value | |
934 | based on which bucket was selected. An obvious design would be for the | |
935 | bucket to communicate the value via <code>set_field</code> on a | |
936 | register. This does not work because registers are part of the | |
afc0c379 BP |
937 | metadata that <code>group</code> saves and restores. The following |
938 | alternative bucket designs do work: | |
be51cd41 BP |
939 | </p> |
940 | ||
afc0c379 BP |
941 | <ul> |
942 | <li> | |
943 | Recursively invoke the rest of the pipeline with | |
944 | <code>resubmit</code>. | |
945 | </li> | |
946 | ||
947 | <li> | |
948 | <p> | |
949 | Use <code>resubmit</code> into a table that uses <code>push</code> | |
950 | to put the value on the stack for the caller to <code>pop</code> | |
951 | off. This works because <code>group</code> preserves only packet | |
952 | data and metadata, not the stack. | |
953 | </p> | |
954 | ||
955 | <p> | |
956 | (This design requires indirection through <code>resubmit</code> | |
957 | because actions sets may not contain <code>push</code> or | |
958 | <code>pop</code> actions.) | |
959 | </p> | |
960 | </li> | |
961 | </ul> | |
962 | ||
be51cd41 BP |
963 | <p> |
964 | An <code>exit</code> action within a group bucket terminates only | |
965 | execution of that bucket, not other buckets or the overall pipeline. | |
966 | </p> | |
967 | ||
968 | <conformance> | |
969 | OpenFlow 1.1 introduced <code>group</code>. Open vSwitch 2.6 and later | |
970 | also supports <code>group</code> as an extension to OpenFlow 1.0. | |
971 | </conformance> | |
972 | </action> | |
973 | ||
974 | </group> | |
975 | ||
976 | <group title="Encapsulation and Decapsulation Actions"> | |
977 | <action name="STRIP_VLAN"> | |
978 | <h2>The <code>strip_vlan</code> and <code>pop</code> actions</h2> | |
979 | <syntax><code>strip_vlan</code></syntax> | |
980 | <syntax><code>pop_vlan</code></syntax> | |
981 | ||
982 | <p> | |
983 | Removes the outermost VLAN tag, if any, from the packet. | |
984 | </p> | |
985 | ||
986 | <p> | |
987 | The two names for this action are synonyms with no semantic difference. | |
988 | The OpenFlow 1.0 specification uses the name <code>strip_vlan</code> | |
989 | and later versions use <code>pop_vlan</code>, but OVS accepts either | |
990 | name regardless of version. | |
991 | </p> | |
992 | ||
993 | <p> | |
994 | In OpenFlow 1.1 and later, consistency rules allow | |
995 | <code>strip_vlan</code> only in a flow that matches only packets with a | |
996 | VLAN tag (or following an action that pushes a VLAN tag, such as | |
997 | <code>push_vlan</code>). See ``Inconsistencies'', above, for more | |
998 | information. | |
999 | </p> | |
1000 | ||
1001 | <conformance> | |
1002 | All versions of OpenFlow and Open vSwitch support this action. | |
1003 | </conformance> | |
1004 | </action> | |
1005 | ||
1006 | <action name="PUSH_VLAN"> | |
1007 | <h2>The <code>push_vlan</code> action</h2> | |
1008 | <syntax><code>push_vlan:</code><var>ethertype</var></syntax> | |
1009 | ||
1010 | <p> | |
1011 | Pushes a new outermost VLAN onto the packet. Uses TPID | |
1012 | <var>ethertype</var>, which must be <code>0x8100</code> for an 802.1Q | |
1013 | C-tag or <code>0x88a8</code> for a 802.1ad S-tag. | |
1014 | </p> | |
1015 | ||
1016 | <conformance> | |
1017 | OpenFlow 1.1 and later supports this action. Open vSwitch 2.8 added | |
1018 | support for multiple VLAN tags (with a limit of 2) and 802.1ad S-tags. | |
1019 | </conformance> | |
1020 | </action> | |
1021 | ||
1022 | <action name="PUSH_MPLS"> | |
1023 | <h2>The <code>push_mpls</code> action</h2> | |
1024 | <syntax><code>push_mpls:<var>ethertype</var></code></syntax> | |
1025 | ||
1026 | <p> | |
1027 | Pushes a new outermost MPLS label stack entry (LSE) onto the packet and | |
1028 | changes the packet's Ethertype to <var>ethertype</var>, which must be | |
1029 | either <code>B0x8847</code> or <code>0x8848</code>. | |
1030 | </p> | |
1031 | ||
1032 | <p> | |
1033 | If the packet did not already contain any MPLS labels, initializes the | |
1034 | new LSE as: | |
1035 | </p> | |
1036 | ||
1037 | <dl> | |
1038 | <dt>Label</dt> | |
1039 | <dd> | |
1040 | 2, if the packet contains IPv6, 0 otherwise. | |
1041 | </dd> | |
1042 | <dt>TC</dt> | |
1043 | <dd> | |
1044 | The low 3 bits of the packet's DSCP value, or 0 if the packet is not | |
1045 | IP. | |
1046 | </dd> | |
1047 | <dt>TTL</dt> | |
1048 | <dd> | |
1049 | Copied from the IP TTL, or 64 if the packet is not IP. | |
1050 | </dd> | |
1051 | </dl> | |
1052 | ||
1053 | <p> | |
1054 | If the packet did already contain an MPLS label, initializes the new | |
1055 | outermost label as a copy of the existing outermost label. | |
1056 | </p> | |
1057 | ||
1058 | <p> | |
1059 | OVS currently supports at most 3 MPLS labels. | |
1060 | </p> | |
1061 | ||
1062 | <p> | |
1063 | This action applies only to Ethernet packets. | |
1064 | </p> | |
1065 | ||
1066 | <conformance> | |
1067 | Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later | |
1068 | support <code>push_mpls</code>. Open vSwitch implements | |
1069 | <code>push_mpls</code> as an extension to OpenFlow 1.0. | |
1070 | </conformance> | |
1071 | </action> | |
1072 | ||
1073 | <action name="POP_MPLS"> | |
1074 | <h2>The <code>pop_mpls</code> action</h2> | |
1075 | <syntax><code>pop_mpls:<var>ethertype</var></code></syntax> | |
1076 | ||
1077 | <p> | |
1078 | Strips the outermost MPLS label stack entry and changes the packet's | |
1079 | Ethertype to <var>ethertype</var>. | |
1080 | </p> | |
1081 | ||
1082 | <p> | |
1083 | This action applies only to Ethernet packets with at least one MPLS | |
1084 | label. If there is more than one MPLS label, then <var>ethertype</var> | |
1085 | should be an MPLS Ethertype (<code>B0x8847</code> or | |
1086 | <code>0x8848</code>). | |
1087 | </p> | |
1088 | ||
1089 | <conformance> | |
1090 | Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later | |
1091 | support <code>pop_mpls</code>. Open vSwitch implements | |
1092 | <code>pop_mpls</code> as an extension to OpenFlow 1.0. | |
1093 | </conformance> | |
1094 | </action> | |
1095 | ||
1096 | <action name="ENCAP"> | |
1097 | <h2>The <code>encap</code> action</h2> | |
1098 | <syntax><code>encap(nsh(</code>[<code>md_type=<var>md_type</var></code>]<code>, </code>[<code>tlv(<var>class</var>,<var>type</var>,<var>value</var>)</code>]...<code>))</code></syntax> | |
1099 | <syntax><code>encap(ethernet)</code></syntax> | |
1100 | ||
1101 | <p> | |
1102 | The <code>encap</code> action encapsulates a packet with a specified | |
1103 | header. It has variants for different kinds of encapsulation. | |
1104 | </p> | |
1105 | ||
1106 | <p> | |
1107 | The <code>encap(nsh(</code>...<code>))</code> variant encapsulates an | |
1108 | Ethernet frame with NSH. The <var>md_type</var> may be <code>1</code> | |
1109 | or <code>2</code> for metadata type 1 or 2, defaulting to 1. For | |
1110 | metadata type 2, TLVs may be specified with <var>class</var> as a | |
1111 | 16-bit hexadecimal integer beginning with <code>0x</code>, | |
1112 | <var>type</var> as an 8-bit decimal integer, and <var>value</var> a | |
1113 | sequence of pairs of hex digits beginning with <code>0x</code>. For | |
1114 | example: | |
1115 | </p> | |
1116 | ||
1117 | <dl> | |
1118 | <dt><code>encap(nsh(md_type=1))</code></dt> | |
1119 | <dd> | |
1120 | Encapsulates the packet with an NSH header with metadata type 1. | |
1121 | </dd> | |
1122 | ||
1123 | <dt><code>encap(nsh(md_type=2,tlv(0x1000,10,0x12345678)))</code></dt> | |
1124 | <dd> | |
1125 | Encapsulates the packet with an NSH header, NSH metadata type 2, and | |
1126 | an NSH TLV with class 0x1000, type 10, and the 4-byte value | |
1127 | 0x12345678. | |
1128 | </dd> | |
1129 | </dl> | |
1130 | ||
1131 | <p> | |
1132 | The <code>encap(ethernet)</code> variant encapsulate a bare L3 packet | |
1133 | in an Ethernet frame. The Ethernet type is initialized to the L3 | |
1134 | packet's type, e.g. 0x0800 if the L3 packet is IPv4. The Ethernet | |
1135 | source and destination are initially zeroed. | |
1136 | </p> | |
1137 | ||
1138 | <conformance> | |
1139 | This action is an Open vSwitch extension to OpenFlow 1.3 and later, | |
1140 | introduced in Open vSwitch 2.8. | |
1141 | </conformance> | |
1142 | </action> | |
1143 | ||
1144 | <action name="DECAP"> | |
1145 | <h2>The <code>decap</code> action</h2> | |
1146 | <syntax><code>decap</code></syntax> | |
1147 | ||
1148 | <p> | |
1149 | Removes an outermost encapsulation from the packet: | |
1150 | </p> | |
1151 | ||
1152 | <ul> | |
1153 | <li> | |
1154 | If the packet is an Ethernet packet, removes the Ethernet header, | |
1155 | which changes the packet into a bare L3 packet. If the packet has | |
1156 | VLAN tags, raises an unsupported packet type error (see ``Error | |
1157 | Handling'', above). | |
1158 | </li> | |
1159 | ||
1160 | <li> | |
1161 | Otherwise, if the packet is an NSH packet, removes the NSH header, | |
1162 | revealing the inner packet. Open vSwitch supports Ethernet, IPv4, | |
1163 | IPv6, and NSH inner packet types. Other types raise unsupported | |
1164 | packet type errors. | |
1165 | </li> | |
1166 | ||
1167 | <li> | |
1168 | Otherwise, raises an unsupported packet type error. | |
1169 | </li> | |
1170 | </ul> | |
1171 | ||
1172 | <conformance> | |
1173 | This action is an Open vSwitch extension to OpenFlow 1.3 and later, | |
1174 | introduced in Open vSwitch 2.8. | |
1175 | </conformance> | |
1176 | </action> | |
1177 | </group> | |
1178 | ||
1179 | <group title="Field Modification Actions"> | |
1180 | <p> | |
1181 | These actions modify packet data and metadata fields. | |
1182 | </p> | |
1183 | ||
1184 | <action name="SET_FIELD"> | |
1185 | <h2>The <code>set_field</code> and <code>load</code> actions</h2> | |
1186 | <syntax><code>set_field:</code><var>value</var>[<code>/</code><var>mask</var>]<code>-></code><var>dst</var></syntax> | |
1187 | <syntax><code>load:</code><var>value</var><code>-></code><var>dst</var><code></code></syntax> | |
1188 | ||
1189 | <p> | |
1190 | These actions loads a literal value into a field or part of a field. | |
1191 | The <code>set_field</code> action takes <var>value</var> in the | |
1192 | customary syntax for field <var>dst</var>, | |
1193 | e.g. <code>00:11:22:33:44:55</code> for an Ethernet address, and | |
1194 | <var>dst</var> as the field's name. The optional <var>mask</var> | |
1195 | allows part of a field to be set. | |
1196 | </p> | |
1197 | ||
1198 | <p> | |
1199 | The <code>load</code> action takes <var>value</var> as an integer value | |
1200 | (in decimal or prefixed by <code>0x</code> for hexadecimal) and | |
1201 | <var>dst</var> as a field or subfield in the syntax described under | |
1202 | ``Field Specifications'' above. | |
1203 | </p> | |
1204 | ||
1205 | <p> | |
1206 | The following all set the Ethernet source address to 00:11:22:33:44:55: | |
1207 | </p> | |
1208 | ||
1209 | <ul> | |
1210 | <li><code>set_field:00:11:22:33:44:55->eth_src</code></li> | |
1211 | <li><code>load:0x001122334455->eth_src</code></li> | |
1212 | <li><code>load:0x001122334455->OXM_OF_ETH_SRC[]</code></li> | |
1213 | </ul> | |
1214 | ||
1215 | <p> | |
1216 | The following all set the multicast bit in the Ethernet destination | |
1217 | address: | |
1218 | </p> | |
1219 | ||
1220 | <ul> | |
1221 | <li><code>set_field:01:00:00:00:00:00/01:00:00:00:00:00->eth_dst</code></li> | |
1222 | <li><code>load:1->eth_dst[40]</code></li> | |
1223 | </ul> | |
1224 | ||
1225 | <p> | |
1226 | Open vSwitch prohibits a <code>set_field</code> or <code>load</code> | |
1227 | action whose <var>dst</var> is not guaranteed to be part of the packet; | |
1228 | for example, <code>set_field</code> of <code>nw_dst</code> is only | |
1229 | allowed in a flow that matches on Ethernet type 0x800. In some cases, | |
1230 | such as in an action set, Open vSwitch can't statically check that | |
1231 | <var>dst</var> is part of the packet, and in that case if it is not | |
1232 | then Open vSwitch treats the action as a no-op. | |
1233 | </p> | |
1234 | ||
1235 | <conformance> | |
1236 | Open vSwitch 1.1 introduced <code>NXAST_REG_LOAD</code> as a extension | |
1237 | to OpenFlow 1.0 and used <code>load</code> to express it. Later, | |
1238 | OpenFlow 1.2 introduced a standard <code>OFPAT_SET_FIELD</code> action | |
1239 | that was restricted to loading entire fields, so Open vSwitch added the | |
1240 | form <code>set_field</code> with this restriction. OpenFlow 1.5 | |
1241 | extended <code>OFPAT_SET_FIELD</code> to the point that it became a | |
1242 | superset of <code>NXAST_REG_LOAD</code>. Open vSwitch translates | |
1243 | either syntax as necessary for the OpenFlow version in use: in OpenFlow | |
1244 | 1.0 and 1.1, <code>NXAST_REG_LOAD</code>; in OpenFlow 1.2, 1.3, and | |
1245 | 1.4, <code>NXAST_REG_LOAD</code> for <code>load</code> or for loading a | |
1246 | subfield, <code>OFPAT_SET_FIELD</code> otherwise; and OpenFlow 1.5 and | |
1247 | later, <code>OFPAT_SET_FIELD</code>. | |
1248 | </conformance> | |
1249 | </action> | |
1250 | ||
1251 | <action name="REG_MOVE"> | |
1252 | <h2>The <code>move</code> action</h2> | |
1253 | <syntax><code>move:<var>src</var>-><var>dst</var></code></syntax> | |
1254 | ||
1255 | <p> | |
1256 | Copies the named bits from field or subfield <var>src</var> to field or | |
1257 | subfield <var>dst</var>. <var>src</var> and <var>dst</var> should | |
1258 | fields or subfields in the syntax described under ``Field | |
1259 | Specifications'' above. The two fields or subfields must have the same | |
1260 | width. | |
1261 | </p> | |
1262 | ||
1263 | <p> | |
1264 | Examples: | |
1265 | </p> | |
1266 | ||
1267 | <ul> | |
1268 | <li> | |
1269 | <code>move:reg0[0..5]->reg1[26..31]</code> copies the six bits | |
1270 | numbered 0 through 5 in register 0 into bits 26 through 31 of | |
1271 | register 1. | |
1272 | </li> | |
1273 | <li> | |
1274 | <code>move:reg0[0..15]->vlan_tci</code> copies the least | |
1275 | significant 16 bits of register 0 into the VLAN TCI field. | |
1276 | </li> | |
1277 | </ul> | |
1278 | ||
1279 | <conformance> | |
1280 | In OpenFlow 1.0 through 1.4, <code>move</code> ordinarily uses an Open | |
1281 | vSwitch extension to OpenFlow. In OpenFlow 1.5, <code>move</code> uses | |
1282 | the OpenFlow 1.5 standard <code>OFPAT_COPY_FIELD</code> action. The | |
1283 | ONF has also made <code>OFPAT_COPY_FIELD</code> available as an | |
1284 | extension to OpenFlow 1.3. Open vSwitch 2.4 and later understands this | |
1285 | extension and uses it if a controller uses it, but for backward | |
1286 | compatibility with older versions of Open vSwitch, | |
1287 | <code>ovs-ofctl</code> does not use it. | |
1288 | </conformance> | |
1289 | </action> | |
1290 | ||
1291 | <action name="SET_ETH_SRC, SET_ETH_DST"> | |
1292 | <h2>The <code>mod_dl_src</code> and <code>mod_dl_dst</code> actions</h2> | |
1293 | <syntax><code>mod_dl_src:</code><var>mac</var></syntax> | |
1294 | <syntax><code>mod_dl_dst:</code><var>mac</var></syntax> | |
1295 | ||
1296 | <p> | |
1297 | Sets the Ethernet source or destination address, respectively, to | |
1298 | <var>mac</var>, which should be expressed in the form | |
1299 | <code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code>. | |
1300 | </p> | |
1301 | ||
1302 | <p> | |
1303 | For L3-only packets, that is, those that lack an Ethernet header, this | |
1304 | action has no effect. | |
1305 | </p> | |
1306 | ||
1307 | <conformance> | |
1308 | OpenFlow 1.0 and 1.1 have specialized actions for these purposes. | |
1309 | OpenFlow 1.2 and later do not, so Open vSwitch translates them to | |
1310 | appropriate <code>OFPAT_SET_FIELD</code> actions for those versions, | |
1311 | </conformance> | |
1312 | </action> | |
1313 | ||
1314 | <action name="SET_IP_SRC, SET_IP_DST"> | |
1315 | <h2>The <code>mod_nw_src</code> and <code>mod_nw_dst</code> actions</h2> | |
1316 | <syntax><code>mod_nw_src:</code><var>ip</var></syntax> | |
1317 | <syntax><code>mod_nw_dst:</code><var>ip</var></syntax> | |
1318 | ||
1319 | <p> | |
1320 | Sets the IPv4 source or destination address, respectively, to | |
1321 | <var>ip</var>, which should be expressed in the form | |
1322 | <code><var>w</var>.<var>x</var>.<var>y</var>.<var>z</var></code>. | |
1323 | </p> | |
1324 | ||
1325 | <p> | |
1326 | In OpenFlow 1.1 and later, consistency rules allow these actions only | |
1327 | in a flow that matches only packets that contain an IPv4 header (or | |
1328 | following an action that adds an IPv4 header, | |
1329 | e.g. <code>pop_mpls:0x0800</code>). See ``Inconsistencies'', above, | |
1330 | for more information. | |
1331 | </p> | |
1332 | ||
1333 | <conformance> | |
1334 | OpenFlow 1.0 and 1.1 have specialized actions for these purposes. | |
1335 | OpenFlow 1.2 and later do not, so Open vSwitch translates them to | |
1336 | appropriate <code>OFPAT_SET_FIELD</code> actions for those versions, | |
1337 | </conformance> | |
1338 | </action> | |
1339 | ||
1340 | <action name="SET_IP_DSCP, SET_IP_ECN"> | |
1341 | <h2>The <code>mod_nw_tos</code> and <code>mod_nw_ecn</code> actions</h2> | |
1342 | <syntax><code>mod_nw_tos:</code><var>tos</var></syntax> | |
1343 | <syntax><code>mod_nw_ecn:</code><var>ecn</var></syntax> | |
1344 | ||
1345 | <p> | |
1346 | The <code>mod_nw_tos</code> action sets the DSCP bits in the IPv4 | |
1347 | ToS/DSCP or IPv6 traffic class field to <var>tos</var>, which must be a | |
1348 | multiple of 4 between 0 and 255. This action does not modify the two | |
1349 | least significant bits of the ToS field (the ECN bits). | |
1350 | </p> | |
1351 | ||
1352 | <p> | |
1353 | The <code>mod_nw_ecn</code> action sets the ECN bits in the IPv4 ToS or | |
1354 | IPv6 traffic class field to <code>ecn</code>, which must be a value | |
1355 | between 0 and 3, inclusive. This action does not modify the six most | |
1356 | significant bits of the field (the DSCP bits). | |
1357 | </p> | |
1358 | ||
1359 | <p> | |
1360 | In OpenFlow 1.1 and later, consistency rules allow these actions only | |
1361 | in a flow that matches only packets that contain an IPv4 or IPv6 header | |
1362 | (or following an action that adds such a header). See | |
1363 | ``Inconsistencies'', above, for more information. | |
1364 | </p> | |
1365 | ||
1366 | <conformance> | |
1367 | OpenFlow 1.0 has a <code>mod_nw_tos</code> action but not | |
1368 | <code>mod_nw_ecn</code>. Open vSwitch implements the latter in | |
1369 | OpenFlow 1.0 as an extension using <code>NXAST_REG_LOAD</code>. | |
1370 | OpenFlow 1.1 has specialized actions for these purposes. OpenFlow 1.2 | |
1371 | and later do not, so Open vSwitch translates them to appropriate | |
1372 | <code>OFPAT_SET_FIELD</code> actions for those versions, | |
1373 | </conformance> | |
1374 | </action> | |
1375 | ||
1376 | <action name="SET_L4_SRC_PORT, SET_L4_DST_PORT"> | |
1377 | <h2>The <code>mod_tp_src</code> and <code>mod_tp_dst</code> actions</h2> | |
1378 | <syntax><code>mod_tp_src:</code><var>port</var></syntax> | |
1379 | <syntax><code>mod_tp_dst:</code><var>port</var></syntax> | |
1380 | ||
1381 | <p> | |
1382 | Sets the TCP or UDP or SCTP source or destination port, respectively, | |
1383 | to <var>port</var>. Both IPv4 and IPv6 are supported. | |
1384 | </p> | |
1385 | ||
1386 | <p> | |
1387 | In OpenFlow 1.1 and later, consistency rules allow these actions only | |
1388 | in a flow that matches only packets that contain a TCP or UDP or SCTP | |
1389 | header. See ``Inconsistencies'', above, for more information. | |
1390 | </p> | |
1391 | ||
1392 | <conformance> | |
1393 | OpenFlow 1.0 and 1.1 have specialized actions for these purposes. | |
1394 | OpenFlow 1.2 and later do not, so Open vSwitch translates them to | |
1395 | appropriate <code>OFPAT_SET_FIELD</code> actions for those versions, | |
1396 | </conformance> | |
1397 | </action> | |
1398 | ||
1399 | <action name="DEC_TTL"> | |
1400 | <h2>The <code>dec_ttl</code> action</h2> | |
1401 | <syntax><code>dec_ttl</code></syntax> | |
1402 | <syntax><code>dec_ttl(<var>id1</var>, </code>[<code><var>id2</var></code>]...<code>)</code></syntax> | |
1403 | ||
1404 | <p> | |
1405 | Decrement TTL of IPv4 packet or hop limit of IPv6 packet. If the TTL | |
1406 | or hop limit is initially 0 or 1, no decrement occurs, as packets | |
1407 | reaching TTL zero must be rejected. Instead, Open vSwitch sends a | |
1408 | ``packet-in'' message with reason code <code>OFPR_INVALID_TTL</code> to | |
1409 | each connected controller that has enabled receiving such messages, and | |
1410 | stops processing the current set of actions. (However, if the current | |
1411 | set of actions was reached through <code>resubmit</code>, the remaining | |
1412 | actions in outer levels resume processing.) | |
1413 | </p> | |
1414 | ||
1415 | <p> | |
1416 | As an Open vSwitch extension to OpenFlow, this action supports the | |
1417 | ability to specify a list of controller IDs. Open vSwitch will only | |
1418 | send the message to controllers with the given ID or IDs. Specifying | |
1419 | no list is equivalent to specifying a single controller ID of zero. | |
1420 | </p> | |
1421 | ||
1422 | <p> | |
1423 | Sets the TCP or UDP or SCTP source or destination port, respectively, | |
1424 | to <var>port</var>. Both IPv4 and IPv6 are supported. | |
1425 | </p> | |
1426 | ||
1427 | <p> | |
1428 | In OpenFlow 1.1 and later, consistency rules allow these actions only | |
1429 | in a flow that matches only packets that contain an IPv4 or IPv6 | |
1430 | header. See ``Inconsistencies'', above, for more information. | |
1431 | </p> | |
1432 | ||
1433 | <conformance> | |
1434 | All versions of OpenFlow and Open vSwitch support this action. | |
1435 | </conformance> | |
1436 | </action> | |
1437 | ||
1438 | <action name="SET_MPLS_LABEL, SET_MPLS_TC, SET_MPLS_TTL"> | |
1439 | <h2>The <code>set_mpls_label</code>, <code>set_mpls_tc</code>, and <code>set_mpls_ttl</code> actions</h2> | |
1440 | <syntax><code>set_mpls_label:</code><var>label</var></syntax> | |
1441 | <syntax><code>set_mpls_tc:</code><var>tc</var></syntax> | |
1442 | <syntax><code>set_mpls_ttl:</code><var>ttl</var></syntax> | |
1443 | ||
1444 | <p> | |
1445 | The <code>set_mpls_label</code> action sets the label of the packet's | |
1446 | outer MPLS label stack entry. <var>label</var> should be a 20-bit | |
1447 | value that is decimal by default; use a <code>0x</code> prefix to | |
1448 | specify the value in hexadecimal. | |
1449 | </p> | |
1450 | ||
1451 | <p> | |
1452 | The <code>set_mpls_tc</code> action sets the traffic class of the | |
1453 | packet's outer MPLS label stack entry. <var>tc</var> should be in the | |
1454 | range 0 to 7, inclusive. | |
1455 | </p> | |
1456 | ||
1457 | <p> | |
1458 | The <code>set_mpls_ttl</code> action sets the TTL of the packet's outer | |
1459 | MPLS label stack entry. <var>ttl</var> should be in the range 0 to 255 | |
1460 | inclusive. | |
1461 | </p> | |
1462 | ||
1463 | <p> | |
1464 | In OpenFlow 1.1 and later, consistency rules allow these actions only | |
1465 | in a flow that matches only packets that contain an MPLS label (or | |
1466 | following an action that adds an MPLS label, | |
1467 | e.g. <code>push_mpls:0x8847</code>). See ``Inconsistencies'', above, | |
1468 | for more information. | |
1469 | </p> | |
1470 | ||
1471 | <conformance> | |
1472 | OpenFlow 1.0 does not support MPLS, but Open vSwitch implements these | |
1473 | actions as extensions. OpenFlow 1.1 has specialized actions for these | |
1474 | purposes. OpenFlow 1.2 and later do not, so Open vSwitch translates | |
1475 | them to appropriate <code>OFPAT_SET_FIELD</code> actions for those | |
1476 | versions, | |
1477 | </conformance> | |
1478 | </action> | |
1479 | ||
1480 | <action name="DEC_MPLS_TTL, DEC_NSH_TTL"> | |
1481 | <h2>The <code>dec_mpls_ttl</code> and <code>dec_nsh_ttl</code> actions</h2> | |
1482 | <syntax><code>dec_mpls_ttl</code></syntax> | |
1483 | <syntax><code>dec_nsh_ttl</code></syntax> | |
1484 | ||
1485 | <p> | |
1486 | These actions decrement the TTL of the packet's outer MPLS label stack | |
1487 | entry or its NSH header, respectively. If the TTL is initially 0 or 1, | |
1488 | no decrement occurs. Instead, Open vSwitch sends a ``packet-in'' | |
1489 | message with reason code <code>BOFPR_INVALID_TTL</code> to OpenFlow | |
1490 | controllers with ID 0, if it has enabled receiving them. Processing | |
1491 | the current set of actions then stops. (However, if the current set of | |
1492 | actions was reached through <code>resubmit</code>, remaining actions in | |
1493 | outer levels resume processing.) | |
1494 | </p> | |
1495 | ||
1496 | <p> | |
1497 | In OpenFlow 1.1 and later, consistency rules allow this actions only in | |
1498 | a flow that matches only packets that contain an MPLS label or an NSH | |
1499 | header, respectively. See ``Inconsistencies'', above, for more | |
1500 | information. | |
1501 | </p> | |
1502 | ||
1503 | <conformance> | |
1504 | <p> | |
1505 | Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and | |
1506 | later support <code>dec_mpls_ttl</code>. Open vSwitch implements | |
1507 | <code>dec_mpls_ttl</code> as an extension to OpenFlow 1.0. | |
1508 | </p> | |
1509 | ||
1510 | <p> | |
1511 | Open vSwitch 2.8 introduced support for NSH, although the NSH draft | |
1512 | changed after release so that only Open vSwitch 2.9 and later conform | |
1513 | to the final protocol specification. The <code>dec_nsh_ttl</code> | |
1514 | action and NSH support in general is an Open vSwitch extension not | |
1515 | supported by any version of OpenFlow. | |
1516 | </p> | |
1517 | </conformance> | |
1518 | </action> | |
5b34f8fc NS |
1519 | |
1520 | <action name="CHECK_PKT_LARGER"> | |
1521 | <h2>The <code>check_pkt_larger</code> action</h2> | |
1522 | <syntax> | |
1523 | <code>check_pkt_larger(<var>pkt_len</var>)-><var>dst</var></code> | |
1524 | </syntax> | |
1525 | ||
1526 | <p> | |
1527 | Checks if the packet is larger than the specified length in | |
1528 | <var>pkt_len</var>. If so, stores 1 in <var>dst</var>, which should be | |
1529 | a 1-bit field; if not, stores 0. | |
1530 | </p> | |
1531 | ||
1532 | <p> | |
b9de30d3 | 1533 | The packet length to check against the argument <var>pkt_len</var> |
5b34f8fc NS |
1534 | includes the L2 header and L2 payload of the packet, but not the VLAN |
1535 | tag (if present). | |
1536 | </p> | |
1537 | ||
1538 | <p> | |
1539 | Examples: | |
1540 | </p> | |
1541 | ||
1542 | <ul> | |
1543 | <li> | |
1544 | <code>check_pkt_larger(1500)->reg0[0]</code> | |
1545 | </li> | |
1546 | ||
1547 | <li> | |
1548 | <code>check_pkt_larger(8000)->reg9[10]</code> | |
1549 | </li> | |
1550 | </ul> | |
1551 | ||
1552 | <p> | |
1553 | This action was added in Open vSwitch 2.11.90. | |
1554 | </p> | |
1555 | </action> | |
81f71381 YHW |
1556 | |
1557 | <action name="DELETE_FIELD"> | |
1558 | <h2>The <code>delete_field</code> action</h2> | |
1559 | <syntax><code>delete_field:</code><var>field</var></syntax> | |
1560 | ||
1561 | <p> | |
1562 | The <code>delete_field</code> action deletes a field in the syntax | |
1563 | described under ``Field Specifications'' above. Currently, only | |
1564 | the tun_metadta fields are supported. | |
1565 | </p> | |
1566 | ||
1567 | <p> | |
1568 | This action was added in Open vSwitch 2.13.90. | |
1569 | </p> | |
1570 | </action> | |
1571 | ||
be51cd41 BP |
1572 | </group> |
1573 | ||
1574 | <group title="Metadata Actions"> | |
1575 | <action name="SET_TUNNEL"> | |
1576 | <h2>The <code>set_tunnel</code> action</h2> | |
1577 | <syntax><code>set_tunnel:</code><var>id</var></syntax> | |
1578 | <syntax><code>set_tunnel64:</code><var>id</var></syntax> | |
1579 | ||
1580 | <p> | |
1581 | Many kinds of tunnels support a tunnel ID, e.g. VXLAN and Geneve have a | |
1582 | 24-bit VNI, and GRE has an optional 32-bit key. This action sets the | |
1583 | value used for tunnel ID in such tunneled packets, although whether it | |
1584 | is used for a particular tunnel depends on the tunnel's configuration. | |
1585 | See the tunnel ID documentation in <code>ovs-fields</code>(7) for more | |
1586 | information. | |
1587 | </p> | |
1588 | ||
1589 | <conformance> | |
1590 | <p> | |
1591 | These actions are OpenFlow extensions. <code>set_tunnel</code> was | |
1592 | introduced in Open vSwitch 1.0. <code>set_tunnel64</code>, which is | |
1593 | needed if <var>id</var> is wider than 32 bits, was added in Open | |
1594 | vSwitch 1.1. Both actions always set the entire tunnel ID field. | |
1595 | </p> | |
1596 | ||
1597 | <p> | |
1598 | Open vSwitch supports these actions in all versions of OpenFlow, but | |
1599 | in OpenFlow 1.2 and later it translates them to an appropriate | |
1600 | standardized <code>OFPAT_SET_FIELD</code> action. | |
1601 | </p> | |
1602 | </conformance> | |
1603 | </action> | |
1604 | ||
1605 | <action name="SET_QUEUE, POP_QUEUE"> | |
1606 | <h2>The <code>set_queue</code> and <code>pop_queue</code> actions</h2> | |
1607 | <syntax><code>set_queue:</code><var>queue</var></syntax> | |
1608 | <syntax><code>pop_queue</code></syntax> | |
1609 | ||
1610 | <p> | |
1611 | The <code>set_queue</code> action sets the queue ID to be used for | |
1612 | subsequent output actions to <var>queue</var>, which must be a 32-bit | |
1613 | integer. The range of meaningful values of <var>queue</var>, and their | |
1614 | meanings, varies greatly from one OpenFlow implementation to another. | |
1615 | Even within a single implementation, there is no guarantee that all | |
1616 | OpenFlow ports have the same queues configured or that all OpenFlow | |
1617 | ports in an implementation can be configured the same way queue-wise. | |
1618 | For more information, see the documentation for the output queue field | |
1619 | in <code>ovs-fields</code>(7). | |
1620 | </p> | |
1621 | ||
1622 | <p> | |
1623 | The <code>pop_queue</code> restores the output queue to the default | |
1624 | that was set when the packet entered the switch (generally 0). | |
1625 | </p> | |
1626 | ||
1627 | <p> | |
1628 | Four billion queues ought to be enough for anyone: <url | |
1629 | href="https://mailman.stanford.edu/pipermail/openflow-spec/2009-August/000394.html"/> | |
1630 | </p> | |
1631 | ||
1632 | <conformance> | |
1633 | <p> | |
1634 | OpenFlow 1.1 introduced the <code>set_queue</code> action. Open | |
1635 | vSwitch also supports it as an extension in OpenFlow 1.0. | |
1636 | </p> | |
1637 | ||
1638 | <p> | |
1639 | The <code>pop_queue</code> action is an Open vSwitch extension. | |
1640 | </p> | |
1641 | </conformance> | |
1642 | </action> | |
1643 | </group> | |
1644 | ||
1645 | <group title="Firewalling Actions"> | |
1646 | <p> | |
1647 | Open vSwitch is often used to implement a firewall. The preferred way to | |
1648 | implement a firewall is ``connection tracking,'' that is, to keep track | |
1649 | of the connection state of individual TCP sessions. The <code>ct</code> | |
1650 | action described in this section, added in Open vSwitch 2.5, implements | |
1651 | connection tracking. For new deployments, it is the recommended way to | |
1652 | implement firewalling with Open vSwitch. | |
1653 | </p> | |
1654 | ||
1655 | <p> | |
1656 | Before <code>ct</code> was added, Open vSwitch did not have built-in | |
1657 | support for connection tracking. Instead, Open vSwitch supported the | |
1658 | <code>learn</code> action, which allows a received packet to add a flow | |
1659 | to an OpenFlow flow table. This could be used to implement a primitive | |
1660 | form of connection tracking: packets passing through the firewall in one | |
1661 | direction could create flows that allowed response packets back through | |
1662 | the firewall in the other direction. The additional | |
1663 | <code>fin_timeout</code> action allowed the learned flows to expire | |
1664 | quickly after TCP session termination. | |
1665 | </p> | |
1666 | ||
1667 | <action name="CT"> | |
1668 | <h2>The <code>ct</code> action</h2> | |
1669 | <syntax><code>ct(<var>argument</var></code>]...<code>)</code></syntax> | |
1670 | <syntax><code>ct(commit</code>[<code>, <var>argument</var></code>]...<code>)</code></syntax> | |
1671 | ||
1672 | <p> | |
1673 | The action has two modes of operation, distinguished by whether | |
1674 | <code>commit</code> is present. The following arguments may be present | |
1675 | in either mode: | |
1676 | </p> | |
1677 | ||
1678 | <dl> | |
1679 | <dt><code>zone=<var>value</var></code></dt> | |
1680 | <dd> | |
1681 | A zone is a 16-bit id that isolates connections into separate | |
1682 | domains, allowing overlapping network addresses in different zones. | |
1683 | If a zone is not provided, then the default is 0. The | |
1684 | <var>value</var> may be specified either as a 16-bit integer literal | |
1685 | or a field or subfield in the syntax described under ``Field | |
1686 | Specifications'' above. | |
1687 | </dd> | |
1688 | </dl> | |
1689 | ||
1690 | <p> | |
1691 | Without <code>commit</code>, this action sends the packet through the | |
1692 | connection tracker. The connection tracker keeps track of the state of | |
1693 | TCP connections for packets passed through it. For each packet through | |
1694 | a connection, it checks that it satisfies TCP invariants and signals | |
1695 | the connection state to later actions using the <code>ct_state</code> | |
1696 | metadata field, which is documented in <code>ovs-fields</code>(7). | |
1697 | </p> | |
1698 | ||
1699 | <p> | |
1700 | In this form, <code>ct</code> forks the OpenFlow pipeline: | |
1701 | </p> | |
1702 | ||
1703 | <ul> | |
1704 | <li> | |
1705 | In one fork, <code>ct</code> passes the packet to the connection | |
1706 | tracker. Afterward, it reinjects the packet into the OpenFlow | |
1707 | pipeline with the connection tracking fields initialized. The | |
1708 | <code>ct_state</code> field is initialized with connection state and | |
1709 | <code>ct_zone</code> to the connection tracking zone specified on the | |
1710 | <code>zone</code> argument. If the connection is one that is already | |
1711 | tracked, <code>ct_mark</code> and <code>ct_label</code> to its | |
1712 | existing mark and label, respectively; otherwise they are zeroed. In | |
1713 | addition, <code>ct_nw_proto</code>, <code>ct_nw_src</code>, | |
1714 | <code>ct_nw_dst</code>, <code>ct_ipv6_src</code>, | |
1715 | <code>ct_ipv6_dst</code>, <code>ct_tp_src</code>, and | |
1716 | <code>ct_tp_dst</code> are initialized appropriately for the original | |
1717 | direction connection. See the <code>resubmit</code> action for a way | |
1718 | to search the flow table with the connection tracking original | |
1719 | direction fields swapped with the packet 5-tuple fields. See | |
1720 | <code>ovs-fields</code>(7) for details on the connection tracking | |
1721 | fields. | |
1722 | </li> | |
1723 | ||
1724 | <li> | |
1725 | In the other fork, the original instance of the packet continues | |
1726 | independent processing following the <code>ct</code> action. The | |
1727 | <code>ct_state</code> field and other connection tracking metadata | |
1728 | are cleared. | |
1729 | </li> | |
1730 | </ul> | |
1731 | ||
1732 | <p> | |
1733 | Without <code>commit</code>, the <code>ct</code> action accepts the | |
1734 | following arguments: | |
1735 | </p> | |
1736 | ||
1737 | <dl> | |
1738 | <dt><code>table=<var>table</var></code></dt> | |
1739 | <dd> | |
1740 | Sets the OpenFlow table where the packet is reinjected. The | |
1741 | <var>table</var> must be a number between 0 and 254 inclusive, or a | |
1742 | table's name. If <var>table</var> is not specified, then the packet | |
1743 | is not reinjected. | |
1744 | </dd> | |
1745 | ||
1746 | <dt><code>nat</code></dt> | |
1747 | <dt><code>nat(<var>type</var>=<var>addrs</var></code>[<code>:<var>ports</var></code>][<code>,<var>flag</var></code>]...<code>)</code></dt> | |
1748 | <dd> | |
1749 | <p> | |
1750 | Specify address and port translation for the connection being | |
1751 | tracked. The <var>type</var> must be <code>src</code>, for source | |
1752 | address/port translation (SNAT), or <code>dst</code>, for destination | |
1753 | address/port translation (DNAT). Setting up address translation for | |
1754 | a new connection takes effect only if the connection is later | |
1755 | committed with <code>ct(commit</code>...<code>)</code>. | |
1756 | </p> | |
1757 | ||
1758 | <p> | |
1759 | The <code>src</code> and <code>dst</code> options take the following | |
1760 | arguments: | |
1761 | </p> | |
1762 | ||
1763 | <dl> | |
1764 | <dt><var>addrs</var></dt> | |
1765 | <dd> | |
1766 | The IP address <var>addr</var> or range | |
1767 | <code><var>addr1</var>-<var>addr2</var></code> from which the | |
1768 | translated address should be selected. If only one address is | |
1769 | given, then that address will always be selected, otherwise the | |
1770 | address selection can be informed by the optional persistent flag | |
1771 | as described below. Either IPv4 or IPv6 addresses can be provided, | |
1772 | but both addresses must be of the same type, and the datapath | |
1773 | behavior is undefined in case of providing IPv4 address range for | |
1774 | an IPv6 packet, or IPv6 address range for an IPv4 packet. IPv6 | |
1775 | addresses must be bracketed with <code>[</code> and <code>]</code> | |
1776 | if a port range is also given. | |
1777 | </dd> | |
1778 | ||
1779 | <dt><var>ports</var></dt> | |
1780 | <dd> | |
1781 | The L4 <var>port</var> or range | |
1782 | <code><var>port1</var>-<var>port2</var></code> from which the | |
32b2c81f DB |
1783 | translated port should be selected. When a port range is |
1784 | specified, fallback to ephemeral ports does not happen, else, | |
1785 | it will. The port number selection can be informed by the | |
1786 | optional <code>random</code> and <code>hash</code> flags | |
1787 | described below. The userspace datapath only supports the | |
1788 | <code>hash</code> behavior. | |
be51cd41 BP |
1789 | </dd> |
1790 | </dl> | |
1791 | ||
1792 | <p> | |
1793 | The optional flags are: | |
1794 | </p> | |
1795 | ||
1796 | <dl> | |
1797 | <dt><code>random</code></dt> | |
1798 | <dd> | |
1799 | The selection of the port from the given range should be done using | |
1800 | a fresh random number. This flag is mutually exclusive with | |
1801 | <code>hash</code>. | |
1802 | </dd> | |
1803 | ||
1804 | <dt><code>hash</code></dt> | |
1805 | <dd> | |
1806 | The selection of the port from the given range should be done using | |
1807 | a datapath specific hash of the packet's IP addresses and the | |
1808 | other, non-mapped port number. This flag is mutually exclusive | |
1809 | with <code>random</code>. | |
1810 | </dd> | |
1811 | ||
1812 | <dt><code>persistent</code></dt> | |
1813 | <dd> | |
1814 | The selection of the IP address from the given range should be done | |
1815 | so that the same mapping can be provided after the system restarts. | |
1816 | </dd> | |
1817 | </dl> | |
1818 | ||
1819 | <p> | |
1820 | If <code>alg</code> is specified for the committing <code>ct</code> | |
1821 | action that also includes <code>nat</code> with a <code>src</code> or | |
1822 | <code>dst</code> attribute, then the datapath tries to set up the | |
1823 | helper to be NAT-aware. This functionality is datapath specific and | |
1824 | may not be supported by all datapaths. | |
1825 | </p> | |
1826 | ||
1827 | <p> | |
1828 | A ``bare'' <code>nat</code> argument with no options will only | |
1829 | translate the packet being processed in the way the connection has been | |
1830 | set up with an earlier, committed <code>ct</code> action. A | |
1831 | <code>nat</code> action with <code>src</code> or <code>dst</code>, when | |
1832 | applied to a packet belonging to an established (rather than new) | |
1833 | connection, will behave the same as a bare <code>nat</code>. | |
1834 | </p> | |
1835 | ||
1836 | <p> | |
1837 | Open vSwitch 2.6 introduced <code>nat</code>. Linux 4.6 was the | |
1838 | earliest upstream kernel that implemented <code>ct</code> support for | |
1839 | <code>nat</code>. | |
1840 | </p> | |
1841 | </dd> | |
1842 | </dl> | |
1843 | ||
1844 | <p> | |
1845 | With <code>commit</code>, the connection tracker commits the connection | |
1846 | to the connection tracking module. The <code>commit</code> flag should | |
1847 | only be used from the pipeline within the first fork of <code>ct</code> | |
1848 | without <code>commit</code>. Information about the connection is | |
1849 | stored beyond the lifetime of the packet in the pipeline. Some | |
1850 | <code>ct_state</code> flags are only available for committed | |
1851 | connections. | |
1852 | </p> | |
1853 | ||
1854 | <p> | |
1855 | The following options are available only with <code>commit</code>: | |
1856 | </p> | |
1857 | ||
1858 | <dl> | |
1859 | <dt><code>force</code></dt> | |
1860 | <dd> | |
1861 | A committed connection always has the directionality of the packet | |
1862 | that caused the connection to be committed in the first place. This | |
1863 | is the ``original direction'' of the connection, and the opposite | |
1864 | direction is the ``reply direction''. If a connection is already | |
1865 | committed, but it is in the wrong direction, <code>force</code> | |
1866 | effectively terminates the existing connection and starts a new one | |
1867 | in the current direction. This flag has no effect if the original | |
1868 | direction of the connection is already the same as that of the | |
1869 | current packet. | |
1870 | </dd> | |
1871 | ||
1872 | <dt><code>exec(<var>action</var></code>...<code>)</code></dt> | |
1873 | <dd> | |
1874 | <p> | |
1875 | Perform each <var>action</var> within the context of connection | |
1876 | tracking. Only actions which modify the <code>ct_mark</code> or | |
1877 | <code>ct_label</code> fields are accepted within <code>exec</code> | |
1878 | action, and these fields may only be modified with this option. For | |
1879 | example: | |
1880 | </p> | |
1881 | ||
1882 | <dl> | |
1883 | <dt><code>set_field:<var>value</var>[/<var>mask</var>]->ct_mark</code></dt> | |
1884 | <dd> | |
1885 | Store a 32-bit metadata value with the connection. Subsequent | |
1886 | lookups for packets in this connection will populate | |
1887 | <code>ct_mark</code> when the packet is sent to the connection | |
1888 | tracker with the table specified. | |
1889 | </dd> | |
1890 | ||
1891 | <dt><code>set_field:<var>value</var>[/<var>mask</var>]->ct_label</code></dt> | |
1892 | <dd> | |
1893 | Store a 128-bit metadata value with the connection. Subsequent | |
1894 | lookups for packets in this connection will populate | |
1895 | <code>ct_label</code> when the packet is sent to the connection | |
1896 | tracker with the table specified. | |
1897 | </dd> | |
1898 | </dl> | |
1899 | </dd> | |
1900 | ||
1901 | <dt><code>alg=<var>alg</var></code></dt> | |
1902 | <dd> | |
1903 | <p> | |
1904 | Specify application layer gateway <var>alg</var> to track specific | |
1905 | connection types. If subsequent related connections are sent | |
1906 | through the <code>ct</code> action, then the <code>rel</code> flag | |
1907 | in the <code>ct_state</code> field will be set. Supported types | |
1908 | include: | |
1909 | </p> | |
1910 | ||
1911 | <dl> | |
1912 | <dt><code>ftp</code></dt> | |
1913 | <dd> | |
1914 | Look for negotiation of FTP data connections. Specify this | |
1915 | option for FTP control connections to detect related data | |
1916 | connections and populate the <code>rel</code> flag for the data | |
1917 | connections. | |
1918 | </dd> | |
1919 | ||
1920 | <dt><code>tftp</code></dt> | |
1921 | <dd> | |
1922 | <p> | |
1923 | Look for negotiation of TFTP data connections. Specify this | |
1924 | option for TFTP control connections to detect related data | |
1925 | connections and populate the <code>rel</code> flag for the data | |
1926 | connections. | |
1927 | </p> | |
1928 | </dd> | |
1929 | </dl> | |
1930 | ||
1931 | <p> | |
1932 | Related connections inherit <code>ct_mark</code> from that stored | |
1933 | with the original connection (i.e. the connection created by | |
1934 | <code>ct(alg=</code>...<code>)</code>). | |
1935 | </p> | |
1936 | </dd> | |
1937 | </dl> | |
1938 | ||
1939 | <p> | |
1940 | With the Linux datapath, global sysctl options affect <code>ct</code> | |
1941 | behavior. In particular, if | |
1942 | <code>net.netfilter.nf_conntrack_helper</code> is enabled, which it is | |
1943 | by default until Linux 4.7, then application layer gateway helpers may | |
1944 | be executed even if <code>alg</code> is not specified. For security | |
1945 | reasons, the netfilter team recommends users disable this option. For | |
1946 | further details, please see <url | |
1947 | href="http://www.netfilter.org/news.html#2012-04-03"/>. | |
1948 | </p> | |
1949 | ||
1950 | <p> | |
1951 | The <code>ct</code> action may be used as a primitive to construct | |
1952 | stateful firewalls by selectively committing some traffic, then | |
1953 | matching <code>ct_state</code> to allow established connections while | |
1954 | denying new connections. The following flows provide an example of how | |
1955 | to implement a simple firewall that allows new connections from port 1 | |
1956 | to port 2, and only allows established connections to send traffic from | |
1957 | port 2 to port 1: | |
1958 | </p> | |
1959 | ||
1960 | <pre> | |
1961 | table=0,priority=1,action=drop | |
1962 | table=0,priority=10,arp,action=normal | |
1963 | table=0,priority=100,ip,ct_state=-trk,action=ct(table=1) | |
1964 | table=1,in_port=1,ip,ct_state=+trk+new,action=ct(commit),2 | |
1965 | table=1,in_port=1,ip,ct_state=+trk+est,action=2 | |
1966 | table=1,in_port=2,ip,ct_state=+trk+new,action=drop | |
1967 | table=1,in_port=2,ip,ct_state=+trk+est,action=1 | |
1968 | </pre> | |
1969 | ||
1970 | <p> | |
1971 | If <code>ct</code> is executed on IPv4 (or IPv6) fragments, then the | |
1972 | message is implicitly reassembled before sending to the connection | |
1973 | tracker and refragmented upon output, to the original maximum received | |
1974 | fragment size. Reassembly occurs within the context of the zone, | |
1975 | meaning that IP fragments in different zones are not assembled | |
1976 | together. Pipeline processing for the initial fragments is halted. | |
1977 | When the final fragment is received, the message is assembled and | |
1978 | pipeline processing continues for that flow. Packet ordering is not | |
1979 | guaranteed by IP protocols, so it is not possible to determine which IP | |
1980 | fragment will cause message reassembly (and therefore continue pipeline | |
1981 | processing). As such, it is strongly recommended that multiple flows | |
1982 | should not execute <code>ct</code> to reassemble fragments from the | |
1983 | same IP message. | |
1984 | </p> | |
1985 | ||
1986 | <conformance> | |
1987 | The <code>ct</code> action was introduced in Open vSwitch 2.5. Some of | |
1988 | its features were introduced later, noted individually above. | |
1989 | </conformance> | |
1990 | </action> | |
1991 | ||
1992 | <action name="CT_CLEAR"> | |
1993 | <h2>The <code>ct_clear</code> action</h2> | |
1994 | <syntax><code>ct_clear</code></syntax> | |
1995 | ||
1996 | <p> | |
1997 | Clears connection tracking state from the flow, zeroing | |
1998 | <code>ct_state</code>, <code>ct_zone</code>, <code>ct_mark</code>, and | |
1999 | <code>ct_label</code>. | |
2000 | </p> | |
2001 | ||
2002 | <p> | |
2003 | This action was introduced in Open vSwitch 2.6.90. | |
2004 | </p> | |
2005 | </action> | |
2006 | ||
2007 | <action name="LEARN"> | |
2008 | <h2>The <code>learn</code> action</h2> | |
2009 | <syntax><code>learn(<var>argument</var></code>...<code>)</code></syntax> | |
2010 | ||
2011 | <p> | |
2012 | The <code>learn</code> action adds or modifies a flow in an OpenFlow | |
2013 | table, similar to <code>ovs-ofctl --strict mod-flows</code>. The | |
2014 | arguments specify the match fields, actions, and other properties of | |
2015 | the flow to be added or modified. | |
2016 | </p> | |
2017 | ||
2018 | <p> | |
2019 | Match fields for the new flow are specified as follows. At least one | |
2020 | match field should ordinarily be specified: | |
2021 | </p> | |
2022 | ||
2023 | <dl> | |
2024 | <dt><code><var>field</var>=<var>value</var></code></dt> | |
2025 | <dd> | |
2026 | <p> | |
2027 | Specifies that <var>field</var>, in the new flow, must match the | |
2028 | literal <var>value</var>, e.g. <code>dl_type=0x800</code>. | |
2029 | Shorthand match syntax, such as <code>ip</code> in place of | |
2030 | <code>dl_type=0x800</code>, is not supported. | |
2031 | </p> | |
2032 | </dd> | |
2033 | ||
2034 | <dt><code><var>field</var>=<var>src</var></code></dt> | |
2035 | <dd> | |
2036 | <p> | |
2037 | Specifies that <var>field</var> in the new flow must match | |
2038 | <var>src</var> taken from the packet currently being processed. | |
2039 | For example, <code>udp_dst=udp_src</code>, applied to a UDP packet | |
2040 | with source port 53, creates a flow which matches | |
2041 | <code>udp_dst=53</code>. <var>field</var> and <var>src</var> must | |
2042 | have the same width. | |
2043 | </p> | |
2044 | </dd> | |
2045 | ||
2046 | <dt><code><var>field</var></code></dt> | |
2047 | <dd> | |
2048 | Shorthand for the previous form when <var>field</var> and | |
2049 | <var>src</var> are the same. For example, <code>udp_dst</code>, | |
2050 | applied to a UDP packet with destination port 53, creates a flow | |
2051 | which matches <code>udp_dst=53</code>. | |
2052 | </dd> | |
2053 | </dl> | |
2054 | ||
2055 | <p> | |
2056 | The <var>field</var> and <var>src</var> arguments above should be | |
2057 | fields or subfields in the syntax described under ``Field | |
2058 | Specifications'' above. | |
2059 | </p> | |
2060 | ||
2061 | <p> | |
2062 | Match field specifications must honor prerequisites for both the flow | |
2063 | with the <code>learn</code> and the new flow that it creates. Consider | |
2064 | the following complete flow, in the syntax accepted by | |
2065 | <code>ovs-ofctl</code>. If the flow's match on <code>udp</code> were | |
2066 | omitted, then the flow would not satisfy the prerequisites for the | |
2067 | <code>learn</code> action's use of <code>udp_src</code>. If | |
2068 | <code>dl_type=0x800</code> or <code>nw_proto</code> were omitted from | |
2069 | <code>learn</code>, then the new flow would not satisfy the | |
2070 | prerequisite for its match on <code>udp_dst</code>. For more | |
2071 | information on prerequisites, please refer to | |
2072 | <code>ovs-fields</code>(7): | |
2073 | </p> | |
2074 | ||
2075 | <pre> | |
2076 | udp, actions=learn(dl_type=0x800, nw_proto=17, udp_dst=udp_src) | |
2077 | </pre> | |
2078 | ||
2079 | <p> | |
2080 | Actions for the new flow are specified as follows. At least one action | |
2081 | should ordinarily be specified: | |
2082 | </p> | |
2083 | ||
2084 | <dl> | |
2085 | <dt><code>load:<var>value</var>-><var>dst</var></code></dt> | |
2086 | <dd> | |
2087 | Adds a <code>load</code> action to the new flow that loads the | |
2088 | literal <var>value</var> into <var>dst</var>. The syntax is the same | |
2089 | as the <code>load</code> action explained in the ``Header | |
2090 | Modification'' section. | |
2091 | </dd> | |
2092 | ||
2093 | <dt><code>load:<var>src</var>-><var>dst</var></code></dt> | |
2094 | <dd> | |
2095 | Adds a <code>load</code> action to the new flow that loads | |
2096 | <var>src</var>, a field or subfield from the packet being processed, | |
2097 | into <var>dst</var>. | |
2098 | </dd> | |
2099 | ||
2100 | <dt><code>output:<var>field</var></code></dt> | |
2101 | <dd> | |
2102 | Adds an <code>output</code> action to the new flow's actions that | |
2103 | outputs to the OpenFlow port taken from <var>field</var>, which must | |
2104 | be a field as described above. | |
2105 | </dd> | |
2106 | ||
2107 | <dt><code>fin_idle_timeout=<var>seconds</var></code></dt> | |
2108 | <dt><code>fin_hard_timeout=<var>seconds</var></code></dt> | |
2109 | <dd> | |
2110 | Adds a <code>fin_timeout</code> action with the specified arguments | |
2111 | to the new flow. This feature was added in Open vSwitch 1.5.90. | |
2112 | </dd> | |
2113 | </dl> | |
2114 | ||
2115 | The following additional arguments are optional: | |
2116 | ||
2117 | <dl> | |
2118 | <dt><code>idle_timeout=<var>seconds</var></code></dt> | |
2119 | <dt><code>hard_timeout=<var>seconds</var></code></dt> | |
2120 | <dt><code>priority=<var>value</var></code></dt> | |
2121 | <dt><code>cookie=<var>value</var></code></dt> | |
2122 | <dt><code>send_flow_rem</code></dt> | |
2123 | <dd> | |
2124 | These arguments have the same meaning as in the usual flow syntax | |
2125 | documented in <code>ovs-ofctl</code>(8). | |
2126 | </dd> | |
2127 | ||
2128 | <dt><code>table=<var>table</var></code></dt> | |
2129 | <dd> | |
2130 | The table in which the new flow should be inserted. Specify a | |
2131 | decimal number between 0 and 254 inclusive or the name of a table. | |
2132 | The default, if table is unspecified, is table 1 (not 0). | |
2133 | </dd> | |
2134 | ||
2135 | <dt><code>delete_learned</code></dt> | |
2136 | <dd> | |
2137 | <p> | |
2138 | When this flag is specified, deleting the flow that contains the | |
2139 | <code>learn</code> action will also delete the flows created by | |
2140 | <code>learn</code>. Specifically, when the last <code>learn</code> | |
2141 | action with this flag and particular <code>table</code> and | |
2142 | <code>cookie</code> values is removed, the switch deletes all of | |
2143 | the flows in the specified table with the specified cookie. | |
2144 | </p> | |
2145 | ||
2146 | <p> | |
2147 | This flag was added in Open vSwitch 2.4. | |
2148 | </p> | |
2149 | </dd> | |
2150 | ||
2151 | <dt><code>limit=<var>number</var></code></dt> | |
2152 | <dd> | |
2153 | <p> | |
2154 | If the number of flows in the new flow's table with the same cookie | |
2155 | exceeds <code>number</code>, the action will not add a new flow. | |
2156 | By default, or with <code>limit=0</code>, there is no limit. | |
2157 | </p> | |
2158 | ||
2159 | <p> | |
2160 | This flag was added in Open vSwitch 2.8. | |
2161 | </p> | |
2162 | </dd> | |
2163 | ||
2164 | <dt><code>result_dst=<var>field</var>[<var>bit</var>]</code></dt> | |
2165 | <dd> | |
2166 | <p> | |
2167 | If learn fails (because the number of flows exceeds | |
2168 | <code>limit</code>), the action sets | |
2169 | <code><var>field</var>[<var>bit</var>]</code> to 0, otherwise it | |
2170 | will be set to 1. <code>field[bit]</code> must be a single bit. | |
2171 | </p> | |
2172 | ||
2173 | <p> | |
2174 | This flag was added in Open vSwitch 2.8. | |
2175 | </p> | |
2176 | </dd> | |
2177 | </dl> | |
2178 | ||
2179 | <p> | |
2180 | By itself, the <code>learn</code> action can only put two kinds of | |
2181 | actions into the flows that it creates: <code>load</code> and | |
2182 | <code>output</code> actions. If <code>learn</code> is used in | |
2183 | isolation, these are severe limits. | |
2184 | </p> | |
2185 | ||
2186 | <p> | |
2187 | However, <code>learn</code> is not meant to be used in isolation. It | |
2188 | is a primitive meant to be used together with other Open vSwitch | |
2189 | features to accomplish a task. Its existing features are enough to | |
2190 | accomplish most tasks. | |
2191 | </p> | |
2192 | ||
2193 | <p> | |
2194 | Here is an outline of a typical pipeline structure that allows for | |
2195 | versatile behavior using <code>learn</code>: | |
2196 | </p> | |
2197 | ||
2198 | <ul> | |
2199 | <li> | |
2200 | Flows in table <var>A</var> contain a <code>learn</code> action, that | |
2201 | populates flows in table <var>L</var>, that use a <code>load</code> | |
2202 | action to populate register <var>R</var> with information about what | |
2203 | was learned. | |
2204 | </li> | |
2205 | ||
2206 | <li> | |
2207 | Flows in table <var>B</var> contain two sequential resubmit actions: | |
2208 | one to table <var>L</var> and another one to table <var>B</var>+1. | |
2209 | </li> | |
2210 | ||
2211 | <li> | |
2212 | Flows in table <var>B</var>+1 match on register <var>R</var> and act | |
2213 | differently depending on what the flows in table <var>L</var> loaded | |
2214 | into it. | |
2215 | </li> | |
2216 | </ul> | |
2217 | ||
2218 | <p> | |
2219 | This approach can be used to implement many <code>learn</code>-based | |
2220 | features. For example: | |
2221 | </p> | |
2222 | ||
2223 | <ul> | |
2224 | <li> | |
2225 | Resubmit to a table selected based on learned information, e.g. see | |
2226 | <url href="https://mail.openvswitch.org/pipermail/ovs-discuss/2016-June/021694.html"/>. | |
2227 | </li> | |
2228 | ||
2229 | <li> | |
2230 | MAC learning in the middle of a pipeline, as described in the ``Open | |
2231 | vSwitch Advanced Features Tutorial'' in the OVS documentation. | |
2232 | </li> | |
2233 | ||
2234 | <li> | |
2235 | TCP state based firewalling, by learning outgoing connections based | |
2236 | on SYN packets and matching them up with incoming packets. (This is | |
2237 | usually better implemented using the <code>ct</code> action.) | |
2238 | </li> | |
2239 | ||
2240 | <li> | |
2241 | At least some of the features described in T. A. Hoff, ``Extending | |
2242 | Open vSwitch to Facilitate Creation of Stateful SDN Applications''. | |
2243 | </li> | |
2244 | </ul> | |
2245 | ||
2246 | <conformance> | |
2247 | The <code>learn</code> action is an Open vSwitch extension to OpenFlow | |
2248 | added in Open vSwitch 1.3. Some features of <code>learn</code> were | |
2249 | added in later versions, as noted individually above. | |
2250 | </conformance> | |
2251 | </action> | |
2252 | ||
2253 | <action name="FIN_TIMEOUT"> | |
2254 | <h2>The <code>fin_timeout</code> action</h2> | |
2255 | <syntax><code>fin_timeout(<var>key</var>=<var>value</var></code>...<code>)</code></syntax> | |
2256 | ||
2257 | <p> | |
2258 | This action changes the idle timeout or hard timeout, or both, of the | |
2259 | OpenFlow flow that contains it, when the flow matches a TCP packet with | |
2260 | the FIN or RST flag. When such a packet is observed, the action | |
2261 | reduces the rule's timeouts to those specified on the action. If the | |
2262 | rule's existing timeout is already shorter than the one that the action | |
2263 | specifies, then that timeout is unaffected. | |
2264 | </p> | |
2265 | ||
2266 | <p> | |
2267 | The timeouts are specified as key-value pairs: | |
2268 | </p> | |
2269 | ||
2270 | <dl> | |
2271 | <dt><code>idle_timeout=</code><var>seconds</var></dt> | |
2272 | <dd> | |
2273 | Causes the flow to expire after the given number of seconds of | |
2274 | inactivity. | |
2275 | </dd> | |
2276 | ||
2277 | <dt><code>hard_timeout=</code><var>seconds</var></dt> | |
2278 | <dd> | |
2279 | Causes the flow to expire after the given number of | |
2280 | <var>seconds</var>, regardless of activity. (<var>seconds</var> | |
2281 | specifies time since the flow's creation, not since the receipt of | |
2282 | the FIN or RST.) | |
2283 | </dd> | |
2284 | </dl> | |
2285 | ||
2286 | <p> | |
2287 | This action is normally added to a learned flow by the | |
2288 | <code>learn</code> action. It is unlikely to be useful otherwise. | |
2289 | </p> | |
2290 | ||
2291 | <conformance> | |
2292 | This Open vSwitch extension action was added in Open vSwitch 1.5.90. | |
2293 | </conformance> | |
2294 | </action> | |
2295 | </group> | |
2296 | ||
2297 | <group title="Programming and Control Flow Actions"> | |
2298 | <action name="RESUBMIT"> | |
2299 | <h2>The <code>resubmit</code> action</h2> | |
2300 | <syntax><code>resubmit:<var>port</var></code></syntax> | |
2301 | <syntax><code>resubmit(</code>[<code><var>port</var></code>]<code>,</code>[<code><var>table</var></code>][<code>,ct</code>]<code>)</code></syntax> | |
2302 | ||
2303 | <p> | |
2304 | Searches an OpenFlow flow table for a matching flow and executes the | |
2305 | actions found, if any, before continuing to the following action in the | |
2306 | current flow entry. Arguments can customize the search: | |
2307 | </p> | |
2308 | ||
2309 | <ul> | |
2310 | <li> | |
2311 | If <var>port</var> is given as an OpenFlow port number or name, then | |
2312 | it specifies a value to use for the input port metadata field as part | |
2313 | of the search, in place of the input port currently in the flow. | |
2314 | Specifying <code>in_port</code> as <var>port</var> is equivalent to | |
2315 | omitting it. | |
2316 | </li> | |
2317 | ||
2318 | <li> | |
2319 | If <var>table</var> is given as an integer between 0 and 254 or a | |
2320 | table name, it specifies the OpenFlow table to search. If it is not | |
2321 | specified, the table from the current flow is used. | |
2322 | </li> | |
2323 | ||
2324 | <li> | |
2325 | <p> | |
2326 | If <code>ct</code> is specified, then the search is done with | |
2327 | packet 5-tuple fields swapped with the corresponding conntrack | |
2328 | original direction tuple fields. See the documentation for | |
2329 | <code>ct</code> above, for more information about connection | |
2330 | tracking, or <code>ovs-fields</code>(7) for details about the | |
2331 | connection tracking fields. | |
2332 | </p> | |
2333 | ||
2334 | <p> | |
2335 | This flag requires a valid connection tracking state as a match | |
2336 | prerequisite in the flow where this action is placed. Examples of | |
2337 | valid connection tracking state matches include | |
2338 | <code>ct_state=+new</code>, <code>ct_state=+est</code>, | |
2339 | <code>ct_state=+rel</code>, and <code>ct_state=+trk-inv</code>. | |
2340 | </p> | |
2341 | </li> | |
2342 | </ul> | |
2343 | ||
2344 | <p> | |
2345 | The changes, if any, to the input port and connection tracking fields | |
2346 | are just for searching the flow table. The changes are not visible to | |
2347 | actions or to later flow table lookups. | |
2348 | </p> | |
2349 | ||
2350 | <p> | |
2351 | The most common use of <code>resubmit</code> is to visit another flow | |
2352 | table without <var>port</var> or <code>ct</code>, like this: | |
2353 | <code>resubmit(,<var>table</var>)</code>. | |
2354 | </p> | |
2355 | ||
2356 | <p> | |
2357 | Recursive <code>resubmit</code> actions are permitted. | |
2358 | </p> | |
2359 | ||
2360 | <conformance> | |
2361 | <p> | |
2362 | The <code>resubmit</code> action is an Open vSwitch extension. | |
2363 | However, the <code>goto_table</code> instruction in OpenFlow 1.1 and | |
2364 | later can be viewed as a kind of restricted <code>resubmit</code>. | |
2365 | </p> | |
2366 | ||
2367 | <p> | |
2368 | Open vSwitch 1.2.90 added <var>table</var>. Open vSwitch 2.7 added | |
2369 | <code>ct</code>. | |
2370 | </p> | |
2371 | ||
2372 | <p> | |
2373 | Open vSwitch imposes a limit on <code>resubmit</code> recursion that | |
2374 | varies among version: | |
2375 | </p> | |
2376 | ||
2377 | <ul> | |
2378 | <li> | |
2379 | Open vSwitch 1.0.1 and earlier did not support recursion. | |
2380 | </li> | |
2381 | ||
2382 | <li> | |
2383 | Open vSwitch 1.0.2 and 1.0.3 limited recursion to 8 levels. | |
2384 | </li> | |
2385 | ||
2386 | <li> | |
2387 | Open vSwitch 1.1 and 1.2 limited recursion to 16 levels. | |
2388 | </li> | |
2389 | ||
2390 | <li> | |
2391 | Open vSwitch 1.2 through 1.8 limited recursion to 32 levels. | |
2392 | </li> | |
2393 | ||
2394 | <li> | |
2395 | Open vSwitch 1.9 through 2.0 limited recursion to 64 levels. | |
2396 | </li> | |
2397 | ||
2398 | <li> | |
2399 | Open vSwitch 2.1 through 2.5 limited recursion to 64 levels and | |
2400 | impose a total limit of 4,096 resubmits per flow translation | |
2401 | (earlier versions did not impose any total limit). | |
2402 | </li> | |
2403 | ||
2404 | <li> | |
2405 | Open vSwitch 2.6 and later imposes the same limits as 2.5, with one | |
2406 | exception: resubmit from table <var>x</var> to any table | |
2407 | <var>y</var> > <var>x</var> does not count against the recursion | |
2408 | depth limit. | |
2409 | </li> | |
2410 | </ul> | |
2411 | </conformance> | |
2412 | </action> | |
2413 | ||
2414 | <action name="CLONE"> | |
2415 | <h2>The <code>clone</code> action</h2> | |
2416 | <syntax><code>clone(<var>action</var>...)</code></syntax> | |
2417 | ||
2418 | <p> | |
2419 | Executes each nested <var>action</var>, saving much of the packet and | |
2420 | pipeline state beforehand and then restoring it afterward. The state | |
2421 | that is saved and restored includes all flow data and metadata | |
2422 | (including, for example, <code>in_port</code> and | |
2423 | <code>ct_state</code>), the stack accessed by <code>push</code> and | |
2424 | <code>pop</code> actions, and the OpenFlow action set. | |
2425 | </p> | |
2426 | ||
2427 | <p> | |
2428 | This action was added in Open vSwitch 2.6.90. | |
2429 | </p> | |
2430 | </action> | |
2431 | ||
2432 | <action name="STACK_PUSH, STACK_POP"> | |
2433 | <h2>The <code>push</code> and <code>pop</code> actions</h2> | |
2434 | <syntax><code>push:<var>src</var></code></syntax> | |
2435 | <syntax><code>pop:<var>dst</var></code></syntax> | |
2436 | <p> | |
2437 | The <code>push</code> action pushes <var>src</var> on a general-purpose | |
2438 | stack. The <code>pop</code> action pops an entry off the stack into | |
2439 | <var>dst</var>. <var>src</var> and <var>dst</var> should be fields or | |
2440 | subfields in the syntax described under ``Field Specifications'' above. | |
2441 | </p> | |
2442 | ||
2443 | <p> | |
2444 | Controllers can use the stack for saving and restoring data or metadata | |
2445 | around <code>resubmit</code> actions, for swapping or rearranging data | |
2446 | and metadata, or for other purposes. Any data or metadata field, or | |
2447 | part of one, may be pushed, and any modifiable field or subfield may be | |
2448 | popped. | |
2449 | </p> | |
2450 | ||
2451 | <p> | |
2452 | The number of bits pushed in a stack entry do not have to match the | |
2453 | number of bits later popped from that entry. If more bits are popped | |
2454 | from an entry than were pushed, then the entry is conceptually | |
2455 | left-padded with 0-bits as needed. If fewer bits are popped than | |
2456 | pushed, then bits are conceptually trimmed from the left side of the | |
2457 | entry. | |
2458 | </p> | |
2459 | ||
2460 | <p> | |
2461 | The stack's size is limited. The limit is intended to be high enough | |
2462 | that ``normal'' use will not pose problems. Stack overflow or | |
2463 | underflow is an error that stops action execution (see ``Stack too | |
2464 | deep'' under ``Error Handling'', above). | |
2465 | </p> | |
2466 | ||
2467 | <p> | |
2468 | Examples: | |
2469 | </p> | |
2470 | ||
2471 | <ul> | |
2472 | <li> | |
2473 | <code>push:reg2[0..5]</code> or <code>push:NXM_NX_REG2[0..5]</code> | |
2474 | pushes on the stack the 6 bits in register 2 bits 0 through 5. | |
2475 | </li> | |
2476 | ||
2477 | <li> | |
2478 | <code>pop:reg2[0..5]</code> or <code>pop:NXM_NX_REG2[0..5]</code> | |
2479 | pops the value from top of the stack and copy bits 0 through 5 of | |
2480 | that value into bits 0 through 5 of register 2. | |
2481 | </li> | |
2482 | </ul> | |
2483 | ||
2484 | <conformance> | |
2485 | Open vSwitch 1.2 introduced <code>push</code> and <code>pop</code> as | |
2486 | OpenFlow extension actions. | |
2487 | </conformance> | |
2488 | </action> | |
2489 | ||
2490 | <action name="EXIT"> | |
2491 | <h2>The <code>exit</code> action</h2> | |
2492 | <syntax><code>exit</code></syntax> | |
2493 | ||
2494 | <p> | |
2495 | This action causes Open vSwitch to immediately halt execution of | |
2496 | further actions. Actions which have already been executed are | |
2497 | unaffected. Any further actions, including those which may be in other | |
2498 | tables, or different levels of the <code>resubmit</code> call stack, | |
2499 | are ignored. However, an <code>exit</code> action within a group | |
2500 | bucket terminates only execution of that bucket, not other buckets or | |
2501 | the overall pipeline. Actions in the action set are still executed | |
2502 | (specify <code>clear_actions</code> before <code>exit</code> to discard | |
2503 | them). | |
2504 | </p> | |
2505 | </action> | |
2506 | ||
2507 | <action name="MULTIPATH"> | |
2508 | <h2>The <code>multipath</code> action</h2> | |
2509 | <syntax><code>multipath(<var>fields</var>, <var>basis</var>, <var>algorithm</var>, <var>n_links</var>, <var>arg</var>, <var>dst</var>)</code></syntax> | |
2510 | ||
2511 | <p> | |
2512 | Hashes <var>fields</var> using <var>basis</var> as a universal hash | |
2513 | parameter, then the applies multipath link selection | |
2514 | <var>algorithm</var> (with parameter <var>arg</var>) to choose one of | |
2515 | <var>n_links</var> output links numbered 0 through <var>n_links</var> | |
2516 | minus 1, and stores the link into <var>dst</var>, which must be a field | |
2517 | or subfield in the syntax described under ``Field Specifications'' | |
2518 | above. | |
2519 | </p> | |
2520 | ||
2521 | <p> | |
2522 | The <code>bundle</code> or <code>bundle_load</code> actions are usually | |
2523 | easier to use than <code>multipath</code>. | |
2524 | </p> | |
2525 | ||
2526 | <p> | |
2527 | <var>fields</var> must be one of the following: | |
2528 | </p> | |
2529 | ||
2530 | <dl> | |
2531 | <dt><code>eth_src</code></dt> | |
2532 | <dd> | |
2533 | Hashes Ethernet source address only. | |
2534 | </dd> | |
2535 | ||
2536 | <dt><code>symmetric_l4</code></dt> | |
2537 | <dd> | |
2538 | Hashes Ethernet source, destination, and type, VLAN ID, IPv4/IPv6 | |
70506167 | 2539 | source, destination, and protocol, and TCP or SCTP (but not UDP) |
be51cd41 BP |
2540 | ports. The hash is computed so that pairs of corresponding flows in |
2541 | each direction hash to the same value, in environments where L2 paths | |
2542 | are the same in each direction. UDP ports are not included in the | |
70506167 | 2543 | hash to support protocols such as VXLAN that use asymmetric ports |
be51cd41 BP |
2544 | in each direction. |
2545 | </dd> | |
2546 | ||
2547 | <dt><code>symmetric_l3l4</code></dt> | |
2548 | <dd> | |
2549 | Hashes IPv4/IPv6 source, destination, and protocol, and TCP or SCTP | |
2550 | (but not UDP) ports. Like <code>symmetric_l4</code>, this is a | |
2551 | symmetric hash, but by excluding L2 headers it is more effective in | |
2552 | environments with asymmetric L2 paths (e.g. paths involving VRRP IP | |
2553 | addresses on a router). Not an effective hash function for protocols | |
2554 | other than IPv4 and IPv6, which hash to a constant zero. | |
2555 | </dd> | |
2556 | ||
2557 | <dt><code>symmetric_l3l4+udp</code></dt> | |
2558 | <dd> | |
2559 | Like <code>symmetric_l3l4+udp</code>, but UDP ports are included in | |
2560 | the hash. This is a more effective hash when asymmetric UDP | |
2561 | protocols such as VXLAN are not a consideration. | |
2562 | </dd> | |
2563 | ||
2564 | <dt><code>symmetric_l3</code></dt> | |
2565 | <dd> | |
2566 | Hashes network source address and network destination address. | |
2567 | </dd> | |
2568 | ||
2569 | <dt><code>nw_src</code></dt> | |
2570 | <dd> | |
2571 | Hashes network source address only. | |
2572 | </dd> | |
2573 | ||
2574 | <dt><code>nw_dst</code></dt> | |
2575 | <dd> | |
2576 | Hashes network destination address only. | |
2577 | </dd> | |
2578 | </dl> | |
2579 | ||
2580 | <p> | |
2581 | The <var>algorithm</var> used to compute the final result | |
2582 | <var>link</var> must be one of the following: | |
2583 | </p> | |
2584 | ||
2585 | <dl> | |
2586 | <dt><code>modulo_n</code></dt> | |
2587 | <dd> | |
2588 | <p> | |
2589 | Computes <var>link</var> = hash(<var>flow</var>) % <var>n_links</var>. | |
2590 | </p> | |
2591 | ||
2592 | <p> | |
2593 | This algorithm redistributes all traffic when <var>n_links</var> | |
2594 | changes. It has <i>O(1)</i> performance. | |
2595 | </p> | |
2596 | ||
2597 | <p> | |
2598 | Use 65535 for <var>max_link</var> to get a raw hash value. | |
2599 | </p> | |
2600 | ||
2601 | <p> | |
2602 | This algorithm is specified by RFC 2992. | |
2603 | </p> | |
2604 | </dd> | |
2605 | ||
2606 | <dt><code>hash_threshold</code></dt> | |
2607 | <dd> | |
2608 | <p> | |
2609 | Computes <var>link</var> = hash(<var>flow</var>) / (<code>MAX_HASH</code> / <var>n_links</var>). | |
2610 | </p> | |
2611 | ||
2612 | <p> | |
2613 | Redistributes between one-quarter and one-half of traffic when | |
2614 | n_links changes. It has <i>O(1)</i> performance. | |
2615 | </p> | |
2616 | ||
2617 | <p> | |
2618 | This algorithm is specified by RFC 2992. | |
2619 | </p> | |
2620 | </dd> | |
2621 | ||
2622 | <dt><code>hrw</code> (Highest Random Weight)</dt> | |
2623 | <dd> | |
2624 | <p> | |
2625 | Computes the following: | |
2626 | </p> | |
2627 | ||
2628 | <pre> | |
2629 | for <var>i</var> in [0,<var>n_links</var>]: | |
2630 | <var>weights</var>[<var>i</var>] = hash(<var>flow</var>, <var>i</var>) | |
2631 | <var>link</var> = { <var>i</var> such that <var>weights</var>[<var>i</var>] >= <var>weights</var>[<var>j</var>] for all <var>j</var> != <var>i</var> } | |
2632 | </pre> | |
2633 | ||
2634 | <p> | |
2635 | Redistributes 1/<var>n_links</var> of traffic when | |
2636 | <var>n_links</var> changes. It has <i>O(<var>n_links</var>)</i> | |
2637 | performance. If <var>n_links</var> is greater than a threshold | |
2638 | (currently 64, but subject to change), Open vSwitch will substitute | |
2639 | another algorithm automatically. | |
2640 | </p> | |
2641 | ||
2642 | <p> | |
2643 | This algorithm is specified by RFC 2992. | |
2644 | </p> | |
2645 | </dd> | |
2646 | ||
2647 | <dt><code>iter_hash</code> (Iterative Hash)</dt> | |
2648 | <dd> | |
2649 | <p> | |
2650 | Computes the following: | |
2651 | </p> | |
2652 | ||
2653 | <pre> | |
2654 | <var>i</var> = 0 | |
2655 | repeat: | |
2656 | <var>i</var> = <var>i</var> + 1 | |
2657 | <var>link</var> = hash(<var>flow</var>, <var>i</var>) % <var>arg</var> | |
2658 | while <var>link</var> > <var>max_link</var> | |
2659 | </pre> | |
2660 | ||
2661 | <p> | |
2662 | Redistributes 1/<var>n_links</var> of traffic when | |
2663 | <var>n_links</var> changes. O(1) performance when | |
2664 | <var>arg</var>/<var>max_link</var> is bounded by a constant. | |
2665 | </p> | |
2666 | ||
2667 | <p> | |
2668 | Redistributes all traffic when <var>arg</var> changes. | |
2669 | </p> | |
2670 | ||
2671 | <p> | |
2672 | <var>arg</var> must be greater than <var>max_link</var> and for | |
2673 | best performance should be no more than approximately | |
2674 | <var>max_link</var> * 2. If <var>arg</var> is outside the | |
2675 | acceptable range, Open vSwitch will automatically substitute the | |
2676 | least power of 2 greater than <var>max_link</var>. | |
2677 | </p> | |
2678 | ||
2679 | <p> | |
2680 | This algorithm is specific to Open vSwitch. | |
2681 | </p> | |
2682 | </dd> | |
2683 | </dl> | |
2684 | ||
2685 | <p> | |
2686 | Only the <code>iter_hash</code> algorithm uses <var>arg</var>. | |
2687 | </p> | |
2688 | ||
2689 | <p> | |
2690 | It is an error if <var>max_link</var> is greater than or equal to | |
2691 | 2**<var>n_bits</var>. | |
2692 | </p> | |
2693 | ||
2694 | <conformance> | |
2695 | This is an OpenFlow extension added in Open vSwitch 1.1. | |
2696 | </conformance> | |
2697 | </action> | |
2698 | </group> | |
2699 | ||
2700 | <group title="Other Actions"> | |
2701 | <action name="CONJUNCTION"> | |
2702 | <h2>The <code>conjunction</code> action</h2> | |
2703 | <syntax><code>conjunction(<var>id</var>, <var>k</var>/<var>n</var>)</code></syntax> | |
2704 | ||
2705 | <p> | |
2706 | This action allows for sophisticated ``conjunctive match'' flows. | |
2707 | Refer to ``Conjunctive Match Fields'' in <code>ovs-fields</code>(7) for | |
2708 | details. | |
2709 | </p> | |
2710 | ||
2711 | <p> | |
2712 | A flow that has one or more <code>conjunction</code> actions may not | |
2713 | have any other actions except for <code>note</code> actions. | |
2714 | </p> | |
2715 | ||
2716 | <conformance> | |
2717 | Open vSwitch 2.4 introduced the <code>conjunction</code> action and | |
2718 | <code>conj_id</code> field. They are Open vSwitch extensions to | |
2719 | OpenFlow. | |
2720 | </conformance> | |
2721 | </action> | |
2722 | ||
2723 | <action name="NOTE"> | |
2724 | <h2>The <code>note</code> action</h2> | |
2725 | <syntax><code>note:</code>[<var>hh</var>]...</syntax> | |
2726 | ||
2727 | <p> | |
2728 | This action does nothing at all. OpenFlow controllers may use it to | |
2729 | annotate flows with more data than can fit in a flow cookie. | |
2730 | </p> | |
2731 | ||
2732 | <p> | |
2733 | The action may include any number of bytes represented as hex digits | |
2734 | <var>hh</var>. Periods may separate pairs of hex digits, for | |
2735 | readability. The <code>note</code> action's format doesn't include an | |
2736 | exact length for its payload, so the provided bytes will be padded on | |
2737 | the right by enough bytes with value 0 to make the total number 6 more | |
2738 | than a multiple of 8. | |
2739 | </p> | |
2740 | ||
2741 | <p> | |
2742 | ||
2743 | </p> | |
2744 | ||
2745 | <conformance> | |
2746 | This action is an extension to OpenFlow introduced in Open vSwitch 1.1. | |
2747 | </conformance> | |
2748 | </action> | |
2749 | ||
2750 | <action name="SAMPLE"> | |
2751 | <h2>The <code>sample</code> action</h2> | |
2752 | <syntax><code>sample(<var>argument</var>...)</code></syntax> | |
2753 | ||
2754 | <p> | |
2755 | Samples packets and sends one sample for every sampled packet. | |
2756 | </p> | |
2757 | ||
2758 | <p> | |
2759 | The following <var>argument</var> forms are accepted: | |
2760 | </p> | |
2761 | ||
2762 | <dl> | |
2763 | <dt><code>probability=<var>packets</var></code></dt> | |
2764 | <dd> | |
2765 | The number of sampled packets out of 65535. Must be greater or equal | |
2766 | to 1. | |
2767 | </dd> | |
2768 | ||
2769 | <dt><code>collector_set_id=<var>id</var></code></dt> | |
2770 | <dd> | |
2771 | The unsigned 32-bit integer identifier of the set of sample | |
2772 | collectors to send sampled packets to. Defaults to 0. | |
2773 | </dd> | |
2774 | ||
2775 | <dt><code>obs_domain_id=<var>id</var></code></dt> | |
2776 | <dd> | |
2777 | When sending samples to IPFIX collectors, the unsigned 32-bit integer | |
2778 | Observation Domain ID sent in every IPFIX flow record. Defaults to | |
2779 | 0. | |
2780 | </dd> | |
2781 | ||
2782 | <dt><code>obs_point_id=<var>id</var></code></dt> | |
2783 | <dd> | |
2784 | When sending samples to IPFIX collectors, the unsigned 32-bit integer | |
2785 | Observation Point ID sent in every IPFIX flow record. Defaults to 0. | |
2786 | </dd> | |
2787 | ||
2788 | <dt><code>sampling_port=<var>port</var></code></dt> | |
2789 | <dd> | |
2790 | Sample packets on <var>port</var>, which should be the ingress or | |
2791 | egress port. This option, which was added in Open vSwitch 2.5.90, | |
2792 | allows the IPFIX implementation to export egress tunnel information. | |
2793 | </dd> | |
2794 | ||
2795 | <dt><code>ingress</code></dt> | |
2796 | <dt><code>egress</code></dt> | |
2797 | <dd> | |
2798 | Specifies explicitly that the packet is being sampled on ingress to | |
2799 | or egress from the switch. IPFIX reports sent by Open vSwitch before | |
2800 | version 2.5.90 did not include a direction. From 2.5.90 until | |
2801 | 2.6.90, IPFIX reports inferred a direction from | |
2802 | <var>sampling_port</var>: if it was the packet's output port, then | |
2803 | the direction was reported as egress, otherwise as ingress. Open | |
2804 | vSwitch 2.6.90 introduced these options, which allow the inferred | |
2805 | direction to be overridden. This is particularly useful when the | |
2806 | ingress (or egress) port is not a tunnel. | |
2807 | </dd> | |
2808 | </dl> | |
2809 | ||
2810 | <p> | |
2811 | Refer to <code>ovs-vswitchd.conf.db</code>(5) for more details on | |
2812 | configuring sample collector sets. | |
2813 | </p> | |
2814 | ||
2815 | <conformance> | |
2816 | This action is an OpenFlow extension added in Open vSwitch 2.4. | |
2817 | </conformance> | |
2818 | </action> | |
2819 | </group> | |
2820 | ||
2821 | <group title="Instructions"> | |
2822 | <p> | |
2823 | Every version of OpenFlow includes actions. OpenFlow 1.1 introduced the | |
2824 | higher-level, related concept of <dfn>instructions</dfn>. In OpenFlow | |
2825 | 1.1 and later, actions within a flow are always encapsulated within an | |
2826 | instruction. Each flow has at most one instruction of each kind, which | |
2827 | are executed in the following fixed order defined in the OpenFlow | |
2828 | specification: | |
2829 | </p> | |
2830 | ||
2831 | <ol> | |
2832 | <li><code>Meter</code></li> | |
2833 | <li><code>Apply-Actions</code></li> | |
2834 | <li><code>Clear-Actions</code></li> | |
2835 | <li><code>Write-Actions</code></li> | |
2836 | <li><code>Write-Metadata</code></li> | |
2837 | <li><code>Stat-Trigger</code> (not supported by Open vSwitch)</li> | |
2838 | <li><code>Goto-Table</code></li> | |
2839 | </ol> | |
2840 | ||
2841 | <p> | |
2842 | The most important instruction is <code>Apply-Actions</code>. This | |
2843 | instruction encapsulates any number of actions, which the instruction | |
2844 | executes. Open vSwitch does not explicitly represent | |
2845 | <code>Apply-Actions</code>. Instead, any action by itself is implicitly | |
2846 | part of an <code>Apply-Actions</code> instructions. | |
2847 | </p> | |
2848 | ||
2849 | <p> | |
2850 | Open vSwitch syntax requires other instructions, if present, to be in the | |
2851 | order listed above. Otherwise it will flag an error. | |
2852 | </p> | |
2853 | ||
2854 | <action name="METER"> | |
2855 | <h2>The <code>meter</code> action and instruction</h2> | |
2856 | <syntax><code>meter:<var>meter_id</var></code></syntax> | |
2857 | ||
2858 | <p> | |
2859 | Apply meter <var>meter_id</var>. If a meter band rate is exceeded, the | |
2860 | packet may be dropped, or modified, depending on the meter band type. | |
2861 | </p> | |
2862 | ||
2863 | <conformance> | |
2864 | <p> | |
2865 | OpenFlow 1.3 introduced the <code>meter</code> instruction. OpenFlow | |
2866 | 1.5 changes <code>meter</code> from an instruction to an action. | |
2867 | </p> | |
2868 | ||
4332b671 BP |
2869 | <p> |
2870 | OpenFlow 1.5 allows implementations to restrict <code>meter</code> to | |
2871 | be the first action in an action list and to exclude | |
2872 | <code>meter</code> from action sets, for better compatibility with | |
2873 | OpenFlow 1.3 and 1.4. Open vSwitch restricts the <code>meter</code> | |
2874 | action both ways. | |
2875 | </p> | |
2876 | ||
be51cd41 BP |
2877 | <p> |
2878 | Open vSwitch 2.0 introduced OpenFlow protocol support for meters, but | |
2879 | it did not include a datapath implementation. Open vSwitch 2.7 added | |
2880 | meter support to the userspace datapath. Open vSwitch 2.10 added | |
4332b671 BP |
2881 | meter support to the kernel datapath. Open vSwitch 2.12 added |
2882 | support for meter as an action in OpenFlow 1.5. | |
be51cd41 BP |
2883 | </p> |
2884 | </conformance> | |
2885 | </action> | |
2886 | ||
2887 | <action name="CLEAR_ACTIONS"> | |
2888 | <h2>The <code>clear_actions</code> instruction</h2> | |
2889 | <syntax><code>clear_actions</code></syntax> | |
2890 | ||
2891 | <p> | |
2892 | Clears the action set. See ``Action Sets'', above, for more | |
2893 | information. | |
2894 | </p> | |
2895 | ||
2896 | <conformance> | |
2897 | OpenFlow 1.1 introduced <code>clear_actions</code>. Open vSwitch 2.1 | |
2898 | added support for <code>clear_actions</code>. | |
2899 | </conformance> | |
2900 | </action> | |
2901 | ||
2902 | <action name="WRITE_ACTIONS"> | |
2903 | <h2>The <code>write_actions</code> instruction</h2> | |
2904 | <syntax><code>write_actions(<var>action</var></code>...<code>)</code></syntax> | |
2905 | ||
2906 | <p> | |
2907 | Adds each <var>action</var> to the action set. The action set is | |
2908 | carried between flow tables and then executed at the end of the | |
2909 | pipeline. Only certain actions may be written to the action set. See | |
2910 | ``Action Sets'', above, for more information. | |
2911 | </p> | |
2912 | ||
2913 | <conformance> | |
2914 | OpenFlow 1.1 introduced <code>write_actions</code>. Open vSwitch 2.1 | |
2915 | added support for <code>write_actions</code>. | |
2916 | </conformance> | |
2917 | </action> | |
2918 | ||
2919 | <action name="WRITE_METADATA"> | |
2920 | <h2>The <code>write_metadata</code> instruction</h2> | |
2921 | <syntax><code>write_metadata:<var>value</var></code>[<code>/<var>mask</var></code>]</syntax> | |
2922 | ||
2923 | <p> | |
2924 | Updates the flow's <code>metadata</code> field. If <var>mask</var> is | |
2925 | omitted, <code>metadata</code> is set exactly to <var>value</var>; if | |
2926 | <var>mask</var> is specified, then a 1-bit in <var>mask</var> indicates | |
2927 | that the corresponding bit in <code>metadata</code> will be replaced | |
2928 | with the corresponding bit from <var>value</var>. Both | |
2929 | <var>value</var> and <var>mask</var> are 64-bit values that are decimal | |
2930 | by default; use a <code>0x</code> prefix to specify them in | |
2931 | hexadecimal. | |
2932 | </p> | |
2933 | ||
2934 | <p> | |
2935 | The <code>metadata</code> field can also be matched in the flow table | |
2936 | and updated with actions such as <code>set_field</code> and | |
2937 | <code>move</code>. | |
2938 | </p> | |
2939 | ||
2940 | <conformance> | |
2941 | OpenFlow 1.1 introduced <code>write_metadata</code>. Open vSwitch 2.1 | |
2942 | added support for <code>write_metadata</code>. | |
2943 | </conformance> | |
2944 | </action> | |
2945 | ||
2946 | <action name="GOTO_TABLE"> | |
2947 | <h2>The <code>goto_table</code> instruction</h2> | |
2948 | <syntax><code>goto_table:<var>table</var></code></syntax> | |
2949 | ||
2950 | <p> | |
2951 | Jumps to <var>table</var> as the next table in the process pipeline. | |
2952 | The table may be a number between 0 and 254 or a table name. | |
2953 | </p> | |
2954 | ||
2955 | <p> | |
2956 | It is an error if <var>table</var> is less than or equal to the table | |
2957 | of the flow that contains it; that is, <code>goto_table</code> must | |
2958 | move forward in the OpenFlow pipeline. Since <code>goto_table</code> | |
2959 | must be the last instruction in a flow, it never leads to recursion. | |
2960 | The <code>resubmit</code> extension action is more flexible. | |
2961 | </p> | |
2962 | ||
2963 | <conformance> | |
2964 | OpenFlow 1.1 introduced <code>goto_table</code>. Open vSwitch 2.1 | |
2965 | added support for <code>goto_table</code>. | |
2966 | </conformance> | |
2967 | </action> | |
2968 | </group> | |
2969 | </actions> |