]> git.proxmox.com Git - mirror_ovs.git/blob - vswitchd/vswitch.xml
userspace: Add GTP-U support.
[mirror_ovs.git] / vswitchd / vswitch.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <database name="ovs-vswitchd.conf.db" title="Open vSwitch Configuration Database">
3 <p>
4 A database with this schema holds the configuration for one Open
5 vSwitch daemon. The top-level configuration for the daemon is the
6 <ref table="Open_vSwitch"/> table, which must have exactly one
7 record. Records in other tables are significant only when they
8 can be reached directly or indirectly from the <ref
9 table="Open_vSwitch"/> table. Records that are not reachable from
10 the <ref table="Open_vSwitch"/> table are automatically deleted
11 from the database, except for records in a few distinguished
12 ``root set'' tables.
13 </p>
14
15 <h2>Common Columns</h2>
16
17 <p>
18 Most tables contain two special columns, named <code>other_config</code>
19 and <code>external_ids</code>. These columns have the same form and
20 purpose each place that they appear, so we describe them here to save space
21 later.
22 </p>
23
24 <dl>
25 <dt><code>other_config</code>: map of string-string pairs</dt>
26 <dd>
27 <p>
28 Key-value pairs for configuring rarely used features. Supported keys,
29 along with the forms taken by their values, are documented individually
30 for each table.
31 </p>
32 <p>
33 A few tables do not have <code>other_config</code> columns because no
34 key-value pairs have yet been defined for them.
35 </p>
36 </dd>
37
38 <dt><code>external_ids</code>: map of string-string pairs</dt>
39 <dd>
40 Key-value pairs for use by external frameworks that integrate with Open
41 vSwitch, rather than by Open vSwitch itself. System integrators should
42 either use the Open vSwitch development mailing list to coordinate on
43 common key-value definitions, or choose key names that are likely to be
44 unique. In some cases, where key-value pairs have been defined that are
45 likely to be widely useful, they are documented individually for each
46 table.
47 </dd>
48 </dl>
49
50 <table name="Open_vSwitch" title="Open vSwitch configuration.">
51 Configuration for an Open vSwitch daemon. There must be exactly
52 one record in the <ref table="Open_vSwitch"/> table.
53
54 <group title="Configuration">
55 <column name="datapaths">
56 Map of datapath types to datapaths. The
57 <ref column="datapath_type"/> column of the <ref table="Bridge"/>
58 table is used as a key for this map. The value points to a row in
59 the <ref table="Datapath"/> table.
60 </column>
61
62 <column name="bridges">
63 Set of bridges managed by the daemon.
64 </column>
65
66 <column name="ssl">
67 SSL used globally by the daemon.
68 </column>
69
70 <column name="external_ids" key="system-id">
71 A unique identifier for the Open vSwitch's physical host.
72 The form of the identifier depends on the type of the host.
73 On a Citrix XenServer, this will likely be the same as
74 <ref column="external_ids" key="xs-system-uuid"/>.
75 </column>
76
77 <column name="external_ids" key="xs-system-uuid">
78 The Citrix XenServer universally unique identifier for the physical
79 host as displayed by <code>xe host-list</code>.
80 </column>
81
82 <column name="external_ids" key="hostname">
83 The hostname for the host running Open vSwitch. This is a fully
84 qualified domain name since version 2.6.2.
85 </column>
86
87 <column name="external_ids" key="rundir">
88 In Open vSwitch 2.8 and later, the run directory of the running Open
89 vSwitch daemon. This directory is used for runtime state such as
90 control and management sockets. The value of <ref
91 column="other_config" key="vhost-sock-dir"/> is relative to this
92 directory.
93 </column>
94
95 <column name="other_config" key="stats-update-interval"
96 type='{"type": "integer", "minInteger": 5000}'>
97 <p>
98 Interval for updating statistics to the database, in milliseconds.
99 This option will affect the update of the <code>statistics</code>
100 column in the following tables: <code>Port</code>, <code>Interface
101 </code>, <code>Mirror</code>.
102 </p>
103 <p>
104 Default value is 5000 ms.
105 </p>
106 <p>
107 Getting statistics more frequently can be achieved via OpenFlow.
108 </p>
109 </column>
110
111 <column name="other_config" key="flow-restore-wait"
112 type='{"type": "boolean"}'>
113 <p>
114 When <code>ovs-vswitchd</code> starts up, it has an empty flow table
115 and therefore it handles all arriving packets in its default fashion
116 according to its configuration, by dropping them or sending them to
117 an OpenFlow controller or switching them as a standalone switch.
118 This behavior is ordinarily desirable. However, if
119 <code>ovs-vswitchd</code> is restarting as part of a ``hot-upgrade,''
120 then this leads to a relatively long period during which packets are
121 mishandled.
122 </p>
123 <p>
124 This option allows for improvement. When <code>ovs-vswitchd</code>
125 starts with this value set as <code>true</code>, it will neither
126 flush or expire previously set datapath flows nor will it send and
127 receive any packets to or from the datapath. When this value is
128 later set to <code>false</code>, <code>ovs-vswitchd</code> will
129 start receiving packets from the datapath and re-setup the flows.
130 </p>
131 <p>
132 Additionally, <code>ovs-vswitchd</code> is prevented from connecting
133 to controllers when this value is set to <code>true</code>. This
134 prevents controllers from making changes to the flow table in the
135 middle of flow restoration, which could result in undesirable
136 intermediate states. Once this value has been set to
137 <code>false</code> and the desired flow state has been
138 restored, <code>ovs-vswitchd</code> will be able to reconnect to
139 controllers and process any new flow table modifications.
140 </p>
141 <p>
142 Thus, with this option, the procedure for a hot-upgrade of
143 <code>ovs-vswitchd</code> becomes roughly the following:
144 </p>
145 <ol>
146 <li>
147 Stop <code>ovs-vswitchd</code>.
148 </li>
149 <li>
150 Set <ref column="other_config" key="flow-restore-wait"/>
151 to <code>true</code>.
152 </li>
153 <li>
154 Start <code>ovs-vswitchd</code>.
155 </li>
156 <li>
157 Use <code>ovs-ofctl</code> (or some other program, such as an
158 OpenFlow controller) to restore the OpenFlow flow table
159 to the desired state.
160 </li>
161 <li>
162 Set <ref column="other_config" key="flow-restore-wait"/>
163 to <code>false</code> (or remove it entirely from the database).
164 </li>
165 </ol>
166 <p>
167 The <code>ovs-ctl</code>'s ``restart'' and ``force-reload-kmod''
168 functions use the above config option during hot upgrades.
169 </p>
170 </column>
171
172 <column name="other_config" key="flow-limit"
173 type='{"type": "integer", "minInteger": 0}'>
174 <p>
175 The maximum
176 number of flows allowed in the datapath flow table. Internally OVS
177 will choose a flow limit which will likely be lower than this number,
178 based on real time network conditions. Tweaking this value is
179 discouraged unless you know exactly what you're doing.
180 </p>
181 <p>
182 The default is 200000.
183 </p>
184 </column>
185
186 <column name="other_config" key="max-idle"
187 type='{"type": "integer", "minInteger": 500}'>
188 <p>
189 The maximum time (in ms) that idle flows will remain cached in the
190 datapath. Internally OVS will check the validity and activity for
191 datapath flows regularly and may expire flows quicker than this
192 number, based on real time network conditions. Tweaking this
193 value is discouraged unless you know exactly what you're doing.
194 </p>
195 <p>
196 The default is 10000.
197 </p>
198 </column>
199
200 <column name="other_config" key="max-revalidator"
201 type='{"type": "integer", "minInteger": 100}'>
202 <p>
203 The maximum time (in ms) that revalidator threads will wait before
204 executing flow revalidation. Note that this is maximum allowed value.
205 Actual timeout used by OVS is minimum of max-idle and max-revalidator
206 values. Tweaking this value is discouraged unless you know exactly
207 what you're doing.
208 </p>
209 <p>
210 The default is 500.
211 </p>
212 </column>
213
214 <column name="other_config" key="min-revalidate-pps"
215 type='{"type": "integer", "minInteger": 1}'>
216 <p>
217 Set minimum pps that flow must have in order to be revalidated when
218 revalidation duration exceeds half of max-revalidator config variable.
219 </p>
220 <p>
221 The default is 5.
222 </p>
223 </column>
224
225 <column name="other_config" key="hw-offload"
226 type='{"type": "boolean"}'>
227 <p>
228 Set this value to <code>true</code> to enable netdev flow offload.
229 </p>
230 <p>
231 The default value is <code>false</code>. Changing this value requires
232 restarting the daemon
233 </p>
234 <p>
235 Currently Open vSwitch supports hardware offloading on
236 Linux systems. On other systems, this value is ignored.
237 This functionality is considered 'experimental'. Depending
238 on which OpenFlow matches and actions are configured,
239 which kernel version is used, and what hardware is
240 available, Open vSwitch may not be able to offload
241 functionality to hardware.
242 </p>
243 <p>
244 In order to dump HW offloaded flows use
245 <code>ovs-appctl dpctl/dump-flows</code>, <code>ovs-dpctl</code>
246 doesn't support this functionality. See ovs-vswitchd(8) for details.
247 </p>
248 </column>
249
250 <column name="other_config" key="tc-policy"
251 type='{"type": "string",
252 "enum": ["set", ["none", "skip_sw", "skip_hw"]]}'>
253 <p>
254 Specified the policy used with HW offloading.
255 Options:
256 <dl>
257 <dt><code>none</code></dt>
258 <dd>Add software rule and offload rule to HW.</dd>
259 <dt><code>skip_sw</code></dt>
260 <dd>Offload rule to HW only.</dd>
261 <dt><code>skip_hw</code></dt>
262 <dd>Add software rule without offloading rule to HW.</dd>
263 </dl>
264 </p>
265 <p>
266 This is only relevant if
267 <ref column="other_config" key="hw-offload"/> is enabled.
268 </p>
269 <p>
270 The default value is <code>none</code>.
271 </p>
272 </column>
273
274 <column name="other_config" key="dpdk-init"
275 type='{"type": "string",
276 "enum": ["set", ["false", "true", "try"]]}'>
277 <p>
278 Set this value to <code>true</code> or <code>try</code> to enable
279 runtime support for DPDK ports. The vswitch must have compile-time
280 support for DPDK as well.
281 </p>
282 <p>
283 A value of <code>true</code> will cause the ovs-vswitchd process to
284 abort if DPDK cannot be initialized. A value of <code>try</code>
285 will allow the ovs-vswitchd process to continue running even if DPDK
286 cannot be initialized.
287 </p>
288 <p>
289 The default value is <code>false</code>. Changing this value requires
290 restarting the daemon
291 </p>
292 <p>
293 If this value is <code>false</code> at startup, any dpdk ports which
294 are configured in the bridge will fail due to memory errors.
295 </p>
296 </column>
297
298 <column name="other_config" key="dpdk-lcore-mask"
299 type='{"type": "integer", "minInteger": 1}'>
300 <p>
301 Specifies the CPU cores where dpdk lcore threads should be spawned.
302 The DPDK lcore threads are used for DPDK library tasks, such as
303 library internal message processing, logging, etc. Value should be in
304 the form of a hex string (so '0x123') similar to the 'taskset' mask
305 input.
306 </p>
307 <p>
308 The lowest order bit corresponds to the first CPU core. A set bit
309 means the corresponding core is available and an lcore thread will be
310 created and pinned to it. If the input does not cover all cores,
311 those uncovered cores are considered not set.
312 </p>
313 <p>
314 For performance reasons, it is best to set this to a single core on
315 the system, rather than allow lcore threads to float.
316 </p>
317 <p>
318 If not specified, the value will be determined by choosing the lowest
319 CPU core from initial cpu affinity list. Otherwise, the value will be
320 passed directly to the DPDK library.
321 </p>
322 </column>
323
324 <column name="other_config" key="pmd-cpu-mask">
325 <p>
326 Specifies CPU mask for setting the cpu affinity of PMD (Poll
327 Mode Driver) threads. Value should be in the form of hex string,
328 similar to the dpdk EAL '-c COREMASK' option input or the 'taskset'
329 mask input.
330 </p>
331 <p>
332 The lowest order bit corresponds to the first CPU core. A set bit
333 means the corresponding core is available and a pmd thread will be
334 created and pinned to it. If the input does not cover all cores,
335 those uncovered cores are considered not set.
336 </p>
337 <p>
338 If not specified, one pmd thread will be created for each numa node
339 and pinned to any available core on the numa node by default.
340 </p>
341 </column>
342
343 <column name="other_config" key="dpdk-alloc-mem"
344 type='{"type": "integer", "minInteger": 0}'>
345 <p>
346 Specifies the amount of memory to preallocate from the hugepage pool,
347 regardless of socket. It is recommended that dpdk-socket-mem is used
348 instead.
349 </p>
350 </column>
351
352 <column name="other_config" key="dpdk-socket-mem"
353 type='{"type": "string"}'>
354 <p>
355 Specifies the amount of memory to preallocate from the hugepage pool,
356 on a per-socket basis.
357 </p>
358 <p>
359 The specifier is a comma-separated string, in ascending order of CPU
360 socket. E.g. On a four socket system 1024,0,2048 would set socket 0
361 to preallocate 1024MB, socket 1 to preallocate 0MB, socket 2 to
362 preallocate 2048MB and socket 3 (no value given) to preallocate 0MB.
363 </p>
364 <p>
365 If dpdk-socket-mem and dpdk-alloc-mem are not specified, dpdk-socket-mem
366 will be used and the default value is 1024 for each numa node. If
367 dpdk-socket-mem and dpdk-alloc-mem are specified at same time,
368 dpdk-socket-mem will be used as default. Changing this value
369 requires restarting the daemon.
370 </p>
371 </column>
372
373 <column name="other_config" key="dpdk-socket-limit"
374 type='{"type": "string"}'>
375 <p>
376 Limits the maximum amount of memory that can be used from the
377 hugepage pool, on a per-socket basis.
378 </p>
379 <p>
380 The specifier is a comma-separated list of memory limits per socket.
381 <code>0</code> will disable the limit for a particular socket.
382 </p>
383 <p>
384 If not specified, OVS will configure limits equal to the amount of
385 preallocated memory specified by <ref column="other_config"
386 key="dpdk-socket-mem"/> or <code>--socket-mem</code> in
387 <ref column="other_config" key="dpdk-extra"/>. If none of the above
388 options specified or <code>--legacy-mem</code> provided in
389 <ref column="other_config" key="dpdk-extra"/>, limits will not be
390 applied.
391 Changing this value requires restarting the daemon.
392 </p>
393 </column>
394
395 <column name="other_config" key="dpdk-hugepage-dir"
396 type='{"type": "string"}'>
397 <p>
398 Specifies the path to the hugetlbfs mount point.
399 </p>
400 <p>
401 If not specified, this will be guessed by the DPDK library (default
402 is /dev/hugepages). Changing this value requires restarting the
403 daemon.
404 </p>
405 </column>
406
407 <column name="other_config" key="dpdk-extra"
408 type='{"type": "string"}'>
409 <p>
410 Specifies additional eal command line arguments for DPDK.
411 </p>
412 <p>
413 The default is empty. Changing this value requires restarting the
414 daemon
415 </p>
416 </column>
417
418 <column name="other_config" key="vhost-sock-dir"
419 type='{"type": "string"}'>
420 <p>
421 Specifies a relative path from <ref column="external_ids"
422 key="rundir"/> to the vhost-user unix domain socket files. If this
423 value is unset, the sockets are put directly in <ref
424 column="external_ids" key="rundir"/>.
425 </p>
426 <p>
427 Changing this value requires restarting the daemon.
428 </p>
429 </column>
430
431 <column name="other_config" key="vhost-iommu-support"
432 type='{"type": "boolean"}'>
433 <p>
434 vHost IOMMU is a security feature, which restricts the vhost memory
435 that a virtio device may access. vHost IOMMU support is disabled by
436 default, due to a bug in QEMU implementations of the vhost REPLY_ACK
437 protocol, (on which vHost IOMMU relies) prior to v2.9.1. Setting this
438 value to <code>true</code> enables vHost IOMMU support for vHost User
439 Client ports in OvS-DPDK, starting from DPDK v17.11.
440 </p>
441 <p>
442 Changing this value requires restarting the daemon.
443 </p>
444 </column>
445
446 <column name="other_config" key="vhost-postcopy-support"
447 type='{"type": "boolean"}'>
448 <p>
449 vHost post-copy is a feature which allows switching live migration
450 of VM attached to dpdkvhostuserclient port to post-copy mode if
451 default pre-copy migration can not be converged or takes too long to
452 converge.
453 Setting this value to <code>true</code> enables vHost post-copy
454 support for all dpdkvhostuserclient ports. Available starting from
455 DPDK v18.11 and QEMU 2.12.
456 </p>
457 <p>
458 Changing this value requires restarting the daemon.
459 </p>
460 </column>
461
462 <column name="other_config" key="per-port-memory"
463 type='{"type": "boolean"}'>
464 <p>
465 By default OVS DPDK uses a shared memory model wherein devices
466 that have the same MTU and socket values can share the same
467 mempool. Setting this value to <code>true</code> changes this
468 behaviour. Per port memory allow DPDK devices to use private
469 memory per device. This can provide greater transparency as
470 regards memory usage but potentially at the cost of greater memory
471 requirements.
472 </p>
473 <p>
474 Changing this value requires restarting the daemon if dpdk-init has
475 already been set to true.
476 </p>
477 </column>
478
479 <column name="other_config" key="tx-flush-interval"
480 type='{"type": "integer",
481 "minInteger": 0, "maxInteger": 1000000}'>
482 <p>
483 Specifies the time in microseconds that a packet can wait in output
484 batch for sending i.e. amount of time that packet can spend in an
485 intermediate output queue before sending to netdev.
486 This option can be used to configure balance between throughput
487 and latency. Lower values decreases latency while higher values
488 may be useful to achieve higher performance.
489 </p>
490 <p>
491 Defaults to 0 i.e. instant packet sending (latency optimized).
492 </p>
493 </column>
494
495 <column name="other_config" key="pmd-perf-metrics"
496 type='{"type": "boolean"}'>
497 <p>
498 Enables recording of detailed PMD performance metrics for analysis
499 and trouble-shooting. This can have a performance impact in the
500 order of 1%.
501 </p>
502 <p>
503 Defaults to false but can be changed at any time.
504 </p>
505 </column>
506
507 <column name="other_config" key="smc-enable"
508 type='{"type": "boolean"}'>
509 <p>
510 Signature match cache or SMC is a cache between EMC and megaflow
511 cache. It does not store the full key of the flow, so it is more
512 memory efficient comparing to EMC cache. SMC is especially useful
513 when flow count is larger than EMC capacity.
514 </p>
515 <p>
516 Defaults to false but can be changed at any time.
517 </p>
518 </column>
519
520 <column name="other_config" key="pmd-rxq-assign"
521 type='{"type": "string",
522 "enum": ["set", ["cycles", "roundrobin"]]}'>
523 <p>
524 Specifies how RX queues will be automatically assigned to CPU cores.
525 Options:
526 <dl>
527 <dt><code>cycles</code></dt>
528 <dd>Rxqs will be sorted by order of measured processing cycles
529 before being assigned to CPU cores.</dd>
530 <dt><code>roundrobin</code></dt>
531 <dd>Rxqs will be round-robined across CPU cores.</dd>
532 </dl>
533 </p>
534 <p>
535 The default value is <code>cycles</code>.
536 </p>
537 <p>
538 Changing this value will affect an automatic re-assignment of Rxqs to
539 CPUs. Note: Rxqs mapped to CPU cores with
540 <code>pmd-rxq-affinity</code> are unaffected.
541 </p>
542 </column>
543
544 <column name="other_config" key="n-handler-threads"
545 type='{"type": "integer", "minInteger": 1}'>
546 <p>
547 Specifies the number of threads for software datapaths to use for
548 handling new flows. The default the number of online CPU cores minus
549 the number of revalidators.
550 </p>
551 <p>
552 This configuration is per datapath. If you have more than one
553 software datapath (e.g. some <code>system</code> bridges and some
554 <code>netdev</code> bridges), then the total number of threads is
555 <code>n-handler-threads</code> times the number of software
556 datapaths.
557 </p>
558 </column>
559
560 <column name="other_config" key="n-revalidator-threads"
561 type='{"type": "integer", "minInteger": 1}'>
562 <p>
563 Specifies the number of threads for software datapaths to use for
564 revalidating flows in the datapath. Typically, there is a direct
565 correlation between the number of revalidator threads, and the number
566 of flows allowed in the datapath. The default is the number of cpu
567 cores divided by four plus one. If <code>n-handler-threads</code> is
568 set, the default changes to the number of cpu cores minus the number
569 of handler threads.
570 </p>
571 <p>
572 This configuration is per datapath. If you have more than one
573 software datapath (e.g. some <code>system</code> bridges and some
574 <code>netdev</code> bridges), then the total number of threads is
575 <code>n-handler-threads</code> times the number of software
576 datapaths.
577 </p>
578 </column>
579
580 <column name="other_config" key="emc-insert-inv-prob"
581 type='{"type": "integer", "minInteger": 0, "maxInteger": 4294967295}'>
582 <p>
583 Specifies the inverse probability (1/emc-insert-inv-prob) of a flow
584 being inserted into the Exact Match Cache (EMC). On average one in
585 every <code>emc-insert-inv-prob</code> packets that generate a unique
586 flow will cause an insertion into the EMC.
587
588 A value of 1 will result in an insertion for every flow (1/1 = 100%)
589 whereas a value of zero will result in no insertions and essentially
590 disable the EMC.
591 </p>
592 <p>
593 Defaults to 100 ie. there is (1/100 =) 1% chance of EMC insertion.
594 </p>
595 </column>
596
597 <column name="other_config" key="vlan-limit"
598 type='{"type": "integer", "minInteger": 0}'>
599 <p>
600 Limits the number of VLAN headers that can be matched to the
601 specified number. Further VLAN headers will be treated as payload,
602 e.g. a packet with more 802.1q headers will match Ethernet type
603 0x8100.
604 </p>
605
606 <p>
607 Open vSwitch userspace currently supports at most 2 VLANs, and each
608 datapath has its own limit. If <code>vlan-limit</code> is nonzero,
609 it acts as a further limit.
610 </p>
611
612 <p>
613 If this value is absent, the default is currently 1. This maintains
614 backward compatibility with controllers that were designed for use
615 with Open vSwitch versions earlier than 2.8, which only supported one
616 VLAN.
617 </p>
618 </column>
619 <column name="other_config" key="bundle-idle-timeout"
620 type='{"type": "integer", "minInteger": 1}'>
621 <p>
622 The maximum time (in seconds) that idle bundles will wait
623 to be expired since it was either opened, modified or closed.
624 </p>
625 <p>
626 OpenFlow specification mandates the timeout to be at least one
627 second. The default is 10 seconds.
628 </p>
629 </column>
630
631 <column name="other_config" key="offload-rebalance"
632 type='{"type": "boolean"}'>
633 <p>
634 Configures HW offload rebalancing, that allows to dynamically
635 offload and un-offload flows while an offload-device is out of
636 resources (OOR). This policy allows flows to be selected for
637 offloading based on the packets-per-second (pps) rate of flows.
638 </p>
639 <p>
640 Set this value to <code>true</code> to enable this option.
641 </p>
642 <p>
643 The default value is <code>false</code>. Changing this value requires
644 restarting the daemon.
645 </p>
646 <p>
647 This is only relevant if HW offloading is enabled (hw-offload).
648 When this policy is enabled, it also requires 'tc-policy' to
649 be set to 'skip_sw'.
650 </p>
651 </column>
652 <column name="other_config" key="pmd-auto-lb"
653 type='{"type": "boolean"}'>
654 <p>
655 Configures PMD Auto Load Balancing that allows automatic assignment of
656 RX queues to PMDs if any of PMDs is overloaded (i.e. processing cycles
657 > 95%).
658 </p>
659 <p>
660 It uses current scheme of cycle based assignment of RX queues that
661 are not statically pinned to PMDs.
662 </p>
663 <p>
664 The default value is <code>false</code>.
665 </p>
666 <p>
667 Set this value to <code>true</code> to enable this option. It is
668 currently disabled by default and an experimental feature.
669 </p>
670 <p>
671 This only comes in effect if cycle based assignment is enabled and
672 there are more than one non-isolated PMDs present and at least one of
673 it polls more than one queue.
674 </p>
675 </column>
676 <column name="other_config" key="pmd-auto-lb-rebal-interval"
677 type='{"type": "integer",
678 "minInteger": 0, "maxInteger": 20000}'>
679 <p>
680 The minimum time (in minutes) 2 consecutive PMD Auto Load Balancing
681 iterations.
682 </p>
683 <p>
684 The defaul value is 1 min. If configured to 0 then it would be
685 converted to default value i.e. 1 min
686 </p>
687 <p>
688 This option can be configured to avoid frequent trigger of auto load
689 balancing of PMDs. For e.g. set the value (in min) such that it occurs
690 once in few hours or a day or a week.
691 </p>
692 </column>
693 <column name="other_config" key="userspace-tso-enable"
694 type='{"type": "boolean"}'>
695 <p>
696 Set this value to <code>true</code> to enable userspace support for
697 TCP Segmentation Offloading (TSO). When it is enabled, the interfaces
698 can provide an oversized TCP segment to the datapath and the datapath
699 will offload the TCP segmentation and checksum calculation to the
700 interfaces when necessary.
701 </p>
702 <p>
703 The default value is <code>false</code>. Changing this value requires
704 restarting the daemon.
705 </p>
706 <p>
707 The feature only works if Open vSwitch is built with DPDK support.
708 </p>
709 <p>
710 The feature is considered experimental.
711 </p>
712 </column>
713 </group>
714 <group title="Status">
715 <column name="next_cfg">
716 Sequence number for client to increment. When a client modifies
717 any part of the database configuration and wishes to wait for
718 Open vSwitch to finish applying the changes, it may increment
719 this sequence number.
720 </column>
721
722 <column name="cur_cfg">
723 Sequence number that Open vSwitch sets to the current value of
724 <ref column="next_cfg"/> after it finishes applying a set of
725 configuration changes.
726 </column>
727
728 <column name="dpdk_initialized">
729 True if <ref column="other_config" key="dpdk-init"/> is set to
730 true and the DPDK library is successfully initialized.
731 </column>
732
733 <group title="Statistics">
734 <p>
735 The <code>statistics</code> column contains key-value pairs that
736 report statistics about a system running an Open vSwitch. These are
737 updated periodically (currently, every 5 seconds). Key-value pairs
738 that cannot be determined or that do not apply to a platform are
739 omitted.
740 </p>
741
742 <column name="other_config" key="enable-statistics"
743 type='{"type": "boolean"}'>
744 Statistics are disabled by default to avoid overhead in the common
745 case when statistics gathering is not useful. Set this value to
746 <code>true</code> to enable populating the <ref column="statistics"/>
747 column or to <code>false</code> to explicitly disable it.
748 </column>
749
750 <column name="statistics" key="cpu"
751 type='{"type": "integer", "minInteger": 1}'>
752 <p>
753 Number of CPU processors, threads, or cores currently online and
754 available to the operating system on which Open vSwitch is running,
755 as an integer. This may be less than the number installed, if some
756 are not online or if they are not available to the operating
757 system.
758 </p>
759 <p>
760 Open vSwitch userspace processes are not multithreaded, but the
761 Linux kernel-based datapath is.
762 </p>
763 </column>
764
765 <column name="statistics" key="load_average">
766 A comma-separated list of three floating-point numbers,
767 representing the system load average over the last 1, 5, and 15
768 minutes, respectively.
769 </column>
770
771 <column name="statistics" key="memory">
772 <p>
773 A comma-separated list of integers, each of which represents a
774 quantity of memory in kilobytes that describes the operating
775 system on which Open vSwitch is running. In respective order,
776 these values are:
777 </p>
778
779 <ol>
780 <li>Total amount of RAM allocated to the OS.</li>
781 <li>RAM allocated to the OS that is in use.</li>
782 <li>RAM that can be flushed out to disk or otherwise discarded
783 if that space is needed for another purpose. This number is
784 necessarily less than or equal to the previous value.</li>
785 <li>Total disk space allocated for swap.</li>
786 <li>Swap space currently in use.</li>
787 </ol>
788
789 <p>
790 On Linux, all five values can be determined and are included. On
791 other operating systems, only the first two values can be
792 determined, so the list will only have two values.
793 </p>
794 </column>
795
796 <column name="statistics" key="process_NAME">
797 <p>
798 One such key-value pair, with <code>NAME</code> replaced by
799 a process name, will exist for each running Open vSwitch
800 daemon process, with <var>name</var> replaced by the
801 daemon's name (e.g. <code>process_ovs-vswitchd</code>). The
802 value is a comma-separated list of integers. The integers
803 represent the following, with memory measured in kilobytes
804 and durations in milliseconds:
805 </p>
806
807 <ol>
808 <li>The process's virtual memory size.</li>
809 <li>The process's resident set size.</li>
810 <li>The amount of user and system CPU time consumed by the
811 process.</li>
812 <li>The number of times that the process has crashed and been
813 automatically restarted by the monitor.</li>
814 <li>The duration since the process was started.</li>
815 <li>The duration for which the process has been running.</li>
816 </ol>
817
818 <p>
819 The interpretation of some of these values depends on whether the
820 process was started with the <option>--monitor</option>. If it
821 was not, then the crash count will always be 0 and the two
822 durations will always be the same. If <option>--monitor</option>
823 was given, then the crash count may be positive; if it is, the
824 latter duration is the amount of time since the most recent crash
825 and restart.
826 </p>
827
828 <p>
829 There will be one key-value pair for each file in Open vSwitch's
830 ``run directory'' (usually <code>/var/run/openvswitch</code>)
831 whose name ends in <code>.pid</code>, whose contents are a
832 process ID, and which is locked by a running process. The
833 <var>name</var> is taken from the pidfile's name.
834 </p>
835
836 <p>
837 Currently Open vSwitch is only able to obtain all of the above
838 detail on Linux systems. On other systems, the same key-value
839 pairs will be present but the values will always be the empty
840 string.
841 </p>
842 </column>
843
844 <column name="statistics" key="file_systems">
845 <p>
846 A space-separated list of information on local, writable file
847 systems. Each item in the list describes one file system and
848 consists in turn of a comma-separated list of the following:
849 </p>
850
851 <ol>
852 <li>Mount point, e.g. <code>/</code> or <code>/var/log</code>.
853 Any spaces or commas in the mount point are replaced by
854 underscores.</li>
855 <li>Total size, in kilobytes, as an integer.</li>
856 <li>Amount of storage in use, in kilobytes, as an integer.</li>
857 </ol>
858
859 <p>
860 This key-value pair is omitted if there are no local, writable
861 file systems or if Open vSwitch cannot obtain the needed
862 information.
863 </p>
864 </column>
865 </group>
866 </group>
867
868 <group title="Version Reporting">
869 <p>
870 These columns report the types and versions of the hardware and
871 software running Open vSwitch. We recommend in general that software
872 should test whether specific features are supported instead of relying
873 on version number checks. These values are primarily intended for
874 reporting to human administrators.
875 </p>
876
877 <column name="ovs_version">
878 The Open vSwitch version number, e.g. <code>1.1.0</code>.
879 </column>
880
881 <column name="db_version">
882 <p>
883 The database schema version number, e.g. <code>1.2.3</code>. See
884 ovsdb-tool(1) for an explanation of the numbering scheme.
885 </p>
886
887 <p>
888 The schema version is part of the database schema, so it can also be
889 retrieved by fetching the schema using the Open vSwitch database
890 protocol.
891 </p>
892 </column>
893
894 <column name="system_type">
895 <p>
896 An identifier for the type of system on top of which Open vSwitch
897 runs, e.g. <code>XenServer</code> or <code>KVM</code>.
898 </p>
899 <p>
900 System integrators are responsible for choosing and setting an
901 appropriate value for this column.
902 </p>
903 </column>
904
905 <column name="system_version">
906 <p>
907 The version of the system identified by <ref column="system_type"/>,
908 e.g. <code>5.6.100-39265p</code> on XenServer 5.6.100 build 39265.
909 </p>
910 <p>
911 System integrators are responsible for choosing and setting an
912 appropriate value for this column.
913 </p>
914 </column>
915
916 <column name="dpdk_version">
917 <p>
918 The version of the linked DPDK library.
919 </p>
920 </column>
921
922 </group>
923
924 <group title="Capabilities">
925 <p>
926 These columns report capabilities of the Open vSwitch instance.
927 </p>
928 <column name="datapath_types">
929 <p>
930 This column reports the different dpifs registered with the system.
931 These are the values that this instance supports in the <ref
932 column="datapath_type" table="Bridge"/> column of the <ref
933 table="Bridge"/> table.
934 </p>
935 </column>
936 <column name="iface_types">
937 <p>
938 This column reports the different netdevs registered with the system.
939 These are the values that this instance supports in the <ref
940 column="type" table="Interface"/> column of the <ref
941 table="Interface"/> table.
942 </p>
943 </column>
944 </group>
945
946 <group title="Database Configuration">
947 <p>
948 These columns primarily configure the Open vSwitch database
949 (<code>ovsdb-server</code>), not the Open vSwitch switch
950 (<code>ovs-vswitchd</code>). The OVSDB database also uses the <ref
951 column="ssl"/> settings.
952 </p>
953
954 <p>
955 The Open vSwitch switch does read the database configuration to
956 determine remote IP addresses to which in-band control should apply.
957 </p>
958
959 <column name="manager_options">
960 <p>
961 Database clients to which the Open vSwitch database server should
962 connect or to which it should listen, along with options for how
963 these connections should be configured. See the <ref
964 table="Manager"/> table for more information.
965 </p>
966
967 <p>
968 For this column to serve its purpose, <code>ovsdb-server</code> must
969 be configured to honor it. The easiest way to do this is to invoke
970 <code>ovsdb-server</code> with the option
971 <option>--remote=db:Open_vSwitch,Open_vSwitch,manager_options</option>
972 The startup scripts that accompany Open vSwitch do this by default.
973 </p>
974 </column>
975 </group>
976
977 <group title="IPsec">
978 <p>
979 These settings control the global configuration of IPsec tunnels. The
980 <code>options</code> column of the <code>Interface</code> table
981 configures IPsec for individual tunnels.
982 </p>
983 <p>
984 OVS IPsec supports the following three forms of authentication.
985 Currently, all IPsec tunnels must use the same form:
986 </p>
987 <ol>
988 <li>
989 Pre-shared keys: Omit the global settings. On each tunnel, set <ref
990 column="options" key="psk"/>.
991 </li>
992 <li>
993 Self-signed certificates: Set the <code>private_key</code> and
994 <code>certificate</code> global settings. On each tunnel, set <ref
995 column="options" key="remote_cert"/>. The remote certificate can be
996 self-signed.
997 </li>
998 <li>
999 CA-signed certificates: Set all of the global settings. On each
1000 tunnel, set <ref column="options" key="remote_name"/> to the common
1001 name (CN) of the remote certificate. The remote certificate must be
1002 signed by the CA.
1003 </li>
1004 </ol>
1005 <column name="other_config" key="private_key"
1006 type='{"type": "string"}'>
1007 <p>
1008 Name of a PEM file containing the private key used as the switch's
1009 identity for IPsec tunnels.
1010 </p>
1011 </column>
1012 <column name="other_config" key="certificate"
1013 type='{"type": "string"}'>
1014 <p>
1015 Name of a PEM file containing a certificate that certifies the
1016 switch's private key, and identifies a trustworthy switch for IPsec
1017 tunnels. The certificate must be x.509 version 3 and with the
1018 string in common name (CN) also set in the subject alternative name
1019 (SAN).
1020 </p>
1021 </column>
1022 <column name="other_config" key="ca_cert"
1023 type='{"type": "string"}'>
1024 <p>
1025 Name of a PEM file containing the CA certificate used to verify
1026 that a remote switch of the IPsec tunnel is trustworthy.
1027 </p>
1028 </column>
1029
1030 <group title="Plaintext Tunnel Policy">
1031 <p>
1032 When an IPsec tunnel is configured in this database, multiple
1033 independent components take responsibility for implementing it.
1034 <code>ovs-vswitchd</code> and its datapath handle packet forwarding
1035 to the tunnel and a separate daemon pushes the tunnel's IPsec policy
1036 configuration to the kernel or other entity that implements it.
1037 There is a race: if the former configuration completes before the
1038 latter, then packets sent by the local host over the tunnel can be
1039 transmitted in plaintext. Using this setting, OVS users can avoid
1040 this undesirable situation.
1041 </p>
1042 <column name="other_config" key="ipsec_skb_mark"
1043 type='{"type": "string"}'>
1044 <p>
1045 This setting takes the form
1046 <code><var>value</var>/<var>mask</var></code>. If it is specified,
1047 then the <code>skb_mark</code> field in every outgoing tunneled
1048 packet sent in plaintext is compared against it and, if it matches,
1049 the packet is dropped. This is a global setting that is applied to
1050 every tunneled packet, regardless of whether IPsec encryption is
1051 enabled for the tunnel, the type of tunnel, or whether OVS is
1052 involved.
1053 </p>
1054
1055 <p>
1056 Example policies:
1057 </p>
1058
1059 <dl>
1060 <dt><code>1/1</code></dt>
1061 <dd>
1062 Drop all unencrypted tunneled packets in which the
1063 least-significant bit of <code>skb_mark</code> is 1. This would
1064 be a useful policy given an OpenFlow flow table that sets
1065 <code>skb_mark</code> to 1 for traffic that should be encrypted.
1066 The default <code>skb_mark</code> is 0, so this would not affect
1067 other traffic.
1068 </dd>
1069
1070 <dt><code>0/1</code></dt>
1071 <dd>
1072 Drop all unencrypted tunneled packets in which the
1073 least-significant bit of <code>skb_mark</code> is 0. This would
1074 be a useful policy if no unencrypted tunneled traffic should exit
1075 the system without being specially whitelisted by setting
1076 <code>skb_mark</code> to 1.
1077 </dd>
1078
1079 <dt>(empty)</dt>
1080 <dd>
1081 If this setting is empty or unset, then all unencrypted tunneled
1082 packets are transmitted in the usual way.
1083 </dd>
1084 </dl>
1085 </column>
1086 </group>
1087 </group>
1088
1089 <group title="Common Columns">
1090 The overall purpose of these columns is described under <code>Common
1091 Columns</code> at the beginning of this document.
1092
1093 <column name="other_config"/>
1094 <column name="external_ids"/>
1095 </group>
1096 </table>
1097
1098 <table name="Bridge">
1099 <p>
1100 Configuration for a bridge within an
1101 <ref table="Open_vSwitch"/>.
1102 </p>
1103 <p>
1104 A <ref table="Bridge"/> record represents an Ethernet switch with one or
1105 more ``ports,'' which are the <ref table="Port"/> records pointed to by
1106 the <ref table="Bridge"/>'s <ref column="ports"/> column.
1107 </p>
1108
1109 <group title="Core Features">
1110 <column name="name">
1111 <p>
1112 Bridge identifier. Must be unique among the names of ports,
1113 interfaces, and bridges on a host.
1114 </p>
1115
1116 <p>
1117 The name must be alphanumeric and must not contain forward or
1118 backward slashes. The name of a bridge is also the name of an <ref
1119 table="Interface"/> (and a <ref table="Port"/>) within the bridge, so
1120 the restrictions on the <ref table="Interface" column="name"/> column
1121 in the <ref table="Interface"/> table, particularly on length, also
1122 apply to bridge names. Refer to the documentation for <ref
1123 table="Interface"/> names for details.
1124 </p>
1125 </column>
1126
1127 <column name="ports">
1128 Ports included in the bridge.
1129 </column>
1130
1131 <column name="mirrors">
1132 Port mirroring configuration.
1133 </column>
1134
1135 <column name="netflow">
1136 NetFlow configuration.
1137 </column>
1138
1139 <column name="sflow">
1140 sFlow(R) configuration.
1141 </column>
1142
1143 <column name="ipfix">
1144 IPFIX configuration.
1145 </column>
1146
1147 <column name="flood_vlans">
1148 <p>
1149 VLAN IDs of VLANs on which MAC address learning should be disabled,
1150 so that packets are flooded instead of being sent to specific ports
1151 that are believed to contain packets' destination MACs. This should
1152 ordinarily be used to disable MAC learning on VLANs used for
1153 mirroring (RSPAN VLANs). It may also be useful for debugging.
1154 </p>
1155 <p>
1156 SLB bonding (see the <ref table="Port" column="bond_mode"/> column in
1157 the <ref table="Port"/> table) is incompatible with
1158 <code>flood_vlans</code>. Consider using another bonding mode or
1159 a different type of mirror instead.
1160 </p>
1161 </column>
1162
1163 <column name="auto_attach">
1164 Auto Attach configuration.
1165 </column>
1166 </group>
1167
1168 <group title="OpenFlow Configuration">
1169 <column name="controller">
1170 <p>
1171 OpenFlow controller set. If unset, then no OpenFlow controllers
1172 will be used.
1173 </p>
1174
1175 <p>
1176 If there are primary controllers, removing all of them clears the
1177 OpenFlow flow tables, group table, and meter table. If there are no
1178 primary controllers, adding one also clears these tables. Other
1179 changes to the set of controllers, such as adding or removing a
1180 service controller, adding another primary controller to supplement
1181 an existing primary controller, or removing only one of two primary
1182 controllers, have no effect on these tables.
1183 </p>
1184 </column>
1185
1186 <column name="flow_tables">
1187 Configuration for OpenFlow tables. Each pair maps from an OpenFlow
1188 table ID to configuration for that table.
1189 </column>
1190
1191 <column name="fail_mode">
1192 <p>When a controller is configured, it is, ordinarily, responsible
1193 for setting up all flows on the switch. Thus, if the connection to
1194 the controller fails, no new network connections can be set up.
1195 If the connection to the controller stays down long enough,
1196 no packets can pass through the switch at all. This setting
1197 determines the switch's response to such a situation. It may be set
1198 to one of the following:
1199 <dl>
1200 <dt><code>standalone</code></dt>
1201 <dd>If no message is received from the controller for three
1202 times the inactivity probe interval
1203 (see <ref column="inactivity_probe"/>), then Open vSwitch
1204 will take over responsibility for setting up flows. In
1205 this mode, Open vSwitch causes the bridge to act like an
1206 ordinary MAC-learning switch. Open vSwitch will continue
1207 to retry connecting to the controller in the background
1208 and, when the connection succeeds, it will discontinue its
1209 standalone behavior.</dd>
1210 <dt><code>secure</code></dt>
1211 <dd>Open vSwitch will not set up flows on its own when the
1212 controller connection fails or when no controllers are
1213 defined. The bridge will continue to retry connecting to
1214 any defined controllers forever.</dd>
1215 </dl>
1216 </p>
1217 <p>
1218 The default is <code>standalone</code> if the value is unset, but
1219 future versions of Open vSwitch may change the default.
1220 </p>
1221 <p>
1222 The <code>standalone</code> mode can create forwarding loops on a
1223 bridge that has more than one uplink port unless STP is enabled. To
1224 avoid loops on such a bridge, configure <code>secure</code> mode or
1225 enable STP (see <ref column="stp_enable"/>).
1226 </p>
1227 <p>
1228 The <ref column="fail_mode"/> setting applies only to primary
1229 controllers. When more than one primary controller is configured,
1230 <ref column="fail_mode"/> is considered only when none of the
1231 configured controllers can be contacted.
1232 </p>
1233 <p>
1234 Changing <ref column="fail_mode"/> when no primary controllers are
1235 configured clears the OpenFlow flow tables, group table, and meter
1236 table.
1237 </p>
1238 </column>
1239
1240 <column name="datapath_id">
1241 Reports the OpenFlow datapath ID in use. Exactly 16 hex digits.
1242 (Setting this column has no useful effect. Set <ref
1243 column="other-config" key="datapath-id"/> instead.)
1244 </column>
1245
1246 <column name="datapath_version">
1247 Reports the datapath version. This column is maintained for
1248 backwards compatibility. The preferred locatation is the
1249 <ref column="datapath_id" table="Datapath"/> column of the
1250 <ref table="Datapath"/> table. The full documentation for this
1251 column is there.
1252 </column>
1253
1254 <column name="other_config" key="datapath-id">
1255 Overrides the default OpenFlow datapath ID, setting it to the specified
1256 value specified in hex. The value must either have a <code>0x</code>
1257 prefix or be exactly 16 hex digits long. May not be all-zero.
1258 </column>
1259
1260 <column name="other_config" key="dp-desc">
1261 Human readable description of datapath. It is a maximum 256
1262 byte-long free-form string to describe the datapath for
1263 debugging purposes, e.g. <code>switch3 in room 3120</code>.
1264 The value is returned by the switch as a part of reply to OFPMP_DESC
1265 request (ofp_desc). The OpenFlow specification (e.g. 1.3.5) describes
1266 the ofp_desc structure to contaion "NULL terminated ASCII strings".
1267 For the compatibility reasons no more than 255 ASCII characters should be used.
1268 </column>
1269
1270 <column name="other_config" key="dp-sn">
1271 Serial number. It is a maximum 32 byte-long free-form string to
1272 provide an additional switch identification. The value is returned
1273 by the switch as a part of reply to OFPMP_DESC request (ofp_desc).
1274 Same as mentioned in the description of <ref column="other-config" key="dp-desc"/>,
1275 the string should be no more than 31 ASCII characters for the compatibility.
1276 </column>
1277
1278 <column name="other_config" key="disable-in-band"
1279 type='{"type": "boolean"}'>
1280 If set to <code>true</code>, disable in-band control on the bridge
1281 regardless of controller and manager settings.
1282 </column>
1283
1284 <column name="other_config" key="in-band-queue"
1285 type='{"type": "integer", "minInteger": 0, "maxInteger": 4294967295}'>
1286 A queue ID as a nonnegative integer. This sets the OpenFlow queue ID
1287 that will be used by flows set up by in-band control on this bridge.
1288 If unset, or if the port used by an in-band control flow does not have
1289 QoS configured, or if the port does not have a queue with the specified
1290 ID, the default queue is used instead.
1291 </column>
1292
1293 <column name="other_config" key="controller-queue-size"
1294 type='{"type": "integer", "minInteger": 1, "maxInteger": 512}'>
1295 This sets the maximum size of the queue of packets that need to be
1296 sent to the OpenFlow management controller. The value must be less
1297 than 512. If not specified the queue size is limited to 100 packets
1298 by default. Note: increasing the queue size might have a negative
1299 impact on latency.
1300 </column>
1301
1302 <column name="protocols">
1303 List of OpenFlow protocols that may be used when negotiating a
1304 connection with a controller. OpenFlow 1.0, 1.1, 1.2, 1.3, 1.4, and
1305 1.5 are enabled by default if this column is empty.
1306 </column>
1307 </group>
1308
1309 <group title="Spanning Tree Configuration">
1310 <p>
1311 The IEEE 802.1D Spanning Tree Protocol (STP) is a network protocol
1312 that ensures loop-free topologies. It allows redundant links to
1313 be included in the network to provide automatic backup paths if
1314 the active links fails.
1315 </p>
1316
1317 <p>
1318 These settings configure the slower-to-converge but still widely
1319 supported version of Spanning Tree Protocol, sometimes known as
1320 802.1D-1998. Open vSwitch also supports the newer Rapid Spanning Tree
1321 Protocol (RSTP), documented later in the section titled <code>Rapid
1322 Spanning Tree Configuration</code>.
1323 </p>
1324
1325 <group title="STP Configuration">
1326 <column name="stp_enable" type='{"type": "boolean"}'>
1327 <p>
1328 Enable spanning tree on the bridge. By default, STP is disabled
1329 on bridges. Bond, internal, and mirror ports are not supported
1330 and will not participate in the spanning tree.
1331 </p>
1332
1333 <p>
1334 STP and RSTP are mutually exclusive. If both are enabled, RSTP
1335 will be used.
1336 </p>
1337 </column>
1338
1339 <column name="other_config" key="stp-system-id">
1340 The bridge's STP identifier (the lower 48 bits of the bridge-id)
1341 in the form
1342 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
1343 By default, the identifier is the MAC address of the bridge.
1344 </column>
1345
1346 <column name="other_config" key="stp-priority"
1347 type='{"type": "integer", "minInteger": 0, "maxInteger": 65535}'>
1348 The bridge's relative priority value for determining the root
1349 bridge (the upper 16 bits of the bridge-id). A bridge with the
1350 lowest bridge-id is elected the root. By default, the priority
1351 is 0x8000.
1352 </column>
1353
1354 <column name="other_config" key="stp-hello-time"
1355 type='{"type": "integer", "minInteger": 1, "maxInteger": 10}'>
1356 The interval between transmissions of hello messages by
1357 designated ports, in seconds. By default the hello interval is
1358 2 seconds.
1359 </column>
1360
1361 <column name="other_config" key="stp-max-age"
1362 type='{"type": "integer", "minInteger": 6, "maxInteger": 40}'>
1363 The maximum age of the information transmitted by the bridge
1364 when it is the root bridge, in seconds. By default, the maximum
1365 age is 20 seconds.
1366 </column>
1367
1368 <column name="other_config" key="stp-forward-delay"
1369 type='{"type": "integer", "minInteger": 4, "maxInteger": 30}'>
1370 The delay to wait between transitioning root and designated
1371 ports to <code>forwarding</code>, in seconds. By default, the
1372 forwarding delay is 15 seconds.
1373 </column>
1374
1375 <column name="other_config" key="mcast-snooping-aging-time"
1376 type='{"type": "integer", "minInteger": 1}'>
1377 <p>
1378 The maximum number of seconds to retain a multicast snooping entry for
1379 which no packets have been seen. The default is currently 300
1380 seconds (5 minutes). The value, if specified, is forced into a
1381 reasonable range, currently 15 to 3600 seconds.
1382 </p>
1383 </column>
1384
1385 <column name="other_config" key="mcast-snooping-table-size"
1386 type='{"type": "integer", "minInteger": 1}'>
1387 <p>
1388 The maximum number of multicast snooping addresses to learn. The
1389 default is currently 2048. The value, if specified, is forced into
1390 a reasonable range, currently 10 to 1,000,000.
1391 </p>
1392 </column>
1393 <column name="other_config" key="mcast-snooping-disable-flood-unregistered"
1394 type='{"type": "boolean"}'>
1395 <p>
1396 If set to <code>false</code>, unregistered multicast packets are forwarded
1397 to all ports.
1398 If set to <code>true</code>, unregistered multicast packets are forwarded
1399 to ports connected to multicast routers.
1400 </p>
1401 </column>
1402 </group>
1403
1404 <group title="STP Status">
1405 <p>
1406 These key-value pairs report the status of 802.1D-1998. They are
1407 present only if STP is enabled (via the <ref column="stp_enable"/>
1408 column).
1409 </p>
1410 <column name="status" key="stp_bridge_id">
1411 The bridge ID used in spanning tree advertisements, in the form
1412 <var>xxxx</var>.<var>yyyyyyyyyyyy</var> where the <var>x</var>s are
1413 the STP priority, the <var>y</var>s are the STP system ID, and each
1414 <var>x</var> and <var>y</var> is a hex digit.
1415 </column>
1416 <column name="status" key="stp_designated_root">
1417 The designated root for this spanning tree, in the same form as <ref
1418 column="status" key="stp_bridge_id"/>. If this bridge is the root,
1419 this will have the same value as <ref column="status"
1420 key="stp_bridge_id"/>, otherwise it will differ.
1421 </column>
1422 <column name="status" key="stp_root_path_cost">
1423 The path cost of reaching the designated bridge. A lower number is
1424 better. The value is 0 if this bridge is the root, otherwise it is
1425 higher.
1426 </column>
1427 </group>
1428 </group>
1429
1430 <group title="Rapid Spanning Tree">
1431 <p>
1432 Rapid Spanning Tree Protocol (RSTP), like STP, is a network protocol
1433 that ensures loop-free topologies. RSTP superseded STP with the
1434 publication of 802.1D-2004. Compared to STP, RSTP converges more
1435 quickly and recovers more quickly from failures.
1436 </p>
1437
1438 <group title="RSTP Configuration">
1439 <column name="rstp_enable" type='{"type": "boolean"}'>
1440 <p>
1441 Enable Rapid Spanning Tree on the bridge. By default, RSTP is disabled
1442 on bridges. Bond, internal, and mirror ports are not supported
1443 and will not participate in the spanning tree.
1444 </p>
1445
1446 <p>
1447 STP and RSTP are mutually exclusive. If both are enabled, RSTP
1448 will be used.
1449 </p>
1450 </column>
1451
1452 <column name="other_config" key="rstp-address">
1453 The bridge's RSTP address (the lower 48 bits of the bridge-id)
1454 in the form
1455 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
1456 By default, the address is the MAC address of the bridge.
1457 </column>
1458
1459 <column name="other_config" key="rstp-priority"
1460 type='{"type": "integer", "minInteger": 0, "maxInteger": 61440}'>
1461 The bridge's relative priority value for determining the root
1462 bridge (the upper 16 bits of the bridge-id). A bridge with the
1463 lowest bridge-id is elected the root. By default, the priority
1464 is 0x8000 (32768). This value needs to be a multiple of 4096,
1465 otherwise it's rounded to the nearest inferior one.
1466 </column>
1467
1468 <column name="other_config" key="rstp-ageing-time"
1469 type='{"type": "integer", "minInteger": 10, "maxInteger": 1000000}'>
1470 The Ageing Time parameter for the Bridge. The default value
1471 is 300 seconds.
1472 </column>
1473
1474 <column name="other_config" key="rstp-force-protocol-version"
1475 type='{"type": "integer"}'>
1476 The Force Protocol Version parameter for the Bridge. This
1477 can take the value 0 (STP Compatibility mode) or 2
1478 (the default, normal operation).
1479 </column>
1480
1481 <column name="other_config" key="rstp-max-age"
1482 type='{"type": "integer", "minInteger": 6, "maxInteger": 40}'>
1483 The maximum age of the information transmitted by the Bridge
1484 when it is the Root Bridge. The default value is 20.
1485 </column>
1486
1487 <column name="other_config" key="rstp-forward-delay"
1488 type='{"type": "integer", "minInteger": 4, "maxInteger": 30}'>
1489 The delay used by STP Bridges to transition Root and Designated
1490 Ports to Forwarding. The default value is 15.
1491 </column>
1492
1493 <column name="other_config" key="rstp-transmit-hold-count"
1494 type='{"type": "integer", "minInteger": 1, "maxInteger": 10}'>
1495 The Transmit Hold Count used by the Port Transmit state machine
1496 to limit transmission rate. The default value is 6.
1497 </column>
1498 </group>
1499
1500 <group title="RSTP Status">
1501 <p>
1502 These key-value pairs report the status of 802.1D-2004. They are
1503 present only if RSTP is enabled (via the <ref column="rstp_enable"/>
1504 column).
1505 </p>
1506 <column name="rstp_status" key="rstp_bridge_id">
1507 The bridge ID used in rapid spanning tree advertisements, in the form
1508 <var>x</var>.<var>yyy</var>.<var>zzzzzzzzzzzz</var> where
1509 <var>x</var> is the RSTP priority, the <var>y</var>s are a locally
1510 assigned system ID extension, the <var>z</var>s are the STP system
1511 ID, and each <var>x</var>, <var>y</var>, or <var>z</var> is a hex
1512 digit.
1513 </column>
1514 <column name="rstp_status" key="rstp_root_id">
1515 The root of this spanning tree, in the same form as <ref
1516 column="rstp_status" key="rstp_bridge_id"/>. If this bridge is the
1517 root, this will have the same value as <ref column="rstp_status"
1518 key="rstp_bridge_id"/>, otherwise it will differ.
1519 </column>
1520 <column name="rstp_status" key="rstp_root_path_cost"
1521 type='{"type": "integer", "minInteger": 0}'>
1522 The path cost of reaching the root. A lower number is better. The
1523 value is 0 if this bridge is the root, otherwise it is higher.
1524 </column>
1525 <column name="rstp_status" key="rstp_designated_id">
1526 The RSTP designated ID, in the same form as <ref column="rstp_status"
1527 key="rstp_bridge_id"/>.
1528 </column>
1529 <column name="rstp_status" key="rstp_designated_port_id">
1530 The RSTP designated port ID, as a 4-digit hex number.
1531 </column>
1532 <column name="rstp_status" key="rstp_bridge_port_id">
1533 The RSTP bridge port ID, as a 4-digit hex number.
1534 </column>
1535 </group>
1536 </group>
1537
1538 <group title="Multicast Snooping Configuration">
1539 Multicast snooping (RFC 4541) monitors the Internet Group Management
1540 Protocol (IGMP) and Multicast Listener Discovery traffic between hosts
1541 and multicast routers. The switch uses what IGMP and MLD snooping
1542 learns to forward multicast traffic only to interfaces that are connected
1543 to interested receivers. Currently it supports IGMPv1, IGMPv2, IGMPv3,
1544 MLDv1 and MLDv2 protocols.
1545
1546 <column name="mcast_snooping_enable">
1547 Enable multicast snooping on the bridge. For now, the default
1548 is disabled.
1549 </column>
1550 </group>
1551
1552 <group title="Other Features">
1553 <column name="datapath_type">
1554 Name of datapath provider. The kernel datapath has type
1555 <code>system</code>. The userspace datapath has type
1556 <code>netdev</code>. A manager may refer to the <ref
1557 table="Open_vSwitch" column="datapath_types"/> column of the <ref
1558 table="Open_vSwitch"/> table for a list of the types accepted by this
1559 Open vSwitch instance.
1560 </column>
1561
1562 <column name="external_ids" key="bridge-id">
1563 A unique identifier of the bridge. On Citrix XenServer this will
1564 commonly be the same as
1565 <ref column="external_ids" key="xs-network-uuids"/>.
1566 </column>
1567
1568 <column name="external_ids" key="xs-network-uuids">
1569 Semicolon-delimited set of universally unique identifier(s) for the
1570 network with which this bridge is associated on a Citrix XenServer
1571 host. The network identifiers are RFC 4122 UUIDs as displayed by,
1572 e.g., <code>xe network-list</code>.
1573 </column>
1574
1575 <column name="other_config" key="hwaddr">
1576 An Ethernet address in the form
1577 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
1578 to set the hardware address of the local port and influence the
1579 datapath ID.
1580 </column>
1581
1582 <column name="other_config" key="forward-bpdu"
1583 type='{"type": "boolean"}'>
1584
1585 <p>
1586 Controls forwarding of BPDUs and other network control frames when
1587 NORMAL action is invoked. When this option is <code>false</code> or
1588 unset, frames with reserved Ethernet addresses (see table below) will
1589 not be forwarded. When this option is <code>true</code>, such frames
1590 will not be treated specially.
1591 </p>
1592
1593 <p>
1594 The above general rule has the following exceptions:
1595 </p>
1596
1597 <ul>
1598 <li>
1599 If STP is enabled on the bridge (see the <ref column="stp_enable"
1600 table="Bridge"/> column in the <ref table="Bridge"/> table), the
1601 bridge processes all received STP packets and never passes them to
1602 OpenFlow or forwards them. This is true even if STP is disabled on
1603 an individual port.
1604 </li>
1605
1606 <li>
1607 If LLDP is enabled on an interface (see the <ref column="lldp"
1608 table="Interface"/> column in the <ref table="Interface"/> table),
1609 the interface processes received LLDP packets and never passes them
1610 to OpenFlow or forwards them.
1611 </li>
1612 </ul>
1613
1614 <p>
1615 Set this option to <code>true</code> if the Open vSwitch bridge
1616 connects different Ethernet networks and is not configured to
1617 participate in STP.
1618 </p>
1619
1620 <p>
1621 This option affects packets with the following destination MAC
1622 addresses:
1623 </p>
1624
1625 <dl>
1626 <dt><code>01:80:c2:00:00:00</code></dt>
1627 <dd>IEEE 802.1D Spanning Tree Protocol (STP).</dd>
1628
1629 <dt><code>01:80:c2:00:00:01</code></dt>
1630 <dd>IEEE Pause frame.</dd>
1631
1632 <dt><code>01:80:c2:00:00:0<var>x</var></code></dt>
1633 <dd>Other reserved protocols.</dd>
1634
1635 <dt><code>00:e0:2b:00:00:00</code></dt>
1636 <dd>Extreme Discovery Protocol (EDP).</dd>
1637
1638 <dt>
1639 <code>00:e0:2b:00:00:04</code> and <code>00:e0:2b:00:00:06</code>
1640 </dt>
1641 <dd>Ethernet Automatic Protection Switching (EAPS).</dd>
1642
1643 <dt><code>01:00:0c:cc:cc:cc</code></dt>
1644 <dd>
1645 Cisco Discovery Protocol (CDP), VLAN Trunking Protocol (VTP),
1646 Dynamic Trunking Protocol (DTP), Port Aggregation Protocol (PAgP),
1647 and others.
1648 </dd>
1649
1650 <dt><code>01:00:0c:cc:cc:cd</code></dt>
1651 <dd>Cisco Shared Spanning Tree Protocol PVSTP+.</dd>
1652
1653 <dt><code>01:00:0c:cd:cd:cd</code></dt>
1654 <dd>Cisco STP Uplink Fast.</dd>
1655
1656 <dt><code>01:00:0c:00:00:00</code></dt>
1657 <dd>Cisco Inter Switch Link.</dd>
1658
1659 <dt><code>01:00:0c:cc:cc:c<var>x</var></code></dt>
1660 <dd>Cisco CFM.</dd>
1661 </dl>
1662 </column>
1663
1664 <column name="other_config" key="mac-aging-time"
1665 type='{"type": "integer", "minInteger": 1}'>
1666 <p>
1667 The maximum number of seconds to retain a MAC learning entry for
1668 which no packets have been seen. The default is currently 300
1669 seconds (5 minutes). The value, if specified, is forced into a
1670 reasonable range, currently 15 to 3600 seconds.
1671 </p>
1672
1673 <p>
1674 A short MAC aging time allows a network to more quickly detect that a
1675 host is no longer connected to a switch port. However, it also makes
1676 it more likely that packets will be flooded unnecessarily, when they
1677 are addressed to a connected host that rarely transmits packets. To
1678 reduce the incidence of unnecessary flooding, use a MAC aging time
1679 longer than the maximum interval at which a host will ordinarily
1680 transmit packets.
1681 </p>
1682 </column>
1683
1684 <column name="other_config" key="mac-table-size"
1685 type='{"type": "integer", "minInteger": 1}'>
1686 <p>
1687 The maximum number of MAC addresses to learn. The default is
1688 currently 8192. The value, if specified, is forced into a reasonable
1689 range, currently 10 to 1,000,000.
1690 </p>
1691 </column>
1692 </group>
1693
1694 <group title="Common Columns">
1695 The overall purpose of these columns is described under <code>Common
1696 Columns</code> at the beginning of this document.
1697
1698 <column name="other_config"/>
1699 <column name="external_ids"/>
1700 </group>
1701 </table>
1702
1703 <table name="Port" table="Port or bond configuration.">
1704 <p>A port within a <ref table="Bridge"/>.</p>
1705 <p>Most commonly, a port has exactly one ``interface,'' pointed to by its
1706 <ref column="interfaces"/> column. Such a port logically
1707 corresponds to a port on a physical Ethernet switch. A port
1708 with more than one interface is a ``bonded port'' (see
1709 <ref group="Bonding Configuration"/>).</p>
1710 <p>Some properties that one might think as belonging to a port are actually
1711 part of the port's <ref table="Interface"/> members.</p>
1712
1713 <column name="name">
1714 Port name. For a non-bonded port, this should be the same as its
1715 interface's name. Port names must otherwise be unique among the names of
1716 ports, interfaces, and bridges on a host. Because port and interfaces
1717 names are usually the same, the restrictions on the <ref
1718 table="Interface" column="name"/> column in the <ref table="Interface"/>
1719 table, particularly on length, also apply to port names. Refer to the
1720 documentation for <ref table="Interface"/> names for details.
1721 </column>
1722
1723 <column name="interfaces">
1724 The port's interfaces. If there is more than one, this is a
1725 bonded Port.
1726 </column>
1727
1728 <group title="VLAN Configuration">
1729 <p>
1730 In short, a VLAN (short for ``virtual LAN'') is a way to partition a
1731 single switch into multiple switches. VLANs can be confusing, so for
1732 an introduction, please refer to the question ``What's a VLAN?'' in the
1733 Open vSwitch FAQ.
1734 </p>
1735
1736 <p>
1737 A VLAN is sometimes encoded into a packet using a 802.1Q or 802.1ad
1738 VLAN header, but every packet is part of some VLAN whether or not it is
1739 encoded in the packet. (A packet that appears to have no VLAN is part
1740 of VLAN 0, by default.) As a result, it's useful to think of a VLAN as
1741 a metadata property of a packet, separate from how the VLAN is encoded.
1742 For a given port, this column determines how the encoding of a packet
1743 that ingresses or egresses the port maps to the packet's VLAN. When a
1744 packet enters the switch, its VLAN is determined based on its setting
1745 in this column and its VLAN headers, if any, and then, conceptually,
1746 the VLAN headers are then stripped off. Conversely, when a packet
1747 exits the switch, its VLAN and the settings in this column determine
1748 what VLAN headers, if any, are pushed onto the packet before it
1749 egresses the port.
1750 </p>
1751
1752 <p>
1753 The VLAN configuration in this column affects Open vSwitch only when it
1754 is doing ``normal switching.'' It does not affect flows set up by an
1755 OpenFlow controller, outside of the OpenFlow ``normal action.''
1756 </p>
1757
1758 <p>
1759 Bridge ports support the following types of VLAN configuration:
1760 </p>
1761
1762 <dl>
1763 <dt>trunk</dt>
1764 <dd>
1765 <p>
1766 A trunk port carries packets on one or more specified VLANs
1767 specified in the <ref column="trunks"/> column (often, on every
1768 VLAN). A packet that ingresses on a trunk port is in the VLAN
1769 specified in its 802.1Q header, or VLAN 0 if the packet has no
1770 802.1Q header. A packet that egresses through a trunk port will
1771 have an 802.1Q header if it has a nonzero VLAN ID.
1772 </p>
1773
1774 <p>
1775 Any packet that ingresses on a trunk port tagged with a VLAN that
1776 the port does not trunk is dropped.
1777 </p>
1778 </dd>
1779
1780 <dt>access</dt>
1781 <dd>
1782 <p>
1783 An access port carries packets on exactly one VLAN specified in the
1784 <ref column="tag"/> column. Packets egressing on an access port
1785 have no 802.1Q header.
1786 </p>
1787
1788 <p>
1789 Any packet with an 802.1Q header with a nonzero VLAN ID that
1790 ingresses on an access port is dropped, regardless of whether the
1791 VLAN ID in the header is the access port's VLAN ID.
1792 </p>
1793 </dd>
1794
1795 <dt>native-tagged</dt>
1796 <dd>
1797 A native-tagged port resembles a trunk port, with the exception that
1798 a packet without an 802.1Q header that ingresses on a native-tagged
1799 port is in the ``native VLAN'' (specified in the <ref column="tag"/>
1800 column).
1801 </dd>
1802
1803 <dt>native-untagged</dt>
1804 <dd>
1805 A native-untagged port resembles a native-tagged port, with the
1806 exception that a packet that egresses on a native-untagged port in
1807 the native VLAN will not have an 802.1Q header.
1808 </dd>
1809
1810 <dt>dot1q-tunnel</dt>
1811 <dd>
1812 <p>
1813 A dot1q-tunnel port is somewhat like an access port. Like an
1814 access port, it carries packets on the single VLAN specified in the
1815 <ref column="tag"/> column and this VLAN, called the service VLAN,
1816 does not appear in an 802.1Q header for packets that ingress or
1817 egress on the port. The main difference lies in the behavior when
1818 packets that include a 802.1Q header ingress on the port. Whereas
1819 an access port drops such packets, a dot1q-tunnel port treats these
1820 as double-tagged with the outer service VLAN <ref column="tag"/>
1821 and the inner customer VLAN taken from the 802.1Q header.
1822 Correspondingly, to egress on the port, a packet outer VLAN (or
1823 only VLAN) must be <ref column="tag"/>, which is removed before
1824 egress, which exposes the inner (customer) VLAN if one is present.
1825 </p>
1826
1827 <p>
1828 If <ref column="cvlans"/> is set, only allows packets in the
1829 specified customer VLANs.
1830 </p>
1831 </dd>
1832 </dl>
1833 <p>
1834 A packet will only egress through bridge ports that carry the VLAN of
1835 the packet, as described by the rules above.
1836 </p>
1837
1838 <column name="vlan_mode">
1839 <p>
1840 The VLAN mode of the port, as described above. When this column is
1841 empty, a default mode is selected as follows:
1842 </p>
1843 <ul>
1844 <li>
1845 If <ref column="tag"/> contains a value, the port is an access
1846 port. The <ref column="trunks"/> column should be empty.
1847 </li>
1848 <li>
1849 Otherwise, the port is a trunk port. The <ref column="trunks"/>
1850 column value is honored if it is present.
1851 </li>
1852 </ul>
1853 </column>
1854
1855 <column name="tag">
1856 <p>
1857 For an access port, the port's implicitly tagged VLAN. For a
1858 native-tagged or native-untagged port, the port's native VLAN. Must
1859 be empty if this is a trunk port.
1860 </p>
1861 </column>
1862
1863 <column name="trunks">
1864 <p>
1865 For a trunk, native-tagged, or native-untagged port, the 802.1Q VLAN
1866 or VLANs that this port trunks; if it is empty, then the port trunks
1867 all VLANs. Must be empty if this is an access port.
1868 </p>
1869 <p>
1870 A native-tagged or native-untagged port always trunks its native
1871 VLAN, regardless of whether <ref column="trunks"/> includes that
1872 VLAN.
1873 </p>
1874 </column>
1875
1876 <column name="cvlans">
1877 <p>
1878 For a dot1q-tunnel port, the customer VLANs that this port includes.
1879 If this is empty, the port includes all customer VLANs.
1880 </p>
1881 <p>
1882 For other kinds of ports, this setting is ignored.
1883 </p>
1884 </column>
1885
1886 <column name="other_config" key="qinq-ethtype"
1887 type='{"type": "string", "enum": ["set", ["802.1ad", "802.1q"]]}'>
1888 <p>
1889 For a dot1q-tunnel port, this is the TPID for the service tag, that
1890 is, for the 802.1Q header that contains the service VLAN ID. Because
1891 packets that actually ingress and egress a dot1q-tunnel port do not
1892 include an 802.1Q header for the service VLAN, this does not affect
1893 packets on the dot1q-tunnel port itself. Rather, it determines the
1894 service VLAN for a packet that ingresses on a dot1q-tunnel port and
1895 egresses on a trunk port.
1896 </p>
1897 <p>
1898 The value <code>802.1ad</code> specifies TPID 0x88a8, which is also
1899 the default if the setting is omitted. The value <code>802.1q</code>
1900 specifies TPID 0x8100.
1901 </p>
1902 <p>
1903 For other kinds of ports, this setting is ignored.
1904 </p>
1905 </column>
1906
1907 <column name="other_config" key="priority-tags"
1908 type='{"type": "string",
1909 "enum": ["set", ["never", "if-nonzero", "always"]]}'>
1910 <p>
1911 An 802.1Q header contains two important pieces of information: a VLAN
1912 ID and a priority. A frame with a zero VLAN ID, called a
1913 ``priority-tagged'' frame, is supposed to be treated the same way as
1914 a frame without an 802.1Q header at all (except for the priority).
1915 </p>
1916
1917 <p>
1918 However, some network elements ignore any frame that has 802.1Q
1919 header at all, even when the VLAN ID is zero. Therefore, by default
1920 Open vSwitch does not output priority-tagged frames, instead omitting
1921 the 802.1Q header entirely if the VLAN ID is zero. Set this key to
1922 <code>if-nonzero</code> to enable priority-tagged frames on a port.
1923 </p>
1924
1925 <p>
1926 For <code>if-nonzero</code> Open vSwitch omits the 802.1Q header on
1927 output if both the VLAN ID and priority would be zero. Set to
1928 <code>always</code> to retain the 802.1Q header in such frames as
1929 well.
1930 </p>
1931
1932 <p>
1933 All frames output to native-tagged ports have a nonzero VLAN ID, so
1934 this setting is not meaningful on native-tagged ports.
1935 </p>
1936 </column>
1937 </group>
1938
1939 <group title="Bonding Configuration">
1940 <p>A port that has more than one interface is a ``bonded port.'' Bonding
1941 allows for load balancing and fail-over.</p>
1942
1943 <p>
1944 The following types of bonding will work with any kind of upstream
1945 switch. On the upstream switch, do not configure the interfaces as a
1946 bond:
1947 </p>
1948
1949 <dl>
1950 <dt><code>balance-slb</code></dt>
1951 <dd>
1952 Balances flows among slaves based on source MAC address and output
1953 VLAN, with periodic rebalancing as traffic patterns change.
1954 </dd>
1955
1956 <dt><code>active-backup</code></dt>
1957 <dd>
1958 Assigns all flows to one slave, failing over to a backup slave when
1959 the active slave is disabled. This is the only bonding mode in which
1960 interfaces may be plugged into different upstream switches.
1961 </dd>
1962 </dl>
1963
1964 <p>
1965 The following modes require the upstream switch to support 802.3ad with
1966 successful LACP negotiation. If LACP negotiation fails and
1967 other-config:lacp-fallback-ab is true, then <code>active-backup</code>
1968 mode is used:
1969 </p>
1970
1971 <dl>
1972 <dt><code>balance-tcp</code></dt>
1973 <dd>
1974 Balances flows among slaves based on L3 and L4 protocol information
1975 such as IP addresses and TCP/UDP ports.
1976 </dd>
1977 </dl>
1978
1979 <p>These columns apply only to bonded ports. Their values are
1980 otherwise ignored.</p>
1981
1982 <column name="bond_mode">
1983 <p>The type of bonding used for a bonded port. Defaults to
1984 <code>active-backup</code> if unset.
1985 </p>
1986 </column>
1987
1988 <column name="other_config" key="bond-hash-basis"
1989 type='{"type": "integer"}'>
1990 An integer hashed along with flows when choosing output slaves in load
1991 balanced bonds. When changed, all flows will be assigned different
1992 hash values possibly causing slave selection decisions to change. Does
1993 not affect bonding modes which do not employ load balancing such as
1994 <code>active-backup</code>.
1995 </column>
1996
1997 <group title="Link Failure Detection">
1998 <p>
1999 An important part of link bonding is detecting that links are down so
2000 that they may be disabled. These settings determine how Open vSwitch
2001 detects link failure.
2002 </p>
2003
2004 <column name="other_config" key="bond-detect-mode"
2005 type='{"type": "string", "enum": ["set", ["carrier", "miimon"]]}'>
2006 The means used to detect link failures. Defaults to
2007 <code>carrier</code> which uses each interface's carrier to detect
2008 failures. When set to <code>miimon</code>, will check for failures
2009 by polling each interface's MII.
2010 </column>
2011
2012 <column name="other_config" key="bond-miimon-interval"
2013 type='{"type": "integer"}'>
2014 The interval, in milliseconds, between successive attempts to poll
2015 each interface's MII. Relevant only when <ref column="other_config"
2016 key="bond-detect-mode"/> is <code>miimon</code>.
2017 </column>
2018
2019 <column name="bond_updelay">
2020 <p>
2021 The number of milliseconds for which the link must stay up on an
2022 interface before the interface is considered to be up. Specify
2023 <code>0</code> to enable the interface immediately.
2024 </p>
2025
2026 <p>
2027 This setting is honored only when at least one bonded interface is
2028 already enabled. When no interfaces are enabled, then the first
2029 bond interface to come up is enabled immediately.
2030 </p>
2031 </column>
2032
2033 <column name="bond_downdelay">
2034 The number of milliseconds for which the link must stay down on an
2035 interface before the interface is considered to be down. Specify
2036 <code>0</code> to disable the interface immediately.
2037 </column>
2038 </group>
2039
2040 <group title="LACP Configuration">
2041 <p>
2042 LACP, the Link Aggregation Control Protocol, is an IEEE standard that
2043 allows switches to automatically detect that they are connected by
2044 multiple links and aggregate across those links. These settings
2045 control LACP behavior.
2046 </p>
2047
2048 <column name="lacp">
2049 Configures LACP on this port. LACP allows directly connected
2050 switches to negotiate which links may be bonded. LACP may be enabled
2051 on non-bonded ports for the benefit of any switches they may be
2052 connected to. <code>active</code> ports are allowed to initiate LACP
2053 negotiations. <code>passive</code> ports are allowed to participate
2054 in LACP negotiations initiated by a remote switch, but not allowed to
2055 initiate such negotiations themselves. If LACP is enabled on a port
2056 whose partner switch does not support LACP, the bond will be
2057 disabled, unless other-config:lacp-fallback-ab is set to true.
2058 Defaults to <code>off</code> if unset.
2059 </column>
2060
2061 <column name="other_config" key="lacp-system-id">
2062 The LACP system ID of this <ref table="Port"/>. The system ID of a
2063 LACP bond is used to identify itself to its partners. Must be a
2064 nonzero MAC address. Defaults to the bridge Ethernet address if
2065 unset.
2066 </column>
2067
2068 <column name="other_config" key="lacp-system-priority"
2069 type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
2070 The LACP system priority of this <ref table="Port"/>. In LACP
2071 negotiations, link status decisions are made by the system with the
2072 numerically lower priority.
2073 </column>
2074
2075 <column name="other_config" key="lacp-time"
2076 type='{"type": "string", "enum": ["set", ["fast", "slow"]]}'>
2077 <p>
2078 The LACP timing which should be used on this <ref table="Port"/>.
2079 By default <code>slow</code> is used. When configured to be
2080 <code>fast</code> LACP heartbeats are requested at a rate of once
2081 per second causing connectivity problems to be detected more
2082 quickly. In <code>slow</code> mode, heartbeats are requested at a
2083 rate of once every 30 seconds.
2084 </p>
2085 </column>
2086
2087 <column name="other_config" key="lacp-fallback-ab"
2088 type='{"type": "boolean"}'>
2089 <p>
2090 Determines the behavior of openvswitch bond in LACP mode. If
2091 the partner switch does not support LACP, setting this option
2092 to <code>true</code> allows openvswitch to fallback to
2093 active-backup. If the option is set to <code>false</code>, the
2094 bond will be disabled. In both the cases, once the partner switch
2095 is configured to LACP mode, the bond will use LACP.
2096 </p>
2097 </column>
2098 </group>
2099
2100 <group title="Rebalancing Configuration">
2101 <p>
2102 These settings control behavior when a bond is in
2103 <code>balance-slb</code> or <code>balance-tcp</code> mode.
2104 </p>
2105
2106 <column name="other_config" key="bond-rebalance-interval"
2107 type='{"type": "integer",
2108 "minInteger": 0, "maxInteger": 2147483647}'>
2109 For a load balanced bonded port, the number of milliseconds between
2110 successive attempts to rebalance the bond, that is, to move flows
2111 from one interface on the bond to another in an attempt to keep usage
2112 of each interface roughly equal. If zero, load balancing is disabled
2113 on the bond (link failure still cause flows to move). If
2114 less than 1000ms, the rebalance interval will be 1000ms.
2115 </column>
2116 </group>
2117
2118 <column name="bond_fake_iface">
2119 For a bonded port, whether to create a fake internal interface with the
2120 name of the port. Use only for compatibility with legacy software that
2121 requires this.
2122 </column>
2123 </group>
2124
2125 <group title="Spanning Tree Protocol">
2126 <p>
2127 The configuration here is only meaningful, and the status is only
2128 populated, when 802.1D-1998 Spanning Tree Protocol is enabled on the
2129 port's <ref column="Bridge"/> with its <ref column="stp_enable"/>
2130 column.
2131 </p>
2132
2133 <group title="STP Configuration">
2134 <column name="other_config" key="stp-enable"
2135 type='{"type": "boolean"}'>
2136 When STP is enabled on a bridge, it is enabled by default on all of
2137 the bridge's ports except bond, internal, and mirror ports (which do
2138 not work with STP). If this column's value is <code>false</code>,
2139 STP is disabled on the port.
2140 </column>
2141
2142 <column name="other_config" key="stp-port-num"
2143 type='{"type": "integer", "minInteger": 1, "maxInteger": 255}'>
2144 The port number used for the lower 8 bits of the port-id. By
2145 default, the numbers will be assigned automatically. If any
2146 port's number is manually configured on a bridge, then they
2147 must all be.
2148 </column>
2149
2150 <column name="other_config" key="stp-port-priority"
2151 type='{"type": "integer", "minInteger": 0, "maxInteger": 255}'>
2152 The port's relative priority value for determining the root
2153 port (the upper 8 bits of the port-id). A port with a lower
2154 port-id will be chosen as the root port. By default, the
2155 priority is 0x80.
2156 </column>
2157
2158 <column name="other_config" key="stp-path-cost"
2159 type='{"type": "integer", "minInteger": 0, "maxInteger": 65535}'>
2160 Spanning tree path cost for the port. A lower number indicates
2161 a faster link. By default, the cost is based on the maximum
2162 speed of the link.
2163 </column>
2164 </group>
2165
2166 <group title="STP Status">
2167 <column name="status" key="stp_port_id">
2168 The port ID used in spanning tree advertisements for this port, as 4
2169 hex digits. Configuring the port ID is described in the
2170 <code>stp-port-num</code> and <code>stp-port-priority</code> keys of
2171 the <code>other_config</code> section earlier.
2172 </column>
2173 <column name="status" key="stp_state"
2174 type='{"type": "string", "enum": ["set",
2175 ["disabled", "listening", "learning",
2176 "forwarding", "blocking"]]}'>
2177 STP state of the port.
2178 </column>
2179 <column name="status" key="stp_sec_in_state"
2180 type='{"type": "integer", "minInteger": 0}'>
2181 The amount of time this port has been in the current STP state, in
2182 seconds.
2183 </column>
2184 <column name="status" key="stp_role"
2185 type='{"type": "string", "enum": ["set",
2186 ["root", "designated", "alternate"]]}'>
2187 STP role of the port.
2188 </column>
2189 </group>
2190 </group>
2191
2192 <group title="Rapid Spanning Tree Protocol">
2193 <p>
2194 The configuration here is only meaningful, and the status and
2195 statistics are only populated, when 802.1D-1998 Spanning Tree Protocol
2196 is enabled on the port's <ref column="Bridge"/> with its <ref
2197 column="stp_enable"/> column.
2198 </p>
2199
2200 <group title="RSTP Configuration">
2201 <column name="other_config" key="rstp-enable"
2202 type='{"type": "boolean"}'>
2203 When RSTP is enabled on a bridge, it is enabled by default on all of
2204 the bridge's ports except bond, internal, and mirror ports (which do
2205 not work with RSTP). If this column's value is <code>false</code>,
2206 RSTP is disabled on the port.
2207 </column>
2208
2209 <column name="other_config" key="rstp-port-priority"
2210 type='{"type": "integer", "minInteger": 0, "maxInteger": 240}'>
2211 The port's relative priority value for determining the root port, in
2212 multiples of 16. By default, the port priority is 0x80 (128). Any
2213 value in the lower 4 bits is rounded off. The significant upper 4
2214 bits become the upper 4 bits of the port-id. A port with the lowest
2215 port-id is elected as the root.
2216 </column>
2217
2218 <column name="other_config" key="rstp-port-num"
2219 type='{"type": "integer", "minInteger": 1, "maxInteger": 4095}'>
2220 The local RSTP port number, used as the lower 12 bits of the port-id.
2221 By default the port numbers are assigned automatically, and typically
2222 may not correspond to the OpenFlow port numbers. A port with the
2223 lowest port-id is elected as the root.
2224 </column>
2225
2226 <column name="other_config" key="rstp-port-path-cost"
2227 type='{"type": "integer"}'>
2228 The port path cost. The Port's contribution, when it is
2229 the Root Port, to the Root Path Cost for the Bridge. By default the
2230 cost is automatically calculated from the port's speed.
2231 </column>
2232
2233 <column name="other_config" key="rstp-port-admin-edge"
2234 type='{"type": "boolean"}'>
2235 The admin edge port parameter for the Port. Default is
2236 <code>false</code>.
2237 </column>
2238
2239 <column name="other_config" key="rstp-port-auto-edge"
2240 type='{"type": "boolean"}'>
2241 The auto edge port parameter for the Port. Default is
2242 <code>true</code>.
2243 </column>
2244
2245 <column name="other_config" key="rstp-port-mcheck"
2246 type='{"type": "boolean"}'>
2247 <p>
2248 The mcheck port parameter for the Port. Default is
2249 <code>false</code>. May be set to force the Port Protocol
2250 Migration state machine to transmit RST BPDUs for a
2251 MigrateTime period, to test whether all STP Bridges on the
2252 attached LAN have been removed and the Port can continue to
2253 transmit RSTP BPDUs. Setting mcheck has no effect if the
2254 Bridge is operating in STP Compatibility mode.
2255 </p>
2256 <p>
2257 Changing the value from <code>true</code> to
2258 <code>false</code> has no effect, but needs to be done if
2259 this behavior is to be triggered again by subsequently
2260 changing the value from <code>false</code> to
2261 <code>true</code>.
2262 </p>
2263 </column>
2264 </group>
2265
2266 <group title="RSTP Status">
2267 <column name="rstp_status" key="rstp_port_id">
2268 The port ID used in spanning tree advertisements for this port, as 4
2269 hex digits. Configuring the port ID is described in the
2270 <code>rstp-port-num</code> and <code>rstp-port-priority</code> keys
2271 of the <code>other_config</code> section earlier.
2272 </column>
2273 <column name="rstp_status" key="rstp_port_role"
2274 type='{"type": "string", "enum": ["set",
2275 ["Root", "Designated", "Alternate", "Backup", "Disabled"]]}'>
2276 RSTP role of the port.
2277 </column>
2278 <column name="rstp_status" key="rstp_port_state"
2279 type='{"type": "string", "enum": ["set",
2280 ["Disabled", "Learning", "Forwarding", "Discarding"]]}'>
2281 RSTP state of the port.
2282 </column>
2283 <column name="rstp_status" key="rstp_designated_bridge_id">
2284 The port's RSTP designated bridge ID, in the same form as <ref
2285 column="rstp_status" key="rstp_bridge_id"/> in the <ref
2286 table="Bridge"/> table.
2287 </column>
2288 <column name="rstp_status" key="rstp_designated_port_id">
2289 The port's RSTP designated port ID, as 4 hex digits.
2290 </column>
2291 <column name="rstp_status" key="rstp_designated_path_cost"
2292 type='{"type": "integer"}'>
2293 The port's RSTP designated path cost. Lower is better.
2294 </column>
2295 </group>
2296
2297 <group title="RSTP Statistics">
2298 <column name="rstp_statistics" key="rstp_tx_count">
2299 Number of RSTP BPDUs transmitted through this port.
2300 </column>
2301 <column name="rstp_statistics" key="rstp_rx_count">
2302 Number of valid RSTP BPDUs received by this port.
2303 </column>
2304 <column name="rstp_statistics" key="rstp_error_count">
2305 Number of invalid RSTP BPDUs received by this port.
2306 </column>
2307 <column name="rstp_statistics" key="rstp_uptime">
2308 The duration covered by the other RSTP statistics, in seconds.
2309 </column>
2310 </group>
2311 </group>
2312
2313 <group title="Multicast Snooping">
2314 <column name="other_config" key="mcast-snooping-flood"
2315 type='{"type": "boolean"}'>
2316 <p>
2317 If set to <code>true</code>, multicast packets (except Reports) are
2318 unconditionally forwarded to the specific port.
2319 </p>
2320 </column>
2321 <column name="other_config" key="mcast-snooping-flood-reports"
2322 type='{"type": "boolean"}'>
2323 <p>
2324 If set to <code>true</code>, multicast Reports are unconditionally
2325 forwarded to the specific port.
2326 </p>
2327 </column>
2328 </group>
2329
2330 <group title="Other Features">
2331 <column name="qos">
2332 Quality of Service configuration for this port.
2333 </column>
2334
2335 <column name="mac">
2336 The MAC address to use for this port for the purpose of choosing the
2337 bridge's MAC address. This column does not necessarily reflect the
2338 port's actual MAC address, nor will setting it change the port's actual
2339 MAC address.
2340 </column>
2341
2342 <column name="fake_bridge">
2343 Does this port represent a sub-bridge for its tagged VLAN within the
2344 Bridge? See ovs-vsctl(8) for more information.
2345 </column>
2346
2347 <column name="protected" type='{"type": "boolean"}'>
2348 The protected ports feature allows certain ports to be designated as
2349 protected. Traffic between protected ports is blocked. Protected
2350 ports can send traffic to unprotected ports. Unprotected ports can
2351 send traffic to any port.
2352 Default is false.
2353 </column>
2354
2355 <column name="external_ids" key="fake-bridge-id-*">
2356 External IDs for a fake bridge (see the <ref column="fake_bridge"/>
2357 column) are defined by prefixing a <ref table="Bridge"/> <ref
2358 table="Bridge" column="external_ids"/> key with
2359 <code>fake-bridge-</code>,
2360 e.g. <code>fake-bridge-xs-network-uuids</code>.
2361 </column>
2362
2363 <column name="other_config" key="transient"
2364 type='{"type": "boolean"}'>
2365 <p>
2366 If set to <code>true</code>, the port will be removed when
2367 <code>ovs-ctl start --delete-transient-ports</code> is used.
2368 </p>
2369 </column>
2370 </group>
2371
2372 <column name="bond_active_slave">
2373 For a bonded port, record the mac address of the current active slave.
2374 </column>
2375
2376 <group title="Port Statistics">
2377 <p>
2378 Key-value pairs that report port statistics. The update period
2379 is controlled by <ref column="other_config"
2380 key="stats-update-interval"/> in the <code>Open_vSwitch</code> table.
2381 </p>
2382 <group title="Statistics: STP transmit and receive counters">
2383 <column name="statistics" key="stp_tx_count">
2384 Number of STP BPDUs sent on this port by the spanning
2385 tree library.
2386 </column>
2387 <column name="statistics" key="stp_rx_count">
2388 Number of STP BPDUs received on this port and accepted by the
2389 spanning tree library.
2390 </column>
2391 <column name="statistics" key="stp_error_count">
2392 Number of bad STP BPDUs received on this port. Bad BPDUs
2393 include runt packets and those with an unexpected protocol ID.
2394 </column>
2395 </group>
2396 </group>
2397
2398 <group title="Common Columns">
2399 The overall purpose of these columns is described under <code>Common
2400 Columns</code> at the beginning of this document.
2401
2402 <column name="other_config"/>
2403 <column name="external_ids"/>
2404 </group>
2405 </table>
2406
2407 <table name="Interface" title="One physical network device in a Port.">
2408 An interface within a <ref table="Port"/>.
2409
2410 <group title="Core Features">
2411 <column name="name">
2412 <p>
2413 Interface name. Should be alphanumeric. For non-bonded port, this
2414 should be the same as the port name. It must otherwise be unique
2415 among the names of ports, interfaces, and bridges on a host.
2416 </p>
2417
2418 <p>
2419 The maximum length of an interface name depends on the underlying
2420 datapath:
2421 </p>
2422
2423 <ul>
2424 <li>
2425 The names of interfaces implemented as Linux and BSD network
2426 devices, including interfaces with type <code>internal</code>,
2427 <code>tap</code>, or <code>system</code> plus the different types
2428 of tunnel ports, are limited to 15 bytes. Windows limits these
2429 names to 255 bytes.
2430 </li>
2431
2432 <li>
2433 The names of patch ports are not used in the underlying datapath,
2434 so operating system restrictions do not apply. Thus, they may have
2435 arbitrary length.
2436 </li>
2437 </ul>
2438
2439 <p>
2440 Regardless of other restrictions, OpenFlow only supports 15-byte
2441 names, which means that <code>ovs-ofctl</code> and OpenFlow
2442 controllers will show names truncated to 15 bytes.
2443 </p>
2444 </column>
2445
2446 <column name="ifindex">
2447 A positive interface index as defined for SNMP MIB-II in RFCs 1213 and
2448 2863, if the interface has one, otherwise 0. The ifindex is useful for
2449 seamless integration with protocols such as SNMP and sFlow.
2450 </column>
2451
2452 <column name="mac_in_use">
2453 The MAC address in use by this interface.
2454 </column>
2455
2456 <column name="mac">
2457 <p>Ethernet address to set for this interface. If unset then the
2458 default MAC address is used:</p>
2459 <ul>
2460 <li>For the local interface, the default is the lowest-numbered MAC
2461 address among the other bridge ports, either the value of the
2462 <ref table="Port" column="mac"/> in its <ref table="Port"/> record,
2463 if set, or its actual MAC (for bonded ports, the MAC of its slave
2464 whose name is first in alphabetical order). Internal ports and
2465 bridge ports that are used as port mirroring destinations (see the
2466 <ref table="Mirror"/> table) are ignored.</li>
2467 <li>For other internal interfaces, the default MAC is randomly
2468 generated.</li>
2469 <li>External interfaces typically have a MAC address associated with
2470 their hardware.</li>
2471 </ul>
2472 <p>Some interfaces may not have a software-controllable MAC
2473 address. This option only affects internal ports. For other type ports,
2474 you can change the MAC address outside Open vSwitch, using ip command.</p>
2475 </column>
2476
2477 <column name="error">
2478 If the configuration of the port failed, as indicated by -1 in <ref
2479 column="ofport"/>, Open vSwitch sets this column to an error
2480 description in human readable form. Otherwise, Open vSwitch clears
2481 this column.
2482 </column>
2483
2484 <group title="OpenFlow Port Number">
2485 <p>
2486 When a client adds a new interface, Open vSwitch chooses an OpenFlow
2487 port number for the new port. If the client that adds the port fills
2488 in <ref column="ofport_request"/>, then Open vSwitch tries to use its
2489 value as the OpenFlow port number. Otherwise, or if the requested
2490 port number is already in use or cannot be used for another reason,
2491 Open vSwitch automatically assigns a free port number. Regardless of
2492 how the port number was obtained, Open vSwitch then reports in <ref
2493 column="ofport"/> the port number actually assigned.
2494 </p>
2495
2496 <p>
2497 Open vSwitch limits the port numbers that it automatically assigns to
2498 the range 1 through 32,767, inclusive. Controllers therefore have
2499 free use of ports 32,768 and up.
2500 </p>
2501
2502 <column name="ofport">
2503 <p>
2504 OpenFlow port number for this interface. Open vSwitch sets this
2505 column's value, so other clients should treat it as read-only.
2506 </p>
2507 <p>
2508 The OpenFlow ``local'' port (<code>OFPP_LOCAL</code>) is 65,534.
2509 The other valid port numbers are in the range 1 to 65,279,
2510 inclusive. Value -1 indicates an error adding the interface.
2511 </p>
2512 </column>
2513
2514 <column name="ofport_request"
2515 type='{"type": "integer", "minInteger": 1, "maxInteger": 65279}'>
2516 <p>
2517 Requested OpenFlow port number for this interface.
2518 </p>
2519
2520 <p>
2521 A client should ideally set this column's value in the same
2522 database transaction that it uses to create the interface. Open
2523 vSwitch version 2.1 and later will honor a later request for a
2524 specific port number, althuogh it might confuse some controllers:
2525 OpenFlow does not have a way to announce a port number change, so
2526 Open vSwitch represents it over OpenFlow as a port deletion
2527 followed immediately by a port addition.
2528 </p>
2529
2530 <p>
2531 If <ref column="ofport_request"/> is set or changed to some other
2532 port's automatically assigned port number, Open vSwitch chooses a
2533 new port number for the latter port.
2534 </p>
2535 </column>
2536 </group>
2537 </group>
2538
2539 <group title="System-Specific Details">
2540 <column name="type">
2541 <p>
2542 The interface type. The types supported by a particular instance of
2543 Open vSwitch are listed in the <ref table="Open_vSwitch"
2544 column="iface_types"/> column in the <ref table="Open_vSwitch"/>
2545 table. The following types are defined:
2546 </p>
2547
2548 <dl>
2549 <dt><code>system</code></dt>
2550 <dd>An ordinary network device, e.g. <code>eth0</code> on Linux.
2551 Sometimes referred to as ``external interfaces'' since they are
2552 generally connected to hardware external to that on which the Open
2553 vSwitch is running. The empty string is a synonym for
2554 <code>system</code>.</dd>
2555
2556 <dt><code>internal</code></dt>
2557 <dd>A simulated network device that sends and receives traffic. An
2558 internal interface whose <ref column="name"/> is the same as its
2559 bridge's <ref table="Open_vSwitch" column="name"/> is called the
2560 ``local interface.'' It does not make sense to bond an internal
2561 interface, so the terms ``port'' and ``interface'' are often used
2562 imprecisely for internal interfaces.</dd>
2563
2564 <dt><code>tap</code></dt>
2565 <dd>
2566 <p>
2567 A TUN/TAP device managed by Open vSwitch.
2568 </p>
2569 <p>
2570 Open vSwitch checks the interface state before send packets
2571 to the device. When it is <code>down</code>, the packets are
2572 dropped and the tx_dropped statistic is updated accordingly.
2573 Older versions of Open vSwitch did not check the interface state
2574 and then the tx_packets was incremented along with tx_dropped.
2575 </p>
2576 </dd>
2577
2578 <dt><code>geneve</code></dt>
2579 <dd>
2580 An Ethernet over Geneve (<code>http://tools.ietf.org/html/draft-ietf-nvo3-geneve</code>)
2581 IPv4/IPv6 tunnel.
2582
2583 A description of how to match and set Geneve options can be found
2584 in the <code>ovs-ofctl</code> manual page.
2585 </dd>
2586
2587 <dt><code>gre</code></dt>
2588 <dd>
2589 Generic Routing Encapsulation (GRE) over IPv4 tunnel,
2590 configurable to encapsulate layer 2 or layer 3 traffic.
2591 </dd>
2592
2593 <dt><code>ip6gre</code></dt>
2594 <dd>
2595 Generic Routing Encapsulation (GRE) over IPv6 tunnel,
2596 encapsulate layer 2 traffic.
2597 </dd>
2598
2599 <dt><code>vxlan</code></dt>
2600 <dd>
2601 <p>
2602 An Ethernet tunnel over the UDP-based VXLAN protocol described in
2603 RFC 7348.
2604 </p>
2605 <p>
2606 Open vSwitch uses IANA-assigned UDP destination port 4789. The
2607 source port used for VXLAN traffic varies on a per-flow basis
2608 and is in the ephemeral port range.
2609 </p>
2610 </dd>
2611
2612 <dt><code>lisp</code></dt>
2613 <dd>
2614 <p>
2615 A layer 3 tunnel over the experimental, UDP-based Locator/ID
2616 Separation Protocol (RFC 6830).
2617 </p>
2618 <p>
2619 Only IPv4 and IPv6 packets are supported by the protocol, and
2620 they are sent and received without an Ethernet header. Traffic
2621 to/from LISP ports is expected to be configured explicitly, and
2622 the ports are not intended to participate in learning based
2623 switching. As such, they are always excluded from packet
2624 flooding.
2625 </p>
2626 </dd>
2627
2628 <dt><code>stt</code></dt>
2629 <dd>
2630 The Stateless TCP Tunnel (STT) is particularly useful when tunnel
2631 endpoints are in end-systems, as it utilizes the capabilities of
2632 standard network interface cards to improve performance. STT utilizes
2633 a TCP-like header inside the IP header. It is stateless, i.e., there is
2634 no TCP connection state of any kind associated with the tunnel. The
2635 TCP-like header is used to leverage the capabilities of existing
2636 network interface cards, but should not be interpreted as implying
2637 any sort of connection state between endpoints.
2638 Since the STT protocol does not engage in the usual TCP 3-way handshake,
2639 so it will have difficulty traversing stateful firewalls.
2640 The protocol is documented at
2641 https://tools.ietf.org/html/draft-davie-stt
2642
2643 All traffic uses a default destination port of 7471.
2644 </dd>
2645
2646 <dt><code>patch</code></dt>
2647 <dd>
2648 A pair of virtual devices that act as a patch cable.
2649 </dd>
2650
2651 <dt><code>gtpu</code></dt>
2652 <dd>
2653 <p>
2654 GPRS Tunneling Protocol (GTP) is a group of IP-based communications
2655 protocols used to carry general packet radio service (GPRS) within
2656 GSM, UMTS and LTE networks. GTP-U is used for carrying user data
2657 within the GPRS core network and between the radio access network
2658 and the core network. The user data transported can be packets in
2659 any of IPv4, IPv6, or PPP formats.
2660 </p>
2661
2662 <p>
2663 The protocol is documented at
2664 http://www.3gpp.org/DynaReport/29281.htm
2665 </p>
2666
2667 <p>
2668 Open vSwitch uses UDP destination port 2152. The source port used
2669 for GTP traffic varies on a per-flow basis and is in the ephemeral
2670 port range.
2671 </p>
2672 </dd>
2673
2674 </dl>
2675 </column>
2676 </group>
2677
2678 <group title="Tunnel Options">
2679 <p>
2680 These options apply to interfaces with <ref column="type"/> of
2681 <code>geneve</code>, <code>gre</code>, <code>ip6gre</code>,
2682 <code>vxlan</code>, <code>lisp</code> and <code>stt</code>.
2683 </p>
2684
2685 <p>
2686 Each tunnel must be uniquely identified by the combination of <ref
2687 column="type"/>, <ref column="options" key="remote_ip"/>, <ref
2688 column="options" key="local_ip"/>, and <ref column="options"
2689 key="in_key"/>. If two ports are defined that are the same except one
2690 has an optional identifier and the other does not, the more specific
2691 one is matched first. <ref column="options" key="in_key"/> is
2692 considered more specific than <ref column="options" key="local_ip"/> if
2693 a port defines one and another port defines the other.
2694 </p>
2695
2696 <column name="options" key="remote_ip">
2697 <p>Required. The remote tunnel endpoint, one of:</p>
2698
2699 <ul>
2700 <li>
2701 An IPv4 or IPv6 address (not a DNS name), e.g. <code>192.168.0.123</code>.
2702 Only unicast endpoints are supported.
2703 </li>
2704 <li>
2705 The word <code>flow</code>. The tunnel accepts packets from any
2706 remote tunnel endpoint. To process only packets from a specific
2707 remote tunnel endpoint, the flow entries may match on the
2708 <code>tun_src</code> or <code>tun_ipv6_src</code>field. When
2709 sending packets to a <code>remote_ip=flow</code> tunnel, the flow
2710 actions must explicitly set the <code>tun_dst</code> or
2711 <code>tun_ipv6_dst</code> field to the IP address of the desired
2712 remote tunnel endpoint, e.g. with a <code>set_field</code> action.
2713 </li>
2714 </ul>
2715
2716 <p>
2717 The remote tunnel endpoint for any packet received from a tunnel
2718 is available in the <code>tun_src</code> field for matching in the
2719 flow table.
2720 </p>
2721 </column>
2722
2723 <column name="options" key="local_ip">
2724 <p>
2725 Optional. The tunnel destination IP that received packets must match.
2726 Default is to match all addresses. If specified, may be one of:
2727 </p>
2728
2729 <ul>
2730 <li>
2731 An IPv4/IPv6 address (not a DNS name), e.g. <code>192.168.12.3</code>.
2732 </li>
2733 <li>
2734 The word <code>flow</code>. The tunnel accepts packets sent to any
2735 of the local IP addresses of the system running OVS. To process
2736 only packets sent to a specific IP address, the flow entries may
2737 match on the <code>tun_dst</code> or <code>tun_ipv6_dst</code> field.
2738 When sending packets to a <code>local_ip=flow</code> tunnel, the flow
2739 actions may explicitly set the <code>tun_src</code> or <code>tun_ipv6_src</code>
2740 field to the desired IP address, e.g. with a <code>set_field</code> action.
2741 However, while routing the tunneled packet out, the local system may
2742 override the specified address with the local IP address configured for the
2743 outgoing system interface.
2744
2745 <p>
2746 This option is valid only for tunnels also configured with the
2747 <code>remote_ip=flow</code> option.
2748 </p>
2749 </li>
2750 </ul>
2751
2752 <p>
2753 The tunnel destination IP address for any packet received from a
2754 tunnel is available in the <code>tun_dst</code> or <code>tun_ipv6_dst</code>
2755 field for matching in the flow table.
2756 </p>
2757 </column>
2758
2759 <column name="options" key="in_key">
2760 <p>Optional. The key that received packets must contain, one of:</p>
2761
2762 <ul>
2763 <li>
2764 <code>0</code>. The tunnel receives packets with no key or with a
2765 key of 0. This is equivalent to specifying no <ref column="options"
2766 key="in_key"/> at all.
2767 </li>
2768 <li>
2769 A positive 24-bit (for Geneve, VXLAN, and LISP), 32-bit (for GRE)
2770 or 64-bit (for STT) number. The tunnel receives only
2771 packets with the specified key.
2772 </li>
2773 <li>
2774 The word <code>flow</code>. The tunnel accepts packets with any
2775 key. The key will be placed in the <code>tun_id</code> field for
2776 matching in the flow table. The <code>ovs-fields</code>(7) manual
2777 page contains additional information about matching fields in
2778 OpenFlow flows.
2779 </li>
2780 </ul>
2781
2782 <p>
2783 </p>
2784 </column>
2785
2786 <column name="options" key="out_key">
2787 <p>Optional. The key to be set on outgoing packets, one of:</p>
2788
2789 <ul>
2790 <li>
2791 <code>0</code>. Packets sent through the tunnel will have no key.
2792 This is equivalent to specifying no <ref column="options"
2793 key="out_key"/> at all.
2794 </li>
2795 <li>
2796 A positive 24-bit (for Geneve, VXLAN and LISP), 32-bit (for GRE) or
2797 64-bit (for STT) number. Packets sent through the tunnel
2798 will have the specified key.
2799 </li>
2800 <li>
2801 The word <code>flow</code>. Packets sent through the tunnel will
2802 have the key set using the <code>set_tunnel</code> Nicira OpenFlow
2803 vendor extension (0 is used in the absence of an action). The
2804 <code>ovs-fields</code>(7) manual page contains additional
2805 information about the Nicira OpenFlow vendor extensions.
2806 </li>
2807 </ul>
2808 </column>
2809
2810 <column name="options" key="dst_port">
2811 Optional. The tunnel transport layer destination port, for UDP and TCP
2812 based tunnel protocols (Geneve, VXLAN, LISP, and STT).
2813 </column>
2814
2815 <column name="options" key="key">
2816 Optional. Shorthand to set <code>in_key</code> and
2817 <code>out_key</code> at the same time.
2818 </column>
2819
2820 <column name="options" key="tos">
2821 Optional. The value of the ToS bits to be set on the encapsulating
2822 packet. ToS is interpreted as DSCP and ECN bits, ECN part must be
2823 zero. It may also be the word <code>inherit</code>, in which case
2824 the ToS will be copied from the inner packet if it is IPv4 or IPv6
2825 (otherwise it will be 0). The ECN fields are always inherited.
2826 Default is 0.
2827 </column>
2828
2829 <column name="options" key="ttl">
2830 Optional. The TTL to be set on the encapsulating packet. It may also
2831 be the word <code>inherit</code>, in which case the TTL will be copied
2832 from the inner packet if it is IPv4 or IPv6 (otherwise it will be the
2833 system default, typically 64). Default is the system default TTL.
2834 </column>
2835
2836 <column name="options" key="df_default"
2837 type='{"type": "boolean"}'>
2838 Optional. If enabled, the Don't Fragment bit will be set on tunnel
2839 outer headers to allow path MTU discovery. Default is enabled; set
2840 to <code>false</code> to disable.
2841 </column>
2842
2843 <column name="options" key="egress_pkt_mark">
2844 Optional. The pkt_mark to be set on the encapsulating packet. This
2845 option sets packet mark for the tunnel endpoint for all tunnel packets
2846 including tunnel monitoring.
2847 </column>
2848
2849 <group title="Tunnel Options: lisp only">
2850 <column name="options" key="packet_type"
2851 type='{"type": "string", "enum": ["set",
2852 ["legacy_l3", "ptap"]]}'>
2853 <p>
2854 A LISP tunnel sends and receives only IPv4 and IPv6 packets. This
2855 option controls what how the tunnel represents the packets that it
2856 sends and receives:
2857 </p>
2858
2859 <ul>
2860 <li>
2861 By default, or if this option is <code>legacy_l3</code>, the
2862 tunnel represents packets as Ethernet frames for compatibility
2863 with legacy OpenFlow controllers that expect this behavior.
2864 </li>
2865 <li>
2866 If this option is <code>ptap</code>, the tunnel represents
2867 packets using the <code>packet_type</code> mechanism introduced
2868 in OpenFlow 1.5.
2869 </li>
2870 </ul>
2871 </column>
2872 </group>
2873
2874 <group title="Tunnel Options: vxlan only">
2875
2876 <column name="options" key="exts">
2877 <p>Optional. Comma separated list of optional VXLAN extensions to
2878 enable. The following extensions are supported:</p>
2879
2880 <ul>
2881 <li>
2882 <code>gbp</code>: VXLAN-GBP allows to transport the group policy
2883 context of a packet across the VXLAN tunnel to other network
2884 peers. See the description of <code>tun_gbp_id</code> and
2885 <code>tun_gbp_flags</code> in <code>ovs-fields</code>(7) for
2886 additional information.
2887 (<code>https://tools.ietf.org/html/draft-smith-vxlan-group-policy</code>)
2888 </li>
2889 <li>
2890 <code>gpe</code>: Support for Generic Protocol Encapsulation in
2891 accordance with IETF draft
2892 <code>https://tools.ietf.org/html/draft-ietf-nvo3-vxlan-gpe</code>.
2893 Without this option, a VXLAN packet always encapsulates an
2894 Ethernet frame. With this option, an VXLAN packet may also
2895 encapsulate an IPv4, IPv6, NSH, or MPLS packet.
2896 </li>
2897 </ul>
2898 </column>
2899
2900 <column name="options" key="packet_type"
2901 type='{"type": "string", "enum": ["set",
2902 ["legacy_l2", "legacy_l3", "ptap"]]}'>
2903 <p>
2904 This option controls what types of packets the tunnel sends and
2905 receives and how it represents them:
2906 </p>
2907
2908 <ul>
2909 <li>
2910 By default, or if this option is <code>legacy_l2</code>, the
2911 tunnel sends and receives only Ethernet frames.
2912 </li>
2913 <li>
2914 If this option is <code>legacy_l3</code>, the tunnel sends and
2915 receives only non-Ethernet (L3) packet, but the packets are
2916 represented as Ethernet frames for compatibility with legacy
2917 OpenFlow controllers that expect this behavior. This requires
2918 enabling <code>gpe</code> in <ref column="options" key="exts"/>.
2919 </li>
2920 <li>
2921 If this option is <code>ptap</code>, Open vSwitch represents
2922 packets in the tunnel using the <code>packet_type</code>
2923 mechanism introduced in OpenFlow 1.5. This mechanism supports
2924 any kind of packet, but actually sending and receiving
2925 non-Ethernet packets requires additionally enabling
2926 <code>gpe</code> in <ref column="options" key="exts"/>.
2927 </li>
2928 </ul>
2929 </column>
2930 </group>
2931
2932 <group title="Tunnel Options: gre only">
2933 <p>
2934 <code>gre</code> interfaces support these options.
2935 </p>
2936
2937 <column name="options" key="packet_type"
2938 type='{"type": "string", "enum": ["set",
2939 ["legacy_l2", "legacy_l3", "ptap"]]}'>
2940 <p>
2941 This option controls what types of packets the tunnel sends and
2942 receives and how it represents them:
2943 </p>
2944
2945 <ul>
2946 <li>
2947 By default, or if this option is <code>legacy_l2</code>, the
2948 tunnel sends and receives only Ethernet frames.
2949 </li>
2950 <li>
2951 If this option is <code>legacy_l3</code>, the tunnel sends and
2952 receives only non-Ethernet (L3) packet, but the packets are
2953 represented as Ethernet frames for compatibility with legacy
2954 OpenFlow controllers that expect this behavior.
2955 </li>
2956 <li>
2957 The <code>legacy_l3</code> option is only available via the
2958 user space datapath. The OVS kernel datapath does not support
2959 devices of type ARPHRD_IPGRE which is the requirement for
2960 <code>legacy_l3</code> type packets.
2961 </li>
2962 <li>
2963 If this option is <code>ptap</code>, the tunnel sends and
2964 receives any kind of packet. Open vSwitch represents packets in
2965 the tunnel using the <code>packet_type</code> mechanism
2966 introduced in OpenFlow 1.5.
2967 </li>
2968 </ul>
2969 </column>
2970 <column name="options" key="seq" type='{"type": "boolean"}'>
2971 <p>
2972 Optional. A 4-byte sequence number field for GRE tunnel only.
2973 Default is disabled, set to <code>true</code> to enable.
2974 Sequence number is incremented by one on each outgoing packet.
2975 </p>
2976 </column>
2977 </group>
2978
2979 <group title="Tunnel Options: gre, ip6gre, geneve, and vxlan">
2980 <p>
2981 <code>gre</code>, <code>ip6gre</code>, <code>geneve</code>,
2982 and <code>vxlan</code> interfaces support these options.
2983 </p>
2984
2985 <column name="options" key="csum" type='{"type": "boolean"}'>
2986 <p>
2987 Optional. Compute encapsulation header (either GRE or UDP)
2988 checksums on outgoing packets. Default is disabled, set to
2989 <code>true</code> to enable. Checksums present on incoming
2990 packets will be validated regardless of this setting.
2991 </p>
2992
2993 <p>
2994 When using the upstream Linux kernel module, computation of
2995 checksums for <code>geneve</code> and <code>vxlan</code> requires
2996 Linux kernel version 4.0 or higher. <code>gre</code> and
2997 <code>ip6gre</code> support checksums for all versions of
2998 Open vSwitch that support GRE.
2999 The out of tree kernel module distributed as part of OVS
3000 can compute all tunnel checksums on any kernel version that it
3001 is compatible with.
3002 </p>
3003
3004 </column>
3005 </group>
3006
3007 <group title="Tunnel Options: IPsec">
3008 <p>
3009 Setting any of these options enables IPsec support for a given
3010 tunnel. <code>gre</code>, <code>ip6gre</code>,
3011 <code>geneve</code>, <code>vxlan</code> and <code>stt</code>
3012 interfaces support these options. See the <code>IPsec</code>
3013 section in the <ref table="Open_vSwitch"/> table for a description
3014 of each mode.
3015 </p>
3016 <column name="options" key="psk" type='{"type": "string"}'>
3017 <p>
3018 In PSK mode only, the preshared secret to negotiate tunnel. This
3019 value must match on both tunnel ends.
3020 </p>
3021 </column>
3022 <column name="options" key="remote_cert" type='{"type": "string"}'>
3023 <p>
3024 In self-signed certificate mode only, name of a PEM file
3025 containing a certificate of the remote switch. The certificate
3026 must be x.509 version 3 and with the string in common name (CN)
3027 also set in the subject alternative name (SAN).
3028 </p>
3029 </column>
3030 <column name="options" key="remote_name" type='{"type": "string"}'>
3031 <p>
3032 In CA-signed certificate mode only, common name (CN) of the remote
3033 certificate.
3034 </p>
3035 </column>
3036 </group>
3037 </group>
3038 <group title="Tunnel Options: erspan only">
3039 <p>
3040 Only <code>erspan</code> interfaces support these options.
3041 </p>
3042 <column name="options" key="erspan_idx">
3043 <p>
3044 20 bit index/port number associated with the ERSPAN traffic's
3045 source port and direction (ingress/egress). This field is
3046 platform dependent.
3047 </p>
3048 </column>
3049
3050 <column name="options" key="erspan_ver">
3051 <p>
3052 ERSPAN version: 1 for version 1 (type II)
3053 or 2 for version 2 (type III).
3054 </p>
3055 </column>
3056
3057 <column name="options" key="erspan_dir">
3058 <p>
3059 Specifies the ERSPAN v2 mirrored traffic's direction.
3060 1 for egress traffic, and 0 for ingress traffic.
3061 </p>
3062 </column>
3063
3064 <column name="options" key="erspan_hwid">
3065 <p>
3066 ERSPAN hardware ID is a 6-bit unique identifier of an
3067 ERSPAN v2 engine within a system.
3068 </p>
3069 </column>
3070 </group>
3071
3072 <group title="Patch Options">
3073 <p>
3074 These options apply only to <dfn>patch ports</dfn>, that is, interfaces
3075 whose <ref column="type"/> column is <code>patch</code>. Patch ports
3076 are mainly a way to connect otherwise independent bridges to one
3077 another, similar to how one might plug an Ethernet cable (a ``patch
3078 cable'') into two physical switches to connect those switches. The
3079 effect of plugging a patch port into two switches is conceptually
3080 similar to that of plugging the two ends of a Linux <code>veth</code>
3081 device into those switches, but the implementation of patch ports makes
3082 them much more efficient.
3083 </p>
3084
3085 <p>
3086 Patch ports may connect two different bridges (the usual case) or the
3087 same bridge. In the latter case, take special care to avoid loops,
3088 e.g. by programming appropriate flows with OpenFlow. Patch ports do
3089 not work if its ends are attached to bridges on different datapaths,
3090 e.g. to connect bridges in <code>system</code> and <code>netdev</code>
3091 datapaths.
3092 </p>
3093
3094 <p>
3095 The following command creates and connects patch ports <code>p0</code>
3096 and <code>p1</code> and adds them to bridges <code>br0</code> and
3097 <code>br1</code>, respectively:
3098 </p>
3099
3100 <pre>
3101 ovs-vsctl add-port br0 p0 -- set Interface p0 type=patch options:peer=p1 \
3102 -- add-port br1 p1 -- set Interface p1 type=patch options:peer=p0
3103 </pre>
3104
3105 <column name="options" key="peer">
3106 The <ref column="name"/> of the <ref table="Interface"/> for the other
3107 side of the patch. The named <ref table="Interface"/>'s own
3108 <code>peer</code> option must specify this <ref table="Interface"/>'s
3109 name. That is, the two patch interfaces must have reversed <ref
3110 column="name"/> and <code>peer</code> values.
3111 </column>
3112 </group>
3113
3114 <group title="PMD (Poll Mode Driver) Options">
3115 <p>
3116 Only PMD netdevs support these options.
3117 </p>
3118
3119 <column name="options" key="n_rxq"
3120 type='{"type": "integer", "minInteger": 1}'>
3121 <p>
3122 Specifies the maximum number of rx queues to be created for PMD
3123 netdev. If not specified or specified to 0, one rx queue will
3124 be created by default.
3125 Not supported by DPDK vHost interfaces.
3126 </p>
3127 </column>
3128
3129 <column name="options" key="dpdk-devargs"
3130 type='{"type": "string"}'>
3131 <p>
3132 Specifies the PCI address associated with the port for physical
3133 devices, or the virtual driver to be used for the port when a virtual
3134 PMD is intended to be used. For the latter, the argument string
3135 typically takes the form of
3136 <code>eth_<var>driver_name</var><var>x</var></code>, where
3137 <var>driver_name</var> is a valid virtual DPDK PMD driver name and
3138 <var>x</var> is a unique identifier of your choice for the given
3139 port. Only supported by the dpdk port type.
3140 </p>
3141 </column>
3142
3143 <column name="other_config" key="pmd-rxq-affinity">
3144 <p>Specifies mapping of RX queues of this interface to CPU cores.</p>
3145 <p>Value should be set in the following form:</p>
3146 <p>
3147 <code>other_config:pmd-rxq-affinity=&lt;rxq-affinity-list&gt;</code>
3148 </p>
3149 <p>where</p>
3150 <p>
3151 <ul>
3152 <li>
3153 &lt;rxq-affinity-list&gt; ::= NULL | &lt;non-empty-list&gt;
3154 </li>
3155 <li>
3156 &lt;non-empty-list&gt; ::= &lt;affinity-pair&gt; |
3157 &lt;affinity-pair&gt; , &lt;non-empty-list&gt;
3158 </li>
3159 <li>
3160 &lt;affinity-pair&gt; ::= &lt;queue-id&gt; : &lt;core-id&gt;
3161 </li>
3162 </ul>
3163 </p>
3164 </column>
3165
3166 <column name="options" key="xdp-mode"
3167 type='{"type": "string",
3168 "enum": ["set", ["best-effort", "native-with-zerocopy",
3169 "native", "generic"]]}'>
3170 <p>
3171 Specifies the operational mode of the XDP program.
3172 <p>
3173 In <code>native-with-zerocopy</code> mode the XDP program is loaded
3174 into the device driver with zero-copy RX and TX enabled. This mode
3175 requires device driver support and has the best performance because
3176 there should be no copying of packets.
3177 </p>
3178 <p>
3179 <code>native</code> is the same as
3180 <code>native-with-zerocopy</code>, but without zero-copy
3181 capability. This requires at least one copy between kernel and the
3182 userspace. This mode also requires support from device driver.
3183 </p>
3184 <p>
3185 In <code>generic</code> case the XDP program in kernel works after
3186 skb allocation on early stages of packet processing inside the
3187 network stack. This mode doesn't require driver support, but has
3188 much lower performance.
3189 </p>
3190 <p>
3191 <code>best-effort</code> tries to detect and choose the best
3192 (fastest) from the available modes for current interface.
3193 </p>
3194 <p>
3195 Note that this option is specific to netdev-afxdp.
3196 Defaults to <code>best-effort</code> mode.
3197 </p>
3198 </p>
3199 </column>
3200
3201 <column name="options" key="use-need-wakeup"
3202 type='{"type": "boolean"}'>
3203 <p>
3204 Specifies whether to use need_wakeup feature in afxdp netdev.
3205 If enabled, OVS explicitly wakes up the kernel RX, using poll()
3206 syscall and wakes up TX, using sendto() syscall. For physical
3207 devices, this feature improves the performance by avoiding
3208 unnecessary sendto syscalls.
3209 Defaults to true if supported by libbpf.
3210 </p>
3211 </column>
3212
3213 <column name="options" key="vhost-server-path"
3214 type='{"type": "string"}'>
3215 <p>
3216 The value specifies the path to the socket associated with a vHost
3217 User client mode device that has been or will be created by QEMU.
3218 Only supported by dpdkvhostuserclient interfaces.
3219 </p>
3220 </column>
3221
3222 <column name="options" key="dq-zero-copy"
3223 type='{"type": "boolean"}'>
3224 <p>
3225 The value specifies whether or not to enable dequeue zero copy on
3226 the given interface.
3227 Must be set before vhost-server-path is specified.
3228 Only supported by dpdkvhostuserclient interfaces.
3229 The feature is considered experimental.
3230 </p>
3231 </column>
3232
3233 <column name="options" key="tx-retries-max"
3234 type='{"type": "integer", "minInteger": 0, "maxInteger": 32}'>
3235 <p>
3236 The value specifies the maximum amount of vhost tx retries that can
3237 be made while trying to send a batch of packets to an interface.
3238 Only supported by dpdkvhostuserclient interfaces.
3239 </p>
3240 <p>
3241 Default value is 8.
3242 </p>
3243 </column>
3244
3245 <column name="options" key="n_rxq_desc"
3246 type='{"type": "integer", "minInteger": 1, "maxInteger": 4096}'>
3247 <p>
3248 Specifies the rx queue size (number rx descriptors) for dpdk ports.
3249 The value must be a power of 2, less than 4096 and supported
3250 by the hardware of the device being configured.
3251 If not specified or an incorrect value is specified, 2048 rx
3252 descriptors will be used by default.
3253 </p>
3254 </column>
3255
3256 <column name="options" key="n_txq_desc"
3257 type='{"type": "integer", "minInteger": 1, "maxInteger": 4096}'>
3258 <p>
3259 Specifies the tx queue size (number tx descriptors) for dpdk ports.
3260 The value must be a power of 2, less than 4096 and supported
3261 by the hardware of the device being configured.
3262 If not specified or an incorrect value is specified, 2048 tx
3263 descriptors will be used by default.
3264 </p>
3265 </column>
3266 </group>
3267
3268 <group title="EMC (Exact Match Cache) Configuration">
3269 <p>
3270 These settings controls behaviour of EMC lookups/insertions for packets
3271 received from the interface.
3272 </p>
3273
3274 <column name="other_config" key="emc-enable" type='{"type": "boolean"}'>
3275 <p>
3276 Specifies if Exact Match Cache (EMC) should be used while processing
3277 packets received from this interface.
3278 If true, <ref table="Open_vSwitch" column="other_config"
3279 key="emc-insert-inv-prob"/> will have effect on this interface.
3280 </p>
3281 <p>
3282 Defaults to true.
3283 </p>
3284 </column>
3285 </group>
3286
3287 <group title="MTU">
3288 <p>
3289 The MTU (maximum transmission unit) is the largest amount of data
3290 that can fit into a single Ethernet frame. The standard Ethernet
3291 MTU is 1500 bytes. Some physical media and many kinds of virtual
3292 interfaces can be configured with higher MTUs.
3293 </p>
3294
3295 <p>
3296 A client may change an interface MTU by filling in
3297 <ref column="mtu_request"/>. Open vSwitch then reports in
3298 <ref column="mtu"/> the currently configured value.
3299 </p>
3300
3301 <column name="mtu">
3302 <p>
3303 The currently configured MTU for the interface.
3304 </p>
3305
3306 <p>
3307 This column will be empty for an interface that does not
3308 have an MTU as, for example, some kinds of tunnels do not.
3309 </p>
3310
3311 <p>
3312 Open vSwitch sets this column's value, so other clients should treat
3313 it as read-only.
3314 </p>
3315 </column>
3316
3317 <column name="mtu_request"
3318 type='{"type": "integer", "minInteger": 1}'>
3319 <p>
3320 Requested MTU (Maximum Transmission Unit) for the interface. A client
3321 can fill this column to change the MTU of an interface.
3322 </p>
3323
3324 <p>
3325 RFC 791 requires every internet module to be able to forward a
3326 datagram of 68 octets without further fragmentation. The maximum
3327 size of an IP packet is 65535 bytes.
3328 </p>
3329
3330 <p>
3331 If this is not set and if the interface has <code>internal</code>
3332 type, Open vSwitch will change the MTU to match the minimum of the
3333 other interfaces in the bridge.
3334 </p>
3335 </column>
3336
3337 </group>
3338
3339 <group title="Interface Status">
3340 <p>
3341 Status information about interfaces attached to bridges, updated every
3342 5 seconds. Not all interfaces have all of these properties; virtual
3343 interfaces don't have a link speed, for example. Non-applicable
3344 columns will have empty values.
3345 </p>
3346 <column name="admin_state">
3347 <p>
3348 The administrative state of the physical network link.
3349 </p>
3350 </column>
3351
3352 <column name="link_state">
3353 <p>
3354 The observed state of the physical network link. This is ordinarily
3355 the link's carrier status. If the interface's <ref table="Port"/> is
3356 a bond configured for miimon monitoring, it is instead the network
3357 link's miimon status.
3358 </p>
3359 </column>
3360
3361 <column name="link_resets">
3362 <p>
3363 The number of times Open vSwitch has observed the
3364 <ref column="link_state"/> of this <ref table="Interface"/> change.
3365 </p>
3366 </column>
3367
3368 <column name="link_speed">
3369 <p>
3370 The negotiated speed of the physical network link.
3371 Valid values are positive integers greater than 0.
3372 </p>
3373 </column>
3374
3375 <column name="duplex">
3376 <p>
3377 The duplex mode of the physical network link.
3378 </p>
3379 </column>
3380
3381 <column name="lacp_current">
3382 Boolean value indicating LACP status for this interface. If true, this
3383 interface has current LACP information about its LACP partner. This
3384 information may be used to monitor the health of interfaces in a LACP
3385 enabled port. This column will be empty if LACP is not enabled.
3386 </column>
3387
3388 <column name="status">
3389 Key-value pairs that report port status. Supported status values are
3390 <ref column="type"/>-dependent; some interfaces may not have a valid
3391 <ref column="status" key="driver_name"/>, for example.
3392 </column>
3393
3394 <column name="status" key="driver_name">
3395 The name of the device driver controlling the network adapter.
3396 </column>
3397
3398 <column name="status" key="driver_version">
3399 The version string of the device driver controlling the network
3400 adapter.
3401 </column>
3402
3403 <column name="status" key="firmware_version">
3404 The version string of the network adapter's firmware, if available.
3405 </column>
3406
3407 <column name="status" key="source_ip">
3408 The source IP address used for an IPv4/IPv6 tunnel end-point, such as
3409 <code>gre</code>.
3410 </column>
3411
3412 <column name="status" key="tunnel_egress_iface">
3413 Egress interface for tunnels. Currently only relevant for tunnels
3414 on Linux systems, this column will show the name of the interface
3415 which is responsible for routing traffic destined for the configured
3416 <ref column="options" key="remote_ip"/>. This could be an internal
3417 interface such as a bridge port.
3418 </column>
3419
3420 <column name="status" key="tunnel_egress_iface_carrier"
3421 type='{"type": "string", "enum": ["set", ["down", "up"]]}'>
3422 Whether carrier is detected on <ref column="status"
3423 key="tunnel_egress_iface"/>.
3424 </column>
3425
3426 <group title="dpdk">
3427 <p>
3428 DPDK specific interface status options.
3429 </p>
3430
3431 <column name="status" key="port_no">
3432 DPDK port ID.
3433 </column>
3434
3435 <column name="status" key="numa_id">
3436 NUMA socket ID to which an Ethernet device is connected.
3437 </column>
3438
3439 <column name="status" key="min_rx_bufsize">
3440 Minimum size of RX buffer.
3441 </column>
3442
3443 <column name="status" key="max_rx_pktlen">
3444 Maximum configurable length of RX pkt.
3445 </column>
3446
3447 <column name="status" key="max_rx_queues">
3448 Maximum number of RX queues.
3449 </column>
3450
3451 <column name="status" key="max_tx_queues">
3452 Maximum number of TX queues.
3453 </column>
3454
3455 <column name="status" key="max_mac_addrs">
3456 Maximum number of MAC addresses.
3457 </column>
3458
3459 <column name="status" key="max_hash_mac_addrs">
3460 Maximum number of hash MAC addresses for MTA and UTA.
3461 </column>
3462
3463 <column name="status" key="max_vfs">
3464 Maximum number of hash MAC addresses for MTA and UTA.
3465 Maximum number of VFs.
3466 </column>
3467
3468 <column name="status" key="max_vmdq_pools">
3469 Maximum number of VMDq pools.
3470 </column>
3471
3472 <column name="status" key="if_type">
3473 Interface type ID according to IANA ifTYPE MIB definitions.
3474 </column>
3475
3476 <column name="status" key="if_descr">
3477 Interface description string.
3478 </column>
3479
3480 <column name="status" key="pci-vendor_id">
3481 Vendor ID of PCI device.
3482 </column>
3483
3484 <column name="status" key="pci-device_id">
3485 Device ID of PCI device.
3486 </column>
3487
3488 </group>
3489 </group>
3490
3491 <group title="Statistics">
3492 <p>
3493 Key-value pairs that report interface statistics. The current
3494 implementation updates these counters periodically. The update period
3495 is controlled by <ref column="other_config"
3496 key="stats-update-interval"/> in the <code>Open_vSwitch</code> table.
3497 Future implementations may update them when an interface is created,
3498 when they are queried (e.g. using an OVSDB <code>select</code>
3499 operation), and just before an interface is deleted due to virtual
3500 interface hot-unplug or VM shutdown, and perhaps at other times, but
3501 not on any regular periodic basis.
3502 </p>
3503 <p>
3504 These are the same statistics reported by OpenFlow in its <code>struct
3505 ofp_port_stats</code> structure. If an interface does not support a
3506 given statistic, then that pair is omitted.
3507 </p>
3508 <group title="Statistics: Successful transmit and receive counters">
3509 <column name="statistics" key="rx_packets">
3510 Number of received packets.
3511 </column>
3512 <column name="statistics" key="rx_bytes">
3513 Number of received bytes.
3514 </column>
3515 <column name="statistics" key="tx_packets">
3516 Number of transmitted packets.
3517 </column>
3518 <column name="statistics" key="tx_bytes">
3519 Number of transmitted bytes.
3520 </column>
3521 </group>
3522 <group title="Statistics: Receive errors">
3523 <column name="statistics" key="rx_dropped">
3524 Number of packets dropped by RX.
3525 </column>
3526 <column name="statistics" key="rx_frame_err">
3527 Number of frame alignment errors.
3528 </column>
3529 <column name="statistics" key="rx_over_err">
3530 Number of packets with RX overrun.
3531 </column>
3532 <column name="statistics" key="rx_crc_err">
3533 Number of CRC errors.
3534 </column>
3535 <column name="statistics" key="rx_errors">
3536 Total number of receive errors, greater than or equal to the sum of
3537 the above.
3538 </column>
3539 </group>
3540 <group title="Statistics: Transmit errors">
3541 <column name="statistics" key="tx_dropped">
3542 Number of packets dropped by TX.
3543 </column>
3544 <column name="statistics" key="collisions">
3545 Number of collisions.
3546 </column>
3547 <column name="statistics" key="tx_errors">
3548 Total number of transmit errors, greater than or equal to the sum of
3549 the above.
3550 </column>
3551 </group>
3552 </group>
3553
3554 <group title="Ingress Policing">
3555 <p>
3556 These settings control ingress policing for packets received on this
3557 interface. On a physical interface, this limits the rate at which
3558 traffic is allowed into the system from the outside; on a virtual
3559 interface (one connected to a virtual machine), this limits the rate at
3560 which the VM is able to transmit.
3561 </p>
3562 <p>
3563 Policing is a simple form of quality-of-service that simply drops
3564 packets received in excess of the configured rate. Due to its
3565 simplicity, policing is usually less accurate and less effective than
3566 egress QoS (which is configured using the <ref table="QoS"/> and <ref
3567 table="Queue"/> tables).
3568 </p>
3569 <p>
3570 Policing is currently implemented on Linux and OVS with DPDK. Both
3571 implementations use a simple ``token bucket'' approach:
3572 </p>
3573 <ul>
3574 <li>
3575 The size of the bucket corresponds to <ref
3576 column="ingress_policing_burst"/>. Initially the bucket is full.
3577 </li>
3578 <li>
3579 Whenever a packet is received, its size (converted to tokens) is
3580 compared to the number of tokens currently in the bucket. If the
3581 required number of tokens are available, they are removed and the
3582 packet is forwarded. Otherwise, the packet is dropped.
3583 </li>
3584 <li>
3585 Whenever it is not full, the bucket is refilled with tokens at the
3586 rate specified by <ref column="ingress_policing_rate"/>.
3587 </li>
3588 </ul>
3589 <p>
3590 Policing interacts badly with some network protocols, and especially
3591 with fragmented IP packets. Suppose that there is enough network
3592 activity to keep the bucket nearly empty all the time. Then this token
3593 bucket algorithm will forward a single packet every so often, with the
3594 period depending on packet size and on the configured rate. All of the
3595 fragments of an IP packets are normally transmitted back-to-back, as a
3596 group. In such a situation, therefore, only one of these fragments
3597 will be forwarded and the rest will be dropped. IP does not provide
3598 any way for the intended recipient to ask for only the remaining
3599 fragments. In such a case there are two likely possibilities for what
3600 will happen next: either all of the fragments will eventually be
3601 retransmitted (as TCP will do), in which case the same problem will
3602 recur, or the sender will not realize that its packet has been dropped
3603 and data will simply be lost (as some UDP-based protocols will do).
3604 Either way, it is possible that no forward progress will ever occur.
3605 </p>
3606 <column name="ingress_policing_rate">
3607 <p>
3608 Maximum rate for data received on this interface, in kbps. Data
3609 received faster than this rate is dropped. Set to <code>0</code>
3610 (the default) to disable policing.
3611 </p>
3612 </column>
3613
3614 <column name="ingress_policing_burst">
3615 <p>Maximum burst size for data received on this interface, in kb. The
3616 default burst size if set to <code>0</code> is 8000 kbit. This value
3617 has no effect if <ref column="ingress_policing_rate"/>
3618 is <code>0</code>.</p>
3619 <p>
3620 Specifying a larger burst size lets the algorithm be more forgiving,
3621 which is important for protocols like TCP that react severely to
3622 dropped packets. The burst size should be at least the size of the
3623 interface's MTU. Specifying a value that is numerically at least as
3624 large as 80% of <ref column="ingress_policing_rate"/> helps TCP come
3625 closer to achieving the full rate.
3626 </p>
3627 </column>
3628 </group>
3629
3630 <group title="Bidirectional Forwarding Detection (BFD)">
3631 <p>
3632 BFD, defined in RFC 5880 and RFC 5881, allows point-to-point
3633 detection of connectivity failures by occasional transmission of
3634 BFD control messages. Open vSwitch implements BFD to serve
3635 as a more popular and standards compliant alternative to CFM.
3636 </p>
3637
3638 <p>
3639 BFD operates by regularly transmitting BFD control messages at a rate
3640 negotiated independently in each direction. Each endpoint specifies
3641 the rate at which it expects to receive control messages, and the rate
3642 at which it is willing to transmit them. By default, Open vSwitch uses
3643 a detection multiplier of three, meaning that an endpoint signals a
3644 connectivity fault if three consecutive BFD control messages fail to
3645 arrive. In the case of a unidirectional connectivity issue, the system
3646 not receiving BFD control messages signals the problem to its peer in
3647 the messages it transmits.
3648 </p>
3649
3650 <p>
3651 The Open vSwitch implementation of BFD aims to comply faithfully
3652 with RFC 5880 requirements. Open vSwitch does not implement the
3653 optional Authentication or ``Echo Mode'' features.
3654 </p>
3655
3656 <group title="BFD Configuration">
3657 <p>
3658 A controller sets up key-value pairs in the <ref column="bfd"/>
3659 column to enable and configure BFD.
3660 </p>
3661
3662 <column name="bfd" key="enable" type='{"type": "boolean"}'>
3663 True to enable BFD on this <ref table="Interface"/>. If not
3664 specified, BFD will not be enabled by default.
3665 </column>
3666
3667 <column name="bfd" key="min_rx"
3668 type='{"type": "integer", "minInteger": 1}'>
3669 The shortest interval, in milliseconds, at which this BFD session
3670 offers to receive BFD control messages. The remote endpoint may
3671 choose to send messages at a slower rate. Defaults to
3672 <code>1000</code>.
3673 </column>
3674
3675 <column name="bfd" key="min_tx"
3676 type='{"type": "integer", "minInteger": 1}'>
3677 The shortest interval, in milliseconds, at which this BFD session is
3678 willing to transmit BFD control messages. Messages will actually be
3679 transmitted at a slower rate if the remote endpoint is not willing to
3680 receive as quickly as specified. Defaults to <code>100</code>.
3681 </column>
3682
3683 <column name="bfd" key="decay_min_rx" type='{"type": "integer"}'>
3684 An alternate receive interval, in milliseconds, that must be greater
3685 than or equal to <ref column="bfd" key="min_rx"/>. The
3686 implementation switches from <ref column="bfd" key="min_rx"/> to <ref
3687 column="bfd" key="decay_min_rx"/> when there is no obvious incoming
3688 data traffic at the interface, to reduce the CPU and bandwidth cost
3689 of monitoring an idle interface. This feature may be disabled by
3690 setting a value of 0. This feature is reset whenever <ref
3691 column="bfd" key="decay_min_rx"/> or <ref column="bfd" key="min_rx"/>
3692 changes.
3693 </column>
3694
3695 <column name="bfd" key="forwarding_if_rx" type='{"type": "boolean"}'>
3696 When <code>true</code>, traffic received on the
3697 <ref table="Interface"/> is used to indicate the capability of packet
3698 I/O. BFD control packets are still transmitted and received. At
3699 least one BFD control packet must be received every 100 * <ref
3700 column="bfd" key="min_rx"/> amount of time. Otherwise, even if
3701 traffic are received, the <ref column="bfd" key="forwarding"/>
3702 will be <code>false</code>.
3703 </column>
3704
3705 <column name="bfd" key="cpath_down" type='{"type": "boolean"}'>
3706 Set to true to notify the remote endpoint that traffic should not be
3707 forwarded to this system for some reason other than a connectivty
3708 failure on the interface being monitored. The typical underlying
3709 reason is ``concatenated path down,'' that is, that connectivity
3710 beyond the local system is down. Defaults to false.
3711 </column>
3712
3713 <column name="bfd" key="check_tnl_key" type='{"type": "boolean"}'>
3714 Set to true to make BFD accept only control messages with a tunnel
3715 key of zero. By default, BFD accepts control messages with any
3716 tunnel key.
3717 </column>
3718
3719 <column name="bfd" key="bfd_local_src_mac">
3720 Set to an Ethernet address in the form
3721 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
3722 to set the MAC used as source for transmitted BFD packets. The
3723 default is the mac address of the BFD enabled interface.
3724 </column>
3725
3726 <column name="bfd" key="bfd_local_dst_mac">
3727 Set to an Ethernet address in the form
3728 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
3729 to set the MAC used as destination for transmitted BFD packets. The
3730 default is <code>00:23:20:00:00:01</code>.
3731 </column>
3732
3733 <column name="bfd" key="bfd_remote_dst_mac">
3734 Set to an Ethernet address in the form
3735 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
3736 to set the MAC used for checking the destination of received BFD packets.
3737 Packets with different destination MAC will not be considered as BFD packets.
3738 If not specified the destination MAC address of received BFD packets
3739 are not checked.
3740 </column>
3741
3742 <column name="bfd" key="bfd_src_ip">
3743 Set to an IPv4 address to set the IP address used as source for
3744 transmitted BFD packets. The default is <code>169.254.1.1</code>.
3745 </column>
3746
3747 <column name="bfd" key="bfd_dst_ip">
3748 Set to an IPv4 address to set the IP address used as destination
3749 for transmitted BFD packets. The default is <code>169.254.1.0</code>.
3750 </column>
3751
3752 <column name="bfd" key="oam">
3753 Some tunnel protocols (such as Geneve) include a bit in the header
3754 to indicate that the encapsulated packet is an OAM frame. By setting
3755 this to true, BFD packets will be marked as OAM if encapsulated in
3756 one of these tunnels.
3757 </column>
3758
3759 <column name="bfd" key="mult"
3760 type='{"type": "integer", "minInteger": 1, "maxInteger": 255}'>
3761 The BFD detection multiplier, which defaults to 3. An endpoint
3762 signals a connectivity fault if the given number of consecutive BFD
3763 control messages fail to arrive.
3764 </column>
3765 </group>
3766
3767 <group title="BFD Status">
3768 <p>
3769 The switch sets key-value pairs in the <ref column="bfd_status"/>
3770 column to report the status of BFD on this interface. When BFD is
3771 not enabled, with <ref column="bfd" key="enable"/>, the switch clears
3772 all key-value pairs from <ref column="bfd_status"/>.
3773 </p>
3774
3775 <column name="bfd_status" key="state"
3776 type='{"type": "string",
3777 "enum": ["set", ["admin_down", "down", "init", "up"]]}'>
3778 Reports the state of the BFD session. The BFD session is fully
3779 healthy and negotiated if <code>UP</code>.
3780 </column>
3781
3782 <column name="bfd_status" key="forwarding" type='{"type": "boolean"}'>
3783 Reports whether the BFD session believes this <ref
3784 table="Interface"/> may be used to forward traffic. Typically this
3785 means the local session is signaling <code>UP</code>, and the remote
3786 system isn't signaling a problem such as concatenated path down.
3787 </column>
3788
3789 <column name="bfd_status" key="diagnostic">
3790 A diagnostic code specifying the local system's reason for the
3791 last change in session state. The error messages are defined in
3792 section 4.1 of [RFC 5880].
3793 </column>
3794
3795 <column name="bfd_status" key="remote_state"
3796 type='{"type": "string",
3797 "enum": ["set", ["admin_down", "down", "init", "up"]]}'>
3798 Reports the state of the remote endpoint's BFD session.
3799 </column>
3800
3801 <column name="bfd_status" key="remote_diagnostic">
3802 A diagnostic code specifying the remote system's reason for the
3803 last change in session state. The error messages are defined in
3804 section 4.1 of [RFC 5880].
3805 </column>
3806
3807 <column name="bfd_status" key="flap_count"
3808 type='{"type": "integer", "minInteger": 0}'>
3809 Counts the number of <ref column="bfd_status" key="forwarding" />
3810 flaps since start. A flap is considered as a change of the
3811 <ref column="bfd_status" key="forwarding" /> value.
3812 </column>
3813 </group>
3814 </group>
3815
3816 <group title="Connectivity Fault Management">
3817 <p>
3818 802.1ag Connectivity Fault Management (CFM) allows a group of
3819 Maintenance Points (MPs) called a Maintenance Association (MA) to
3820 detect connectivity problems with each other. MPs within a MA should
3821 have complete and exclusive interconnectivity. This is verified by
3822 occasionally broadcasting Continuity Check Messages (CCMs) at a
3823 configurable transmission interval.
3824 </p>
3825
3826 <p>
3827 According to the 802.1ag specification, each Maintenance Point should
3828 be configured out-of-band with a list of Remote Maintenance Points it
3829 should have connectivity to. Open vSwitch differs from the
3830 specification in this area. It simply assumes the link is faulted if
3831 no Remote Maintenance Points are reachable, and considers it not
3832 faulted otherwise.
3833 </p>
3834
3835 <p>
3836 When operating over tunnels which have no <code>in_key</code>, or an
3837 <code>in_key</code> of <code>flow</code>. CFM will only accept CCMs
3838 with a tunnel key of zero.
3839 </p>
3840
3841 <column name="cfm_mpid">
3842 <p>
3843 A Maintenance Point ID (MPID) uniquely identifies each endpoint
3844 within a Maintenance Association. The MPID is used to identify this
3845 endpoint to other Maintenance Points in the MA. Each end of a link
3846 being monitored should have a different MPID. Must be configured to
3847 enable CFM on this <ref table="Interface"/>.
3848 </p>
3849 <p>
3850 According to the 802.1ag specification, MPIDs can only range between
3851 [1, 8191]. However, extended mode (see <ref column="other_config"
3852 key="cfm_extended"/>) supports eight byte MPIDs.
3853 </p>
3854 </column>
3855
3856 <column name="cfm_flap_count">
3857 Counts the number of cfm fault flapps since boot. A flap is
3858 considered to be a change of the <ref column="cfm_fault"/> value.
3859 </column>
3860
3861 <column name="cfm_fault">
3862 <p>
3863 Indicates a connectivity fault triggered by an inability to receive
3864 heartbeats from any remote endpoint. When a fault is triggered on
3865 <ref table="Interface"/>s participating in bonds, they will be
3866 disabled.
3867 </p>
3868 <p>
3869 Faults can be triggered for several reasons. Most importantly they
3870 are triggered when no CCMs are received for a period of 3.5 times the
3871 transmission interval. Faults are also triggered when any CCMs
3872 indicate that a Remote Maintenance Point is not receiving CCMs but
3873 able to send them. Finally, a fault is triggered if a CCM is
3874 received which indicates unexpected configuration. Notably, this
3875 case arises when a CCM is received which advertises the local MPID.
3876 </p>
3877 </column>
3878
3879 <column name="cfm_fault_status" key="recv">
3880 Indicates a CFM fault was triggered due to a lack of CCMs received on
3881 the <ref table="Interface"/>.
3882 </column>
3883
3884 <column name="cfm_fault_status" key="rdi">
3885 Indicates a CFM fault was triggered due to the reception of a CCM with
3886 the RDI bit flagged. Endpoints set the RDI bit in their CCMs when they
3887 are not receiving CCMs themselves. This typically indicates a
3888 unidirectional connectivity failure.
3889 </column>
3890
3891 <column name="cfm_fault_status" key="maid">
3892 Indicates a CFM fault was triggered due to the reception of a CCM with
3893 a MAID other than the one Open vSwitch uses. CFM broadcasts are tagged
3894 with an identification number in addition to the MPID called the MAID.
3895 Open vSwitch only supports receiving CCM broadcasts tagged with the
3896 MAID it uses internally.
3897 </column>
3898
3899 <column name="cfm_fault_status" key="loopback">
3900 Indicates a CFM fault was triggered due to the reception of a CCM
3901 advertising the same MPID configured in the <ref column="cfm_mpid"/>
3902 column of this <ref table="Interface"/>. This may indicate a loop in
3903 the network.
3904 </column>
3905
3906 <column name="cfm_fault_status" key="overflow">
3907 Indicates a CFM fault was triggered because the CFM module received
3908 CCMs from more remote endpoints than it can keep track of.
3909 </column>
3910
3911 <column name="cfm_fault_status" key="override">
3912 Indicates a CFM fault was manually triggered by an administrator using
3913 an <code>ovs-appctl</code> command.
3914 </column>
3915
3916 <column name="cfm_fault_status" key="interval">
3917 Indicates a CFM fault was triggered due to the reception of a CCM
3918 frame having an invalid interval.
3919 </column>
3920
3921 <column name="cfm_remote_opstate">
3922 <p>When in extended mode, indicates the operational state of the
3923 remote endpoint as either <code>up</code> or <code>down</code>. See
3924 <ref column="other_config" key="cfm_opstate"/>.
3925 </p>
3926 </column>
3927
3928 <column name="cfm_health">
3929 <p>
3930 Indicates the health of the interface as a percentage of CCM frames
3931 received over 21 <ref column="other_config" key="cfm_interval"/>s.
3932 The health of an interface is undefined if it is communicating with
3933 more than one <ref column="cfm_remote_mpids"/>. It reduces if
3934 healthy heartbeats are not received at the expected rate, and
3935 gradually improves as healthy heartbeats are received at the desired
3936 rate. Every 21 <ref column="other_config" key="cfm_interval"/>s, the
3937 health of the interface is refreshed.
3938 </p>
3939 <p>
3940 As mentioned above, the faults can be triggered for several reasons.
3941 The link health will deteriorate even if heartbeats are received but
3942 they are reported to be unhealthy. An unhealthy heartbeat in this
3943 context is a heartbeat for which either some fault is set or is out
3944 of sequence. The interface health can be 100 only on receiving
3945 healthy heartbeats at the desired rate.
3946 </p>
3947 </column>
3948
3949 <column name="cfm_remote_mpids">
3950 When CFM is properly configured, Open vSwitch will occasionally
3951 receive CCM broadcasts. These broadcasts contain the MPID of the
3952 sending Maintenance Point. The list of MPIDs from which this
3953 <ref table="Interface"/> is receiving broadcasts from is regularly
3954 collected and written to this column.
3955 </column>
3956
3957 <column name="other_config" key="cfm_interval"
3958 type='{"type": "integer"}'>
3959 <p>
3960 The interval, in milliseconds, between transmissions of CFM
3961 heartbeats. Three missed heartbeat receptions indicate a
3962 connectivity fault.
3963 </p>
3964
3965 <p>
3966 In standard operation only intervals of 3, 10, 100, 1,000, 10,000,
3967 60,000, or 600,000 ms are supported. Other values will be rounded
3968 down to the nearest value on the list. Extended mode (see <ref
3969 column="other_config" key="cfm_extended"/>) supports any interval up
3970 to 65,535 ms. In either mode, the default is 1000 ms.
3971 </p>
3972
3973 <p>We do not recommend using intervals less than 100 ms.</p>
3974 </column>
3975
3976 <column name="other_config" key="cfm_extended"
3977 type='{"type": "boolean"}'>
3978 When <code>true</code>, the CFM module operates in extended mode. This
3979 causes it to use a nonstandard destination address to avoid conflicting
3980 with compliant implementations which may be running concurrently on the
3981 network. Furthermore, extended mode increases the accuracy of the
3982 <code>cfm_interval</code> configuration parameter by breaking wire
3983 compatibility with 802.1ag compliant implementations. And extended
3984 mode allows eight byte MPIDs. Defaults to <code>false</code>.
3985 </column>
3986
3987 <column name="other_config" key="cfm_demand" type='{"type": "boolean"}'>
3988 <p>
3989 When <code>true</code>, and
3990 <ref column="other_config" key="cfm_extended"/> is true, the CFM
3991 module operates in demand mode. When in demand mode, traffic
3992 received on the <ref table="Interface"/> is used to indicate
3993 liveness. CCMs are still transmitted and received. At least one
3994 CCM must be received every 100 * <ref column="other_config"
3995 key="cfm_interval"/> amount of time. Otherwise, even if traffic
3996 are received, the CFM module will raise the connectivity fault.
3997 </p>
3998
3999 <p>
4000 Demand mode has a couple of caveats:
4001 <ul>
4002 <li>
4003 To ensure that ovs-vswitchd has enough time to pull statistics
4004 from the datapath, the fault detection interval is set to
4005 3.5 * MAX(<ref column="other_config" key="cfm_interval"/>, 500)
4006 ms.
4007 </li>
4008
4009 <li>
4010 To avoid ambiguity, demand mode disables itself when there are
4011 multiple remote maintenance points.
4012 </li>
4013
4014 <li>
4015 If the <ref table="Interface"/> is heavily congested, CCMs
4016 containing the <ref column="other_config" key="cfm_opstate"/>
4017 status may be dropped causing changes in the operational state to
4018 be delayed. Similarly, if CCMs containing the RDI bit are not
4019 received, unidirectional link failures may not be detected.
4020 </li>
4021 </ul>
4022 </p>
4023 </column>
4024
4025 <column name="other_config" key="cfm_opstate"
4026 type='{"type": "string", "enum": ["set", ["down", "up"]]}'>
4027 When <code>down</code>, the CFM module marks all CCMs it generates as
4028 operationally down without triggering a fault. This allows remote
4029 maintenance points to choose not to forward traffic to the
4030 <ref table="Interface"/> on which this CFM module is running.
4031 Currently, in Open vSwitch, the opdown bit of CCMs affects
4032 <ref table="Interface"/>s participating in bonds, and the bundle
4033 OpenFlow action. This setting is ignored when CFM is not in extended
4034 mode. Defaults to <code>up</code>.
4035 </column>
4036
4037 <column name="other_config" key="cfm_ccm_vlan"
4038 type='{"type": "integer", "minInteger": 1, "maxInteger": 4095}'>
4039 When set, the CFM module will apply a VLAN tag to all CCMs it generates
4040 with the given value. May be the string <code>random</code> in which
4041 case each CCM will be tagged with a different randomly generated VLAN.
4042 </column>
4043
4044 <column name="other_config" key="cfm_ccm_pcp"
4045 type='{"type": "integer", "minInteger": 1, "maxInteger": 7}'>
4046 When set, the CFM module will apply a VLAN tag to all CCMs it generates
4047 with the given PCP value, the VLAN ID of the tag is governed by the
4048 value of <ref column="other_config" key="cfm_ccm_vlan"/>. If
4049 <ref column="other_config" key="cfm_ccm_vlan"/> is unset, a VLAN ID of
4050 zero is used.
4051 </column>
4052
4053 </group>
4054
4055 <group title="Bonding Configuration">
4056 <column name="other_config" key="lacp-port-id"
4057 type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
4058 The LACP port ID of this <ref table="Interface"/>. Port IDs are
4059 used in LACP negotiations to identify individual ports
4060 participating in a bond.
4061 </column>
4062
4063 <column name="other_config" key="lacp-port-priority"
4064 type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
4065 The LACP port priority of this <ref table="Interface"/>. In LACP
4066 negotiations <ref table="Interface"/>s with numerically lower
4067 priorities are preferred for aggregation.
4068 </column>
4069
4070 <column name="other_config" key="lacp-aggregation-key"
4071 type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
4072 The LACP aggregation key of this <ref table="Interface"/>. <ref
4073 table="Interface"/>s with different aggregation keys may not be active
4074 within a given <ref table="Port"/> at the same time.
4075 </column>
4076 </group>
4077
4078 <group title="Virtual Machine Identifiers">
4079 <p>
4080 These key-value pairs specifically apply to an interface that
4081 represents a virtual Ethernet interface connected to a virtual
4082 machine. These key-value pairs should not be present for other types
4083 of interfaces. Keys whose names end in <code>-uuid</code> have
4084 values that uniquely identify the entity in question. For a Citrix
4085 XenServer hypervisor, these values are UUIDs in RFC 4122 format.
4086 Other hypervisors may use other formats.
4087 </p>
4088
4089 <column name="external_ids" key="attached-mac">
4090 The MAC address programmed into the ``virtual hardware'' for this
4091 interface, in the form
4092 <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
4093 For Citrix XenServer, this is the value of the <code>MAC</code> field
4094 in the VIF record for this interface.
4095 </column>
4096
4097 <column name="external_ids" key="iface-id">
4098 A system-unique identifier for the interface. On XenServer, this will
4099 commonly be the same as <ref column="external_ids" key="xs-vif-uuid"/>.
4100 </column>
4101
4102 <column name="external_ids" key="iface-status"
4103 type='{"type": "string",
4104 "enum": ["set", ["active", "inactive"]]}'>
4105 <p>
4106 Hypervisors may sometimes have more than one interface associated
4107 with a given <ref column="external_ids" key="iface-id"/>, only one of
4108 which is actually in use at a given time. For example, in some
4109 circumstances XenServer has both a ``tap'' and a ``vif'' interface
4110 for a single <ref column="external_ids" key="iface-id"/>, but only
4111 uses one of them at a time. A hypervisor that behaves this way must
4112 mark the currently in use interface <code>active</code> and the
4113 others <code>inactive</code>. A hypervisor that never has more than
4114 one interface for a given <ref column="external_ids" key="iface-id"/>
4115 may mark that interface <code>active</code> or omit <ref
4116 column="external_ids" key="iface-status"/> entirely.
4117 </p>
4118
4119 <p>
4120 During VM migration, a given <ref column="external_ids"
4121 key="iface-id"/> might transiently be marked <code>active</code> on
4122 two different hypervisors. That is, <code>active</code> means that
4123 this <ref column="external_ids" key="iface-id"/> is the active
4124 instance within a single hypervisor, not in a broader scope.
4125 There is one exception: some hypervisors support ``migration'' from a
4126 given hypervisor to itself (most often for test purposes). During
4127 such a ``migration,'' two instances of a single <ref
4128 column="external_ids" key="iface-id"/> might both be briefly marked
4129 <code>active</code> on a single hypervisor.
4130 </p>
4131 </column>
4132
4133 <column name="external_ids" key="xs-vif-uuid">
4134 The virtual interface associated with this interface.
4135 </column>
4136
4137 <column name="external_ids" key="xs-network-uuid">
4138 The virtual network to which this interface is attached.
4139 </column>
4140
4141 <column name="external_ids" key="vm-id">
4142 The VM to which this interface belongs. On XenServer, this will be the
4143 same as <ref column="external_ids" key="xs-vm-uuid"/>.
4144 </column>
4145
4146 <column name="external_ids" key="xs-vm-uuid">
4147 The VM to which this interface belongs.
4148 </column>
4149 </group>
4150
4151 <group title="Auto Attach Configuration">
4152 <p>
4153 Auto Attach configuration for a particular interface.
4154 </p>
4155
4156 <column name="lldp" key="enable" type='{"type": "boolean"}'>
4157 True to enable LLDP on this <ref table="Interface"/>. If not
4158 specified, LLDP will be disabled by default.
4159 </column>
4160 </group>
4161
4162 <group title="Flow control Configuration">
4163 <p>
4164 Ethernet flow control defined in IEEE 802.1Qbb provides link level flow
4165 control using MAC pause frames. Implemented only for interfaces with
4166 type <code>dpdk</code>.
4167 </p>
4168
4169 <column name="options" key="rx-flow-ctrl" type='{"type": "boolean"}'>
4170 Set to <code>true</code> to enable Rx flow control on physical ports.
4171 By default, Rx flow control is disabled.
4172 </column>
4173
4174 <column name="options" key="tx-flow-ctrl" type='{"type": "boolean"}'>
4175 Set to <code>true</code> to enable Tx flow control on physical ports.
4176 By default, Tx flow control is disabled.
4177 </column>
4178
4179 <column name="options" key="flow-ctrl-autoneg"
4180 type='{"type": "boolean"}'>
4181 Set to <code>true</code> to enable flow control auto negotiation on
4182 physical ports. By default, auto-neg is disabled.
4183 </column>
4184 </group>
4185
4186 <group title="Link State Change detection mode">
4187 <column name="options" key="dpdk-lsc-interrupt"
4188 type='{"type": "boolean"}'>
4189 <p>
4190 Set this value to <code>true</code> to configure interrupt mode for
4191 Link State Change (LSC) detection instead of poll mode for the DPDK
4192 interface.
4193 </p>
4194 <p>
4195 If this value is not set, poll mode is configured.
4196 </p>
4197 <p>
4198 This parameter has an effect only on netdev dpdk interfaces.
4199 </p>
4200 </column>
4201 </group>
4202
4203 <group title="Common Columns">
4204 The overall purpose of these columns is described under <code>Common
4205 Columns</code> at the beginning of this document.
4206
4207 <column name="other_config"/>
4208 <column name="external_ids"/>
4209 </group>
4210 </table>
4211
4212 <table name="Flow_Table" title="OpenFlow table configuration">
4213 <p>Configuration for a particular OpenFlow table.</p>
4214
4215 <column name="name">
4216 The table's name. Set this column to change the name that controllers
4217 will receive when they request table statistics, e.g. <code>ovs-ofctl
4218 dump-tables</code>. The name does not affect switch behavior.
4219 </column>
4220
4221 <group title="Eviction Policy">
4222 <p>
4223 Open vSwitch supports limiting the number of flows that may be
4224 installed in a flow table, via the <ref column="flow_limit"/> column.
4225 When adding a flow would exceed this limit, by default Open vSwitch
4226 reports an error, but there are two ways to configure Open vSwitch to
4227 instead delete (``evict'') a flow to make room for the new one:
4228 </p>
4229
4230 <ul>
4231 <li>
4232 Set the <ref column="overflow_policy"/> column to <code>evict</code>.
4233 </li>
4234
4235 <li>
4236 Send an OpenFlow 1.4+ ``table mod request'' to enable eviction for
4237 the flow table (e.g. <code>ovs-ofctl -O OpenFlow14 mod-table br0 0
4238 evict</code> to enable eviction on flow table 0 of bridge
4239 <code>br0</code>).
4240 </li>
4241 </ul>
4242
4243 <p>
4244 When a flow must be evicted due to overflow, the flow to evict is
4245 chosen through an approximation of the following algorithm. This
4246 algorithm is used regardless of how eviction was enabled:
4247 </p>
4248
4249 <ol>
4250 <li>
4251 Divide the flows in the table into groups based on the values of the
4252 fields or subfields specified in the <ref column="groups"/> column,
4253 so that all of the flows in a given group have the same values for
4254 those fields. If a flow does not specify a given field, that field's
4255 value is treated as 0. If <ref column="groups"/> is empty, then all
4256 of the flows in the flow table are treated as a single group.
4257 </li>
4258
4259 <li>
4260 Consider the flows in the largest group, that is, the group that
4261 contains the greatest number of flows. If two or more groups all
4262 have the same largest number of flows, consider the flows in all of
4263 those groups.
4264 </li>
4265
4266 <li>
4267 If the flows under consideration have different importance values,
4268 eliminate from consideration any flows except those with the lowest
4269 importance. (``Importance,'' a 16-bit integer value attached to each
4270 flow, was introduced in OpenFlow 1.4. Flows inserted with older
4271 versions of OpenFlow always have an importance of 0.)
4272 </li>
4273
4274 <li>
4275 Among the flows under consideration, choose the flow that expires
4276 soonest for eviction.
4277 </li>
4278 </ol>
4279
4280 <p>
4281 The eviction process only considers flows that have an idle timeout
4282 or a hard timeout. That is, eviction never deletes permanent flows.
4283 (Permanent flows do count against <ref column="flow_limit"/>.)
4284 </p>
4285
4286 <column name="flow_limit">
4287 If set, limits the number of flows that may be added to the table.
4288 Open vSwitch may limit the number of flows in a table for other
4289 reasons, e.g. due to hardware limitations or for resource availability
4290 or performance reasons.
4291 </column>
4292
4293 <column name="overflow_policy">
4294 <p>
4295 Controls the switch's behavior when an OpenFlow flow table
4296 modification request would add flows in excess of <ref
4297 column="flow_limit"/>. The supported values are:
4298 </p>
4299
4300 <dl>
4301 <dt><code>refuse</code></dt>
4302 <dd>
4303 Refuse to add the flow or flows. This is also the default policy
4304 when <ref column="overflow_policy"/> is unset.
4305 </dd>
4306
4307 <dt><code>evict</code></dt>
4308 <dd>
4309 Delete a flow chosen according to the algorithm described above.
4310 </dd>
4311 </dl>
4312 </column>
4313
4314 <column name="groups">
4315 <p>
4316 When <ref column="overflow_policy"/> is <code>evict</code>, this
4317 controls how flows are chosen for eviction when the flow table would
4318 otherwise exceed <ref column="flow_limit"/> flows. Its value is a
4319 set of NXM fields or sub-fields, each of which takes one of the forms
4320 <code><var>field</var>[]</code> or
4321 <code><var>field</var>[<var>start</var>..<var>end</var>]</code>,
4322 e.g. <code>NXM_OF_IN_PORT[]</code>. Please see
4323 <code>meta-flow.h</code> for a complete list of NXM field names.
4324 </p>
4325
4326 <p>
4327 Open vSwitch ignores any invalid or unknown field specifications.
4328 </p>
4329
4330 <p>
4331 When eviction is not enabled, via <ref column="overflow_policy"/> or
4332 an OpenFlow 1.4+ ``table mod,'' this column has no effect.
4333 </p>
4334 </column>
4335 </group>
4336
4337 <group title="Classifier Optimization">
4338 <column name="prefixes">
4339 <p>
4340 This string set specifies which fields should be used for
4341 address prefix tracking. Prefix tracking allows the
4342 classifier to skip rules with longer than necessary prefixes,
4343 resulting in better wildcarding for datapath flows.
4344 </p>
4345 <p>
4346 Prefix tracking may be beneficial when a flow table contains
4347 matches on IP address fields with different prefix lengths.
4348 For example, when a flow table contains IP address matches on
4349 both full addresses and proper prefixes, the full address
4350 matches will typically cause the datapath flow to un-wildcard
4351 the whole address field (depending on flow entry priorities).
4352 In this case each packet with a different address gets handed
4353 to the userspace for flow processing and generates its own
4354 datapath flow. With prefix tracking enabled for the address
4355 field in question packets with addresses matching shorter
4356 prefixes would generate datapath flows where the irrelevant
4357 address bits are wildcarded, allowing the same datapath flow
4358 to handle all the packets within the prefix in question. In
4359 this case many userspace upcalls can be avoided and the
4360 overall performance can be better.
4361 </p>
4362 <p>
4363 This is a performance optimization only, so packets will
4364 receive the same treatment with or without prefix tracking.
4365 </p>
4366 <p>
4367 The supported fields are: <code>tun_id</code>,
4368 <code>tun_src</code>, <code>tun_dst</code>,
4369 <code>tun_ipv6_src</code>, <code>tun_ipv6_dst</code>,
4370 <code>nw_src</code>, <code>nw_dst</code> (or aliases
4371 <code>ip_src</code> and <code>ip_dst</code>),
4372 <code>ipv6_src</code>, and <code>ipv6_dst</code>. (Using this
4373 feature for <code>tun_id</code> would only make sense if the
4374 tunnel IDs have prefix structure similar to IP addresses.)
4375 </p>
4376
4377 <p>
4378 By default, the <code>prefixes=ip_dst,ip_src</code> are used
4379 on each flow table. This instructs the flow classifier to
4380 track the IP destination and source addresses used by the
4381 rules in this specific flow table.
4382 </p>
4383
4384 <p>
4385 The keyword <code>none</code> is recognized as an explicit
4386 override of the default values, causing no prefix fields to be
4387 tracked.
4388 </p>
4389
4390 <p>
4391 To set the prefix fields, the flow table record needs to
4392 exist:
4393 </p>
4394
4395 <dl>
4396 <dt><code>ovs-vsctl set Bridge br0 flow_tables:0=@N1 -- --id=@N1 create Flow_Table name=table0</code></dt>
4397 <dd>
4398 Creates a flow table record for the OpenFlow table number 0.
4399 </dd>
4400
4401 <dt><code>ovs-vsctl set Flow_Table table0 prefixes=ip_dst,ip_src</code></dt>
4402 <dd>
4403 Enables prefix tracking for IP source and destination
4404 address fields.
4405 </dd>
4406 </dl>
4407
4408 <p>
4409 There is a maximum number of fields that can be enabled for any
4410 one flow table. Currently this limit is 3.
4411 </p>
4412 </column>
4413 </group>
4414
4415 <group title="Common Columns">
4416 The overall purpose of these columns is described under <code>Common
4417 Columns</code> at the beginning of this document.
4418
4419 <column name="external_ids"/>
4420 </group>
4421 </table>
4422
4423 <table name="QoS" title="Quality of Service configuration">
4424 <p>Quality of Service (QoS) configuration for each Port that
4425 references it.</p>
4426
4427 <column name="type">
4428 <p>The type of QoS to implement. The currently defined types are
4429 listed below:</p>
4430 <dl>
4431 <dt><code>linux-htb</code></dt>
4432 <dd>
4433 Linux ``hierarchy token bucket'' classifier. See tc-htb(8) (also at
4434 <code>http://linux.die.net/man/8/tc-htb</code>) and the HTB manual
4435 (<code>http://luxik.cdi.cz/~devik/qos/htb/manual/userg.htm</code>)
4436 for information on how this classifier works and how to configure it.
4437 </dd>
4438
4439 <dt><code>linux-hfsc</code></dt>
4440 <dd>
4441 Linux "Hierarchical Fair Service Curve" classifier.
4442 See <code>http://linux-ip.net/articles/hfsc.en/</code> for
4443 information on how this classifier works.
4444 </dd>
4445
4446 <dt><code>linux-sfq</code></dt>
4447 <dd>
4448 Linux ``Stochastic Fairness Queueing'' classifier. See
4449 <code>tc-sfq</code>(8) (also at
4450 <code>http://linux.die.net/man/8/tc-sfq</code>) for information on
4451 how this classifier works.
4452 </dd>
4453
4454 <dt><code>linux-codel</code></dt>
4455 <dd>
4456 Linux ``Controlled Delay'' classifier. See <code>tc-codel</code>(8)
4457 (also at
4458 <code>http://man7.org/linux/man-pages/man8/tc-codel.8.html</code>)
4459 for information on how this classifier works.
4460 </dd>
4461
4462 <dt><code>linux-fq_codel</code></dt>
4463 <dd>
4464 Linux ``Fair Queuing with Controlled Delay'' classifier. See
4465 <code>tc-fq_codel</code>(8) (also at
4466 <code>http://man7.org/linux/man-pages/man8/tc-fq_codel.8.html</code>)
4467 for information on how this classifier works.
4468 </dd>
4469
4470 <dt><code>linux-netem</code></dt>
4471 <dd>
4472 Linux ``Network Emulator'' classifier. See
4473 <code>tc-netem</code>(8) (also at
4474 <code>http://man7.org/linux/man-pages/man8/tc-netem.8.html</code>)
4475 for information on how this classifier works.
4476 </dd>
4477
4478 <dt><code>linux-noop</code></dt>
4479 <dd>
4480 Linux ``No operation.'' By default, Open vSwitch manages quality of
4481 service on all of its configured ports. This can be helpful, but
4482 sometimes administrators prefer to use other software to manage QoS.
4483 This <ref column="type"/> prevents Open vSwitch from changing the QoS
4484 configuration for a port.
4485 </dd>
4486
4487 <dt><code>egress-policer</code></dt>
4488 <dd>
4489 A DPDK egress policer algorithm using the DPDK
4490 rte_meter library. The rte_meter library provides an implementation
4491 which allows the metering and policing of traffic. The implementation
4492 in OVS essentially creates a single token bucket used to police
4493 traffic. It should be noted that when the rte_meter is configured as
4494 part of QoS there will be a performance overhead as the rte_meter
4495 itself will consume CPU cycles in order to police traffic. These CPU
4496 cycles ordinarily are used for packet proccessing. As such the drop
4497 in performance will be noticed in terms of overall aggregate traffic
4498 throughput.
4499 </dd>
4500 <dt><code>trtcm-policer</code></dt>
4501 <dd>
4502 A DPDK egress policer algorithm using RFC 4115's Two-Rate,
4503 Three-Color marker. It's a two-level hierarchical policer
4504 which first does a color-blind marking of the traffic at the queue
4505 level, followed by a color-aware marking at the port level. At the
4506 end traffic marked as Green or Yellow is forwarded, Red is dropped.
4507 For details on how traffic is marked, see RFC 4115.
4508
4509 If the ``default queue'', 0, is not configured it's automatically
4510 created with the same <code>other_config</code> values as the
4511 physical port.
4512 </dd>
4513 </dl>
4514 </column>
4515
4516 <column name="queues">
4517 <p>A map from queue numbers to <ref table="Queue"/> records. The
4518 supported range of queue numbers depend on <ref column="type"/>. The
4519 queue numbers are the same as the <code>queue_id</code> used in
4520 OpenFlow in <code>struct ofp_action_enqueue</code> and other
4521 structures.</p>
4522
4523 <p>
4524 Queue 0 is the ``default queue.'' It is used by OpenFlow output
4525 actions when no specific queue has been set. When no configuration for
4526 queue 0 is present, it is automatically configured as if a <ref
4527 table="Queue"/> record with empty <ref table="Queue" column="dscp"/>
4528 and <ref table="Queue" column="other_config"/> columns had been
4529 specified.
4530 (Before version 1.6, Open vSwitch would leave queue 0 unconfigured in
4531 this case. With some queuing disciplines, this dropped all packets
4532 destined for the default queue.)
4533 </p>
4534 </column>
4535
4536 <group title="Configuration for linux-htb and linux-hfsc">
4537 <p>
4538 The <code>linux-htb</code> and <code>linux-hfsc</code> classes support
4539 the following key-value pair:
4540 </p>
4541
4542 <column name="other_config" key="max-rate" type='{"type": "integer"}'>
4543 Maximum rate shared by all queued traffic, in bit/s. Optional. If not
4544 specified, for physical interfaces, the default is the link rate. For
4545 other interfaces or if the link rate cannot be determined, the default
4546 is currently 100 Mbps.
4547 </column>
4548 </group>
4549
4550 <group title="Configuration for egress-policer QoS">
4551 <p>
4552 <ref table="QoS"/> <ref table="QoS" column="type"/>
4553 <code>egress-policer</code> provides egress policing for userspace
4554 port types with DPDK.
4555
4556 It has the following key-value pairs defined.
4557 </p>
4558
4559 <column name="other_config" key="cir" type='{"type": "integer"}'>
4560 The Committed Information Rate (CIR) is measured in bytes of IP
4561 packets per second, i.e. it includes the IP header, but not link
4562 specific (e.g. Ethernet) headers. This represents the bytes per second
4563 rate at which the token bucket will be updated. The cir value is
4564 calculated by (pps x packet data size). For example assuming a user
4565 wishes to limit a stream consisting of 64 byte packets to 1 million
4566 packets per second the CIR would be set to to to 46000000. This value
4567 can be broken into '1,000,000 x 46'. Where 1,000,000 is the policing
4568 rate for the number of packets per second and 46 represents the size
4569 of the packet data for a 64 byte ip packet.
4570 </column>
4571 <column name="other_config" key="cbs" type='{"type": "integer"}'>
4572 The Committed Burst Size (CBS) is measured in bytes and represents a
4573 token bucket. At a minimum this value should be be set to the expected
4574 largest size packet in the traffic stream. In practice larger values
4575 may be used to increase the size of the token bucket. If a packet can
4576 be transmitted then the cbs will be decremented by the number of
4577 bytes/tokens of the packet. If there are not enough tokens in the cbs
4578 bucket the packet will be dropped.
4579 </column>
4580 <column name="other_config" key="eir" type='{"type": "integer"}'>
4581 The Excess Information Rate (EIR) is measured in bytes of IP
4582 packets per second, i.e. it includes the IP header, but not link
4583 specific (e.g. Ethernet) headers. This represents the bytes per second
4584 rate at which the token bucket will be updated. The eir value is
4585 calculated by (pps x packet data size). For example assuming a user
4586 wishes to limit a stream consisting of 64 byte packets to 1 million
4587 packets per second the EIR would be set to to to 46000000. This value
4588 can be broken into '1,000,000 x 46'. Where 1,000,000 is the policing
4589 rate for the number of packets per second and 46 represents the size
4590 of the packet data for a 64 byte ip packet.
4591 </column>
4592 <column name="other_config" key="ebs" type='{"type": "integer"}'>
4593 The Excess Burst Size (EBS) is measured in bytes and represents a
4594 token bucket. At a minimum this value should be be set to the expected
4595 largest size packet in the traffic stream. In practice larger values
4596 may be used to increase the size of the token bucket. If a packet can
4597 be transmitted then the ebs will be decremented by the number of
4598 bytes/tokens of the packet. If there are not enough tokens in the cbs
4599 bucket the packet might be dropped.
4600 </column>
4601 </group>
4602
4603 <group title="Configuration for linux-sfq">
4604 <p>
4605 The <code>linux-sfq</code> QoS supports the following key-value pairs:
4606 </p>
4607
4608 <column name="other_config" key="perturb" type='{"type": "integer"}'>
4609 Number of seconds between consecutive perturbations in hashing algorithm.
4610 Different flows can end up in the same hash bucket causing unfairness.
4611 Perturbation's goal is to remove possible unfairness.
4612 The default and recommended value is 10. Too low a value is discouraged
4613 because each perturbation can cause packet reordering.
4614 </column>
4615 <column name="other_config" key="quantum" type='{"type": "integer"}'>
4616 Number of bytes <code>linux-sfq</code> QoS can dequeue in one turn in
4617 round-robin from one flow. The default and recommended value is equal
4618 to interface's MTU.
4619 </column>
4620 </group>
4621
4622 <group title="Configuration for linux-netem">
4623 <p>
4624 The <code>linux-netem</code> QoS supports the following key-value
4625 pairs:
4626 </p>
4627
4628 <column name="other_config" key="latency" type='{"type": "integer"}'>
4629 Adds the chosen delay to the packets outgoing to chosen network
4630 interface. The latency value expressed in us.
4631 </column>
4632 <column name="other_config" key="limit" type='{"type": "integer"}'>
4633 Maximum number of packets the qdisc may hold queued at a time.
4634 The default value is 1000.
4635 </column>
4636 <column name="other_config" key="loss" type='{"type": "integer"}'>
4637 Adds an independent loss probability to the packets outgoing from the
4638 chosen network interface.
4639 </column>
4640 </group>
4641
4642 <group title="Common Columns">
4643 The overall purpose of these columns is described under <code>Common
4644 Columns</code> at the beginning of this document.
4645
4646 <column name="other_config"/>
4647 <column name="external_ids"/>
4648 </group>
4649 </table>
4650
4651 <table name="Queue" title="QoS output queue.">
4652 <p>A configuration for a port output queue, used in configuring Quality of
4653 Service (QoS) features. May be referenced by <ref column="queues"
4654 table="QoS"/> column in <ref table="QoS"/> table.</p>
4655
4656 <column name="dscp">
4657 If set, Open vSwitch will mark all traffic egressing this
4658 <ref table="Queue"/> with the given DSCP bits. Traffic egressing the
4659 default <ref table="Queue"/> is only marked if it was explicitly selected
4660 as the <ref table="Queue"/> at the time the packet was output. If unset,
4661 the DSCP bits of traffic egressing this <ref table="Queue"/> will remain
4662 unchanged.
4663 </column>
4664
4665 <group title="Configuration for linux-htb QoS">
4666 <p>
4667 <ref table="QoS"/> <ref table="QoS" column="type"/>
4668 <code>linux-htb</code> may use <code>queue_id</code>s less than 61440.
4669 It has the following key-value pairs defined.
4670 </p>
4671
4672 <column name="other_config" key="min-rate"
4673 type='{"type": "integer", "minInteger": 1}'>
4674 Minimum guaranteed bandwidth, in bit/s.
4675 </column>
4676
4677 <column name="other_config" key="max-rate"
4678 type='{"type": "integer", "minInteger": 1}'>
4679 Maximum allowed bandwidth, in bit/s. Optional. If specified, the
4680 queue's rate will not be allowed to exceed the specified value, even
4681 if excess bandwidth is available. If unspecified, defaults to no
4682 limit.
4683 </column>
4684
4685 <column name="other_config" key="burst"
4686 type='{"type": "integer", "minInteger": 1}'>
4687 Burst size, in bits. This is the maximum amount of ``credits'' that a
4688 queue can accumulate while it is idle. Optional. Details of the
4689 <code>linux-htb</code> implementation require a minimum burst size, so
4690 a too-small <code>burst</code> will be silently ignored.
4691 </column>
4692
4693 <column name="other_config" key="priority"
4694 type='{"type": "integer", "minInteger": 0, "maxInteger": 4294967295}'>
4695 A queue with a smaller <code>priority</code> will receive all the
4696 excess bandwidth that it can use before a queue with a larger value
4697 receives any. Specific priority values are unimportant; only relative
4698 ordering matters. Defaults to 0 if unspecified.
4699 </column>
4700 </group>
4701
4702 <group title="Configuration for linux-hfsc QoS">
4703 <p>
4704 <ref table="QoS"/> <ref table="QoS" column="type"/>
4705 <code>linux-hfsc</code> may use <code>queue_id</code>s less than 61440.
4706 It has the following key-value pairs defined.
4707 </p>
4708
4709 <column name="other_config" key="min-rate"
4710 type='{"type": "integer", "minInteger": 1}'>
4711 Minimum guaranteed bandwidth, in bit/s.
4712 </column>
4713
4714 <column name="other_config" key="max-rate"
4715 type='{"type": "integer", "minInteger": 1}'>
4716 Maximum allowed bandwidth, in bit/s. Optional. If specified, the
4717 queue's rate will not be allowed to exceed the specified value, even if
4718 excess bandwidth is available. If unspecified, defaults to no
4719 limit.
4720 </column>
4721 </group>
4722
4723 <group title="Common Columns">
4724 The overall purpose of these columns is described under <code>Common
4725 Columns</code> at the beginning of this document.
4726
4727 <column name="other_config"/>
4728 <column name="external_ids"/>
4729 </group>
4730 </table>
4731
4732 <table name="Mirror" title="Port mirroring.">
4733 <p>A port mirror within a <ref table="Bridge"/>.</p>
4734 <p>A port mirror configures a bridge to send selected frames to special
4735 ``mirrored'' ports, in addition to their normal destinations. Mirroring
4736 traffic may also be referred to as SPAN or RSPAN, depending on how
4737 the mirrored traffic is sent.</p>
4738
4739 <p>
4740 When a packet enters an Open vSwitch bridge, it becomes eligible for
4741 mirroring based on its ingress port and VLAN. As the packet travels
4742 through the flow tables, each time it is output to a port, it becomes
4743 eligible for mirroring based on the egress port and VLAN. In Open
4744 vSwitch 2.5 and later, mirroring occurs just after a packet first becomes
4745 eligible, using the packet as it exists at that point; in Open vSwitch
4746 2.4 and earlier, mirroring occurs only after a packet has traversed all
4747 the flow tables, using the original packet as it entered the bridge.
4748 This makes a difference only when the flow table modifies the packet: in
4749 Open vSwitch 2.4, the modifications are never visible to mirrors, whereas
4750 in Open vSwitch 2.5 and later modifications made before the first output
4751 that makes it eligible for mirroring to a particular destination are
4752 visible.
4753 </p>
4754
4755 <p>
4756 A packet that enters an Open vSwitch bridge is mirrored to a particular
4757 destination only once, even if it is eligible for multiple reasons. For
4758 example, a packet would be mirrored to a particular <ref
4759 column="output_port"/> only once, even if it is selected for mirroring to
4760 that port by <ref column="select_dst_port"/> and <ref
4761 column="select_src_port"/> in the same or different <ref table="Mirror"/>
4762 records.
4763 </p>
4764
4765 <column name="name">
4766 Arbitrary identifier for the <ref table="Mirror"/>.
4767 </column>
4768
4769 <group title="Selecting Packets for Mirroring">
4770 <p>
4771 To be selected for mirroring, a given packet must enter or leave the
4772 bridge through a selected port and it must also be in one of the
4773 selected VLANs.
4774 </p>
4775
4776 <column name="select_all">
4777 If true, every packet arriving or departing on any port is
4778 selected for mirroring.
4779 </column>
4780
4781 <column name="select_dst_port">
4782 Ports on which departing packets are selected for mirroring.
4783 </column>
4784
4785 <column name="select_src_port">
4786 Ports on which arriving packets are selected for mirroring.
4787 </column>
4788
4789 <column name="select_vlan">
4790 VLANs on which packets are selected for mirroring. An empty set
4791 selects packets on all VLANs.
4792 </column>
4793 </group>
4794
4795 <group title="Mirroring Destination Configuration">
4796 <p>
4797 These columns are mutually exclusive. Exactly one of them must be
4798 nonempty.
4799 </p>
4800
4801 <column name="output_port">
4802 <p>Output port for selected packets, if nonempty.</p>
4803 <p>Specifying a port for mirror output reserves that port exclusively
4804 for mirroring. No frames other than those selected for mirroring
4805 via this column
4806 will be forwarded to the port, and any frames received on the port
4807 will be discarded.</p>
4808 <p>
4809 The output port may be any kind of port supported by Open vSwitch.
4810 It may be, for example, a physical port (sometimes called SPAN) or a
4811 GRE tunnel.
4812 </p>
4813 </column>
4814
4815 <column name="output_vlan">
4816 <p>Output VLAN for selected packets, if nonempty.</p>
4817 <p>The frames will be sent out all ports that trunk
4818 <ref column="output_vlan"/>, as well as any ports with implicit VLAN
4819 <ref column="output_vlan"/>. When a mirrored frame is sent out a
4820 trunk port, the frame's VLAN tag will be set to
4821 <ref column="output_vlan"/>, replacing any existing tag; when it is
4822 sent out an implicit VLAN port, the frame will not be tagged. This
4823 type of mirroring is sometimes called RSPAN.</p>
4824 <p>
4825 See the documentation for
4826 <ref column="other_config" key="forward-bpdu"/> in the
4827 <ref table="Interface"/> table for a list of destination MAC
4828 addresses which will not be mirrored to a VLAN to avoid confusing
4829 switches that interpret the protocols that they represent.
4830 </p>
4831 <p><em>Please note:</em> Mirroring to a VLAN can disrupt a network that
4832 contains unmanaged switches. Consider an unmanaged physical switch
4833 with two ports: port 1, connected to an end host, and port 2,
4834 connected to an Open vSwitch configured to mirror received packets
4835 into VLAN 123 on port 2. Suppose that the end host sends a packet on
4836 port 1 that the physical switch forwards to port 2. The Open vSwitch
4837 forwards this packet to its destination and then reflects it back on
4838 port 2 in VLAN 123. This reflected packet causes the unmanaged
4839 physical switch to replace the MAC learning table entry, which
4840 correctly pointed to port 1, with one that incorrectly points to port
4841 2. Afterward, the physical switch will direct packets destined for
4842 the end host to the Open vSwitch on port 2, instead of to the end
4843 host on port 1, disrupting connectivity. If mirroring to a VLAN is
4844 desired in this scenario, then the physical switch must be replaced
4845 by one that learns Ethernet addresses on a per-VLAN basis. In
4846 addition, learning should be disabled on the VLAN containing mirrored
4847 traffic. If this is not done then intermediate switches will learn
4848 the MAC address of each end host from the mirrored traffic. If
4849 packets being sent to that end host are also mirrored, then they will
4850 be dropped since the switch will attempt to send them out the input
4851 port. Disabling learning for the VLAN will cause the switch to
4852 correctly send the packet out all ports configured for that VLAN. If
4853 Open vSwitch is being used as an intermediate switch, learning can be
4854 disabled by adding the mirrored VLAN to <ref column="flood_vlans"/>
4855 in the appropriate <ref table="Bridge"/> table or tables.</p>
4856 <p>
4857 Mirroring to a GRE tunnel has fewer caveats than mirroring to a
4858 VLAN and should generally be preferred.
4859 </p>
4860 </column>
4861
4862 <column name="snaplen">
4863 <p>Maximum per-packet number of bytes to mirror.</p>
4864 <p>A mirrored packet with size larger than <ref column="snaplen"/>
4865 will be truncated in datapath to <ref column="snaplen"/> bytes
4866 before sending to the mirror output port. If omitted, packets
4867 are not truncated.
4868 </p>
4869 </column>
4870 </group>
4871
4872 <group title="Statistics: Mirror counters">
4873 <p>
4874 Key-value pairs that report mirror statistics. The update period
4875 is controlled by <ref column="other_config"
4876 key="stats-update-interval"/> in the <code>Open_vSwitch</code> table.
4877 </p>
4878 <column name="statistics" key="tx_packets">
4879 Number of packets transmitted through this mirror.
4880 </column>
4881 <column name="statistics" key="tx_bytes">
4882 Number of bytes transmitted through this mirror.
4883 </column>
4884 </group>
4885
4886 <group title="Common Columns">
4887 The overall purpose of these columns is described under <code>Common
4888 Columns</code> at the beginning of this document.
4889
4890 <column name="external_ids"/>
4891 </group>
4892 </table>
4893
4894 <table name="Controller" title="OpenFlow controller configuration.">
4895 <p>An OpenFlow controller.</p>
4896
4897 <group title="Core Features">
4898 <column name="type">
4899 <p>
4900 Open vSwitch supports two kinds of OpenFlow controllers. A bridge
4901 may have any number of each kind:
4902 </p>
4903
4904 <dl>
4905 <dt>Primary controllers</dt>
4906 <dd>
4907 <p>
4908 This is the kind of controller envisioned by the OpenFlow
4909 specifications. Usually, a primary controller implements a
4910 network policy by taking charge of the switch's flow table.
4911 </p>
4912
4913 <p>
4914 The <ref table="Bridge" column="fail_mode"/> column in the <ref
4915 table="Bridge"/> table applies to primary controllers.
4916 </p>
4917
4918 <p>
4919 When multiple primary controllers are configured, Open vSwitch
4920 connects to all of them simultaneously. OpenFlow provides few
4921 facilities to allow multiple controllers to coordinate in
4922 interacting with a single switch, so more than one primary
4923 controller should be specified only if the controllers are
4924 themselves designed to coordinate with each other.
4925 </p>
4926 </dd>
4927 <dt>Service controllers</dt>
4928 <dd>
4929 <p>
4930 These kinds of OpenFlow controller connections are intended for
4931 occasional support and maintenance use, e.g. with
4932 <code>ovs-ofctl</code>. Usually a service controller connects
4933 only briefly to inspect or modify some of a switch's state.
4934 </p>
4935
4936 <p>
4937 The <ref table="Bridge" column="fail_mode"/> column in the <ref
4938 table="Bridge"/> table does not apply to service controllers.
4939 </p>
4940 </dd>
4941 </dl>
4942
4943 <p>
4944 By default, Open vSwitch treats controllers with active connection
4945 methods as primary controllers and those with passive connection
4946 methods as service controllers. Set this column to the desired type
4947 to override this default.
4948 </p>
4949 </column>
4950
4951 <column name="target">
4952 <p>Connection method for controller.</p>
4953 <p>
4954 The following active connection methods are currently supported:
4955 </p>
4956 <dl>
4957 <dt><code>ssl:<var>host</var></code>[<code>:<var>port</var></code>]</dt>
4958 <dd>
4959 <p>The specified SSL <var>port</var> on the host at the
4960 given <var>host</var>, which can either be a DNS name (if built
4961 with unbound library) or an IP address. The <ref table="Open_vSwitch"
4962 column="ssl"/> column in the <ref table="Open_vSwitch"/> table must
4963 point to a valid SSL configuration when this form is used.</p>
4964 <p>If <var>port</var> is not specified, it defaults to 6653.</p>
4965 <p>SSL support is an optional feature that is not always built as
4966 part of Open vSwitch.</p>
4967 </dd>
4968 <dt><code>tcp:<var>host</var></code>[<code>:<var>port</var></code>]</dt>
4969 <dd>
4970 <p>
4971 The specified TCP <var>port</var> on the host at the given
4972 <var>host</var>, which can either be a DNS name (if built with
4973 unbound library) or an IP address (IPv4 or IPv6). If <var>host</var>
4974 is an IPv6 address, wrap it in square brackets, e.g.
4975 <code>tcp:[::1]:6653</code>.
4976 </p>
4977 <p>
4978 If <var>port</var> is not specified, it defaults to 6653.
4979 </p>
4980 </dd>
4981 </dl>
4982 <p>
4983 The following passive connection methods are currently supported:
4984 </p>
4985 <dl>
4986 <dt><code>pssl:</code>[<var>port</var>][<code>:<var>host</var></code>]</dt>
4987 <dd>
4988 <p>
4989 Listens for SSL connections on the specified TCP <var>port</var>.
4990 If <var>host</var>, which can either be a DNS name (if built with
4991 unbound library) or an IP address, is specified, then connections
4992 are restricted to the resolved or specified local IP address
4993 (either IPv4 or IPv6). If <var>host</var> is an IPv6 address,
4994 wrap it in square brackets, e.g. <code>pssl:6653:[::1]</code>.
4995 </p>
4996 <p>
4997 If <var>port</var> is not specified, it defaults to
4998 6653. If <var>host</var> is not specified then it listens only on
4999 IPv4 (but not IPv6) addresses. The
5000 <ref table="Open_vSwitch" column="ssl"/>
5001 column in the <ref table="Open_vSwitch"/> table must point to a
5002 valid SSL configuration when this form is used.
5003 </p>
5004 <p>
5005 If <var>port</var> is not specified, it currently to 6653.
5006 </p>
5007 <p>
5008 SSL support is an optional feature that is not always built as
5009 part of Open vSwitch.
5010 </p>
5011 </dd>
5012 <dt><code>ptcp:</code>[<var>port</var>][<code>:<var>host</var></code>]</dt>
5013 <dd>
5014 <p>
5015 Listens for connections on the specified TCP <var>port</var>. If
5016 <var>host</var>, which can either be a DNS name (if built with
5017 unbound library) or an IP address, is specified, then connections
5018 are restricted to the resolved or specified local IP address
5019 (either IPv4 or IPv6). If <var>host</var> is an IPv6 address, wrap
5020 it in square brackets, e.g. <code>ptcp:6653:[::1]</code>. If
5021 <var>host</var> is not specified then it listens only on IPv4
5022 addresses.
5023 </p>
5024 <p>
5025 If <var>port</var> is not specified, it defaults to 6653.
5026 </p>
5027 </dd>
5028 </dl>
5029 <p>When multiple controllers are configured for a single bridge, the
5030 <ref column="target"/> values must be unique. Duplicate
5031 <ref column="target"/> values yield unspecified results.</p>
5032 </column>
5033
5034 <column name="connection_mode">
5035 <p>If it is specified, this setting must be one of the following
5036 strings that describes how Open vSwitch contacts this OpenFlow
5037 controller over the network:</p>
5038
5039 <dl>
5040 <dt><code>in-band</code></dt>
5041 <dd>In this mode, this controller's OpenFlow traffic travels over the
5042 bridge associated with the controller. With this setting, Open
5043 vSwitch allows traffic to and from the controller regardless of the
5044 contents of the OpenFlow flow table. (Otherwise, Open vSwitch
5045 would never be able to connect to the controller, because it did
5046 not have a flow to enable it.) This is the most common connection
5047 mode because it is not necessary to maintain two independent
5048 networks.</dd>
5049 <dt><code>out-of-band</code></dt>
5050 <dd>In this mode, OpenFlow traffic uses a control network separate
5051 from the bridge associated with this controller, that is, the
5052 bridge does not use any of its own network devices to communicate
5053 with the controller. The control network must be configured
5054 separately, before or after <code>ovs-vswitchd</code> is started.
5055 </dd>
5056 </dl>
5057
5058 <p>If not specified, the default is implementation-specific.</p>
5059 </column>
5060 </group>
5061
5062 <group title="Controller Failure Detection and Handling">
5063 <column name="max_backoff">
5064 Maximum number of milliseconds to wait between connection attempts.
5065 Default is implementation-specific.
5066 </column>
5067
5068 <column name="inactivity_probe">
5069 Maximum number of milliseconds of idle time on connection to
5070 controller before sending an inactivity probe message. If Open
5071 vSwitch does not communicate with the controller for the specified
5072 number of seconds, it will send a probe. If a response is not
5073 received for the same additional amount of time, Open vSwitch
5074 assumes the connection has been broken and attempts to reconnect.
5075 Default is implementation-specific. A value of 0 disables
5076 inactivity probes.
5077 </column>
5078 </group>
5079
5080 <group title="Asynchronous Messages">
5081 <p>
5082 OpenFlow switches send certain messages to controllers spontanenously,
5083 that is, not in response to any request from the controller. These
5084 messages are called ``asynchronous messages.'' These columns allow
5085 asynchronous messages to be limited or disabled to ensure the best use
5086 of network resources.
5087 </p>
5088
5089 <column name="enable_async_messages">
5090 The OpenFlow protocol enables asynchronous messages at time of
5091 connection establishment, which means that a controller can receive
5092 asynchronous messages, potentially many of them, even if it turns them
5093 off immediately after connecting. Set this column to
5094 <code>false</code> to change Open vSwitch behavior to disable, by
5095 default, all asynchronous messages. The controller can use the
5096 <code>NXT_SET_ASYNC_CONFIG</code> Nicira extension to OpenFlow to turn
5097 on any messages that it does want to receive, if any.
5098 </column>
5099
5100 <group title="Controller Rate Limiting">
5101 <p>
5102 A switch can forward packets to a controller over the OpenFlow
5103 protocol. Forwarding packets this way at too high a rate can
5104 overwhelm a controller, frustrate use of the OpenFlow connection for
5105 other purposes, increase the latency of flow setup, and use an
5106 unreasonable amount of bandwidth. Therefore, Open vSwitch supports
5107 limiting the rate of packet forwarding to a controller.
5108 </p>
5109
5110 <p>
5111 There are two main reasons in OpenFlow for a packet to be sent to a
5112 controller: either the packet ``misses'' in the flow table, that is,
5113 there is no matching flow, or a flow table action says to send the
5114 packet to the controller. Open vSwitch limits the rate of each kind
5115 of packet separately at the configured rate. Therefore, the actual
5116 rate that packets are sent to the controller can be up to twice the
5117 configured rate, when packets are sent for both reasons.
5118 </p>
5119
5120 <p>
5121 This feature is specific to forwarding packets over an OpenFlow
5122 connection. It is not general-purpose QoS. See the <ref
5123 table="QoS"/> table for quality of service configuration, and <ref
5124 column="ingress_policing_rate" table="Interface"/> in the <ref
5125 table="Interface"/> table for ingress policing configuration.
5126 </p>
5127
5128 <column name="controller_queue_size">
5129 <p>
5130 This sets the maximum size of the queue of packets that need to be
5131 sent to this OpenFlow controller. The value must be less than 512.
5132 If not specified the queue size is limited to the value set for
5133 the management controller in <ref table="Bridge"
5134 column="other_config" key="controller-queue-size"/> if present or
5135 100 packets by default. Note: increasing the queue size might
5136 have a negative impact on latency.
5137 </p>
5138 </column>
5139
5140 <column name="controller_rate_limit">
5141 <p>
5142 The maximum rate at which the switch will forward packets to the
5143 OpenFlow controller, in packets per second. If no value is
5144 specified, rate limiting is disabled.
5145 </p>
5146 </column>
5147
5148 <column name="controller_burst_limit">
5149 <p>
5150 When a high rate triggers rate-limiting, Open vSwitch queues
5151 packets to the controller for each port and transmits them to the
5152 controller at the configured rate. This value limits the number of
5153 queued packets. Ports on a bridge share the packet queue fairly.
5154 </p>
5155
5156 <p>
5157 This value has no effect unless <ref
5158 column="controller_rate_limit"/> is configured. The current
5159 default when this value is not specified is one-quarter of <ref
5160 column="controller_rate_limit"/>, meaning that queuing can delay
5161 forwarding a packet to the controller by up to 250 ms.
5162 </p>
5163 </column>
5164
5165 <group title="Controller Rate Limiting Statistics">
5166 <p>
5167 These values report the effects of rate limiting. Their values are
5168 relative to establishment of the most recent OpenFlow connection,
5169 or since rate limiting was enabled, whichever happened more
5170 recently. Each consists of two values, one with <code>TYPE</code>
5171 replaced by <code>miss</code> for rate limiting flow table misses,
5172 and the other with <code>TYPE</code> replaced by
5173 <code>action</code> for rate limiting packets sent by OpenFlow
5174 actions.
5175 </p>
5176
5177 <p>
5178 These statistics are reported only when controller rate limiting is
5179 enabled.
5180 </p>
5181
5182 <column name="status" key="packet-in-TYPE-bypassed"
5183 type='{"type": "integer", "minInteger": 0}'>
5184 Number of packets sent directly to the controller, without queuing,
5185 because the rate did not exceed the configured maximum.
5186 </column>
5187
5188 <column name="status" key="packet-in-TYPE-queued"
5189 type='{"type": "integer", "minInteger": 0}'>
5190 Number of packets added to the queue to send later.
5191 </column>
5192
5193 <column name="status" key="packet-in-TYPE-dropped"
5194 type='{"type": "integer", "minInteger": 0}'>
5195 Number of packets added to the queue that were later dropped due to
5196 overflow. This value is less than or equal to <ref column="status"
5197 key="packet-in-TYPE-queued"/>.
5198 </column>
5199
5200 <column name="status" key="packet-in-TYPE-backlog"
5201 type='{"type": "integer", "minInteger": 0}'>
5202 Number of packets currently queued. The other statistics increase
5203 monotonically, but this one fluctuates between 0 and the <ref
5204 column="controller_burst_limit"/> as conditions change.
5205 </column>
5206 </group>
5207 </group>
5208 </group>
5209
5210 <group title="Additional In-Band Configuration">
5211 <p>These values are considered only in in-band control mode (see
5212 <ref column="connection_mode"/>).</p>
5213
5214 <p>When multiple controllers are configured on a single bridge, there
5215 should be only one set of unique values in these columns. If different
5216 values are set for these columns in different controllers, the effect
5217 is unspecified.</p>
5218
5219 <column name="local_ip">
5220 The IP address to configure on the local port,
5221 e.g. <code>192.168.0.123</code>. If this value is unset, then
5222 <ref column="local_netmask"/> and <ref column="local_gateway"/> are
5223 ignored.
5224 </column>
5225
5226 <column name="local_netmask">
5227 The IP netmask to configure on the local port,
5228 e.g. <code>255.255.255.0</code>. If <ref column="local_ip"/> is set
5229 but this value is unset, then the default is chosen based on whether
5230 the IP address is class A, B, or C.
5231 </column>
5232
5233 <column name="local_gateway">
5234 The IP address of the gateway to configure on the local port, as a
5235 string, e.g. <code>192.168.0.1</code>. Leave this column unset if
5236 this network has no gateway.
5237 </column>
5238 </group>
5239
5240 <group title="Controller Status">
5241 <column name="is_connected">
5242 <code>true</code> if currently connected to this controller,
5243 <code>false</code> otherwise.
5244 </column>
5245
5246 <column name="role"
5247 type='{"type": "string", "enum": ["set", ["other", "master", "slave"]]}'>
5248 <p>The level of authority this controller has on the associated
5249 bridge. Possible values are:</p>
5250 <dl>
5251 <dt><code>other</code></dt>
5252 <dd>Allows the controller access to all OpenFlow features.</dd>
5253 <dt><code>master</code></dt>
5254 <dd>Equivalent to <code>other</code>, except that there may be at
5255 most one master controller at a time. When a controller configures
5256 itself as <code>master</code>, any existing master is demoted to
5257 the <code>slave</code> role.</dd>
5258 <dt><code>slave</code></dt>
5259 <dd>Allows the controller read-only access to OpenFlow features.
5260 Attempts to modify the flow table will be rejected with an
5261 error. Slave controllers do not receive OFPT_PACKET_IN or
5262 OFPT_FLOW_REMOVED messages, but they do receive OFPT_PORT_STATUS
5263 messages.</dd>
5264 </dl>
5265 </column>
5266
5267 <column name="status" key="last_error">
5268 A human-readable description of the last error on the connection
5269 to the controller; i.e. <code>strerror(errno)</code>. This key
5270 will exist only if an error has occurred.
5271 </column>
5272
5273 <column name="status" key="state"
5274 type='{"type": "string", "enum": ["set", ["VOID", "BACKOFF", "CONNECTING", "ACTIVE", "IDLE"]]}'>
5275 <p>
5276 The state of the connection to the controller:
5277 </p>
5278 <dl>
5279 <dt><code>VOID</code></dt>
5280 <dd>Connection is disabled.</dd>
5281
5282 <dt><code>BACKOFF</code></dt>
5283 <dd>Attempting to reconnect at an increasing period.</dd>
5284
5285 <dt><code>CONNECTING</code></dt>
5286 <dd>Attempting to connect.</dd>
5287
5288 <dt><code>ACTIVE</code></dt>
5289 <dd>Connected, remote host responsive.</dd>
5290
5291 <dt><code>IDLE</code></dt>
5292 <dd>Connection is idle. Waiting for response to keep-alive.</dd>
5293 </dl>
5294 <p>
5295 These values may change in the future. They are provided only for
5296 human consumption.
5297 </p>
5298 </column>
5299
5300 <column name="status" key="sec_since_connect"
5301 type='{"type": "integer", "minInteger": 0}'>
5302 The amount of time since this controller last successfully connected to
5303 the switch (in seconds). Value is empty if controller has never
5304 successfully connected.
5305 </column>
5306
5307 <column name="status" key="sec_since_disconnect"
5308 type='{"type": "integer", "minInteger": 1}'>
5309 The amount of time since this controller last disconnected from
5310 the switch (in seconds). Value is empty if controller has never
5311 disconnected.
5312 </column>
5313 </group>
5314
5315 <group title="Connection Parameters">
5316 <p>
5317 Additional configuration for a connection between the controller
5318 and the Open vSwitch.
5319 </p>
5320
5321 <column name="other_config" key="dscp"
5322 type='{"type": "integer"}'>
5323 The Differentiated Service Code Point (DSCP) is specified using 6 bits
5324 in the Type of Service (TOS) field in the IP header. DSCP provides a
5325 mechanism to classify the network traffic and provide Quality of
5326 Service (QoS) on IP networks.
5327
5328 The DSCP value specified here is used when establishing the connection
5329 between the controller and the Open vSwitch. If no value is specified,
5330 a default value of 48 is chosen. Valid DSCP values must be in the
5331 range 0 to 63.
5332 </column>
5333 </group>
5334
5335
5336 <group title="Common Columns">
5337 The overall purpose of these columns is described under <code>Common
5338 Columns</code> at the beginning of this document.
5339
5340 <column name="external_ids"/>
5341 <column name="other_config"/>
5342 </group>
5343 </table>
5344
5345 <table name="Manager" title="OVSDB management connection.">
5346 <p>
5347 Configuration for a database connection to an Open vSwitch database
5348 (OVSDB) client.
5349 </p>
5350
5351 <p>
5352 This table primarily configures the Open vSwitch database
5353 (<code>ovsdb-server</code>), not the Open vSwitch switch
5354 (<code>ovs-vswitchd</code>). The switch does read the table to determine
5355 what connections should be treated as in-band.
5356 </p>
5357
5358 <p>
5359 The Open vSwitch database server can initiate and maintain active
5360 connections to remote clients. It can also listen for database
5361 connections.
5362 </p>
5363
5364 <group title="Core Features">
5365 <column name="target">
5366 <p>Connection method for managers.</p>
5367 <p>
5368 The following connection methods are currently supported:
5369 </p>
5370 <dl>
5371 <dt><code>ssl:<var>host</var></code>[<code>:<var>port</var></code>]</dt>
5372 <dd>
5373 <p>
5374 The specified SSL <var>port</var> on the host at the given
5375 <var>host</var>, which can either be a DNS name (if built with
5376 unbound library) or an IP address. The <ref table="Open_vSwitch"
5377 column="ssl"/> column in the <ref table="Open_vSwitch"/>
5378 table must point to a valid SSL configuration when this
5379 form is used.
5380 </p>
5381 <p>
5382 If <var>port</var> is not specified, it defaults to 6640.
5383 </p>
5384 <p>
5385 SSL support is an optional feature that is not always
5386 built as part of Open vSwitch.
5387 </p>
5388 </dd>
5389
5390 <dt><code>tcp:<var>host</var></code>[<code>:<var>port</var></code>]</dt>
5391 <dd>
5392 <p>
5393 The specified TCP <var>port</var> on the host at the given
5394 <var>host</var>, which can either be a DNS name (if built with
5395 unbound library) or an IP address (IPv4 or IPv6). If <var>host</var>
5396 is an IPv6 address, wrap it in square brackets, e.g.
5397 <code>tcp:[::1]:6640</code>.
5398 </p>
5399 <p>
5400 If <var>port</var> is not specified, it defaults to 6640.
5401 </p>
5402 </dd>
5403 <dt><code>pssl:</code>[<var>port</var>][<code>:<var>host</var></code>]</dt>
5404 <dd>
5405 <p>
5406 Listens for SSL connections on the specified TCP <var>port</var>.
5407 Specify 0 for <var>port</var> to have the kernel automatically
5408 choose an available port. If <var>host</var>, which can either
5409 be a DNS name (if built with unbound library) or an IP address,
5410 is specified, then connections are restricted to the resolved or
5411 specified local IP address (either IPv4 or IPv6 address). If
5412 <var>host</var> is an IPv6 address, wrap in square brackets,
5413 e.g. <code>pssl:6640:[::1]</code>. If <var>host</var> is not
5414 specified then it listens only on IPv4 (but not IPv6) addresses.
5415 The <ref table="Open_vSwitch" column="ssl"/> column in the <ref
5416 table="Open_vSwitch"/> table must point to a valid SSL
5417 configuration when this form is used.
5418 </p>
5419 <p>
5420 If <var>port</var> is not specified, it defaults to 6640.
5421 </p>
5422 <p>
5423 SSL support is an optional feature that is not always built as
5424 part of Open vSwitch.
5425 </p>
5426 </dd>
5427 <dt><code>ptcp:</code>[<var>port</var>][<code>:<var>host</var></code>]</dt>
5428 <dd>
5429 <p>
5430 Listens for connections on the specified TCP <var>port</var>.
5431 Specify 0 for <var>port</var> to have the kernel automatically
5432 choose an available port. If <var>host</var>, which can either
5433 be a DNS name (if built with unbound library) or an IP address,
5434 is specified, then connections are restricted to the resolved or
5435 specified local IP address (either IPv4 or IPv6 address). If
5436 <var>host</var> is an IPv6 address, wrap it in square brackets,
5437 e.g. <code>ptcp:6640:[::1]</code>. If <var>host</var> is not
5438 specified then it listens only on IPv4 addresses.
5439 </p>
5440 <p>
5441 If <var>port</var> is not specified, it defaults to 6640.
5442 </p>
5443 </dd>
5444 </dl>
5445 <p>When multiple managers are configured, the <ref column="target"/>
5446 values must be unique. Duplicate <ref column="target"/> values yield
5447 unspecified results.</p>
5448 </column>
5449
5450 <column name="connection_mode">
5451 <p>
5452 If it is specified, this setting must be one of the following strings
5453 that describes how Open vSwitch contacts this OVSDB client over the
5454 network:
5455 </p>
5456
5457 <dl>
5458 <dt><code>in-band</code></dt>
5459 <dd>
5460 In this mode, this connection's traffic travels over a bridge
5461 managed by Open vSwitch. With this setting, Open vSwitch allows
5462 traffic to and from the client regardless of the contents of the
5463 OpenFlow flow table. (Otherwise, Open vSwitch would never be able
5464 to connect to the client, because it did not have a flow to enable
5465 it.) This is the most common connection mode because it is not
5466 necessary to maintain two independent networks.
5467 </dd>
5468 <dt><code>out-of-band</code></dt>
5469 <dd>
5470 In this mode, the client's traffic uses a control network separate
5471 from that managed by Open vSwitch, that is, Open vSwitch does not
5472 use any of its own network devices to communicate with the client.
5473 The control network must be configured separately, before or after
5474 <code>ovs-vswitchd</code> is started.
5475 </dd>
5476 </dl>
5477
5478 <p>
5479 If not specified, the default is implementation-specific.
5480 </p>
5481 </column>
5482 </group>
5483
5484 <group title="Client Failure Detection and Handling">
5485 <column name="max_backoff">
5486 Maximum number of milliseconds to wait between connection attempts.
5487 Default is implementation-specific.
5488 </column>
5489
5490 <column name="inactivity_probe">
5491 Maximum number of milliseconds of idle time on connection to the client
5492 before sending an inactivity probe message. If Open vSwitch does not
5493 communicate with the client for the specified number of seconds, it
5494 will send a probe. If a response is not received for the same
5495 additional amount of time, Open vSwitch assumes the connection has been
5496 broken and attempts to reconnect. Default is implementation-specific.
5497 A value of 0 disables inactivity probes.
5498 </column>
5499 </group>
5500
5501 <group title="Status">
5502 <p>
5503 Key-value pair of <ref column="is_connected"/> is always updated.
5504 Other key-value pairs in the status columns may be updated depends
5505 on the <ref column="target"/> type.
5506 </p>
5507
5508 <p>
5509 When <ref column="target"/> specifies a connection method that
5510 listens for inbound connections (e.g. <code>ptcp:</code> or
5511 <code>punix:</code>), both <ref column="n_connections"/> and
5512 <ref column="is_connected"/> may also be updated while the
5513 remaining key-value pairs are omitted.
5514 </p>
5515
5516 <p>
5517 On the other hand, when <ref column="target"/> specifies an
5518 outbound connection, all key-value pairs may be updated, except
5519 the above-mentioned two key-value pairs associated with inbound
5520 connection targets. They are omitted.
5521 </p>
5522
5523 <column name="is_connected">
5524 <code>true</code> if currently connected to this manager,
5525 <code>false</code> otherwise.
5526 </column>
5527
5528 <column name="status" key="last_error">
5529 A human-readable description of the last error on the connection
5530 to the manager; i.e. <code>strerror(errno)</code>. This key
5531 will exist only if an error has occurred.
5532 </column>
5533
5534 <column name="status" key="state"
5535 type='{"type": "string", "enum": ["set", ["VOID", "BACKOFF", "CONNECTING", "ACTIVE", "IDLE"]]}'>
5536 <p>
5537 The state of the connection to the manager:
5538 </p>
5539 <dl>
5540 <dt><code>VOID</code></dt>
5541 <dd>Connection is disabled.</dd>
5542
5543 <dt><code>BACKOFF</code></dt>
5544 <dd>Attempting to reconnect at an increasing period.</dd>
5545
5546 <dt><code>CONNECTING</code></dt>
5547 <dd>Attempting to connect.</dd>
5548
5549 <dt><code>ACTIVE</code></dt>
5550 <dd>Connected, remote host responsive.</dd>
5551
5552 <dt><code>IDLE</code></dt>
5553 <dd>Connection is idle. Waiting for response to keep-alive.</dd>
5554 </dl>
5555 <p>
5556 These values may change in the future. They are provided only for
5557 human consumption.
5558 </p>
5559 </column>
5560
5561 <column name="status" key="sec_since_connect"
5562 type='{"type": "integer", "minInteger": 0}'>
5563 The amount of time since this manager last successfully connected
5564 to the database (in seconds). Value is empty if manager has never
5565 successfully connected.
5566 </column>
5567
5568 <column name="status" key="sec_since_disconnect"
5569 type='{"type": "integer", "minInteger": 0}'>
5570 The amount of time since this manager last disconnected from the
5571 database (in seconds). Value is empty if manager has never
5572 disconnected.
5573 </column>
5574
5575 <column name="status" key="locks_held">
5576 Space-separated list of the names of OVSDB locks that the connection
5577 holds. Omitted if the connection does not hold any locks.
5578 </column>
5579
5580 <column name="status" key="locks_waiting">
5581 Space-separated list of the names of OVSDB locks that the connection is
5582 currently waiting to acquire. Omitted if the connection is not waiting
5583 for any locks.
5584 </column>
5585
5586 <column name="status" key="locks_lost">
5587 Space-separated list of the names of OVSDB locks that the connection
5588 has had stolen by another OVSDB client. Omitted if no locks have been
5589 stolen from this connection.
5590 </column>
5591
5592 <column name="status" key="n_connections"
5593 type='{"type": "integer", "minInteger": 2}'>
5594 When <ref column="target"/> specifies a connection method that
5595 listens for inbound connections (e.g. <code>ptcp:</code> or
5596 <code>pssl:</code>) and more than one connection is actually active,
5597 the value is the number of active connections. Otherwise, this
5598 key-value pair is omitted.
5599 </column>
5600
5601 <column name="status" key="bound_port" type='{"type": "integer"}'>
5602 When <ref column="target"/> is <code>ptcp:</code> or
5603 <code>pssl:</code>, this is the TCP port on which the OVSDB server is
5604 listening. (This is particularly useful when <ref
5605 column="target"/> specifies a port of 0, allowing the kernel to
5606 choose any available port.)
5607 </column>
5608 </group>
5609
5610 <group title="Connection Parameters">
5611 <p>
5612 Additional configuration for a connection between the manager
5613 and the Open vSwitch Database.
5614 </p>
5615
5616 <column name="other_config" key="dscp"
5617 type='{"type": "integer"}'>
5618 The Differentiated Service Code Point (DSCP) is specified using 6 bits
5619 in the Type of Service (TOS) field in the IP header. DSCP provides a
5620 mechanism to classify the network traffic and provide Quality of
5621 Service (QoS) on IP networks.
5622
5623 The DSCP value specified here is used when establishing the connection
5624 between the manager and the Open vSwitch. If no value is specified, a
5625 default value of 48 is chosen. Valid DSCP values must be in the range
5626 0 to 63.
5627 </column>
5628 </group>
5629
5630 <group title="Common Columns">
5631 The overall purpose of these columns is described under <code>Common
5632 Columns</code> at the beginning of this document.
5633
5634 <column name="external_ids"/>
5635 <column name="other_config"/>
5636 </group>
5637 </table>
5638
5639 <table name="NetFlow">
5640 A NetFlow target. NetFlow is a protocol that exports a number of
5641 details about terminating IP flows, such as the principals involved
5642 and duration.
5643
5644 <column name="targets">
5645 NetFlow targets in the form
5646 <code><var>ip</var>:<var>port</var></code>. The <var>ip</var>
5647 must be specified numerically, not as a DNS name.
5648 </column>
5649
5650 <column name="engine_id">
5651 Engine ID to use in NetFlow messages. Defaults to datapath index
5652 if not specified.
5653 </column>
5654
5655 <column name="engine_type">
5656 Engine type to use in NetFlow messages. Defaults to datapath
5657 index if not specified.
5658 </column>
5659
5660 <column name="active_timeout">
5661 <p>
5662 The interval at which NetFlow records are sent for flows that
5663 are still active, in seconds. A value of <code>0</code>
5664 requests the default timeout (currently 600 seconds); a value
5665 of <code>-1</code> disables active timeouts.
5666 </p>
5667
5668 <p>
5669 The NetFlow passive timeout, for flows that become inactive,
5670 is not configurable. It will vary depending on the Open
5671 vSwitch version, the forms and contents of the OpenFlow flow
5672 tables, CPU and memory usage, and network activity. A typical
5673 passive timeout is about a second.
5674 </p>
5675 </column>
5676
5677 <column name="add_id_to_interface">
5678 <p>If this column's value is <code>false</code>, the ingress and egress
5679 interface fields of NetFlow flow records are derived from OpenFlow port
5680 numbers. When it is <code>true</code>, the 7 most significant bits of
5681 these fields will be replaced by the least significant 7 bits of the
5682 engine id. This is useful because many NetFlow collectors do not
5683 expect multiple switches to be sending messages from the same host, so
5684 they do not store the engine information which could be used to
5685 disambiguate the traffic.</p>
5686 <p>When this option is enabled, a maximum of 508 ports are supported.</p>
5687 </column>
5688
5689 <group title="Common Columns">
5690 The overall purpose of these columns is described under <code>Common
5691 Columns</code> at the beginning of this document.
5692
5693 <column name="external_ids"/>
5694 </group>
5695 </table>
5696
5697 <table name="Datapath">
5698 <p>
5699 Configuration for a datapath within <ref table="Open_vSwitch"/>.
5700 </p>
5701 <p>
5702 A datapath is responsible for providing the packet handling in Open
5703 vSwitch. There are two primary datapath implementations used by
5704 Open vSwitch: kernel and userspace. Kernel datapath
5705 implementations are available for Linux and Hyper-V, and selected
5706 as <code>system</code> in the <ref column="datapath_type"/> column
5707 of the <ref table="Bridge"/> table. The userspace datapath is used
5708 by DPDK and AF-XDP, and is selected as <code>netdev</code> in the
5709 <ref column="datapath_type"/> column of the <ref table="Bridge"/>
5710 table.
5711 </p>
5712 <p>
5713 A datapath of a particular type is shared by all the bridges that use
5714 that datapath. Thus, configurations applied to this table affect
5715 all bridges that use this datapath.
5716 </p>
5717
5718 <column name="datapath_version">
5719 <p>
5720 Reports the version number of the Open vSwitch datapath in use.
5721 This allows management software to detect and report discrepancies
5722 between Open vSwitch userspace and datapath versions. (The <ref
5723 column="ovs_version" table="Open_vSwitch"/> column in the <ref
5724 table="Open_vSwitch"/> reports the Open vSwitch userspace version.)
5725 The version reported depends on the datapath in use:
5726 </p>
5727
5728 <ul>
5729 <li>
5730 When the kernel module included in the Open vSwitch source tree is
5731 used, this column reports the Open vSwitch version from which the
5732 module was taken.
5733 </li>
5734
5735 <li>
5736 When the kernel module that is part of the upstream Linux kernel is
5737 used, this column reports <code>&lt;unknown&gt;</code>.
5738 </li>
5739
5740 <li>
5741 When the datapath is built into the <code>ovs-vswitchd</code>
5742 binary, this column reports <code>&lt;built-in&gt;</code>. A
5743 built-in datapath is by definition the same version as the rest of
5744 the Open vSwitch userspace.
5745 </li>
5746
5747 <li>
5748 Other datapaths (such as the Hyper-V kernel datapath) currently
5749 report <code>&lt;unknown&gt;</code>.
5750 </li>
5751 </ul>
5752
5753 <p>
5754 A version discrepancy between <code>ovs-vswitchd</code> and the
5755 datapath in use is not normally cause for alarm. The Open vSwitch
5756 kernel datapaths for Linux and Hyper-V, in particular, are designed
5757 for maximum inter-version compatibility: any userspace version works
5758 with with any kernel version. Some reasons do exist to insist on
5759 particular user/kernel pairings. First, newer kernel versions add
5760 new features, that can only be used by new-enough userspace, e.g.
5761 VXLAN tunneling requires certain minimal userspace and kernel
5762 versions. Second, as an extension to the first reason, some newer
5763 kernel versions add new features for enhancing performance that only
5764 new-enough userspace versions can take advantage of.
5765 </p>
5766 </column>
5767
5768 <column name="ct_zones">
5769 Configuration for connection tracking zones. Each pair maps from a
5770 zone id to a configuration for that zone. Zone <code>0</code> applies
5771 to the default zone (ie, the one used if a zone is not specified in
5772 connection tracking-related OpenFlow matches and actions).
5773 </column>
5774
5775 <group title="Capabilities">
5776 <p>
5777 The <ref column="capabilities"/> column reports a datapath's
5778 features. For the <code>netdev</code> datapath, the
5779 capabilities are fixed for a given version of Open vSwitch
5780 because this datapath is built into the
5781 <code>ovs-vswitchd</code> binary. The Linux kernel and
5782 Windows and other datapaths, which are external to OVS
5783 userspace, can vary in version and capabilities independently
5784 from <code>ovs-vswitchd</code>.
5785 </p>
5786
5787 <p>
5788 Some of these features indicate whether higher-level Open vSwitch
5789 features are available. For example, OpenFlow features for
5790 connection-tracking are available only when <ref column="capabilities"
5791 key="ct_state"/> is <code>true</code>. A controller that wishes to
5792 determine whether a feature is supported could, therefore, consult the
5793 relevant capabilities in this table. However, as a general rule, it is
5794 better for a controller to try to use the higher-level feature and use
5795 the result as an indication of support, since the low-level
5796 capabilities are more likely to shift over time than the high-level
5797 features that rely on them.
5798 </p>
5799
5800 <column name="capabilities" key="max_vlan_headers"
5801 type='{"type": "integer", "minInteger": 0}'>
5802 Number of 802.1q VLAN headers supported by the datapath, as probed by
5803 the <code>ovs-vswitchd</code> slow path. If the datapath supports more
5804 VLAN headers than the slow path, this reports the slow path's limit.
5805 The value of <ref column="other-config" key="vlan-limit"/> in the <ref
5806 table="Open_vSwitch"/> table does not influence the number reported
5807 here.
5808 </column>
5809 <column name="capabilities" key="recirc" type='{"type": "boolean"}'>
5810 If this is true, then the datapath supports recirculation,
5811 specifically OVS_KEY_ATTR_RECIRC_ID. Recirculation enables
5812 higher performance for MPLS and active-active load balancing
5813 bonding modes.
5814 </column>
5815 <group title="Connection-Tracking Capabilities">
5816 <p>
5817 These capabilities are granular because Open vSwitch and its
5818 datapaths added support for connection tracking over several
5819 releases, with features added individually over that time.
5820 </p>
5821
5822 <column name="capabilities" key="ct_state" type='{"type": "boolean"}'>
5823 <p>
5824 If true, datapath supports OVS_KEY_ATTR_CT_STATE, which indicates
5825 support for the bits in the OpenFlow <code>ct_state</code> field
5826 (see <code>ovs-fields</code>(7)) other than <code>snat</code> and
5827 <code>dnat</code>, which have a separate capability.
5828 </p>
5829
5830 <p>
5831 If this is false, the datapath does not support connection-tracking
5832 at all and the remaining connection-tracking capabilities should
5833 all be false. In this case, Open vSwitch will reject flows that
5834 match on the <code>ct_state</code> field or use the <code>ct</code>
5835 action.
5836 </p>
5837 </column>
5838 <column name="capabilities" key="ct_state_nat"
5839 type='{"type": "boolean"}'>
5840 <p>
5841 If true, it means that the datapath supports the <code>snat</code>
5842 and <code>dnat</code> flags in the OpenFlow <code>ct_state</code>
5843 field. The <code>ct_state</code> capability must be true for this
5844 to make sense.
5845 </p>
5846
5847 <p>
5848 If false, Open vSwitch will reject flows that match on the
5849 <code>snat</code> or <code>dnat</code> bits in
5850 <code>ct_state</code> or use <code>nat</code> in the
5851 <code>ct</code> action.
5852 </p>
5853 </column>
5854 <column name="capabilities" key="ct_zone" type='{"type": "boolean"}'>
5855 If true, datapath supports OVS_KEY_ATTR_CT_ZONE. If false, Open
5856 vSwitch rejects flows that match on the <code>ct_zone</code> field or
5857 that specify a nonzero zone or a zone field on the <code>ct</code>
5858 action.
5859 </column>
5860 <column name="capabilities" key="ct_mark" type='{"type": "boolean"}'>
5861 If true, datapath supports OVS_KEY_ATTR_CT_MARK. If false, Open
5862 vSwitch rejects flows that match on the <code>ct_mark</code> field or
5863 that set <code>ct_mark</code> in the <code>ct</code> action.
5864 </column>
5865 <column name="capabilities" key="ct_label" type='{"type": "boolean"}'>
5866 If true, datapath supports OVS_KEY_ATTR_CT_LABEL. If false, Open
5867 vSwitch rejects flows that match on the <code>ct_label</code> field
5868 or that set <code>ct_label</code> in the <code>ct</code> action.
5869 </column>
5870 <column name="capabilities" key="ct_orig_tuple"
5871 type='{"type": "boolean"}'>
5872 <p>
5873 If true, the datapath supports matching the 5-tuple from the
5874 connection's original direction for IPv4 traffic. If false, Open
5875 vSwitch rejects flows that match on <code>ct_nw_src</code> or
5876 <code>ct_nw_dst</code>, that use the <code>ct</code> feature of the
5877 <code>resubmit</code> action, or the <code>force</code> keyword in
5878 the <code>ct</code> action. (The latter isn't tied to connection
5879 tracking support of original tuples in any technical way. They are
5880 conflated because all current datapaths implemented the two
5881 features at the same time.)
5882 </p>
5883
5884 <p>
5885 If this and <ref column="capabilities" key="ct_orig_tuple6"/> are
5886 both false, Open vSwitch rejects flows that match on
5887 <code>ct_nw_proto</code>, <code>ct_tp_src</code>, or
5888 <code>ct_tp_dst</code>.
5889 </p>
5890 </column>
5891 <column name="capabilities" key="ct_orig_tuple6"
5892 type='{"type": "boolean"}'>
5893 If true, the datapath supports matching the 5-tuple from the
5894 connection's original direction for IPv6 traffic. If false, Open
5895 vSwitch rejects flows that match on <code>ct_ipv6_src</code> or
5896 <code>ct_ipv6_dst</code>.
5897 </column>
5898 </group>
5899 <column name="capabilities" key="masked_set_action"
5900 type='{"type": "boolean"}'>
5901 True if the datapath supports masked data in OVS_ACTION_ATTR_SET
5902 actions. Masked data can improve performance by allowing megaflows to
5903 match on fewer fields.
5904 </column>
5905 <column name="capabilities" key="tnl_push_pop"
5906 type='{"type": "boolean"}'>
5907 True if the datapath supports tnl_push and pop actions. This is a
5908 prerequisite for a datapath to support native tunneling.
5909 </column>
5910 <column name="capabilities" key="ufid" type='{"type": "boolean"}'>
5911 True if the datapath supports OVS_FLOW_ATTR_UFID. UFID support
5912 improves revalidation performance by transferring less data between
5913 the slow path and the datapath.
5914 </column>
5915 <column name="capabilities" key="trunc" type='{"type": "boolean"}'>
5916 True if the datapath supports OVS_ACTION_ATTR_TRUNC action. If false,
5917 the <code>output</code> action with packet truncation requires every
5918 packet to be sent to the Open vSwitch slow path, which is likely to
5919 make it too slow for mirroring traffic in bulk.
5920 </column>
5921 <column name="capabilities" key="nd_ext" type='{"type": "boolean"}'>
5922 True if the datapath supports OVS_KEY_ATTR_ND_EXTENSIONS to match on
5923 ICMPv6 "ND reserved" and "ND option type" header fields. If false,
5924 the datapath reports error if the feature is used.
5925 </column>
5926 <group title="Clone Actions">
5927 <p>
5928 When Open vSwitch translates actions from OpenFlow into the datapath
5929 representation, some of the datapath actions may modify the packet or
5930 have other side effects that later datapath actions can't undo. The
5931 OpenFlow <code>ct</code>, <code>meter</code>, <code>output</code>
5932 with truncation, <code>encap</code>, <code>decap</code>, and
5933 <code>dec_nsh_ttl</code> actions fall into this category. Often,
5934 this is not a problem because nothing later on needs the original
5935 packet.
5936 </p>
5937
5938 <p>
5939 Such actions can, however, occur in circumstances where the
5940 translation does require the original packet. For example, an
5941 OpenFlow <code>output</code> action might direct a packet to a patch
5942 port, which might in turn lead to a <code>ct</code> action that NATs
5943 the packet (which cannot be undone), and then afterward when control
5944 flow pops back across the patch port some other action might need to
5945 act on the original packet.
5946 </p>
5947
5948 <p>
5949 Open vSwitch has two different ways to implement this ``save and
5950 restore'' via datapath actions. These capabilities indicate which
5951 one Open vSwitch will choose. When neither is available, Open
5952 vSwitch simply fails in situations that require this feature.
5953 </p>
5954
5955 <column name="capabilities" key="clone" type='{"type": "boolean"}'>
5956 <p>
5957 True if the datapath supports OVS_ACTION_ATTR_CLONE action. This
5958 is the preferred option for saving and restoring packets, since it
5959 is intended for the purpose, but old datapaths do not support it.
5960 Open vSwitch will use it whenever it is available.
5961 </p>
5962
5963 <p>
5964 (The OpenFlow <code>clone</code> action does not always yield a
5965 OVS_ACTION_ATTR_CLONE action. It only does so when the datapath
5966 supports it and the <code>clone</code> brackets actions that
5967 otherwise cannot be undone.)
5968 </p>
5969 </column>
5970 <column name="capabilities" key="sample_nesting"
5971 type='{"type": "integer", "minInteger": 0}'>
5972 Maximum level of nesting allowed by OVS_ACTION_ATTR_SAMPLE action.
5973 Open vSwitch misuses this action for saving and restoring packets
5974 when the datapath supports more than 3 levels of nesting and
5975 OVS_ACTION_ATTR_CLONE is not available.
5976 </column>
5977 </group>
5978 <column name="capabilities" key="ct_eventmask"
5979 type='{"type": "boolean"}'>
5980 True if the datapath's OVS_ACTION_ATTR_CT action implements the
5981 OVS_CT_ATTR_EVENTMASK attribute. When this is true, Open vSwitch uses
5982 the event mask feature to limit the kinds of events reported to
5983 conntrack update listeners. When Open vSwitch doesn't limit the event
5984 mask, listeners receive reports of numerous usually unimportant events,
5985 such as TCP state machine changes, which can waste CPU time.
5986 </column>
5987 <column name="capabilities" key="ct_clear" type='{"type": "boolean"}'>
5988 True if the datapath supports OVS_ACTION_ATTR_CT_CLEAR action.
5989 If false, the OpenFlow <code>ct_clear</code> action has no effect
5990 on the datapath.
5991 </column>
5992 <column name="capabilities" key="max_hash_alg"
5993 type='{"type": "integer", "minInteger": 0}'>
5994 Highest supported dp_hash algorithm. This allows Open vSwitch to avoid
5995 requesting a packet hash that the datapath does not support.
5996 </column>
5997 <column name="capabilities" key="check_pkt_len"
5998 type='{"type": "boolean"}'>
5999 True if the datapath supports OVS_ACTION_ATTR_CHECK_PKT_LEN. If false,
6000 Open vSwitch implements the <code>check_pkt_larger</code> action by
6001 sending every packet through the Open vSwitch slow path, which is
6002 likely to make it too slow for handling traffic in bulk.
6003 </column>
6004 <column name="capabilities" key="ct_timeout" type='{"type": "boolean"}'>
6005 True if the datapath supports OVS_CT_ATTR_TIMEOUT in the
6006 OVS_ACTION_ATTR_CT action. If false, Open vswitch cannot implement
6007 timeout policies based on connection tracking zones, as configured
6008 through the <code>CT_Timeout_Policy</code> table.
6009 </column>
6010 <column name="capabilities" key="explicit_drop_action"
6011 type='{"type": "boolean"}'>
6012 True if the datapath supports OVS_ACTION_ATTR_DROP. If false,
6013 explicit drop action will not be sent to the datapath.
6014 </column>
6015 </group>
6016
6017 <group title="Common Columns">
6018 The overall purpose of these columns is described under <code>Common
6019 Columns</code> at the beginning of this document.
6020
6021 <column name="external_ids"/>
6022 </group>
6023 </table>
6024
6025 <table name="CT_Zone">
6026 Connection tracking zone configuration
6027
6028 <column name="timeout_policy">
6029 Connection tracking timeout policy for this zone. If a timeout policy
6030 is not specified, it defaults to the timeout policy in the system.
6031 </column>
6032
6033 <group title="Common Columns">
6034 The overall purpose of these columns is described under <code>Common
6035 Columns</code> at the beginning of this document.
6036
6037 <column name="external_ids"/>
6038 </group>
6039 </table>
6040
6041 <table name="CT_Timeout_Policy">
6042 Connection tracking timeout policy configuration
6043
6044 <group title="Timeouts">
6045 <column name="timeouts">
6046 The <code>timeouts</code> column contains key-value pairs used
6047 to configure connection tracking timeouts in a datapath.
6048 Key-value pairs that are not supported by a datapath are
6049 ignored. The timeout value is in seconds.
6050 </column>
6051
6052 <group title="TCP Timeouts">
6053 <column name="timeouts" key="tcp_syn_sent">
6054 The timeout for the connection after the first TCP SYN packet has
6055 been seen by conntrack.
6056 </column>
6057
6058 <column name="timeouts" key="tcp_syn_recv">
6059 The timeout of the connection after the first TCP SYN-ACK packet
6060 has been seen by conntrack.
6061 </column>
6062
6063 <column name="timeouts" key="tcp_established">
6064 The timeout of the connection after the connection has been fully
6065 established.
6066 </column>
6067
6068 <column name="timeouts" key="tcp_fin_wait">
6069 The timeout of the connection after the first TCP FIN packet
6070 has been seen by conntrack.
6071 </column>
6072
6073 <column name="timeouts" key="tcp_close_wait">
6074 The timeout of the connection after the first TCP ACK packet
6075 has been seen after it receives TCP FIN packet. This timeout
6076 is only supported by the Linux kernel datapath.
6077 </column>
6078
6079 <column name="timeouts" key="tcp_last_ack">
6080 The timeout of the connection after TCP FIN packets have been
6081 seen by conntrack from both directions. This timeout is only
6082 supported by the Linux kernel datapath.
6083 </column>
6084
6085 <column name="timeouts" key="tcp_time_wait">
6086 The timeout of the connection after conntrack has seen the
6087 TCP ACK packet for the second TCP FIN packet.
6088 </column>
6089
6090 <column name="timeouts" key="tcp_close">
6091 The timeout of the connection after the first TCP RST packet
6092 has been seen by conntrack.
6093 </column>
6094
6095 <column name="timeouts" key="tcp_syn_sent2">
6096 The timeout of the connection when only a TCP SYN packet has been
6097 seen by conntrack from both directions (simultaneous open).
6098 This timeout is only supported by the Linux kernel datapath.
6099 </column>
6100
6101 <column name="timeouts" key="tcp_retransmit">
6102 The timeout of the connection when it exceeds the maximum
6103 number of retransmissions. This timeout is only supported by
6104 the Linux kernel datapath.
6105 </column>
6106
6107 <column name="timeouts" key="tcp_unack">
6108 The timeout of the connection when non-SYN packets create an
6109 established connection in TCP loose tracking mode. This timeout
6110 is only supported by the Linux kernel datapath.
6111 </column>
6112 </group>
6113
6114 <group title="UDP Timeouts">
6115 <column name="timeouts" key="udp_first">
6116 The timeout of the connection after the first UDP packet has
6117 been seen by conntrack. This timeout is only supported by the
6118 userspace datapath.
6119 </column>
6120
6121 <column name="timeouts" key="udp_single">
6122 The timeout of the connection when conntrack only seen UDP
6123 packet from the source host, but the destination host has never
6124 sent one back.
6125 </column>
6126
6127 <column name="timeouts" key="udp_multiple">
6128 The timeout of the connection when UDP packets have been seen in
6129 both directions.
6130 </column>
6131 </group>
6132
6133 <group title="ICMP Timeouts">
6134 <column name="timeouts" key="icmp_first">
6135 The timeout of the connection after the first ICMP packet has
6136 been seen by conntrack.
6137 </column>
6138
6139 <column name="timeouts" key="icmp_reply">
6140 The timeout of the connection after an ICMP error is replied in
6141 response to an ICMP packet. This timeout is only supported by
6142 the userspace datapath.
6143 </column>
6144 </group>
6145 </group>
6146
6147 <group title="Common Columns">
6148 The overall purpose of these columns is described under <code>Common
6149 Columns</code> at the beginning of this document.
6150
6151 <column name="external_ids"/>
6152 </group>
6153 </table>
6154
6155 <table name="SSL">
6156 SSL configuration for an Open_vSwitch.
6157
6158 <column name="private_key">
6159 Name of a PEM file containing the private key used as the switch's
6160 identity for SSL connections to the controller.
6161 </column>
6162
6163 <column name="certificate">
6164 Name of a PEM file containing a certificate, signed by the
6165 certificate authority (CA) used by the controller and manager,
6166 that certifies the switch's private key, identifying a trustworthy
6167 switch.
6168 </column>
6169
6170 <column name="ca_cert">
6171 Name of a PEM file containing the CA certificate used to verify
6172 that the switch is connected to a trustworthy controller.
6173 </column>
6174
6175 <column name="bootstrap_ca_cert">
6176 If set to <code>true</code>, then Open vSwitch will attempt to
6177 obtain the CA certificate from the controller on its first SSL
6178 connection and save it to the named PEM file. If it is successful,
6179 it will immediately drop the connection and reconnect, and from then
6180 on all SSL connections must be authenticated by a certificate signed
6181 by the CA certificate thus obtained. <em>This option exposes the
6182 SSL connection to a man-in-the-middle attack obtaining the initial
6183 CA certificate.</em> It may still be useful for bootstrapping.
6184 </column>
6185
6186 <group title="Common Columns">
6187 The overall purpose of these columns is described under <code>Common
6188 Columns</code> at the beginning of this document.
6189
6190 <column name="external_ids"/>
6191 </group>
6192 </table>
6193
6194 <table name="sFlow">
6195 <p>A set of sFlow(R) targets. sFlow is a protocol for remote
6196 monitoring of switches.</p>
6197
6198 <column name="agent">
6199 <p>
6200 Determines the agent address, that is, the IP address reported to
6201 collectors as the source of the sFlow data. It may be an IP address or
6202 the name of a network device. In the latter case, the network device's
6203 IP address is used,
6204 </p>
6205
6206 <p>
6207 If not specified, the agent device is figured from the first target
6208 address and the routing table. If the routing table does not contain a
6209 route to the target, the IP address defaults to the <ref
6210 table="Controller" column="local_ip"/> in the collector's <ref
6211 table="Controller"/>.
6212 </p>
6213
6214 <p>
6215 If an agent IP address cannot be determined, sFlow is disabled.
6216 </p>
6217 </column>
6218
6219 <column name="header">
6220 Number of bytes of a sampled packet to send to the collector.
6221 If not specified, the default is 128 bytes.
6222 </column>
6223
6224 <column name="polling">
6225 Polling rate in seconds to send port statistics to the collector.
6226 If not specified, defaults to 30 seconds.
6227 </column>
6228
6229 <column name="sampling">
6230 Rate at which packets should be sampled and sent to the collector.
6231 If not specified, defaults to 400, which means one out of 400
6232 packets, on average, will be sent to the collector.
6233 </column>
6234
6235 <column name="targets">
6236 sFlow targets in the form
6237 <code><var>ip</var>:<var>port</var></code>.
6238 </column>
6239
6240 <group title="Common Columns">
6241 The overall purpose of these columns is described under <code>Common
6242 Columns</code> at the beginning of this document.
6243
6244 <column name="external_ids"/>
6245 </group>
6246 </table>
6247
6248 <table name="IPFIX">
6249 <p>Configuration for sending packets to IPFIX collectors.</p>
6250
6251 <p>
6252 IPFIX is a protocol that exports a number of details about flows. The
6253 IPFIX implementation in Open vSwitch samples packets at a configurable
6254 rate, extracts flow information from those packets, optionally caches and
6255 aggregates the flow information, and sends the result to one or more
6256 collectors.
6257 </p>
6258
6259 <p>
6260 IPFIX in Open vSwitch can be configured two different ways:
6261 </p>
6262
6263 <ul>
6264 <li>
6265 With <em>per-bridge sampling</em>, Open vSwitch performs IPFIX sampling
6266 automatically on all packets that pass through a bridge. To configure
6267 per-bridge sampling, create an <ref table="IPFIX"/> record and point a
6268 <ref table="Bridge"/> table's <ref table="Bridge" column="ipfix"/>
6269 column to it. The <ref table="Flow_Sample_Collector_Set"/> table is
6270 not used for per-bridge sampling.
6271 </li>
6272
6273 <li>
6274 <p>
6275 With <em>flow-based sampling</em>, <code>sample</code> actions in the
6276 OpenFlow flow table drive IPFIX sampling. See
6277 <code>ovs-actions</code>(7) for a description of the
6278 <code>sample</code> action.
6279 </p>
6280
6281 <p>
6282 Flow-based sampling also requires database configuration: create a
6283 <ref table="IPFIX"/> record that describes the IPFIX configuration
6284 and a <ref table="Flow_Sample_Collector_Set"/> record that points to
6285 the <ref table="Bridge"/> whose flow table holds the
6286 <code>sample</code> actions and to <ref table="IPFIX"/> record. The
6287 <ref table="Bridge" column="ipfix"/> in the <ref table="Bridge"/>
6288 table is not used for flow-based sampling.
6289 </p>
6290 </li>
6291 </ul>
6292
6293 <column name="targets">
6294 IPFIX target collectors in the form
6295 <code><var>ip</var>:<var>port</var></code>.
6296 </column>
6297
6298 <column name="cache_active_timeout">
6299 The maximum period in seconds for which an IPFIX flow record is
6300 cached and aggregated before being sent. If not specified,
6301 defaults to 0. If 0, caching is disabled.
6302 </column>
6303
6304 <column name="cache_max_flows">
6305 The maximum number of IPFIX flow records that can be cached at a
6306 time. If not specified, defaults to 0. If 0, caching is
6307 disabled.
6308 </column>
6309
6310 <column name="other_config" key="enable-tunnel-sampling"
6311 type='{"type": "boolean"}'>
6312 <p>
6313 Set to <code>true</code> to enable sampling and reporting tunnel
6314 header 7-tuples in IPFIX flow records. Tunnel sampling is enabled
6315 by default.
6316 </p>
6317
6318 <p>
6319 The following enterprise entities report the sampled tunnel info:
6320 </p>
6321
6322 <dl>
6323 <dt>tunnelType:</dt>
6324 <dd>
6325 <p>ID: 891, and enterprise ID 6876 (VMware).</p>
6326 <p>type: unsigned 8-bit integer.</p>
6327 <p>data type semantics: identifier.</p>
6328 <p>description: Identifier of the layer 2 network overlay network
6329 encapsulation type: 0x01 VxLAN, 0x02 GRE, 0x03 LISP, 0x07 GENEVE.</p>
6330 </dd>
6331 <dt>tunnelKey:</dt>
6332 <dd>
6333 <p>ID: 892, and enterprise ID 6876 (VMware).</p>
6334 <p>type: variable-length octetarray.</p>
6335 <p>data type semantics: identifier.</p>
6336 <p>description: Key which is used for identifying an individual
6337 traffic flow within a VxLAN (24-bit VNI), GENEVE (24-bit VNI),
6338 GRE (32-bit key), or LISP (24-bit instance ID) tunnel. The
6339 key is encoded in this octetarray as a 3-, 4-, or 8-byte integer
6340 ID in network byte order.</p>
6341 </dd>
6342 <dt>tunnelSourceIPv4Address:</dt>
6343 <dd>
6344 <p>ID: 893, and enterprise ID 6876 (VMware).</p>
6345 <p>type: unsigned 32-bit integer.</p>
6346 <p>data type semantics: identifier.</p>
6347 <p>description: The IPv4 source address in the tunnel IP packet
6348 header.</p>
6349 </dd>
6350 <dt>tunnelDestinationIPv4Address:</dt>
6351 <dd>
6352 <p>ID: 894, and enterprise ID 6876 (VMware).</p>
6353 <p>type: unsigned 32-bit integer.</p>
6354 <p>data type semantics: identifier.</p>
6355 <p>description: The IPv4 destination address in the tunnel IP
6356 packet header.</p>
6357 </dd>
6358 <dt>tunnelProtocolIdentifier:</dt>
6359 <dd>
6360 <p>ID: 895, and enterprise ID 6876 (VMware).</p>
6361 <p>type: unsigned 8-bit integer.</p>
6362 <p>data type semantics: identifier.</p>
6363 <p>description: The value of the protocol number in the tunnel
6364 IP packet header. The protocol number identifies the tunnel IP
6365 packet payload type.</p>
6366 </dd>
6367 <dt>tunnelSourceTransportPort:</dt>
6368 <dd>
6369 <p>ID: 896, and enterprise ID 6876 (VMware).</p>
6370 <p>type: unsigned 16-bit integer.</p>
6371 <p>data type semantics: identifier.</p>
6372 <p>description: The source port identifier in the tunnel transport
6373 header. For the transport protocols UDP, TCP, and SCTP, this is
6374 the source port number given in the respective header.</p>
6375 </dd>
6376 <dt>tunnelDestinationTransportPort:</dt>
6377 <dd>
6378 <p>ID: 897, and enterprise ID 6876 (VMware).</p>
6379 <p>type: unsigned 16-bit integer.</p>
6380 <p>data type semantics: identifier.</p>
6381 <p>description: The destination port identifier in the tunnel
6382 transport header. For the transport protocols UDP, TCP, and SCTP,
6383 this is the destination port number given in the respective header.
6384 </p>
6385 </dd>
6386 </dl>
6387
6388 <p>
6389 Before Open vSwitch 2.5.90, <ref column="other_config"
6390 key="enable-tunnel-sampling"/> was only supported with per-bridge
6391 sampling, and ignored otherwise. Open vSwitch 2.5.90 and later support
6392 <ref column="other_config" key="enable-tunnel-sampling"/> for
6393 per-bridge and per-flow sampling.
6394 </p>
6395 </column>
6396
6397 <column name="other_config" key="virtual_obs_id"
6398 type='{"type": "string"}'>
6399 <p>
6400 A string that accompanies each IPFIX flow record. Its intended use is
6401 for the ``virtual observation ID,'' an identifier of a virtual
6402 observation point that is locally unique in a virtual network. It
6403 describes a location in the virtual network where IP packets can be
6404 observed. The maximum length is 254 bytes. If not specified, the
6405 field is omitted from the IPFIX flow record.
6406 </p>
6407
6408 <p>
6409 The following enterprise entity reports the specified virtual
6410 observation ID:
6411 </p>
6412
6413 <dl>
6414 <dt>virtualObsID:</dt>
6415 <dd>
6416 <p>ID: 898, and enterprise ID 6876 (VMware).</p>
6417 <p>type: variable-length string.</p>
6418 <p>data type semantics: identifier.</p>
6419 <p>description: A virtual observation domain ID that is locally
6420 unique in a virtual network.
6421 </p>
6422 </dd>
6423 </dl>
6424
6425 <p>
6426 This feature was introduced in Open vSwitch 2.5.90.
6427 </p>
6428 </column>
6429
6430 <group title="Per-Bridge Sampling">
6431 <p>
6432 These values affect only per-bridge sampling. See above for a
6433 description of the differences between per-bridge and flow-based
6434 sampling.
6435 </p>
6436
6437 <column name="sampling">
6438 The rate at which packets should be sampled and sent to each target
6439 collector. If not specified, defaults to 400, which means one out of
6440 400 packets, on average, will be sent to each target collector.
6441 </column>
6442
6443 <column name="obs_domain_id">
6444 The IPFIX Observation Domain ID sent in each IPFIX packet. If not
6445 specified, defaults to 0.
6446 </column>
6447
6448 <column name="obs_point_id">
6449 The IPFIX Observation Point ID sent in each IPFIX flow record. If not
6450 specified, defaults to 0.
6451 </column>
6452
6453 <column name="other_config" key="enable-input-sampling"
6454 type='{"type": "boolean"}'>
6455 By default, Open vSwitch samples and reports flows at bridge port input
6456 in IPFIX flow records. Set this column to <code>false</code> to
6457 disable input sampling.
6458 </column>
6459
6460 <column name="other_config" key="enable-output-sampling"
6461 type='{"type": "boolean"}'>
6462 By default, Open vSwitch samples and reports flows at bridge port
6463 output in IPFIX flow records. Set this column to <code>false</code> to
6464 disable output sampling.
6465 </column>
6466 </group>
6467
6468 <group title="Common Columns">
6469 The overall purpose of these columns is described under <code>Common
6470 Columns</code> at the beginning of this document.
6471
6472 <column name="external_ids"/>
6473 </group>
6474 </table>
6475
6476 <table name="Flow_Sample_Collector_Set">
6477 <p>
6478 A set of IPFIX collectors of packet samples generated by OpenFlow
6479 <code>sample</code> actions. This table is used only for IPFIX
6480 flow-based sampling, not for per-bridge sampling (see the <ref
6481 table="IPFIX"/> table for a description of the two forms).
6482 </p>
6483
6484 <column name="id">
6485 The ID of this collector set, unique among the bridge's
6486 collector sets, to be used as the <code>collector_set_id</code>
6487 in OpenFlow <code>sample</code> actions.
6488 </column>
6489
6490 <column name="bridge">
6491 The bridge into which OpenFlow <code>sample</code> actions can
6492 be added to send packet samples to this set of IPFIX collectors.
6493 </column>
6494
6495 <column name="ipfix">
6496 Configuration of the set of IPFIX collectors to send one flow
6497 record per sampled packet to.
6498 </column>
6499
6500 <group title="Common Columns">
6501 The overall purpose of these columns is described under <code>Common
6502 Columns</code> at the beginning of this document.
6503
6504 <column name="external_ids"/>
6505 </group>
6506 </table>
6507
6508 <table name="AutoAttach">
6509 <p>
6510 Auto Attach configuration within a bridge. The IETF Auto-Attach SPBM
6511 draft standard describes a compact method of using IEEE 802.1AB Link
6512 Layer Discovery Protocol (LLDP) together with a IEEE 802.1aq Shortest
6513 Path Bridging (SPB) network to automatically attach network devices
6514 to individual services in a SPB network. The intent here is to allow
6515 network applications and devices using OVS to be able to easily take
6516 advantage of features offered by industry standard SPB networks.
6517 </p>
6518
6519 <p>
6520 Auto Attach (AA) uses LLDP to communicate between a directly connected
6521 Auto Attach Client (AAC) and Auto Attach Server (AAS). The LLDP protocol
6522 is extended to add two new Type-Length-Value tuples (TLVs). The first
6523 new TLV supports the ongoing discovery of directly connected AA
6524 correspondents. Auto Attach operates by regularly transmitting AA
6525 discovery TLVs between the AA client and AA server. By exchanging these
6526 discovery messages, both the AAC and AAS learn the system name and
6527 system description of their peer. In the OVS context, OVS operates as
6528 the AA client and the AA server resides on a switch at the edge of the
6529 SPB network.
6530 </p>
6531
6532 <p>
6533 Once AA discovery has been completed the AAC then uses the second new TLV
6534 to deliver identifier mappings from the AAC to the AAS. A primary feature
6535 of Auto Attach is to facilitate the mapping of VLANs defined outside the
6536 SPB network onto service ids (ISIDs) defined within the SPM network. By
6537 doing so individual external VLANs can be mapped onto specific SPB
6538 network services. These VLAN id to ISID mappings can be configured and
6539 managed locally using new options added to the ovs-vsctl command.
6540 </p>
6541
6542 <p>
6543 The Auto Attach OVS feature does not provide a full implementation of
6544 the LLDP protocol. Support for the mandatory TLVs as defined by the LLDP
6545 standard and support for the AA TLV extensions is provided. LLDP
6546 protocol support in OVS can be enabled or disabled on a port by port
6547 basis. LLDP support is disabled by default.
6548 </p>
6549
6550 <column name="system_name">
6551 The system_name string is exported in LLDP messages. It should uniquely
6552 identify the bridge in the network.
6553 </column>
6554
6555 <column name="system_description">
6556 The system_description string is exported in LLDP messages. It should
6557 describe the type of software and hardware.
6558 </column>
6559
6560 <column name="mappings">
6561 A mapping from SPB network Individual Service Identifier (ISID) to VLAN
6562 id.
6563 </column>
6564 </table>
6565 </database>