]>
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> | |
5a7f15ab BP |
792 | <syntax><code>bundle(</code><var>fields</var><code>, </code><var>basis</var><code>, </code><var>algorithm</var><code>, ofport, slaves:</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>, slaves:</code><var>port</var>...<code>)</code></syntax> | |
be51cd41 BP |
794 | |
795 | <p> | |
796 | These actions choose a port (``slave'') from a comma-separated OpenFlow | |
797 | <var>port</var> list. After selecting the port, <code>bundle</code> | |
798 | outputs to it, whereas <code>bundle_load</code> writes its port number | |
5a7f15ab BP |
799 | to <var>dst</var>, which must be a 16-bit or wider field or subfield in |
800 | the syntax described under ``Field Specifications'' above. | |
be51cd41 BP |
801 | </p> |
802 | ||
803 | <p> | |
804 | These actions hash a set of <var>fields</var> using <var>basis</var> as | |
805 | a universal hash parameter, then apply the bundle link selection | |
806 | <var>algorithm</var> to choose a <var>port</var>. | |
807 | </p> | |
808 | ||
809 | <p> | |
810 | <var>fields</var> must be one of the following. For the options with | |
811 | ``symmetric'' in the name, reversing source and destination addresses | |
812 | yields the same hash: | |
813 | </p> | |
814 | ||
815 | <dl> | |
816 | <dt><code>eth_src</code></dt> | |
817 | <dd> | |
818 | Ethernet source address. | |
819 | </dd> | |
820 | ||
821 | <dt><code>nw_src</code></dt> | |
822 | <dd> | |
823 | IPv4 or IPv6 source address. | |
824 | </dd> | |
825 | ||
826 | <dt><code>nw_dst</code></dt> | |
827 | <dd> | |
828 | IPv4 or IPv6 destination address. | |
829 | </dd> | |
830 | ||
831 | <dt><code>symmetric_l4</code></dt> | |
832 | <dd> | |
833 | Ethernet source and destination, Ethernet type, VLAN ID or IDs (if | |
834 | any), IPv4 or IPv6 source and destination, IP protocol, TCP or SCTP | |
835 | (but not UDP) source and destination. | |
836 | </dd> | |
837 | ||
838 | <dt><code>symmetric_l3l4</code></dt> | |
839 | <dd> | |
840 | IPv4 or IPv6 source and destination, IP protocol, TCP or SCTP (but | |
841 | not UDP) source and destination. | |
842 | </dd> | |
843 | ||
844 | <dt><code>symmetric_l3l4+udp</code></dt> | |
845 | <dd> | |
846 | Like <code>symmetric_l3l4</code> but include UDP ports. | |
847 | </dd> | |
848 | </dl> | |
849 | ||
5a7f15ab BP |
850 | <p> |
851 | <var>algorithm</var> must be one of the following: | |
852 | </p> | |
853 | ||
854 | <dl> | |
855 | <dt><code>active_backup</code></dt> | |
856 | <dd> | |
857 | Chooses the first live port listed in <var>slaves</var>. | |
858 | </dd> | |
859 | ||
860 | <dt><code>hrw</code> (Highest Random Weight)</dt> | |
861 | <dd> | |
862 | <p> | |
863 | Computes the following, considering only the live ports in | |
864 | <var>slaves</var>: | |
865 | </p> | |
866 | ||
867 | <pre> | |
868 | for <var>i</var> in [1,<var>n_slaves</var>]: | |
869 | <var>weights</var>[<var>i</var>] = hash(<var>flow</var>, <var>i</var>) | |
870 | <var>slave</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> } | |
871 | </pre> | |
872 | ||
873 | <p> | |
874 | This algorithm is specified by RFC 2992. | |
875 | </p> | |
876 | </dd> | |
877 | </dl> | |
878 | ||
879 | <p> | |
880 | The algorithms take port liveness into account when selecting slaves. | |
881 | The definition of whether a port is live is subject to change. It | |
882 | currently takes into account carrier status and link monitoring | |
883 | protocols such as BFD and CFM. If none of the slaves is live, | |
884 | <code>bundle</code> does not output the packet and | |
885 | <code>bundle_load</code> stores <code>OFPP_NONE</code> (65535) in the | |
886 | output field. | |
887 | </p> | |
888 | ||
889 | <p> | |
890 | Example: <code>bundle(eth_src,0,hrw,ofport,slaves:4,8)</code> uses an | |
891 | Ethernet source hash with basis 0, to select between OpenFlow ports 4 | |
892 | and 8 using the Highest Random Weight algorithm. | |
893 | </p> | |
894 | ||
be51cd41 BP |
895 | <conformance> |
896 | Open vSwitch 1.2 introduced the <code>bundle</code> and | |
897 | <code>bundle_load</code> OpenFlow extension actions. | |
898 | </conformance> | |
899 | </action> | |
900 | ||
901 | <action name="GROUP"> | |
902 | <h2>The <code>group</code> action</h2> | |
903 | <syntax><code>group:</code><var>group</var></syntax> | |
904 | <p> | |
905 | Outputs the packet to the OpenFlow group <var>group</var>, which must | |
906 | be a number in the range 0 to 4294967040 (0xffffff00). The group must | |
907 | exist or Open vSwitch will refuse to add the flow. When a group is | |
908 | deleted, Open vSwitch also deletes all of the flows that output to it. | |
909 | </p> | |
910 | ||
911 | <p> | |
912 | Groups contain action sets, whose semantics are described above in the | |
913 | section ``Action Sets''. The semantics of action sets can be | |
914 | surprising to users who expect action list semantics, since action sets | |
915 | reorder and sometimes ignore actions. | |
916 | </p> | |
917 | ||
918 | <p> | |
919 | A <code>group</code> action usually executes the action set or sets in | |
920 | one or more group buckets. Open vSwitch saves the packet and metadata | |
921 | before it executes each bucket, and then restores it afterward. Thus, | |
922 | when a group executes more than one bucket, this means that each bucket | |
923 | executes on the same packet and metadata. Moreover, regardless of the | |
924 | number of buckets executed, the packet and metadata are the same before | |
925 | and after executing the group. | |
926 | </p> | |
927 | ||
928 | <p> | |
929 | Sometimes saving and restoring the packet and metadata can be | |
930 | undesirable. In these situations, workarounds are possible. For | |
931 | example, consider a pipeline design in which a <code>select</code> | |
932 | group bucket is to communicate to a later stage of processing a value | |
933 | based on which bucket was selected. An obvious design would be for the | |
934 | bucket to communicate the value via <code>set_field</code> on a | |
935 | register. This does not work because registers are part of the | |
afc0c379 BP |
936 | metadata that <code>group</code> saves and restores. The following |
937 | alternative bucket designs do work: | |
be51cd41 BP |
938 | </p> |
939 | ||
afc0c379 BP |
940 | <ul> |
941 | <li> | |
942 | Recursively invoke the rest of the pipeline with | |
943 | <code>resubmit</code>. | |
944 | </li> | |
945 | ||
946 | <li> | |
947 | <p> | |
948 | Use <code>resubmit</code> into a table that uses <code>push</code> | |
949 | to put the value on the stack for the caller to <code>pop</code> | |
950 | off. This works because <code>group</code> preserves only packet | |
951 | data and metadata, not the stack. | |
952 | </p> | |
953 | ||
954 | <p> | |
955 | (This design requires indirection through <code>resubmit</code> | |
956 | because actions sets may not contain <code>push</code> or | |
957 | <code>pop</code> actions.) | |
958 | </p> | |
959 | </li> | |
960 | </ul> | |
961 | ||
be51cd41 BP |
962 | <p> |
963 | An <code>exit</code> action within a group bucket terminates only | |
964 | execution of that bucket, not other buckets or the overall pipeline. | |
965 | </p> | |
966 | ||
967 | <conformance> | |
968 | OpenFlow 1.1 introduced <code>group</code>. Open vSwitch 2.6 and later | |
969 | also supports <code>group</code> as an extension to OpenFlow 1.0. | |
970 | </conformance> | |
971 | </action> | |
972 | ||
973 | </group> | |
974 | ||
975 | <group title="Encapsulation and Decapsulation Actions"> | |
976 | <action name="STRIP_VLAN"> | |
977 | <h2>The <code>strip_vlan</code> and <code>pop</code> actions</h2> | |
978 | <syntax><code>strip_vlan</code></syntax> | |
979 | <syntax><code>pop_vlan</code></syntax> | |
980 | ||
981 | <p> | |
982 | Removes the outermost VLAN tag, if any, from the packet. | |
983 | </p> | |
984 | ||
985 | <p> | |
986 | The two names for this action are synonyms with no semantic difference. | |
987 | The OpenFlow 1.0 specification uses the name <code>strip_vlan</code> | |
988 | and later versions use <code>pop_vlan</code>, but OVS accepts either | |
989 | name regardless of version. | |
990 | </p> | |
991 | ||
992 | <p> | |
993 | In OpenFlow 1.1 and later, consistency rules allow | |
994 | <code>strip_vlan</code> only in a flow that matches only packets with a | |
995 | VLAN tag (or following an action that pushes a VLAN tag, such as | |
996 | <code>push_vlan</code>). See ``Inconsistencies'', above, for more | |
997 | information. | |
998 | </p> | |
999 | ||
1000 | <conformance> | |
1001 | All versions of OpenFlow and Open vSwitch support this action. | |
1002 | </conformance> | |
1003 | </action> | |
1004 | ||
1005 | <action name="PUSH_VLAN"> | |
1006 | <h2>The <code>push_vlan</code> action</h2> | |
1007 | <syntax><code>push_vlan:</code><var>ethertype</var></syntax> | |
1008 | ||
1009 | <p> | |
1010 | Pushes a new outermost VLAN onto the packet. Uses TPID | |
1011 | <var>ethertype</var>, which must be <code>0x8100</code> for an 802.1Q | |
1012 | C-tag or <code>0x88a8</code> for a 802.1ad S-tag. | |
1013 | </p> | |
1014 | ||
1015 | <conformance> | |
1016 | OpenFlow 1.1 and later supports this action. Open vSwitch 2.8 added | |
1017 | support for multiple VLAN tags (with a limit of 2) and 802.1ad S-tags. | |
1018 | </conformance> | |
1019 | </action> | |
1020 | ||
1021 | <action name="PUSH_MPLS"> | |
1022 | <h2>The <code>push_mpls</code> action</h2> | |
1023 | <syntax><code>push_mpls:<var>ethertype</var></code></syntax> | |
1024 | ||
1025 | <p> | |
1026 | Pushes a new outermost MPLS label stack entry (LSE) onto the packet and | |
1027 | changes the packet's Ethertype to <var>ethertype</var>, which must be | |
1028 | either <code>B0x8847</code> or <code>0x8848</code>. | |
1029 | </p> | |
1030 | ||
1031 | <p> | |
1032 | If the packet did not already contain any MPLS labels, initializes the | |
1033 | new LSE as: | |
1034 | </p> | |
1035 | ||
1036 | <dl> | |
1037 | <dt>Label</dt> | |
1038 | <dd> | |
1039 | 2, if the packet contains IPv6, 0 otherwise. | |
1040 | </dd> | |
1041 | <dt>TC</dt> | |
1042 | <dd> | |
1043 | The low 3 bits of the packet's DSCP value, or 0 if the packet is not | |
1044 | IP. | |
1045 | </dd> | |
1046 | <dt>TTL</dt> | |
1047 | <dd> | |
1048 | Copied from the IP TTL, or 64 if the packet is not IP. | |
1049 | </dd> | |
1050 | </dl> | |
1051 | ||
1052 | <p> | |
1053 | If the packet did already contain an MPLS label, initializes the new | |
1054 | outermost label as a copy of the existing outermost label. | |
1055 | </p> | |
1056 | ||
1057 | <p> | |
1058 | OVS currently supports at most 3 MPLS labels. | |
1059 | </p> | |
1060 | ||
1061 | <p> | |
1062 | This action applies only to Ethernet packets. | |
1063 | </p> | |
1064 | ||
1065 | <conformance> | |
1066 | Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later | |
1067 | support <code>push_mpls</code>. Open vSwitch implements | |
1068 | <code>push_mpls</code> as an extension to OpenFlow 1.0. | |
1069 | </conformance> | |
1070 | </action> | |
1071 | ||
1072 | <action name="POP_MPLS"> | |
1073 | <h2>The <code>pop_mpls</code> action</h2> | |
1074 | <syntax><code>pop_mpls:<var>ethertype</var></code></syntax> | |
1075 | ||
1076 | <p> | |
1077 | Strips the outermost MPLS label stack entry and changes the packet's | |
1078 | Ethertype to <var>ethertype</var>. | |
1079 | </p> | |
1080 | ||
1081 | <p> | |
1082 | This action applies only to Ethernet packets with at least one MPLS | |
1083 | label. If there is more than one MPLS label, then <var>ethertype</var> | |
1084 | should be an MPLS Ethertype (<code>B0x8847</code> or | |
1085 | <code>0x8848</code>). | |
1086 | </p> | |
1087 | ||
1088 | <conformance> | |
1089 | Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and later | |
1090 | support <code>pop_mpls</code>. Open vSwitch implements | |
1091 | <code>pop_mpls</code> as an extension to OpenFlow 1.0. | |
1092 | </conformance> | |
1093 | </action> | |
1094 | ||
1095 | <action name="ENCAP"> | |
1096 | <h2>The <code>encap</code> action</h2> | |
1097 | <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> | |
1098 | <syntax><code>encap(ethernet)</code></syntax> | |
1099 | ||
1100 | <p> | |
1101 | The <code>encap</code> action encapsulates a packet with a specified | |
1102 | header. It has variants for different kinds of encapsulation. | |
1103 | </p> | |
1104 | ||
1105 | <p> | |
1106 | The <code>encap(nsh(</code>...<code>))</code> variant encapsulates an | |
1107 | Ethernet frame with NSH. The <var>md_type</var> may be <code>1</code> | |
1108 | or <code>2</code> for metadata type 1 or 2, defaulting to 1. For | |
1109 | metadata type 2, TLVs may be specified with <var>class</var> as a | |
1110 | 16-bit hexadecimal integer beginning with <code>0x</code>, | |
1111 | <var>type</var> as an 8-bit decimal integer, and <var>value</var> a | |
1112 | sequence of pairs of hex digits beginning with <code>0x</code>. For | |
1113 | example: | |
1114 | </p> | |
1115 | ||
1116 | <dl> | |
1117 | <dt><code>encap(nsh(md_type=1))</code></dt> | |
1118 | <dd> | |
1119 | Encapsulates the packet with an NSH header with metadata type 1. | |
1120 | </dd> | |
1121 | ||
1122 | <dt><code>encap(nsh(md_type=2,tlv(0x1000,10,0x12345678)))</code></dt> | |
1123 | <dd> | |
1124 | Encapsulates the packet with an NSH header, NSH metadata type 2, and | |
1125 | an NSH TLV with class 0x1000, type 10, and the 4-byte value | |
1126 | 0x12345678. | |
1127 | </dd> | |
1128 | </dl> | |
1129 | ||
1130 | <p> | |
1131 | The <code>encap(ethernet)</code> variant encapsulate a bare L3 packet | |
1132 | in an Ethernet frame. The Ethernet type is initialized to the L3 | |
1133 | packet's type, e.g. 0x0800 if the L3 packet is IPv4. The Ethernet | |
1134 | source and destination are initially zeroed. | |
1135 | </p> | |
1136 | ||
1137 | <conformance> | |
1138 | This action is an Open vSwitch extension to OpenFlow 1.3 and later, | |
1139 | introduced in Open vSwitch 2.8. | |
1140 | </conformance> | |
1141 | </action> | |
1142 | ||
1143 | <action name="DECAP"> | |
1144 | <h2>The <code>decap</code> action</h2> | |
1145 | <syntax><code>decap</code></syntax> | |
1146 | ||
1147 | <p> | |
1148 | Removes an outermost encapsulation from the packet: | |
1149 | </p> | |
1150 | ||
1151 | <ul> | |
1152 | <li> | |
1153 | If the packet is an Ethernet packet, removes the Ethernet header, | |
1154 | which changes the packet into a bare L3 packet. If the packet has | |
1155 | VLAN tags, raises an unsupported packet type error (see ``Error | |
1156 | Handling'', above). | |
1157 | </li> | |
1158 | ||
1159 | <li> | |
1160 | Otherwise, if the packet is an NSH packet, removes the NSH header, | |
1161 | revealing the inner packet. Open vSwitch supports Ethernet, IPv4, | |
1162 | IPv6, and NSH inner packet types. Other types raise unsupported | |
1163 | packet type errors. | |
1164 | </li> | |
1165 | ||
1166 | <li> | |
1167 | Otherwise, raises an unsupported packet type error. | |
1168 | </li> | |
1169 | </ul> | |
1170 | ||
1171 | <conformance> | |
1172 | This action is an Open vSwitch extension to OpenFlow 1.3 and later, | |
1173 | introduced in Open vSwitch 2.8. | |
1174 | </conformance> | |
1175 | </action> | |
1176 | </group> | |
1177 | ||
1178 | <group title="Field Modification Actions"> | |
1179 | <p> | |
1180 | These actions modify packet data and metadata fields. | |
1181 | </p> | |
1182 | ||
1183 | <action name="SET_FIELD"> | |
1184 | <h2>The <code>set_field</code> and <code>load</code> actions</h2> | |
1185 | <syntax><code>set_field:</code><var>value</var>[<code>/</code><var>mask</var>]<code>-></code><var>dst</var></syntax> | |
1186 | <syntax><code>load:</code><var>value</var><code>-></code><var>dst</var><code></code></syntax> | |
1187 | ||
1188 | <p> | |
1189 | These actions loads a literal value into a field or part of a field. | |
1190 | The <code>set_field</code> action takes <var>value</var> in the | |
1191 | customary syntax for field <var>dst</var>, | |
1192 | e.g. <code>00:11:22:33:44:55</code> for an Ethernet address, and | |
1193 | <var>dst</var> as the field's name. The optional <var>mask</var> | |
1194 | allows part of a field to be set. | |
1195 | </p> | |
1196 | ||
1197 | <p> | |
1198 | The <code>load</code> action takes <var>value</var> as an integer value | |
1199 | (in decimal or prefixed by <code>0x</code> for hexadecimal) and | |
1200 | <var>dst</var> as a field or subfield in the syntax described under | |
1201 | ``Field Specifications'' above. | |
1202 | </p> | |
1203 | ||
1204 | <p> | |
1205 | The following all set the Ethernet source address to 00:11:22:33:44:55: | |
1206 | </p> | |
1207 | ||
1208 | <ul> | |
1209 | <li><code>set_field:00:11:22:33:44:55->eth_src</code></li> | |
1210 | <li><code>load:0x001122334455->eth_src</code></li> | |
1211 | <li><code>load:0x001122334455->OXM_OF_ETH_SRC[]</code></li> | |
1212 | </ul> | |
1213 | ||
1214 | <p> | |
1215 | The following all set the multicast bit in the Ethernet destination | |
1216 | address: | |
1217 | </p> | |
1218 | ||
1219 | <ul> | |
1220 | <li><code>set_field:01:00:00:00:00:00/01:00:00:00:00:00->eth_dst</code></li> | |
1221 | <li><code>load:1->eth_dst[40]</code></li> | |
1222 | </ul> | |
1223 | ||
1224 | <p> | |
1225 | Open vSwitch prohibits a <code>set_field</code> or <code>load</code> | |
1226 | action whose <var>dst</var> is not guaranteed to be part of the packet; | |
1227 | for example, <code>set_field</code> of <code>nw_dst</code> is only | |
1228 | allowed in a flow that matches on Ethernet type 0x800. In some cases, | |
1229 | such as in an action set, Open vSwitch can't statically check that | |
1230 | <var>dst</var> is part of the packet, and in that case if it is not | |
1231 | then Open vSwitch treats the action as a no-op. | |
1232 | </p> | |
1233 | ||
1234 | <conformance> | |
1235 | Open vSwitch 1.1 introduced <code>NXAST_REG_LOAD</code> as a extension | |
1236 | to OpenFlow 1.0 and used <code>load</code> to express it. Later, | |
1237 | OpenFlow 1.2 introduced a standard <code>OFPAT_SET_FIELD</code> action | |
1238 | that was restricted to loading entire fields, so Open vSwitch added the | |
1239 | form <code>set_field</code> with this restriction. OpenFlow 1.5 | |
1240 | extended <code>OFPAT_SET_FIELD</code> to the point that it became a | |
1241 | superset of <code>NXAST_REG_LOAD</code>. Open vSwitch translates | |
1242 | either syntax as necessary for the OpenFlow version in use: in OpenFlow | |
1243 | 1.0 and 1.1, <code>NXAST_REG_LOAD</code>; in OpenFlow 1.2, 1.3, and | |
1244 | 1.4, <code>NXAST_REG_LOAD</code> for <code>load</code> or for loading a | |
1245 | subfield, <code>OFPAT_SET_FIELD</code> otherwise; and OpenFlow 1.5 and | |
1246 | later, <code>OFPAT_SET_FIELD</code>. | |
1247 | </conformance> | |
1248 | </action> | |
1249 | ||
1250 | <action name="REG_MOVE"> | |
1251 | <h2>The <code>move</code> action</h2> | |
1252 | <syntax><code>move:<var>src</var>-><var>dst</var></code></syntax> | |
1253 | ||
1254 | <p> | |
1255 | Copies the named bits from field or subfield <var>src</var> to field or | |
1256 | subfield <var>dst</var>. <var>src</var> and <var>dst</var> should | |
1257 | fields or subfields in the syntax described under ``Field | |
1258 | Specifications'' above. The two fields or subfields must have the same | |
1259 | width. | |
1260 | </p> | |
1261 | ||
1262 | <p> | |
1263 | Examples: | |
1264 | </p> | |
1265 | ||
1266 | <ul> | |
1267 | <li> | |
1268 | <code>move:reg0[0..5]->reg1[26..31]</code> copies the six bits | |
1269 | numbered 0 through 5 in register 0 into bits 26 through 31 of | |
1270 | register 1. | |
1271 | </li> | |
1272 | <li> | |
1273 | <code>move:reg0[0..15]->vlan_tci</code> copies the least | |
1274 | significant 16 bits of register 0 into the VLAN TCI field. | |
1275 | </li> | |
1276 | </ul> | |
1277 | ||
1278 | <conformance> | |
1279 | In OpenFlow 1.0 through 1.4, <code>move</code> ordinarily uses an Open | |
1280 | vSwitch extension to OpenFlow. In OpenFlow 1.5, <code>move</code> uses | |
1281 | the OpenFlow 1.5 standard <code>OFPAT_COPY_FIELD</code> action. The | |
1282 | ONF has also made <code>OFPAT_COPY_FIELD</code> available as an | |
1283 | extension to OpenFlow 1.3. Open vSwitch 2.4 and later understands this | |
1284 | extension and uses it if a controller uses it, but for backward | |
1285 | compatibility with older versions of Open vSwitch, | |
1286 | <code>ovs-ofctl</code> does not use it. | |
1287 | </conformance> | |
1288 | </action> | |
1289 | ||
1290 | <action name="SET_ETH_SRC, SET_ETH_DST"> | |
1291 | <h2>The <code>mod_dl_src</code> and <code>mod_dl_dst</code> actions</h2> | |
1292 | <syntax><code>mod_dl_src:</code><var>mac</var></syntax> | |
1293 | <syntax><code>mod_dl_dst:</code><var>mac</var></syntax> | |
1294 | ||
1295 | <p> | |
1296 | Sets the Ethernet source or destination address, respectively, to | |
1297 | <var>mac</var>, which should be expressed in the form | |
1298 | <code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code>. | |
1299 | </p> | |
1300 | ||
1301 | <p> | |
1302 | For L3-only packets, that is, those that lack an Ethernet header, this | |
1303 | action has no effect. | |
1304 | </p> | |
1305 | ||
1306 | <conformance> | |
1307 | OpenFlow 1.0 and 1.1 have specialized actions for these purposes. | |
1308 | OpenFlow 1.2 and later do not, so Open vSwitch translates them to | |
1309 | appropriate <code>OFPAT_SET_FIELD</code> actions for those versions, | |
1310 | </conformance> | |
1311 | </action> | |
1312 | ||
1313 | <action name="SET_IP_SRC, SET_IP_DST"> | |
1314 | <h2>The <code>mod_nw_src</code> and <code>mod_nw_dst</code> actions</h2> | |
1315 | <syntax><code>mod_nw_src:</code><var>ip</var></syntax> | |
1316 | <syntax><code>mod_nw_dst:</code><var>ip</var></syntax> | |
1317 | ||
1318 | <p> | |
1319 | Sets the IPv4 source or destination address, respectively, to | |
1320 | <var>ip</var>, which should be expressed in the form | |
1321 | <code><var>w</var>.<var>x</var>.<var>y</var>.<var>z</var></code>. | |
1322 | </p> | |
1323 | ||
1324 | <p> | |
1325 | In OpenFlow 1.1 and later, consistency rules allow these actions only | |
1326 | in a flow that matches only packets that contain an IPv4 header (or | |
1327 | following an action that adds an IPv4 header, | |
1328 | e.g. <code>pop_mpls:0x0800</code>). See ``Inconsistencies'', above, | |
1329 | for more information. | |
1330 | </p> | |
1331 | ||
1332 | <conformance> | |
1333 | OpenFlow 1.0 and 1.1 have specialized actions for these purposes. | |
1334 | OpenFlow 1.2 and later do not, so Open vSwitch translates them to | |
1335 | appropriate <code>OFPAT_SET_FIELD</code> actions for those versions, | |
1336 | </conformance> | |
1337 | </action> | |
1338 | ||
1339 | <action name="SET_IP_DSCP, SET_IP_ECN"> | |
1340 | <h2>The <code>mod_nw_tos</code> and <code>mod_nw_ecn</code> actions</h2> | |
1341 | <syntax><code>mod_nw_tos:</code><var>tos</var></syntax> | |
1342 | <syntax><code>mod_nw_ecn:</code><var>ecn</var></syntax> | |
1343 | ||
1344 | <p> | |
1345 | The <code>mod_nw_tos</code> action sets the DSCP bits in the IPv4 | |
1346 | ToS/DSCP or IPv6 traffic class field to <var>tos</var>, which must be a | |
1347 | multiple of 4 between 0 and 255. This action does not modify the two | |
1348 | least significant bits of the ToS field (the ECN bits). | |
1349 | </p> | |
1350 | ||
1351 | <p> | |
1352 | The <code>mod_nw_ecn</code> action sets the ECN bits in the IPv4 ToS or | |
1353 | IPv6 traffic class field to <code>ecn</code>, which must be a value | |
1354 | between 0 and 3, inclusive. This action does not modify the six most | |
1355 | significant bits of the field (the DSCP bits). | |
1356 | </p> | |
1357 | ||
1358 | <p> | |
1359 | In OpenFlow 1.1 and later, consistency rules allow these actions only | |
1360 | in a flow that matches only packets that contain an IPv4 or IPv6 header | |
1361 | (or following an action that adds such a header). See | |
1362 | ``Inconsistencies'', above, for more information. | |
1363 | </p> | |
1364 | ||
1365 | <conformance> | |
1366 | OpenFlow 1.0 has a <code>mod_nw_tos</code> action but not | |
1367 | <code>mod_nw_ecn</code>. Open vSwitch implements the latter in | |
1368 | OpenFlow 1.0 as an extension using <code>NXAST_REG_LOAD</code>. | |
1369 | OpenFlow 1.1 has specialized actions for these purposes. OpenFlow 1.2 | |
1370 | and later do not, so Open vSwitch translates them to appropriate | |
1371 | <code>OFPAT_SET_FIELD</code> actions for those versions, | |
1372 | </conformance> | |
1373 | </action> | |
1374 | ||
1375 | <action name="SET_L4_SRC_PORT, SET_L4_DST_PORT"> | |
1376 | <h2>The <code>mod_tp_src</code> and <code>mod_tp_dst</code> actions</h2> | |
1377 | <syntax><code>mod_tp_src:</code><var>port</var></syntax> | |
1378 | <syntax><code>mod_tp_dst:</code><var>port</var></syntax> | |
1379 | ||
1380 | <p> | |
1381 | Sets the TCP or UDP or SCTP source or destination port, respectively, | |
1382 | to <var>port</var>. Both IPv4 and IPv6 are supported. | |
1383 | </p> | |
1384 | ||
1385 | <p> | |
1386 | In OpenFlow 1.1 and later, consistency rules allow these actions only | |
1387 | in a flow that matches only packets that contain a TCP or UDP or SCTP | |
1388 | header. See ``Inconsistencies'', above, for more information. | |
1389 | </p> | |
1390 | ||
1391 | <conformance> | |
1392 | OpenFlow 1.0 and 1.1 have specialized actions for these purposes. | |
1393 | OpenFlow 1.2 and later do not, so Open vSwitch translates them to | |
1394 | appropriate <code>OFPAT_SET_FIELD</code> actions for those versions, | |
1395 | </conformance> | |
1396 | </action> | |
1397 | ||
1398 | <action name="DEC_TTL"> | |
1399 | <h2>The <code>dec_ttl</code> action</h2> | |
1400 | <syntax><code>dec_ttl</code></syntax> | |
1401 | <syntax><code>dec_ttl(<var>id1</var>, </code>[<code><var>id2</var></code>]...<code>)</code></syntax> | |
1402 | ||
1403 | <p> | |
1404 | Decrement TTL of IPv4 packet or hop limit of IPv6 packet. If the TTL | |
1405 | or hop limit is initially 0 or 1, no decrement occurs, as packets | |
1406 | reaching TTL zero must be rejected. Instead, Open vSwitch sends a | |
1407 | ``packet-in'' message with reason code <code>OFPR_INVALID_TTL</code> to | |
1408 | each connected controller that has enabled receiving such messages, and | |
1409 | stops processing the current set of actions. (However, if the current | |
1410 | set of actions was reached through <code>resubmit</code>, the remaining | |
1411 | actions in outer levels resume processing.) | |
1412 | </p> | |
1413 | ||
1414 | <p> | |
1415 | As an Open vSwitch extension to OpenFlow, this action supports the | |
1416 | ability to specify a list of controller IDs. Open vSwitch will only | |
1417 | send the message to controllers with the given ID or IDs. Specifying | |
1418 | no list is equivalent to specifying a single controller ID of zero. | |
1419 | </p> | |
1420 | ||
1421 | <p> | |
1422 | Sets the TCP or UDP or SCTP source or destination port, respectively, | |
1423 | to <var>port</var>. Both IPv4 and IPv6 are supported. | |
1424 | </p> | |
1425 | ||
1426 | <p> | |
1427 | In OpenFlow 1.1 and later, consistency rules allow these actions only | |
1428 | in a flow that matches only packets that contain an IPv4 or IPv6 | |
1429 | header. See ``Inconsistencies'', above, for more information. | |
1430 | </p> | |
1431 | ||
1432 | <conformance> | |
1433 | All versions of OpenFlow and Open vSwitch support this action. | |
1434 | </conformance> | |
1435 | </action> | |
1436 | ||
1437 | <action name="SET_MPLS_LABEL, SET_MPLS_TC, SET_MPLS_TTL"> | |
1438 | <h2>The <code>set_mpls_label</code>, <code>set_mpls_tc</code>, and <code>set_mpls_ttl</code> actions</h2> | |
1439 | <syntax><code>set_mpls_label:</code><var>label</var></syntax> | |
1440 | <syntax><code>set_mpls_tc:</code><var>tc</var></syntax> | |
1441 | <syntax><code>set_mpls_ttl:</code><var>ttl</var></syntax> | |
1442 | ||
1443 | <p> | |
1444 | The <code>set_mpls_label</code> action sets the label of the packet's | |
1445 | outer MPLS label stack entry. <var>label</var> should be a 20-bit | |
1446 | value that is decimal by default; use a <code>0x</code> prefix to | |
1447 | specify the value in hexadecimal. | |
1448 | </p> | |
1449 | ||
1450 | <p> | |
1451 | The <code>set_mpls_tc</code> action sets the traffic class of the | |
1452 | packet's outer MPLS label stack entry. <var>tc</var> should be in the | |
1453 | range 0 to 7, inclusive. | |
1454 | </p> | |
1455 | ||
1456 | <p> | |
1457 | The <code>set_mpls_ttl</code> action sets the TTL of the packet's outer | |
1458 | MPLS label stack entry. <var>ttl</var> should be in the range 0 to 255 | |
1459 | inclusive. | |
1460 | </p> | |
1461 | ||
1462 | <p> | |
1463 | In OpenFlow 1.1 and later, consistency rules allow these actions only | |
1464 | in a flow that matches only packets that contain an MPLS label (or | |
1465 | following an action that adds an MPLS label, | |
1466 | e.g. <code>push_mpls:0x8847</code>). See ``Inconsistencies'', above, | |
1467 | for more information. | |
1468 | </p> | |
1469 | ||
1470 | <conformance> | |
1471 | OpenFlow 1.0 does not support MPLS, but Open vSwitch implements these | |
1472 | actions as extensions. OpenFlow 1.1 has specialized actions for these | |
1473 | purposes. OpenFlow 1.2 and later do not, so Open vSwitch translates | |
1474 | them to appropriate <code>OFPAT_SET_FIELD</code> actions for those | |
1475 | versions, | |
1476 | </conformance> | |
1477 | </action> | |
1478 | ||
1479 | <action name="DEC_MPLS_TTL, DEC_NSH_TTL"> | |
1480 | <h2>The <code>dec_mpls_ttl</code> and <code>dec_nsh_ttl</code> actions</h2> | |
1481 | <syntax><code>dec_mpls_ttl</code></syntax> | |
1482 | <syntax><code>dec_nsh_ttl</code></syntax> | |
1483 | ||
1484 | <p> | |
1485 | These actions decrement the TTL of the packet's outer MPLS label stack | |
1486 | entry or its NSH header, respectively. If the TTL is initially 0 or 1, | |
1487 | no decrement occurs. Instead, Open vSwitch sends a ``packet-in'' | |
1488 | message with reason code <code>BOFPR_INVALID_TTL</code> to OpenFlow | |
1489 | controllers with ID 0, if it has enabled receiving them. Processing | |
1490 | the current set of actions then stops. (However, if the current set of | |
1491 | actions was reached through <code>resubmit</code>, remaining actions in | |
1492 | outer levels resume processing.) | |
1493 | </p> | |
1494 | ||
1495 | <p> | |
1496 | In OpenFlow 1.1 and later, consistency rules allow this actions only in | |
1497 | a flow that matches only packets that contain an MPLS label or an NSH | |
1498 | header, respectively. See ``Inconsistencies'', above, for more | |
1499 | information. | |
1500 | </p> | |
1501 | ||
1502 | <conformance> | |
1503 | <p> | |
1504 | Open vSwitch 1.11 introduced support for MPLS. OpenFlow 1.1 and | |
1505 | later support <code>dec_mpls_ttl</code>. Open vSwitch implements | |
1506 | <code>dec_mpls_ttl</code> as an extension to OpenFlow 1.0. | |
1507 | </p> | |
1508 | ||
1509 | <p> | |
1510 | Open vSwitch 2.8 introduced support for NSH, although the NSH draft | |
1511 | changed after release so that only Open vSwitch 2.9 and later conform | |
1512 | to the final protocol specification. The <code>dec_nsh_ttl</code> | |
1513 | action and NSH support in general is an Open vSwitch extension not | |
1514 | supported by any version of OpenFlow. | |
1515 | </p> | |
1516 | </conformance> | |
1517 | </action> | |
5b34f8fc NS |
1518 | |
1519 | <action name="CHECK_PKT_LARGER"> | |
1520 | <h2>The <code>check_pkt_larger</code> action</h2> | |
1521 | <syntax> | |
1522 | <code>check_pkt_larger(<var>pkt_len</var>)-><var>dst</var></code> | |
1523 | </syntax> | |
1524 | ||
1525 | <p> | |
1526 | Checks if the packet is larger than the specified length in | |
1527 | <var>pkt_len</var>. If so, stores 1 in <var>dst</var>, which should be | |
1528 | a 1-bit field; if not, stores 0. | |
1529 | </p> | |
1530 | ||
1531 | <p> | |
1532 | The packet length to check againt the argument <var>pkt_len</var> | |
1533 | includes the L2 header and L2 payload of the packet, but not the VLAN | |
1534 | tag (if present). | |
1535 | </p> | |
1536 | ||
1537 | <p> | |
1538 | Examples: | |
1539 | </p> | |
1540 | ||
1541 | <ul> | |
1542 | <li> | |
1543 | <code>check_pkt_larger(1500)->reg0[0]</code> | |
1544 | </li> | |
1545 | ||
1546 | <li> | |
1547 | <code>check_pkt_larger(8000)->reg9[10]</code> | |
1548 | </li> | |
1549 | </ul> | |
1550 | ||
1551 | <p> | |
1552 | This action was added in Open vSwitch 2.11.90. | |
1553 | </p> | |
1554 | </action> | |
be51cd41 BP |
1555 | </group> |
1556 | ||
1557 | <group title="Metadata Actions"> | |
1558 | <action name="SET_TUNNEL"> | |
1559 | <h2>The <code>set_tunnel</code> action</h2> | |
1560 | <syntax><code>set_tunnel:</code><var>id</var></syntax> | |
1561 | <syntax><code>set_tunnel64:</code><var>id</var></syntax> | |
1562 | ||
1563 | <p> | |
1564 | Many kinds of tunnels support a tunnel ID, e.g. VXLAN and Geneve have a | |
1565 | 24-bit VNI, and GRE has an optional 32-bit key. This action sets the | |
1566 | value used for tunnel ID in such tunneled packets, although whether it | |
1567 | is used for a particular tunnel depends on the tunnel's configuration. | |
1568 | See the tunnel ID documentation in <code>ovs-fields</code>(7) for more | |
1569 | information. | |
1570 | </p> | |
1571 | ||
1572 | <conformance> | |
1573 | <p> | |
1574 | These actions are OpenFlow extensions. <code>set_tunnel</code> was | |
1575 | introduced in Open vSwitch 1.0. <code>set_tunnel64</code>, which is | |
1576 | needed if <var>id</var> is wider than 32 bits, was added in Open | |
1577 | vSwitch 1.1. Both actions always set the entire tunnel ID field. | |
1578 | </p> | |
1579 | ||
1580 | <p> | |
1581 | Open vSwitch supports these actions in all versions of OpenFlow, but | |
1582 | in OpenFlow 1.2 and later it translates them to an appropriate | |
1583 | standardized <code>OFPAT_SET_FIELD</code> action. | |
1584 | </p> | |
1585 | </conformance> | |
1586 | </action> | |
1587 | ||
1588 | <action name="SET_QUEUE, POP_QUEUE"> | |
1589 | <h2>The <code>set_queue</code> and <code>pop_queue</code> actions</h2> | |
1590 | <syntax><code>set_queue:</code><var>queue</var></syntax> | |
1591 | <syntax><code>pop_queue</code></syntax> | |
1592 | ||
1593 | <p> | |
1594 | The <code>set_queue</code> action sets the queue ID to be used for | |
1595 | subsequent output actions to <var>queue</var>, which must be a 32-bit | |
1596 | integer. The range of meaningful values of <var>queue</var>, and their | |
1597 | meanings, varies greatly from one OpenFlow implementation to another. | |
1598 | Even within a single implementation, there is no guarantee that all | |
1599 | OpenFlow ports have the same queues configured or that all OpenFlow | |
1600 | ports in an implementation can be configured the same way queue-wise. | |
1601 | For more information, see the documentation for the output queue field | |
1602 | in <code>ovs-fields</code>(7). | |
1603 | </p> | |
1604 | ||
1605 | <p> | |
1606 | The <code>pop_queue</code> restores the output queue to the default | |
1607 | that was set when the packet entered the switch (generally 0). | |
1608 | </p> | |
1609 | ||
1610 | <p> | |
1611 | Four billion queues ought to be enough for anyone: <url | |
1612 | href="https://mailman.stanford.edu/pipermail/openflow-spec/2009-August/000394.html"/> | |
1613 | </p> | |
1614 | ||
1615 | <conformance> | |
1616 | <p> | |
1617 | OpenFlow 1.1 introduced the <code>set_queue</code> action. Open | |
1618 | vSwitch also supports it as an extension in OpenFlow 1.0. | |
1619 | </p> | |
1620 | ||
1621 | <p> | |
1622 | The <code>pop_queue</code> action is an Open vSwitch extension. | |
1623 | </p> | |
1624 | </conformance> | |
1625 | </action> | |
1626 | </group> | |
1627 | ||
1628 | <group title="Firewalling Actions"> | |
1629 | <p> | |
1630 | Open vSwitch is often used to implement a firewall. The preferred way to | |
1631 | implement a firewall is ``connection tracking,'' that is, to keep track | |
1632 | of the connection state of individual TCP sessions. The <code>ct</code> | |
1633 | action described in this section, added in Open vSwitch 2.5, implements | |
1634 | connection tracking. For new deployments, it is the recommended way to | |
1635 | implement firewalling with Open vSwitch. | |
1636 | </p> | |
1637 | ||
1638 | <p> | |
1639 | Before <code>ct</code> was added, Open vSwitch did not have built-in | |
1640 | support for connection tracking. Instead, Open vSwitch supported the | |
1641 | <code>learn</code> action, which allows a received packet to add a flow | |
1642 | to an OpenFlow flow table. This could be used to implement a primitive | |
1643 | form of connection tracking: packets passing through the firewall in one | |
1644 | direction could create flows that allowed response packets back through | |
1645 | the firewall in the other direction. The additional | |
1646 | <code>fin_timeout</code> action allowed the learned flows to expire | |
1647 | quickly after TCP session termination. | |
1648 | </p> | |
1649 | ||
1650 | <action name="CT"> | |
1651 | <h2>The <code>ct</code> action</h2> | |
1652 | <syntax><code>ct(<var>argument</var></code>]...<code>)</code></syntax> | |
1653 | <syntax><code>ct(commit</code>[<code>, <var>argument</var></code>]...<code>)</code></syntax> | |
1654 | ||
1655 | <p> | |
1656 | The action has two modes of operation, distinguished by whether | |
1657 | <code>commit</code> is present. The following arguments may be present | |
1658 | in either mode: | |
1659 | </p> | |
1660 | ||
1661 | <dl> | |
1662 | <dt><code>zone=<var>value</var></code></dt> | |
1663 | <dd> | |
1664 | A zone is a 16-bit id that isolates connections into separate | |
1665 | domains, allowing overlapping network addresses in different zones. | |
1666 | If a zone is not provided, then the default is 0. The | |
1667 | <var>value</var> may be specified either as a 16-bit integer literal | |
1668 | or a field or subfield in the syntax described under ``Field | |
1669 | Specifications'' above. | |
1670 | </dd> | |
1671 | </dl> | |
1672 | ||
1673 | <p> | |
1674 | Without <code>commit</code>, this action sends the packet through the | |
1675 | connection tracker. The connection tracker keeps track of the state of | |
1676 | TCP connections for packets passed through it. For each packet through | |
1677 | a connection, it checks that it satisfies TCP invariants and signals | |
1678 | the connection state to later actions using the <code>ct_state</code> | |
1679 | metadata field, which is documented in <code>ovs-fields</code>(7). | |
1680 | </p> | |
1681 | ||
1682 | <p> | |
1683 | In this form, <code>ct</code> forks the OpenFlow pipeline: | |
1684 | </p> | |
1685 | ||
1686 | <ul> | |
1687 | <li> | |
1688 | In one fork, <code>ct</code> passes the packet to the connection | |
1689 | tracker. Afterward, it reinjects the packet into the OpenFlow | |
1690 | pipeline with the connection tracking fields initialized. The | |
1691 | <code>ct_state</code> field is initialized with connection state and | |
1692 | <code>ct_zone</code> to the connection tracking zone specified on the | |
1693 | <code>zone</code> argument. If the connection is one that is already | |
1694 | tracked, <code>ct_mark</code> and <code>ct_label</code> to its | |
1695 | existing mark and label, respectively; otherwise they are zeroed. In | |
1696 | addition, <code>ct_nw_proto</code>, <code>ct_nw_src</code>, | |
1697 | <code>ct_nw_dst</code>, <code>ct_ipv6_src</code>, | |
1698 | <code>ct_ipv6_dst</code>, <code>ct_tp_src</code>, and | |
1699 | <code>ct_tp_dst</code> are initialized appropriately for the original | |
1700 | direction connection. See the <code>resubmit</code> action for a way | |
1701 | to search the flow table with the connection tracking original | |
1702 | direction fields swapped with the packet 5-tuple fields. See | |
1703 | <code>ovs-fields</code>(7) for details on the connection tracking | |
1704 | fields. | |
1705 | </li> | |
1706 | ||
1707 | <li> | |
1708 | In the other fork, the original instance of the packet continues | |
1709 | independent processing following the <code>ct</code> action. The | |
1710 | <code>ct_state</code> field and other connection tracking metadata | |
1711 | are cleared. | |
1712 | </li> | |
1713 | </ul> | |
1714 | ||
1715 | <p> | |
1716 | Without <code>commit</code>, the <code>ct</code> action accepts the | |
1717 | following arguments: | |
1718 | </p> | |
1719 | ||
1720 | <dl> | |
1721 | <dt><code>table=<var>table</var></code></dt> | |
1722 | <dd> | |
1723 | Sets the OpenFlow table where the packet is reinjected. The | |
1724 | <var>table</var> must be a number between 0 and 254 inclusive, or a | |
1725 | table's name. If <var>table</var> is not specified, then the packet | |
1726 | is not reinjected. | |
1727 | </dd> | |
1728 | ||
1729 | <dt><code>nat</code></dt> | |
1730 | <dt><code>nat(<var>type</var>=<var>addrs</var></code>[<code>:<var>ports</var></code>][<code>,<var>flag</var></code>]...<code>)</code></dt> | |
1731 | <dd> | |
1732 | <p> | |
1733 | Specify address and port translation for the connection being | |
1734 | tracked. The <var>type</var> must be <code>src</code>, for source | |
1735 | address/port translation (SNAT), or <code>dst</code>, for destination | |
1736 | address/port translation (DNAT). Setting up address translation for | |
1737 | a new connection takes effect only if the connection is later | |
1738 | committed with <code>ct(commit</code>...<code>)</code>. | |
1739 | </p> | |
1740 | ||
1741 | <p> | |
1742 | The <code>src</code> and <code>dst</code> options take the following | |
1743 | arguments: | |
1744 | </p> | |
1745 | ||
1746 | <dl> | |
1747 | <dt><var>addrs</var></dt> | |
1748 | <dd> | |
1749 | The IP address <var>addr</var> or range | |
1750 | <code><var>addr1</var>-<var>addr2</var></code> from which the | |
1751 | translated address should be selected. If only one address is | |
1752 | given, then that address will always be selected, otherwise the | |
1753 | address selection can be informed by the optional persistent flag | |
1754 | as described below. Either IPv4 or IPv6 addresses can be provided, | |
1755 | but both addresses must be of the same type, and the datapath | |
1756 | behavior is undefined in case of providing IPv4 address range for | |
1757 | an IPv6 packet, or IPv6 address range for an IPv4 packet. IPv6 | |
1758 | addresses must be bracketed with <code>[</code> and <code>]</code> | |
1759 | if a port range is also given. | |
1760 | </dd> | |
1761 | ||
1762 | <dt><var>ports</var></dt> | |
1763 | <dd> | |
1764 | The L4 <var>port</var> or range | |
1765 | <code><var>port1</var>-<var>port2</var></code> from which the | |
32b2c81f DB |
1766 | translated port should be selected. When a port range is |
1767 | specified, fallback to ephemeral ports does not happen, else, | |
1768 | it will. The port number selection can be informed by the | |
1769 | optional <code>random</code> and <code>hash</code> flags | |
1770 | described below. The userspace datapath only supports the | |
1771 | <code>hash</code> behavior. | |
be51cd41 BP |
1772 | </dd> |
1773 | </dl> | |
1774 | ||
1775 | <p> | |
1776 | The optional flags are: | |
1777 | </p> | |
1778 | ||
1779 | <dl> | |
1780 | <dt><code>random</code></dt> | |
1781 | <dd> | |
1782 | The selection of the port from the given range should be done using | |
1783 | a fresh random number. This flag is mutually exclusive with | |
1784 | <code>hash</code>. | |
1785 | </dd> | |
1786 | ||
1787 | <dt><code>hash</code></dt> | |
1788 | <dd> | |
1789 | The selection of the port from the given range should be done using | |
1790 | a datapath specific hash of the packet's IP addresses and the | |
1791 | other, non-mapped port number. This flag is mutually exclusive | |
1792 | with <code>random</code>. | |
1793 | </dd> | |
1794 | ||
1795 | <dt><code>persistent</code></dt> | |
1796 | <dd> | |
1797 | The selection of the IP address from the given range should be done | |
1798 | so that the same mapping can be provided after the system restarts. | |
1799 | </dd> | |
1800 | </dl> | |
1801 | ||
1802 | <p> | |
1803 | If <code>alg</code> is specified for the committing <code>ct</code> | |
1804 | action that also includes <code>nat</code> with a <code>src</code> or | |
1805 | <code>dst</code> attribute, then the datapath tries to set up the | |
1806 | helper to be NAT-aware. This functionality is datapath specific and | |
1807 | may not be supported by all datapaths. | |
1808 | </p> | |
1809 | ||
1810 | <p> | |
1811 | A ``bare'' <code>nat</code> argument with no options will only | |
1812 | translate the packet being processed in the way the connection has been | |
1813 | set up with an earlier, committed <code>ct</code> action. A | |
1814 | <code>nat</code> action with <code>src</code> or <code>dst</code>, when | |
1815 | applied to a packet belonging to an established (rather than new) | |
1816 | connection, will behave the same as a bare <code>nat</code>. | |
1817 | </p> | |
1818 | ||
1819 | <p> | |
1820 | Open vSwitch 2.6 introduced <code>nat</code>. Linux 4.6 was the | |
1821 | earliest upstream kernel that implemented <code>ct</code> support for | |
1822 | <code>nat</code>. | |
1823 | </p> | |
1824 | </dd> | |
1825 | </dl> | |
1826 | ||
1827 | <p> | |
1828 | With <code>commit</code>, the connection tracker commits the connection | |
1829 | to the connection tracking module. The <code>commit</code> flag should | |
1830 | only be used from the pipeline within the first fork of <code>ct</code> | |
1831 | without <code>commit</code>. Information about the connection is | |
1832 | stored beyond the lifetime of the packet in the pipeline. Some | |
1833 | <code>ct_state</code> flags are only available for committed | |
1834 | connections. | |
1835 | </p> | |
1836 | ||
1837 | <p> | |
1838 | The following options are available only with <code>commit</code>: | |
1839 | </p> | |
1840 | ||
1841 | <dl> | |
1842 | <dt><code>force</code></dt> | |
1843 | <dd> | |
1844 | A committed connection always has the directionality of the packet | |
1845 | that caused the connection to be committed in the first place. This | |
1846 | is the ``original direction'' of the connection, and the opposite | |
1847 | direction is the ``reply direction''. If a connection is already | |
1848 | committed, but it is in the wrong direction, <code>force</code> | |
1849 | effectively terminates the existing connection and starts a new one | |
1850 | in the current direction. This flag has no effect if the original | |
1851 | direction of the connection is already the same as that of the | |
1852 | current packet. | |
1853 | </dd> | |
1854 | ||
1855 | <dt><code>exec(<var>action</var></code>...<code>)</code></dt> | |
1856 | <dd> | |
1857 | <p> | |
1858 | Perform each <var>action</var> within the context of connection | |
1859 | tracking. Only actions which modify the <code>ct_mark</code> or | |
1860 | <code>ct_label</code> fields are accepted within <code>exec</code> | |
1861 | action, and these fields may only be modified with this option. For | |
1862 | example: | |
1863 | </p> | |
1864 | ||
1865 | <dl> | |
1866 | <dt><code>set_field:<var>value</var>[/<var>mask</var>]->ct_mark</code></dt> | |
1867 | <dd> | |
1868 | Store a 32-bit metadata value with the connection. Subsequent | |
1869 | lookups for packets in this connection will populate | |
1870 | <code>ct_mark</code> when the packet is sent to the connection | |
1871 | tracker with the table specified. | |
1872 | </dd> | |
1873 | ||
1874 | <dt><code>set_field:<var>value</var>[/<var>mask</var>]->ct_label</code></dt> | |
1875 | <dd> | |
1876 | Store a 128-bit metadata value with the connection. Subsequent | |
1877 | lookups for packets in this connection will populate | |
1878 | <code>ct_label</code> when the packet is sent to the connection | |
1879 | tracker with the table specified. | |
1880 | </dd> | |
1881 | </dl> | |
1882 | </dd> | |
1883 | ||
1884 | <dt><code>alg=<var>alg</var></code></dt> | |
1885 | <dd> | |
1886 | <p> | |
1887 | Specify application layer gateway <var>alg</var> to track specific | |
1888 | connection types. If subsequent related connections are sent | |
1889 | through the <code>ct</code> action, then the <code>rel</code> flag | |
1890 | in the <code>ct_state</code> field will be set. Supported types | |
1891 | include: | |
1892 | </p> | |
1893 | ||
1894 | <dl> | |
1895 | <dt><code>ftp</code></dt> | |
1896 | <dd> | |
1897 | Look for negotiation of FTP data connections. Specify this | |
1898 | option for FTP control connections to detect related data | |
1899 | connections and populate the <code>rel</code> flag for the data | |
1900 | connections. | |
1901 | </dd> | |
1902 | ||
1903 | <dt><code>tftp</code></dt> | |
1904 | <dd> | |
1905 | <p> | |
1906 | Look for negotiation of TFTP data connections. Specify this | |
1907 | option for TFTP control connections to detect related data | |
1908 | connections and populate the <code>rel</code> flag for the data | |
1909 | connections. | |
1910 | </p> | |
1911 | </dd> | |
1912 | </dl> | |
1913 | ||
1914 | <p> | |
1915 | Related connections inherit <code>ct_mark</code> from that stored | |
1916 | with the original connection (i.e. the connection created by | |
1917 | <code>ct(alg=</code>...<code>)</code>). | |
1918 | </p> | |
1919 | </dd> | |
1920 | </dl> | |
1921 | ||
1922 | <p> | |
1923 | With the Linux datapath, global sysctl options affect <code>ct</code> | |
1924 | behavior. In particular, if | |
1925 | <code>net.netfilter.nf_conntrack_helper</code> is enabled, which it is | |
1926 | by default until Linux 4.7, then application layer gateway helpers may | |
1927 | be executed even if <code>alg</code> is not specified. For security | |
1928 | reasons, the netfilter team recommends users disable this option. For | |
1929 | further details, please see <url | |
1930 | href="http://www.netfilter.org/news.html#2012-04-03"/>. | |
1931 | </p> | |
1932 | ||
1933 | <p> | |
1934 | The <code>ct</code> action may be used as a primitive to construct | |
1935 | stateful firewalls by selectively committing some traffic, then | |
1936 | matching <code>ct_state</code> to allow established connections while | |
1937 | denying new connections. The following flows provide an example of how | |
1938 | to implement a simple firewall that allows new connections from port 1 | |
1939 | to port 2, and only allows established connections to send traffic from | |
1940 | port 2 to port 1: | |
1941 | </p> | |
1942 | ||
1943 | <pre> | |
1944 | table=0,priority=1,action=drop | |
1945 | table=0,priority=10,arp,action=normal | |
1946 | table=0,priority=100,ip,ct_state=-trk,action=ct(table=1) | |
1947 | table=1,in_port=1,ip,ct_state=+trk+new,action=ct(commit),2 | |
1948 | table=1,in_port=1,ip,ct_state=+trk+est,action=2 | |
1949 | table=1,in_port=2,ip,ct_state=+trk+new,action=drop | |
1950 | table=1,in_port=2,ip,ct_state=+trk+est,action=1 | |
1951 | </pre> | |
1952 | ||
1953 | <p> | |
1954 | If <code>ct</code> is executed on IPv4 (or IPv6) fragments, then the | |
1955 | message is implicitly reassembled before sending to the connection | |
1956 | tracker and refragmented upon output, to the original maximum received | |
1957 | fragment size. Reassembly occurs within the context of the zone, | |
1958 | meaning that IP fragments in different zones are not assembled | |
1959 | together. Pipeline processing for the initial fragments is halted. | |
1960 | When the final fragment is received, the message is assembled and | |
1961 | pipeline processing continues for that flow. Packet ordering is not | |
1962 | guaranteed by IP protocols, so it is not possible to determine which IP | |
1963 | fragment will cause message reassembly (and therefore continue pipeline | |
1964 | processing). As such, it is strongly recommended that multiple flows | |
1965 | should not execute <code>ct</code> to reassemble fragments from the | |
1966 | same IP message. | |
1967 | </p> | |
1968 | ||
1969 | <conformance> | |
1970 | The <code>ct</code> action was introduced in Open vSwitch 2.5. Some of | |
1971 | its features were introduced later, noted individually above. | |
1972 | </conformance> | |
1973 | </action> | |
1974 | ||
1975 | <action name="CT_CLEAR"> | |
1976 | <h2>The <code>ct_clear</code> action</h2> | |
1977 | <syntax><code>ct_clear</code></syntax> | |
1978 | ||
1979 | <p> | |
1980 | Clears connection tracking state from the flow, zeroing | |
1981 | <code>ct_state</code>, <code>ct_zone</code>, <code>ct_mark</code>, and | |
1982 | <code>ct_label</code>. | |
1983 | </p> | |
1984 | ||
1985 | <p> | |
1986 | This action was introduced in Open vSwitch 2.6.90. | |
1987 | </p> | |
1988 | </action> | |
1989 | ||
1990 | <action name="LEARN"> | |
1991 | <h2>The <code>learn</code> action</h2> | |
1992 | <syntax><code>learn(<var>argument</var></code>...<code>)</code></syntax> | |
1993 | ||
1994 | <p> | |
1995 | The <code>learn</code> action adds or modifies a flow in an OpenFlow | |
1996 | table, similar to <code>ovs-ofctl --strict mod-flows</code>. The | |
1997 | arguments specify the match fields, actions, and other properties of | |
1998 | the flow to be added or modified. | |
1999 | </p> | |
2000 | ||
2001 | <p> | |
2002 | Match fields for the new flow are specified as follows. At least one | |
2003 | match field should ordinarily be specified: | |
2004 | </p> | |
2005 | ||
2006 | <dl> | |
2007 | <dt><code><var>field</var>=<var>value</var></code></dt> | |
2008 | <dd> | |
2009 | <p> | |
2010 | Specifies that <var>field</var>, in the new flow, must match the | |
2011 | literal <var>value</var>, e.g. <code>dl_type=0x800</code>. | |
2012 | Shorthand match syntax, such as <code>ip</code> in place of | |
2013 | <code>dl_type=0x800</code>, is not supported. | |
2014 | </p> | |
2015 | </dd> | |
2016 | ||
2017 | <dt><code><var>field</var>=<var>src</var></code></dt> | |
2018 | <dd> | |
2019 | <p> | |
2020 | Specifies that <var>field</var> in the new flow must match | |
2021 | <var>src</var> taken from the packet currently being processed. | |
2022 | For example, <code>udp_dst=udp_src</code>, applied to a UDP packet | |
2023 | with source port 53, creates a flow which matches | |
2024 | <code>udp_dst=53</code>. <var>field</var> and <var>src</var> must | |
2025 | have the same width. | |
2026 | </p> | |
2027 | </dd> | |
2028 | ||
2029 | <dt><code><var>field</var></code></dt> | |
2030 | <dd> | |
2031 | Shorthand for the previous form when <var>field</var> and | |
2032 | <var>src</var> are the same. For example, <code>udp_dst</code>, | |
2033 | applied to a UDP packet with destination port 53, creates a flow | |
2034 | which matches <code>udp_dst=53</code>. | |
2035 | </dd> | |
2036 | </dl> | |
2037 | ||
2038 | <p> | |
2039 | The <var>field</var> and <var>src</var> arguments above should be | |
2040 | fields or subfields in the syntax described under ``Field | |
2041 | Specifications'' above. | |
2042 | </p> | |
2043 | ||
2044 | <p> | |
2045 | Match field specifications must honor prerequisites for both the flow | |
2046 | with the <code>learn</code> and the new flow that it creates. Consider | |
2047 | the following complete flow, in the syntax accepted by | |
2048 | <code>ovs-ofctl</code>. If the flow's match on <code>udp</code> were | |
2049 | omitted, then the flow would not satisfy the prerequisites for the | |
2050 | <code>learn</code> action's use of <code>udp_src</code>. If | |
2051 | <code>dl_type=0x800</code> or <code>nw_proto</code> were omitted from | |
2052 | <code>learn</code>, then the new flow would not satisfy the | |
2053 | prerequisite for its match on <code>udp_dst</code>. For more | |
2054 | information on prerequisites, please refer to | |
2055 | <code>ovs-fields</code>(7): | |
2056 | </p> | |
2057 | ||
2058 | <pre> | |
2059 | udp, actions=learn(dl_type=0x800, nw_proto=17, udp_dst=udp_src) | |
2060 | </pre> | |
2061 | ||
2062 | <p> | |
2063 | Actions for the new flow are specified as follows. At least one action | |
2064 | should ordinarily be specified: | |
2065 | </p> | |
2066 | ||
2067 | <dl> | |
2068 | <dt><code>load:<var>value</var>-><var>dst</var></code></dt> | |
2069 | <dd> | |
2070 | Adds a <code>load</code> action to the new flow that loads the | |
2071 | literal <var>value</var> into <var>dst</var>. The syntax is the same | |
2072 | as the <code>load</code> action explained in the ``Header | |
2073 | Modification'' section. | |
2074 | </dd> | |
2075 | ||
2076 | <dt><code>load:<var>src</var>-><var>dst</var></code></dt> | |
2077 | <dd> | |
2078 | Adds a <code>load</code> action to the new flow that loads | |
2079 | <var>src</var>, a field or subfield from the packet being processed, | |
2080 | into <var>dst</var>. | |
2081 | </dd> | |
2082 | ||
2083 | <dt><code>output:<var>field</var></code></dt> | |
2084 | <dd> | |
2085 | Adds an <code>output</code> action to the new flow's actions that | |
2086 | outputs to the OpenFlow port taken from <var>field</var>, which must | |
2087 | be a field as described above. | |
2088 | </dd> | |
2089 | ||
2090 | <dt><code>fin_idle_timeout=<var>seconds</var></code></dt> | |
2091 | <dt><code>fin_hard_timeout=<var>seconds</var></code></dt> | |
2092 | <dd> | |
2093 | Adds a <code>fin_timeout</code> action with the specified arguments | |
2094 | to the new flow. This feature was added in Open vSwitch 1.5.90. | |
2095 | </dd> | |
2096 | </dl> | |
2097 | ||
2098 | The following additional arguments are optional: | |
2099 | ||
2100 | <dl> | |
2101 | <dt><code>idle_timeout=<var>seconds</var></code></dt> | |
2102 | <dt><code>hard_timeout=<var>seconds</var></code></dt> | |
2103 | <dt><code>priority=<var>value</var></code></dt> | |
2104 | <dt><code>cookie=<var>value</var></code></dt> | |
2105 | <dt><code>send_flow_rem</code></dt> | |
2106 | <dd> | |
2107 | These arguments have the same meaning as in the usual flow syntax | |
2108 | documented in <code>ovs-ofctl</code>(8). | |
2109 | </dd> | |
2110 | ||
2111 | <dt><code>table=<var>table</var></code></dt> | |
2112 | <dd> | |
2113 | The table in which the new flow should be inserted. Specify a | |
2114 | decimal number between 0 and 254 inclusive or the name of a table. | |
2115 | The default, if table is unspecified, is table 1 (not 0). | |
2116 | </dd> | |
2117 | ||
2118 | <dt><code>delete_learned</code></dt> | |
2119 | <dd> | |
2120 | <p> | |
2121 | When this flag is specified, deleting the flow that contains the | |
2122 | <code>learn</code> action will also delete the flows created by | |
2123 | <code>learn</code>. Specifically, when the last <code>learn</code> | |
2124 | action with this flag and particular <code>table</code> and | |
2125 | <code>cookie</code> values is removed, the switch deletes all of | |
2126 | the flows in the specified table with the specified cookie. | |
2127 | </p> | |
2128 | ||
2129 | <p> | |
2130 | This flag was added in Open vSwitch 2.4. | |
2131 | </p> | |
2132 | </dd> | |
2133 | ||
2134 | <dt><code>limit=<var>number</var></code></dt> | |
2135 | <dd> | |
2136 | <p> | |
2137 | If the number of flows in the new flow's table with the same cookie | |
2138 | exceeds <code>number</code>, the action will not add a new flow. | |
2139 | By default, or with <code>limit=0</code>, there is no limit. | |
2140 | </p> | |
2141 | ||
2142 | <p> | |
2143 | This flag was added in Open vSwitch 2.8. | |
2144 | </p> | |
2145 | </dd> | |
2146 | ||
2147 | <dt><code>result_dst=<var>field</var>[<var>bit</var>]</code></dt> | |
2148 | <dd> | |
2149 | <p> | |
2150 | If learn fails (because the number of flows exceeds | |
2151 | <code>limit</code>), the action sets | |
2152 | <code><var>field</var>[<var>bit</var>]</code> to 0, otherwise it | |
2153 | will be set to 1. <code>field[bit]</code> must be a single bit. | |
2154 | </p> | |
2155 | ||
2156 | <p> | |
2157 | This flag was added in Open vSwitch 2.8. | |
2158 | </p> | |
2159 | </dd> | |
2160 | </dl> | |
2161 | ||
2162 | <p> | |
2163 | By itself, the <code>learn</code> action can only put two kinds of | |
2164 | actions into the flows that it creates: <code>load</code> and | |
2165 | <code>output</code> actions. If <code>learn</code> is used in | |
2166 | isolation, these are severe limits. | |
2167 | </p> | |
2168 | ||
2169 | <p> | |
2170 | However, <code>learn</code> is not meant to be used in isolation. It | |
2171 | is a primitive meant to be used together with other Open vSwitch | |
2172 | features to accomplish a task. Its existing features are enough to | |
2173 | accomplish most tasks. | |
2174 | </p> | |
2175 | ||
2176 | <p> | |
2177 | Here is an outline of a typical pipeline structure that allows for | |
2178 | versatile behavior using <code>learn</code>: | |
2179 | </p> | |
2180 | ||
2181 | <ul> | |
2182 | <li> | |
2183 | Flows in table <var>A</var> contain a <code>learn</code> action, that | |
2184 | populates flows in table <var>L</var>, that use a <code>load</code> | |
2185 | action to populate register <var>R</var> with information about what | |
2186 | was learned. | |
2187 | </li> | |
2188 | ||
2189 | <li> | |
2190 | Flows in table <var>B</var> contain two sequential resubmit actions: | |
2191 | one to table <var>L</var> and another one to table <var>B</var>+1. | |
2192 | </li> | |
2193 | ||
2194 | <li> | |
2195 | Flows in table <var>B</var>+1 match on register <var>R</var> and act | |
2196 | differently depending on what the flows in table <var>L</var> loaded | |
2197 | into it. | |
2198 | </li> | |
2199 | </ul> | |
2200 | ||
2201 | <p> | |
2202 | This approach can be used to implement many <code>learn</code>-based | |
2203 | features. For example: | |
2204 | </p> | |
2205 | ||
2206 | <ul> | |
2207 | <li> | |
2208 | Resubmit to a table selected based on learned information, e.g. see | |
2209 | <url href="https://mail.openvswitch.org/pipermail/ovs-discuss/2016-June/021694.html"/>. | |
2210 | </li> | |
2211 | ||
2212 | <li> | |
2213 | MAC learning in the middle of a pipeline, as described in the ``Open | |
2214 | vSwitch Advanced Features Tutorial'' in the OVS documentation. | |
2215 | </li> | |
2216 | ||
2217 | <li> | |
2218 | TCP state based firewalling, by learning outgoing connections based | |
2219 | on SYN packets and matching them up with incoming packets. (This is | |
2220 | usually better implemented using the <code>ct</code> action.) | |
2221 | </li> | |
2222 | ||
2223 | <li> | |
2224 | At least some of the features described in T. A. Hoff, ``Extending | |
2225 | Open vSwitch to Facilitate Creation of Stateful SDN Applications''. | |
2226 | </li> | |
2227 | </ul> | |
2228 | ||
2229 | <conformance> | |
2230 | The <code>learn</code> action is an Open vSwitch extension to OpenFlow | |
2231 | added in Open vSwitch 1.3. Some features of <code>learn</code> were | |
2232 | added in later versions, as noted individually above. | |
2233 | </conformance> | |
2234 | </action> | |
2235 | ||
2236 | <action name="FIN_TIMEOUT"> | |
2237 | <h2>The <code>fin_timeout</code> action</h2> | |
2238 | <syntax><code>fin_timeout(<var>key</var>=<var>value</var></code>...<code>)</code></syntax> | |
2239 | ||
2240 | <p> | |
2241 | This action changes the idle timeout or hard timeout, or both, of the | |
2242 | OpenFlow flow that contains it, when the flow matches a TCP packet with | |
2243 | the FIN or RST flag. When such a packet is observed, the action | |
2244 | reduces the rule's timeouts to those specified on the action. If the | |
2245 | rule's existing timeout is already shorter than the one that the action | |
2246 | specifies, then that timeout is unaffected. | |
2247 | </p> | |
2248 | ||
2249 | <p> | |
2250 | The timeouts are specified as key-value pairs: | |
2251 | </p> | |
2252 | ||
2253 | <dl> | |
2254 | <dt><code>idle_timeout=</code><var>seconds</var></dt> | |
2255 | <dd> | |
2256 | Causes the flow to expire after the given number of seconds of | |
2257 | inactivity. | |
2258 | </dd> | |
2259 | ||
2260 | <dt><code>hard_timeout=</code><var>seconds</var></dt> | |
2261 | <dd> | |
2262 | Causes the flow to expire after the given number of | |
2263 | <var>seconds</var>, regardless of activity. (<var>seconds</var> | |
2264 | specifies time since the flow's creation, not since the receipt of | |
2265 | the FIN or RST.) | |
2266 | </dd> | |
2267 | </dl> | |
2268 | ||
2269 | <p> | |
2270 | This action is normally added to a learned flow by the | |
2271 | <code>learn</code> action. It is unlikely to be useful otherwise. | |
2272 | </p> | |
2273 | ||
2274 | <conformance> | |
2275 | This Open vSwitch extension action was added in Open vSwitch 1.5.90. | |
2276 | </conformance> | |
2277 | </action> | |
2278 | </group> | |
2279 | ||
2280 | <group title="Programming and Control Flow Actions"> | |
2281 | <action name="RESUBMIT"> | |
2282 | <h2>The <code>resubmit</code> action</h2> | |
2283 | <syntax><code>resubmit:<var>port</var></code></syntax> | |
2284 | <syntax><code>resubmit(</code>[<code><var>port</var></code>]<code>,</code>[<code><var>table</var></code>][<code>,ct</code>]<code>)</code></syntax> | |
2285 | ||
2286 | <p> | |
2287 | Searches an OpenFlow flow table for a matching flow and executes the | |
2288 | actions found, if any, before continuing to the following action in the | |
2289 | current flow entry. Arguments can customize the search: | |
2290 | </p> | |
2291 | ||
2292 | <ul> | |
2293 | <li> | |
2294 | If <var>port</var> is given as an OpenFlow port number or name, then | |
2295 | it specifies a value to use for the input port metadata field as part | |
2296 | of the search, in place of the input port currently in the flow. | |
2297 | Specifying <code>in_port</code> as <var>port</var> is equivalent to | |
2298 | omitting it. | |
2299 | </li> | |
2300 | ||
2301 | <li> | |
2302 | If <var>table</var> is given as an integer between 0 and 254 or a | |
2303 | table name, it specifies the OpenFlow table to search. If it is not | |
2304 | specified, the table from the current flow is used. | |
2305 | </li> | |
2306 | ||
2307 | <li> | |
2308 | <p> | |
2309 | If <code>ct</code> is specified, then the search is done with | |
2310 | packet 5-tuple fields swapped with the corresponding conntrack | |
2311 | original direction tuple fields. See the documentation for | |
2312 | <code>ct</code> above, for more information about connection | |
2313 | tracking, or <code>ovs-fields</code>(7) for details about the | |
2314 | connection tracking fields. | |
2315 | </p> | |
2316 | ||
2317 | <p> | |
2318 | This flag requires a valid connection tracking state as a match | |
2319 | prerequisite in the flow where this action is placed. Examples of | |
2320 | valid connection tracking state matches include | |
2321 | <code>ct_state=+new</code>, <code>ct_state=+est</code>, | |
2322 | <code>ct_state=+rel</code>, and <code>ct_state=+trk-inv</code>. | |
2323 | </p> | |
2324 | </li> | |
2325 | </ul> | |
2326 | ||
2327 | <p> | |
2328 | The changes, if any, to the input port and connection tracking fields | |
2329 | are just for searching the flow table. The changes are not visible to | |
2330 | actions or to later flow table lookups. | |
2331 | </p> | |
2332 | ||
2333 | <p> | |
2334 | The most common use of <code>resubmit</code> is to visit another flow | |
2335 | table without <var>port</var> or <code>ct</code>, like this: | |
2336 | <code>resubmit(,<var>table</var>)</code>. | |
2337 | </p> | |
2338 | ||
2339 | <p> | |
2340 | Recursive <code>resubmit</code> actions are permitted. | |
2341 | </p> | |
2342 | ||
2343 | <conformance> | |
2344 | <p> | |
2345 | The <code>resubmit</code> action is an Open vSwitch extension. | |
2346 | However, the <code>goto_table</code> instruction in OpenFlow 1.1 and | |
2347 | later can be viewed as a kind of restricted <code>resubmit</code>. | |
2348 | </p> | |
2349 | ||
2350 | <p> | |
2351 | Open vSwitch 1.2.90 added <var>table</var>. Open vSwitch 2.7 added | |
2352 | <code>ct</code>. | |
2353 | </p> | |
2354 | ||
2355 | <p> | |
2356 | Open vSwitch imposes a limit on <code>resubmit</code> recursion that | |
2357 | varies among version: | |
2358 | </p> | |
2359 | ||
2360 | <ul> | |
2361 | <li> | |
2362 | Open vSwitch 1.0.1 and earlier did not support recursion. | |
2363 | </li> | |
2364 | ||
2365 | <li> | |
2366 | Open vSwitch 1.0.2 and 1.0.3 limited recursion to 8 levels. | |
2367 | </li> | |
2368 | ||
2369 | <li> | |
2370 | Open vSwitch 1.1 and 1.2 limited recursion to 16 levels. | |
2371 | </li> | |
2372 | ||
2373 | <li> | |
2374 | Open vSwitch 1.2 through 1.8 limited recursion to 32 levels. | |
2375 | </li> | |
2376 | ||
2377 | <li> | |
2378 | Open vSwitch 1.9 through 2.0 limited recursion to 64 levels. | |
2379 | </li> | |
2380 | ||
2381 | <li> | |
2382 | Open vSwitch 2.1 through 2.5 limited recursion to 64 levels and | |
2383 | impose a total limit of 4,096 resubmits per flow translation | |
2384 | (earlier versions did not impose any total limit). | |
2385 | </li> | |
2386 | ||
2387 | <li> | |
2388 | Open vSwitch 2.6 and later imposes the same limits as 2.5, with one | |
2389 | exception: resubmit from table <var>x</var> to any table | |
2390 | <var>y</var> > <var>x</var> does not count against the recursion | |
2391 | depth limit. | |
2392 | </li> | |
2393 | </ul> | |
2394 | </conformance> | |
2395 | </action> | |
2396 | ||
2397 | <action name="CLONE"> | |
2398 | <h2>The <code>clone</code> action</h2> | |
2399 | <syntax><code>clone(<var>action</var>...)</code></syntax> | |
2400 | ||
2401 | <p> | |
2402 | Executes each nested <var>action</var>, saving much of the packet and | |
2403 | pipeline state beforehand and then restoring it afterward. The state | |
2404 | that is saved and restored includes all flow data and metadata | |
2405 | (including, for example, <code>in_port</code> and | |
2406 | <code>ct_state</code>), the stack accessed by <code>push</code> and | |
2407 | <code>pop</code> actions, and the OpenFlow action set. | |
2408 | </p> | |
2409 | ||
2410 | <p> | |
2411 | This action was added in Open vSwitch 2.6.90. | |
2412 | </p> | |
2413 | </action> | |
2414 | ||
2415 | <action name="STACK_PUSH, STACK_POP"> | |
2416 | <h2>The <code>push</code> and <code>pop</code> actions</h2> | |
2417 | <syntax><code>push:<var>src</var></code></syntax> | |
2418 | <syntax><code>pop:<var>dst</var></code></syntax> | |
2419 | <p> | |
2420 | The <code>push</code> action pushes <var>src</var> on a general-purpose | |
2421 | stack. The <code>pop</code> action pops an entry off the stack into | |
2422 | <var>dst</var>. <var>src</var> and <var>dst</var> should be fields or | |
2423 | subfields in the syntax described under ``Field Specifications'' above. | |
2424 | </p> | |
2425 | ||
2426 | <p> | |
2427 | Controllers can use the stack for saving and restoring data or metadata | |
2428 | around <code>resubmit</code> actions, for swapping or rearranging data | |
2429 | and metadata, or for other purposes. Any data or metadata field, or | |
2430 | part of one, may be pushed, and any modifiable field or subfield may be | |
2431 | popped. | |
2432 | </p> | |
2433 | ||
2434 | <p> | |
2435 | The number of bits pushed in a stack entry do not have to match the | |
2436 | number of bits later popped from that entry. If more bits are popped | |
2437 | from an entry than were pushed, then the entry is conceptually | |
2438 | left-padded with 0-bits as needed. If fewer bits are popped than | |
2439 | pushed, then bits are conceptually trimmed from the left side of the | |
2440 | entry. | |
2441 | </p> | |
2442 | ||
2443 | <p> | |
2444 | The stack's size is limited. The limit is intended to be high enough | |
2445 | that ``normal'' use will not pose problems. Stack overflow or | |
2446 | underflow is an error that stops action execution (see ``Stack too | |
2447 | deep'' under ``Error Handling'', above). | |
2448 | </p> | |
2449 | ||
2450 | <p> | |
2451 | Examples: | |
2452 | </p> | |
2453 | ||
2454 | <ul> | |
2455 | <li> | |
2456 | <code>push:reg2[0..5]</code> or <code>push:NXM_NX_REG2[0..5]</code> | |
2457 | pushes on the stack the 6 bits in register 2 bits 0 through 5. | |
2458 | </li> | |
2459 | ||
2460 | <li> | |
2461 | <code>pop:reg2[0..5]</code> or <code>pop:NXM_NX_REG2[0..5]</code> | |
2462 | pops the value from top of the stack and copy bits 0 through 5 of | |
2463 | that value into bits 0 through 5 of register 2. | |
2464 | </li> | |
2465 | </ul> | |
2466 | ||
2467 | <conformance> | |
2468 | Open vSwitch 1.2 introduced <code>push</code> and <code>pop</code> as | |
2469 | OpenFlow extension actions. | |
2470 | </conformance> | |
2471 | </action> | |
2472 | ||
2473 | <action name="EXIT"> | |
2474 | <h2>The <code>exit</code> action</h2> | |
2475 | <syntax><code>exit</code></syntax> | |
2476 | ||
2477 | <p> | |
2478 | This action causes Open vSwitch to immediately halt execution of | |
2479 | further actions. Actions which have already been executed are | |
2480 | unaffected. Any further actions, including those which may be in other | |
2481 | tables, or different levels of the <code>resubmit</code> call stack, | |
2482 | are ignored. However, an <code>exit</code> action within a group | |
2483 | bucket terminates only execution of that bucket, not other buckets or | |
2484 | the overall pipeline. Actions in the action set are still executed | |
2485 | (specify <code>clear_actions</code> before <code>exit</code> to discard | |
2486 | them). | |
2487 | </p> | |
2488 | </action> | |
2489 | ||
2490 | <action name="MULTIPATH"> | |
2491 | <h2>The <code>multipath</code> action</h2> | |
2492 | <syntax><code>multipath(<var>fields</var>, <var>basis</var>, <var>algorithm</var>, <var>n_links</var>, <var>arg</var>, <var>dst</var>)</code></syntax> | |
2493 | ||
2494 | <p> | |
2495 | Hashes <var>fields</var> using <var>basis</var> as a universal hash | |
2496 | parameter, then the applies multipath link selection | |
2497 | <var>algorithm</var> (with parameter <var>arg</var>) to choose one of | |
2498 | <var>n_links</var> output links numbered 0 through <var>n_links</var> | |
2499 | minus 1, and stores the link into <var>dst</var>, which must be a field | |
2500 | or subfield in the syntax described under ``Field Specifications'' | |
2501 | above. | |
2502 | </p> | |
2503 | ||
2504 | <p> | |
2505 | The <code>bundle</code> or <code>bundle_load</code> actions are usually | |
2506 | easier to use than <code>multipath</code>. | |
2507 | </p> | |
2508 | ||
2509 | <p> | |
2510 | <var>fields</var> must be one of the following: | |
2511 | </p> | |
2512 | ||
2513 | <dl> | |
2514 | <dt><code>eth_src</code></dt> | |
2515 | <dd> | |
2516 | Hashes Ethernet source address only. | |
2517 | </dd> | |
2518 | ||
2519 | <dt><code>symmetric_l4</code></dt> | |
2520 | <dd> | |
2521 | Hashes Ethernet source, destination, and type, VLAN ID, IPv4/IPv6 | |
70506167 | 2522 | source, destination, and protocol, and TCP or SCTP (but not UDP) |
be51cd41 BP |
2523 | ports. The hash is computed so that pairs of corresponding flows in |
2524 | each direction hash to the same value, in environments where L2 paths | |
2525 | are the same in each direction. UDP ports are not included in the | |
70506167 | 2526 | hash to support protocols such as VXLAN that use asymmetric ports |
be51cd41 BP |
2527 | in each direction. |
2528 | </dd> | |
2529 | ||
2530 | <dt><code>symmetric_l3l4</code></dt> | |
2531 | <dd> | |
2532 | Hashes IPv4/IPv6 source, destination, and protocol, and TCP or SCTP | |
2533 | (but not UDP) ports. Like <code>symmetric_l4</code>, this is a | |
2534 | symmetric hash, but by excluding L2 headers it is more effective in | |
2535 | environments with asymmetric L2 paths (e.g. paths involving VRRP IP | |
2536 | addresses on a router). Not an effective hash function for protocols | |
2537 | other than IPv4 and IPv6, which hash to a constant zero. | |
2538 | </dd> | |
2539 | ||
2540 | <dt><code>symmetric_l3l4+udp</code></dt> | |
2541 | <dd> | |
2542 | Like <code>symmetric_l3l4+udp</code>, but UDP ports are included in | |
2543 | the hash. This is a more effective hash when asymmetric UDP | |
2544 | protocols such as VXLAN are not a consideration. | |
2545 | </dd> | |
2546 | ||
2547 | <dt><code>symmetric_l3</code></dt> | |
2548 | <dd> | |
2549 | Hashes network source address and network destination address. | |
2550 | </dd> | |
2551 | ||
2552 | <dt><code>nw_src</code></dt> | |
2553 | <dd> | |
2554 | Hashes network source address only. | |
2555 | </dd> | |
2556 | ||
2557 | <dt><code>nw_dst</code></dt> | |
2558 | <dd> | |
2559 | Hashes network destination address only. | |
2560 | </dd> | |
2561 | </dl> | |
2562 | ||
2563 | <p> | |
2564 | The <var>algorithm</var> used to compute the final result | |
2565 | <var>link</var> must be one of the following: | |
2566 | </p> | |
2567 | ||
2568 | <dl> | |
2569 | <dt><code>modulo_n</code></dt> | |
2570 | <dd> | |
2571 | <p> | |
2572 | Computes <var>link</var> = hash(<var>flow</var>) % <var>n_links</var>. | |
2573 | </p> | |
2574 | ||
2575 | <p> | |
2576 | This algorithm redistributes all traffic when <var>n_links</var> | |
2577 | changes. It has <i>O(1)</i> performance. | |
2578 | </p> | |
2579 | ||
2580 | <p> | |
2581 | Use 65535 for <var>max_link</var> to get a raw hash value. | |
2582 | </p> | |
2583 | ||
2584 | <p> | |
2585 | This algorithm is specified by RFC 2992. | |
2586 | </p> | |
2587 | </dd> | |
2588 | ||
2589 | <dt><code>hash_threshold</code></dt> | |
2590 | <dd> | |
2591 | <p> | |
2592 | Computes <var>link</var> = hash(<var>flow</var>) / (<code>MAX_HASH</code> / <var>n_links</var>). | |
2593 | </p> | |
2594 | ||
2595 | <p> | |
2596 | Redistributes between one-quarter and one-half of traffic when | |
2597 | n_links changes. It has <i>O(1)</i> performance. | |
2598 | </p> | |
2599 | ||
2600 | <p> | |
2601 | This algorithm is specified by RFC 2992. | |
2602 | </p> | |
2603 | </dd> | |
2604 | ||
2605 | <dt><code>hrw</code> (Highest Random Weight)</dt> | |
2606 | <dd> | |
2607 | <p> | |
2608 | Computes the following: | |
2609 | </p> | |
2610 | ||
2611 | <pre> | |
2612 | for <var>i</var> in [0,<var>n_links</var>]: | |
2613 | <var>weights</var>[<var>i</var>] = hash(<var>flow</var>, <var>i</var>) | |
2614 | <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> } | |
2615 | </pre> | |
2616 | ||
2617 | <p> | |
2618 | Redistributes 1/<var>n_links</var> of traffic when | |
2619 | <var>n_links</var> changes. It has <i>O(<var>n_links</var>)</i> | |
2620 | performance. If <var>n_links</var> is greater than a threshold | |
2621 | (currently 64, but subject to change), Open vSwitch will substitute | |
2622 | another algorithm automatically. | |
2623 | </p> | |
2624 | ||
2625 | <p> | |
2626 | This algorithm is specified by RFC 2992. | |
2627 | </p> | |
2628 | </dd> | |
2629 | ||
2630 | <dt><code>iter_hash</code> (Iterative Hash)</dt> | |
2631 | <dd> | |
2632 | <p> | |
2633 | Computes the following: | |
2634 | </p> | |
2635 | ||
2636 | <pre> | |
2637 | <var>i</var> = 0 | |
2638 | repeat: | |
2639 | <var>i</var> = <var>i</var> + 1 | |
2640 | <var>link</var> = hash(<var>flow</var>, <var>i</var>) % <var>arg</var> | |
2641 | while <var>link</var> > <var>max_link</var> | |
2642 | </pre> | |
2643 | ||
2644 | <p> | |
2645 | Redistributes 1/<var>n_links</var> of traffic when | |
2646 | <var>n_links</var> changes. O(1) performance when | |
2647 | <var>arg</var>/<var>max_link</var> is bounded by a constant. | |
2648 | </p> | |
2649 | ||
2650 | <p> | |
2651 | Redistributes all traffic when <var>arg</var> changes. | |
2652 | </p> | |
2653 | ||
2654 | <p> | |
2655 | <var>arg</var> must be greater than <var>max_link</var> and for | |
2656 | best performance should be no more than approximately | |
2657 | <var>max_link</var> * 2. If <var>arg</var> is outside the | |
2658 | acceptable range, Open vSwitch will automatically substitute the | |
2659 | least power of 2 greater than <var>max_link</var>. | |
2660 | </p> | |
2661 | ||
2662 | <p> | |
2663 | This algorithm is specific to Open vSwitch. | |
2664 | </p> | |
2665 | </dd> | |
2666 | </dl> | |
2667 | ||
2668 | <p> | |
2669 | Only the <code>iter_hash</code> algorithm uses <var>arg</var>. | |
2670 | </p> | |
2671 | ||
2672 | <p> | |
2673 | It is an error if <var>max_link</var> is greater than or equal to | |
2674 | 2**<var>n_bits</var>. | |
2675 | </p> | |
2676 | ||
2677 | <conformance> | |
2678 | This is an OpenFlow extension added in Open vSwitch 1.1. | |
2679 | </conformance> | |
2680 | </action> | |
2681 | </group> | |
2682 | ||
2683 | <group title="Other Actions"> | |
2684 | <action name="CONJUNCTION"> | |
2685 | <h2>The <code>conjunction</code> action</h2> | |
2686 | <syntax><code>conjunction(<var>id</var>, <var>k</var>/<var>n</var>)</code></syntax> | |
2687 | ||
2688 | <p> | |
2689 | This action allows for sophisticated ``conjunctive match'' flows. | |
2690 | Refer to ``Conjunctive Match Fields'' in <code>ovs-fields</code>(7) for | |
2691 | details. | |
2692 | </p> | |
2693 | ||
2694 | <p> | |
2695 | A flow that has one or more <code>conjunction</code> actions may not | |
2696 | have any other actions except for <code>note</code> actions. | |
2697 | </p> | |
2698 | ||
2699 | <conformance> | |
2700 | Open vSwitch 2.4 introduced the <code>conjunction</code> action and | |
2701 | <code>conj_id</code> field. They are Open vSwitch extensions to | |
2702 | OpenFlow. | |
2703 | </conformance> | |
2704 | </action> | |
2705 | ||
2706 | <action name="NOTE"> | |
2707 | <h2>The <code>note</code> action</h2> | |
2708 | <syntax><code>note:</code>[<var>hh</var>]...</syntax> | |
2709 | ||
2710 | <p> | |
2711 | This action does nothing at all. OpenFlow controllers may use it to | |
2712 | annotate flows with more data than can fit in a flow cookie. | |
2713 | </p> | |
2714 | ||
2715 | <p> | |
2716 | The action may include any number of bytes represented as hex digits | |
2717 | <var>hh</var>. Periods may separate pairs of hex digits, for | |
2718 | readability. The <code>note</code> action's format doesn't include an | |
2719 | exact length for its payload, so the provided bytes will be padded on | |
2720 | the right by enough bytes with value 0 to make the total number 6 more | |
2721 | than a multiple of 8. | |
2722 | </p> | |
2723 | ||
2724 | <p> | |
2725 | ||
2726 | </p> | |
2727 | ||
2728 | <conformance> | |
2729 | This action is an extension to OpenFlow introduced in Open vSwitch 1.1. | |
2730 | </conformance> | |
2731 | </action> | |
2732 | ||
2733 | <action name="SAMPLE"> | |
2734 | <h2>The <code>sample</code> action</h2> | |
2735 | <syntax><code>sample(<var>argument</var>...)</code></syntax> | |
2736 | ||
2737 | <p> | |
2738 | Samples packets and sends one sample for every sampled packet. | |
2739 | </p> | |
2740 | ||
2741 | <p> | |
2742 | The following <var>argument</var> forms are accepted: | |
2743 | </p> | |
2744 | ||
2745 | <dl> | |
2746 | <dt><code>probability=<var>packets</var></code></dt> | |
2747 | <dd> | |
2748 | The number of sampled packets out of 65535. Must be greater or equal | |
2749 | to 1. | |
2750 | </dd> | |
2751 | ||
2752 | <dt><code>collector_set_id=<var>id</var></code></dt> | |
2753 | <dd> | |
2754 | The unsigned 32-bit integer identifier of the set of sample | |
2755 | collectors to send sampled packets to. Defaults to 0. | |
2756 | </dd> | |
2757 | ||
2758 | <dt><code>obs_domain_id=<var>id</var></code></dt> | |
2759 | <dd> | |
2760 | When sending samples to IPFIX collectors, the unsigned 32-bit integer | |
2761 | Observation Domain ID sent in every IPFIX flow record. Defaults to | |
2762 | 0. | |
2763 | </dd> | |
2764 | ||
2765 | <dt><code>obs_point_id=<var>id</var></code></dt> | |
2766 | <dd> | |
2767 | When sending samples to IPFIX collectors, the unsigned 32-bit integer | |
2768 | Observation Point ID sent in every IPFIX flow record. Defaults to 0. | |
2769 | </dd> | |
2770 | ||
2771 | <dt><code>sampling_port=<var>port</var></code></dt> | |
2772 | <dd> | |
2773 | Sample packets on <var>port</var>, which should be the ingress or | |
2774 | egress port. This option, which was added in Open vSwitch 2.5.90, | |
2775 | allows the IPFIX implementation to export egress tunnel information. | |
2776 | </dd> | |
2777 | ||
2778 | <dt><code>ingress</code></dt> | |
2779 | <dt><code>egress</code></dt> | |
2780 | <dd> | |
2781 | Specifies explicitly that the packet is being sampled on ingress to | |
2782 | or egress from the switch. IPFIX reports sent by Open vSwitch before | |
2783 | version 2.5.90 did not include a direction. From 2.5.90 until | |
2784 | 2.6.90, IPFIX reports inferred a direction from | |
2785 | <var>sampling_port</var>: if it was the packet's output port, then | |
2786 | the direction was reported as egress, otherwise as ingress. Open | |
2787 | vSwitch 2.6.90 introduced these options, which allow the inferred | |
2788 | direction to be overridden. This is particularly useful when the | |
2789 | ingress (or egress) port is not a tunnel. | |
2790 | </dd> | |
2791 | </dl> | |
2792 | ||
2793 | <p> | |
2794 | Refer to <code>ovs-vswitchd.conf.db</code>(5) for more details on | |
2795 | configuring sample collector sets. | |
2796 | </p> | |
2797 | ||
2798 | <conformance> | |
2799 | This action is an OpenFlow extension added in Open vSwitch 2.4. | |
2800 | </conformance> | |
2801 | </action> | |
2802 | </group> | |
2803 | ||
2804 | <group title="Instructions"> | |
2805 | <p> | |
2806 | Every version of OpenFlow includes actions. OpenFlow 1.1 introduced the | |
2807 | higher-level, related concept of <dfn>instructions</dfn>. In OpenFlow | |
2808 | 1.1 and later, actions within a flow are always encapsulated within an | |
2809 | instruction. Each flow has at most one instruction of each kind, which | |
2810 | are executed in the following fixed order defined in the OpenFlow | |
2811 | specification: | |
2812 | </p> | |
2813 | ||
2814 | <ol> | |
2815 | <li><code>Meter</code></li> | |
2816 | <li><code>Apply-Actions</code></li> | |
2817 | <li><code>Clear-Actions</code></li> | |
2818 | <li><code>Write-Actions</code></li> | |
2819 | <li><code>Write-Metadata</code></li> | |
2820 | <li><code>Stat-Trigger</code> (not supported by Open vSwitch)</li> | |
2821 | <li><code>Goto-Table</code></li> | |
2822 | </ol> | |
2823 | ||
2824 | <p> | |
2825 | The most important instruction is <code>Apply-Actions</code>. This | |
2826 | instruction encapsulates any number of actions, which the instruction | |
2827 | executes. Open vSwitch does not explicitly represent | |
2828 | <code>Apply-Actions</code>. Instead, any action by itself is implicitly | |
2829 | part of an <code>Apply-Actions</code> instructions. | |
2830 | </p> | |
2831 | ||
2832 | <p> | |
2833 | Open vSwitch syntax requires other instructions, if present, to be in the | |
2834 | order listed above. Otherwise it will flag an error. | |
2835 | </p> | |
2836 | ||
2837 | <action name="METER"> | |
2838 | <h2>The <code>meter</code> action and instruction</h2> | |
2839 | <syntax><code>meter:<var>meter_id</var></code></syntax> | |
2840 | ||
2841 | <p> | |
2842 | Apply meter <var>meter_id</var>. If a meter band rate is exceeded, the | |
2843 | packet may be dropped, or modified, depending on the meter band type. | |
2844 | </p> | |
2845 | ||
2846 | <conformance> | |
2847 | <p> | |
2848 | OpenFlow 1.3 introduced the <code>meter</code> instruction. OpenFlow | |
2849 | 1.5 changes <code>meter</code> from an instruction to an action. | |
2850 | </p> | |
2851 | ||
4332b671 BP |
2852 | <p> |
2853 | OpenFlow 1.5 allows implementations to restrict <code>meter</code> to | |
2854 | be the first action in an action list and to exclude | |
2855 | <code>meter</code> from action sets, for better compatibility with | |
2856 | OpenFlow 1.3 and 1.4. Open vSwitch restricts the <code>meter</code> | |
2857 | action both ways. | |
2858 | </p> | |
2859 | ||
be51cd41 BP |
2860 | <p> |
2861 | Open vSwitch 2.0 introduced OpenFlow protocol support for meters, but | |
2862 | it did not include a datapath implementation. Open vSwitch 2.7 added | |
2863 | meter support to the userspace datapath. Open vSwitch 2.10 added | |
4332b671 BP |
2864 | meter support to the kernel datapath. Open vSwitch 2.12 added |
2865 | support for meter as an action in OpenFlow 1.5. | |
be51cd41 BP |
2866 | </p> |
2867 | </conformance> | |
2868 | </action> | |
2869 | ||
2870 | <action name="CLEAR_ACTIONS"> | |
2871 | <h2>The <code>clear_actions</code> instruction</h2> | |
2872 | <syntax><code>clear_actions</code></syntax> | |
2873 | ||
2874 | <p> | |
2875 | Clears the action set. See ``Action Sets'', above, for more | |
2876 | information. | |
2877 | </p> | |
2878 | ||
2879 | <conformance> | |
2880 | OpenFlow 1.1 introduced <code>clear_actions</code>. Open vSwitch 2.1 | |
2881 | added support for <code>clear_actions</code>. | |
2882 | </conformance> | |
2883 | </action> | |
2884 | ||
2885 | <action name="WRITE_ACTIONS"> | |
2886 | <h2>The <code>write_actions</code> instruction</h2> | |
2887 | <syntax><code>write_actions(<var>action</var></code>...<code>)</code></syntax> | |
2888 | ||
2889 | <p> | |
2890 | Adds each <var>action</var> to the action set. The action set is | |
2891 | carried between flow tables and then executed at the end of the | |
2892 | pipeline. Only certain actions may be written to the action set. See | |
2893 | ``Action Sets'', above, for more information. | |
2894 | </p> | |
2895 | ||
2896 | <conformance> | |
2897 | OpenFlow 1.1 introduced <code>write_actions</code>. Open vSwitch 2.1 | |
2898 | added support for <code>write_actions</code>. | |
2899 | </conformance> | |
2900 | </action> | |
2901 | ||
2902 | <action name="WRITE_METADATA"> | |
2903 | <h2>The <code>write_metadata</code> instruction</h2> | |
2904 | <syntax><code>write_metadata:<var>value</var></code>[<code>/<var>mask</var></code>]</syntax> | |
2905 | ||
2906 | <p> | |
2907 | Updates the flow's <code>metadata</code> field. If <var>mask</var> is | |
2908 | omitted, <code>metadata</code> is set exactly to <var>value</var>; if | |
2909 | <var>mask</var> is specified, then a 1-bit in <var>mask</var> indicates | |
2910 | that the corresponding bit in <code>metadata</code> will be replaced | |
2911 | with the corresponding bit from <var>value</var>. Both | |
2912 | <var>value</var> and <var>mask</var> are 64-bit values that are decimal | |
2913 | by default; use a <code>0x</code> prefix to specify them in | |
2914 | hexadecimal. | |
2915 | </p> | |
2916 | ||
2917 | <p> | |
2918 | The <code>metadata</code> field can also be matched in the flow table | |
2919 | and updated with actions such as <code>set_field</code> and | |
2920 | <code>move</code>. | |
2921 | </p> | |
2922 | ||
2923 | <conformance> | |
2924 | OpenFlow 1.1 introduced <code>write_metadata</code>. Open vSwitch 2.1 | |
2925 | added support for <code>write_metadata</code>. | |
2926 | </conformance> | |
2927 | </action> | |
2928 | ||
2929 | <action name="GOTO_TABLE"> | |
2930 | <h2>The <code>goto_table</code> instruction</h2> | |
2931 | <syntax><code>goto_table:<var>table</var></code></syntax> | |
2932 | ||
2933 | <p> | |
2934 | Jumps to <var>table</var> as the next table in the process pipeline. | |
2935 | The table may be a number between 0 and 254 or a table name. | |
2936 | </p> | |
2937 | ||
2938 | <p> | |
2939 | It is an error if <var>table</var> is less than or equal to the table | |
2940 | of the flow that contains it; that is, <code>goto_table</code> must | |
2941 | move forward in the OpenFlow pipeline. Since <code>goto_table</code> | |
2942 | must be the last instruction in a flow, it never leads to recursion. | |
2943 | The <code>resubmit</code> extension action is more flexible. | |
2944 | </p> | |
2945 | ||
2946 | <conformance> | |
2947 | OpenFlow 1.1 introduced <code>goto_table</code>. Open vSwitch 2.1 | |
2948 | added support for <code>goto_table</code>. | |
2949 | </conformance> | |
2950 | </action> | |
2951 | </group> | |
2952 | </actions> |