mcast-snoop: Add support to control Reports forwarding
[cascardo/ovs.git] / vswitchd / vswitch.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <database 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="bridges">
56         Set of bridges managed by the daemon.
57       </column>
58
59       <column name="ssl">
60         SSL used globally by the daemon.
61       </column>
62
63       <column name="external_ids" key="system-id">
64         A unique identifier for the Open vSwitch's physical host.
65         The form of the identifier depends on the type of the host.
66         On a Citrix XenServer, this will likely be the same as
67         <ref column="external_ids" key="xs-system-uuid"/>.
68       </column>
69
70       <column name="external_ids" key="xs-system-uuid">
71         The Citrix XenServer universally unique identifier for the physical
72         host as displayed by <code>xe host-list</code>.
73       </column>
74
75       <column name="other_config" key="stats-update-interval"
76               type='{"type": "integer", "minInteger": 5000}'>
77         <p>
78           Interval for updating statistics to the database, in milliseconds.
79           This option will affect the update of the <code>statistics</code>
80           column in the following tables: <code>Port</code>, <code>Interface
81           </code>, <code>Mirror</code>.
82         </p>
83         <p>
84           Default value is 5000 ms.
85         </p>
86         <p>
87           Getting statistics more frequently can be achieved via OpenFlow.
88         </p>
89       </column>
90
91       <column name="other_config" key="flow-restore-wait"
92               type='{"type": "boolean"}'>
93         <p>
94           When <code>ovs-vswitchd</code> starts up, it has an empty flow table
95           and therefore it handles all arriving packets in its default fashion
96           according to its configuration, by dropping them or sending them to
97           an OpenFlow controller or switching them as a standalone switch.
98           This behavior is ordinarily desirable.  However, if
99           <code>ovs-vswitchd</code> is restarting as part of a ``hot-upgrade,''
100           then this leads to a relatively long period during which packets are
101           mishandled.
102         </p>
103         <p>
104           This option allows for improvement.  When <code>ovs-vswitchd</code>
105           starts with this value set as <code>true</code>, it will neither
106           flush or expire previously set datapath flows nor will it send and
107           receive any packets to or from the datapath.  When this value is
108           later set to <code>false</code>, <code>ovs-vswitchd</code> will
109           start receiving packets from the datapath and re-setup the flows.
110         </p>
111         <p>
112           Thus, with this option, the procedure for a hot-upgrade of
113           <code>ovs-vswitchd</code> becomes roughly the following:
114         </p>
115         <ol>
116           <li>
117             Stop <code>ovs-vswitchd</code>.
118           </li>
119           <li>
120             Set <ref column="other_config" key="flow-restore-wait"/>
121             to <code>true</code>.
122           </li>
123           <li>
124             Start <code>ovs-vswitchd</code>.
125           </li>
126           <li>
127             Use <code>ovs-ofctl</code> (or some other program, such as an
128             OpenFlow controller) to restore the OpenFlow flow table
129             to the desired state.
130           </li>
131           <li>
132             Set <ref column="other_config" key="flow-restore-wait"/>
133             to <code>false</code> (or remove it entirely from the database).
134           </li>
135         </ol>
136         <p>
137           The <code>ovs-ctl</code>'s ``restart'' and ``force-reload-kmod''
138           functions use the above config option during hot upgrades.
139         </p>
140       </column>
141
142       <column name="other_config" key="flow-limit"
143               type='{"type": "integer", "minInteger": 0}'>
144         <p>
145           The maximum
146           number of flows allowed in the datapath flow table.  Internally OVS
147           will choose a flow limit which will likely be lower than this number,
148           based on real time network conditions.
149         </p>
150         <p>
151           The default is 200000.
152         </p>
153       </column>
154
155       <column name="other_config" key="n-dpdk-rxqs"
156               type='{"type": "integer", "minInteger": 1}'>
157         <p>
158           Specifies the number of rx queues to be created for each dpdk
159           interface.  If not specified or specified to 0, one rx queue will
160           be created for each dpdk interface by default.
161         </p>
162       </column>
163
164       <column name="other_config" key="pmd-cpu-mask">
165         <p>
166           Specifies CPU mask for setting the cpu affinity of PMD (Poll
167           Mode Driver) threads.  Value should be in the form of hex string,
168           similar to the dpdk EAL '-c COREMASK' option input or the 'taskset'
169           mask input.
170         </p>
171         <p>
172           The lowest order bit corresponds to the first CPU core.  A set bit
173           means the corresponding core is available and a pmd thread will be
174           created and pinned to it.  If the input does not cover all cores,
175           those uncovered cores are considered not set.
176         </p>
177         <p>
178           If not specified, one pmd thread will be created for each numa node
179           and pinned to any available core on the numa node by default.
180         </p>
181       </column>
182
183       <column name="other_config" key="n-handler-threads"
184               type='{"type": "integer", "minInteger": 1}'>
185         <p>
186           Specifies the number of threads for software datapaths to use for
187           handling new flows.  The default the number of online CPU cores minus
188           the number of revalidators.
189         </p>
190         <p>
191           This configuration is per datapath.  If you have more than one
192           software datapath (e.g. some <code>system</code> bridges and some
193           <code>netdev</code> bridges), then the total number of threads is
194           <code>n-handler-threads</code> times the number of software
195           datapaths.
196         </p>
197       </column>
198
199       <column name="other_config" key="n-revalidator-threads"
200               type='{"type": "integer", "minInteger": 1}'>
201         <p>
202           Specifies the number of threads for software datapaths to use for
203           revalidating flows in the datapath.  Typically, there is a direct
204           correlation between the number of revalidator threads, and the number
205           of flows allowed in the datapath.  The default is the number of cpu
206           cores divided by four plus one.  If <code>n-handler-threads</code> is
207           set, the default changes to the number of cpu cores minus the number
208           of handler threads.
209         </p>
210         <p>
211           This configuration is per datapath.  If you have more than one
212           software datapath (e.g. some <code>system</code> bridges and some
213           <code>netdev</code> bridges), then the total number of threads is
214           <code>n-handler-threads</code> times the number of software
215           datapaths.
216         </p>
217       </column>
218     </group>
219
220     <group title="Status">
221       <column name="next_cfg">
222         Sequence number for client to increment.  When a client modifies
223         any part of the database configuration and wishes to wait for
224         Open vSwitch to finish applying the changes, it may increment
225         this sequence number.
226       </column>
227
228       <column name="cur_cfg">
229         Sequence number that Open vSwitch sets to the current value of
230         <ref column="next_cfg"/> after it finishes applying a set of
231         configuration changes.
232       </column>
233
234       <group title="Statistics">
235         <p>
236           The <code>statistics</code> column contains key-value pairs that
237           report statistics about a system running an Open vSwitch.  These are
238           updated periodically (currently, every 5 seconds).  Key-value pairs
239           that cannot be determined or that do not apply to a platform are
240           omitted.
241         </p>
242
243         <column name="other_config" key="enable-statistics"
244                 type='{"type": "boolean"}'>
245           Statistics are disabled by default to avoid overhead in the common
246           case when statistics gathering is not useful.  Set this value to
247           <code>true</code> to enable populating the <ref column="statistics"/>
248           column or to <code>false</code> to explicitly disable it.
249         </column>
250
251         <column name="statistics" key="cpu"
252                 type='{"type": "integer", "minInteger": 1}'>
253           <p>
254             Number of CPU processors, threads, or cores currently online and
255             available to the operating system on which Open vSwitch is running,
256             as an integer.  This may be less than the number installed, if some
257             are not online or if they are not available to the operating
258             system.
259           </p>
260           <p>
261             Open vSwitch userspace processes are not multithreaded, but the
262             Linux kernel-based datapath is.
263           </p>
264         </column>
265
266         <column name="statistics" key="load_average">
267           A comma-separated list of three floating-point numbers,
268           representing the system load average over the last 1, 5, and 15
269           minutes, respectively.
270         </column>
271
272         <column name="statistics" key="memory">
273           <p>
274             A comma-separated list of integers, each of which represents a
275             quantity of memory in kilobytes that describes the operating
276             system on which Open vSwitch is running.  In respective order,
277             these values are:
278           </p>
279
280           <ol>
281             <li>Total amount of RAM allocated to the OS.</li>
282             <li>RAM allocated to the OS that is in use.</li>
283             <li>RAM that can be flushed out to disk or otherwise discarded
284             if that space is needed for another purpose.  This number is
285             necessarily less than or equal to the previous value.</li>
286             <li>Total disk space allocated for swap.</li>
287             <li>Swap space currently in use.</li>
288           </ol>
289
290           <p>
291             On Linux, all five values can be determined and are included.  On
292             other operating systems, only the first two values can be
293             determined, so the list will only have two values.
294           </p>
295         </column>
296
297         <column name="statistics" key="process_NAME">
298           <p>
299             One such key-value pair, with <code>NAME</code> replaced by
300             a process name, will exist for each running Open vSwitch
301             daemon process, with <var>name</var> replaced by the
302             daemon's name (e.g. <code>process_ovs-vswitchd</code>).  The
303             value is a comma-separated list of integers.  The integers
304             represent the following, with memory measured in kilobytes
305             and durations in milliseconds:
306           </p>
307
308           <ol>
309             <li>The process's virtual memory size.</li>
310             <li>The process's resident set size.</li>
311             <li>The amount of user and system CPU time consumed by the
312             process.</li>
313             <li>The number of times that the process has crashed and been
314             automatically restarted by the monitor.</li>
315             <li>The duration since the process was started.</li>
316             <li>The duration for which the process has been running.</li>
317           </ol>
318
319           <p>
320             The interpretation of some of these values depends on whether the
321             process was started with the <option>--monitor</option>.  If it
322             was not, then the crash count will always be 0 and the two
323             durations will always be the same.  If <option>--monitor</option>
324             was given, then the crash count may be positive; if it is, the
325             latter duration is the amount of time since the most recent crash
326             and restart.
327           </p>
328
329           <p>
330             There will be one key-value pair for each file in Open vSwitch's
331             ``run directory'' (usually <code>/var/run/openvswitch</code>)
332             whose name ends in <code>.pid</code>, whose contents are a
333             process ID, and which is locked by a running process.  The
334             <var>name</var> is taken from the pidfile's name.
335           </p>
336
337           <p>
338             Currently Open vSwitch is only able to obtain all of the above
339             detail on Linux systems.  On other systems, the same key-value
340             pairs will be present but the values will always be the empty
341             string.
342           </p>
343         </column>
344
345         <column name="statistics" key="file_systems">
346           <p>
347             A space-separated list of information on local, writable file
348             systems.  Each item in the list describes one file system and
349             consists in turn of a comma-separated list of the following:
350           </p>
351
352           <ol>
353             <li>Mount point, e.g. <code>/</code> or <code>/var/log</code>.
354             Any spaces or commas in the mount point are replaced by
355             underscores.</li>
356             <li>Total size, in kilobytes, as an integer.</li>
357             <li>Amount of storage in use, in kilobytes, as an integer.</li>
358           </ol>
359
360           <p>
361             This key-value pair is omitted if there are no local, writable
362             file systems or if Open vSwitch cannot obtain the needed
363             information.
364           </p>
365         </column>
366       </group>
367     </group>
368
369     <group title="Version Reporting">
370       <p>
371         These columns report the types and versions of the hardware and
372         software running Open vSwitch.  We recommend in general that software
373         should test whether specific features are supported instead of relying
374         on version number checks.  These values are primarily intended for
375         reporting to human administrators.
376       </p>
377
378       <column name="ovs_version">
379         The Open vSwitch version number, e.g. <code>1.1.0</code>.
380       </column>
381
382       <column name="db_version">
383         <p>
384           The database schema version number in the form
385           <code><var>major</var>.<var>minor</var>.<var>tweak</var></code>,
386           e.g. <code>1.2.3</code>.  Whenever the database schema is changed in
387           a non-backward compatible way (e.g. deleting a column or a table),
388           <var>major</var> is incremented.  When the database schema is changed
389           in a backward compatible way (e.g. adding a new column),
390           <var>minor</var> is incremented.  When the database schema is changed
391           cosmetically (e.g. reindenting its syntax), <var>tweak</var> is
392           incremented.
393         </p>
394
395         <p>
396           The schema version is part of the database schema, so it can also be
397           retrieved by fetching the schema using the Open vSwitch database
398           protocol.
399         </p>
400       </column>
401
402       <column name="system_type">
403         <p>
404           An identifier for the type of system on top of which Open vSwitch
405           runs, e.g. <code>XenServer</code> or <code>KVM</code>.
406         </p>
407         <p>
408           System integrators are responsible for choosing and setting an
409           appropriate value for this column.
410         </p>
411       </column>
412
413       <column name="system_version">
414         <p>
415           The version of the system identified by <ref column="system_type"/>,
416           e.g. <code>5.6.100-39265p</code> on XenServer 5.6.100 build 39265.
417         </p>
418         <p>
419           System integrators are responsible for choosing and setting an
420           appropriate value for this column.
421         </p>
422       </column>
423
424     </group>
425
426     <group title="Database Configuration">
427       <p>
428         These columns primarily configure the Open vSwitch database
429         (<code>ovsdb-server</code>), not the Open vSwitch switch
430         (<code>ovs-vswitchd</code>).  The OVSDB database also uses the <ref
431         column="ssl"/> settings.
432       </p>
433
434       <p>
435         The Open vSwitch switch does read the database configuration to
436         determine remote IP addresses to which in-band control should apply.
437       </p>
438
439       <column name="manager_options">
440         Database clients to which the Open vSwitch database server should
441         connect or to which it should listen, along with options for how these
442         connection should be configured.  See the <ref table="Manager"/> table
443         for more information.
444       </column>
445     </group>
446
447     <group title="Common Columns">
448       The overall purpose of these columns is described under <code>Common
449       Columns</code> at the beginning of this document.
450
451       <column name="other_config"/>
452       <column name="external_ids"/>
453     </group>
454   </table>
455
456   <table name="Bridge">
457     <p>
458       Configuration for a bridge within an
459       <ref table="Open_vSwitch"/>.
460     </p>
461     <p>
462       A <ref table="Bridge"/> record represents an Ethernet switch with one or
463       more ``ports,'' which are the <ref table="Port"/> records pointed to by
464       the <ref table="Bridge"/>'s <ref column="ports"/> column.
465     </p>
466
467     <group title="Core Features">
468       <column name="name">
469         Bridge identifier.  Should be alphanumeric and no more than about 8
470         bytes long.  Must be unique among the names of ports, interfaces, and
471         bridges on a host.
472       </column>
473
474       <column name="ports">
475         Ports included in the bridge.
476       </column>
477
478       <column name="mirrors">
479         Port mirroring configuration.
480       </column>
481
482       <column name="netflow">
483         NetFlow configuration.
484       </column>
485
486       <column name="sflow">
487         sFlow(R) configuration.
488       </column>
489
490       <column name="ipfix">
491         IPFIX configuration.
492       </column>
493
494       <column name="flood_vlans">
495         <p>
496           VLAN IDs of VLANs on which MAC address learning should be disabled,
497           so that packets are flooded instead of being sent to specific ports
498           that are believed to contain packets' destination MACs.  This should
499           ordinarily be used to disable MAC learning on VLANs used for
500           mirroring (RSPAN VLANs).  It may also be useful for debugging.
501         </p>
502         <p>
503           SLB bonding (see the <ref table="Port" column="bond_mode"/> column in
504           the <ref table="Port"/> table) is incompatible with
505           <code>flood_vlans</code>.  Consider using another bonding mode or
506           a different type of mirror instead.
507         </p>
508       </column>
509     </group>
510
511     <group title="OpenFlow Configuration">
512       <column name="controller">
513         <p>
514           OpenFlow controller set.  If unset, then no OpenFlow controllers
515           will be used.
516         </p>
517
518         <p>
519           If there are primary controllers, removing all of them clears the
520           flow table.  If there are no primary controllers, adding one also
521           clears the flow table.  Other changes to the set of controllers, such
522           as adding or removing a service controller, adding another primary
523           controller to supplement an existing primary controller, or removing
524           only one of two primary controllers, have no effect on the flow
525           table.
526         </p>
527       </column>
528
529       <column name="flow_tables">
530         Configuration for OpenFlow tables.  Each pair maps from an OpenFlow
531         table ID to configuration for that table.
532       </column>
533
534       <column name="fail_mode">
535         <p>When a controller is configured, it is, ordinarily, responsible
536         for setting up all flows on the switch.  Thus, if the connection to
537         the controller fails, no new network connections can be set up.
538         If the connection to the controller stays down long enough,
539         no packets can pass through the switch at all.  This setting
540         determines the switch's response to such a situation.  It may be set
541         to one of the following:
542         <dl>
543           <dt><code>standalone</code></dt>
544           <dd>If no message is received from the controller for three
545           times the inactivity probe interval
546           (see <ref column="inactivity_probe"/>), then Open vSwitch
547           will take over responsibility for setting up flows.  In
548           this mode, Open vSwitch causes the bridge to act like an
549           ordinary MAC-learning switch.  Open vSwitch will continue
550           to retry connecting to the controller in the background
551           and, when the connection succeeds, it will discontinue its
552           standalone behavior.</dd>
553           <dt><code>secure</code></dt>
554           <dd>Open vSwitch will not set up flows on its own when the
555           controller connection fails or when no controllers are
556           defined.  The bridge will continue to retry connecting to
557           any defined controllers forever.</dd>
558         </dl>
559         </p>
560         <p>
561           The default is <code>standalone</code> if the value is unset, but
562           future versions of Open vSwitch may change the default.
563         </p>
564         <p>
565           The <code>standalone</code> mode can create forwarding loops on a
566           bridge that has more than one uplink port unless STP is enabled.  To
567           avoid loops on such a bridge, configure <code>secure</code> mode or
568           enable STP (see <ref column="stp_enable"/>).
569         </p>
570         <p>When more than one controller is configured,
571         <ref column="fail_mode"/> is considered only when none of the
572         configured controllers can be contacted.</p>
573         <p>
574           Changing <ref column="fail_mode"/> when no primary controllers are
575           configured clears the flow table.
576         </p>
577       </column>
578
579       <column name="datapath_id">
580         Reports the OpenFlow datapath ID in use.  Exactly 16 hex digits.
581         (Setting this column has no useful effect.  Set <ref
582         column="other-config" key="datapath-id"/> instead.)
583       </column>
584
585       <column name="datapath_version">
586         <p>
587           Reports the version number of the Open vSwitch datapath in use.
588           This allows management software to detect and report discrepancies
589           between Open vSwitch userspace and datapath versions.  (The <ref
590           column="ovs_version" table="Open_vSwitch"/> column in the <ref
591           table="Open_vSwitch"/> reports the Open vSwitch userspace version.)
592           The version reported depends on the datapath in use:
593         </p>
594
595         <ul>
596           <li>
597             When the kernel module included in the Open vSwitch source tree is
598             used, this column reports the Open vSwitch version from which the
599             module was taken.
600           </li>
601
602           <li>
603             When the kernel module that is part of the upstream Linux kernel is
604             used, this column reports <code>&lt;unknown&gt;</code>.
605           </li>
606
607           <li>
608             When the datapath is built into the <code>ovs-vswitchd</code>
609             binary, this column reports <code>&lt;built-in&gt;</code>.  A
610             built-in datapath is by definition the same version as the rest of
611             the Open VSwitch userspace.
612           </li>
613
614           <li>
615             Other datapaths (such as the Hyper-V kernel datapath) currently
616             report <code>&lt;unknown&gt;</code>.
617           </li>
618         </ul>
619
620         <p>
621           A version discrepancy between <code>ovs-vswitchd</code> and the
622           datapath in use is not normally cause for alarm.  The Open vSwitch
623           kernel datapaths for Linux and Hyper-V, in particular, are designed
624           for maximum inter-version compatibility: any userspace version works
625           with with any kernel version.  Some reasons do exist to insist on
626           particular user/kernel pairings.  First, newer kernel versions add
627           new features, that can only be used by new-enough userspace, e.g.
628           VXLAN tunneling requires certain minimal userspace and kernel
629           versions.  Second, as an extension to the first reason, some newer
630           kernel versions add new features for enhancing performance that only
631           new-enough userspace versions can take advantage of.
632         </p>
633       </column>
634
635       <column name="other_config" key="datapath-id">
636         Exactly 16 hex digits to set the OpenFlow datapath ID to a specific
637         value.  May not be all-zero.
638       </column>
639
640       <column name="other_config" key="dp-desc">
641         Human readable description of datapath.  It it a maximum 256
642         byte-long free-form string to describe the datapath for
643         debugging purposes, e.g. <code>switch3 in room 3120</code>.
644       </column>
645
646       <column name="other_config" key="disable-in-band"
647               type='{"type": "boolean"}'>
648         If set to <code>true</code>, disable in-band control on the bridge
649         regardless of controller and manager settings.
650       </column>
651
652       <column name="other_config" key="in-band-queue"
653               type='{"type": "integer", "minInteger": 0, "maxInteger": 4294967295}'>
654         A queue ID as a nonnegative integer.  This sets the OpenFlow queue ID
655         that will be used by flows set up by in-band control on this bridge.
656         If unset, or if the port used by an in-band control flow does not have
657         QoS configured, or if the port does not have a queue with the specified
658         ID, the default queue is used instead.
659       </column>
660
661       <column name="protocols">
662         <p>
663           List of OpenFlow protocols that may be used when negotiating
664           a connection with a controller.  OpenFlow 1.0, 1.1, 1.2, and
665           1.3 are enabled by default if this column is empty.
666         </p>
667
668         <p>
669           OpenFlow 1.4 is not enabled by default because its implementation is
670           missing features.
671         </p>
672
673         <p>
674           OpenFlow 1.5 has the same risks as OpenFlow 1.4, but it is even more
675           experimental because the OpenFlow 1.5 specification is still under
676           development and thus subject to change.  Pass
677           <code>--enable-of15</code> to <code>ovs-vswitchd</code> to allow
678           OpenFlow 1.5 to be enabled.
679         </p>
680       </column>
681     </group>
682
683     <group title="Spanning Tree Configuration">
684       The IEEE 802.1D Spanning Tree Protocol (STP) is a network protocol
685       that ensures loop-free topologies.  It allows redundant links to
686       be included in the network to provide automatic backup paths if
687       the active links fails.
688
689       <column name="stp_enable" type='{"type": "boolean"}'>
690         Enable spanning tree on the bridge.  By default, STP is disabled
691         on bridges.  Bond, internal, and mirror ports are not supported
692         and will not participate in the spanning tree.
693       </column>
694
695       <column name="other_config" key="stp-system-id">
696         The bridge's STP identifier (the lower 48 bits of the bridge-id)
697         in the form
698         <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
699         By default, the identifier is the MAC address of the bridge.
700       </column>
701
702       <column name="other_config" key="stp-priority"
703               type='{"type": "integer", "minInteger": 0, "maxInteger": 65535}'>
704         The bridge's relative priority value for determining the root
705         bridge (the upper 16 bits of the bridge-id).  A bridge with the
706         lowest bridge-id is elected the root.  By default, the priority
707         is 0x8000.
708       </column>
709
710       <column name="other_config" key="stp-hello-time"
711               type='{"type": "integer", "minInteger": 1, "maxInteger": 10}'>
712         The interval between transmissions of hello messages by
713         designated ports, in seconds.  By default the hello interval is
714         2 seconds.
715       </column>
716
717       <column name="other_config" key="stp-max-age"
718               type='{"type": "integer", "minInteger": 6, "maxInteger": 40}'>
719         The maximum age of the information transmitted by the bridge
720         when it is the root bridge, in seconds.  By default, the maximum
721         age is 20 seconds.
722       </column>
723
724       <column name="other_config" key="stp-forward-delay"
725               type='{"type": "integer", "minInteger": 4, "maxInteger": 30}'>
726         The delay to wait between transitioning root and designated
727         ports to <code>forwarding</code>, in seconds.  By default, the
728         forwarding delay is 15 seconds.
729       </column>
730
731       <column name="other_config" key="mcast-snooping-aging-time"
732               type='{"type": "integer", "minInteger": 1}'>
733         <p>
734           The maximum number of seconds to retain a multicast snooping entry for
735           which no packets have been seen.  The default is currently 300
736           seconds (5 minutes).  The value, if specified, is forced into a
737           reasonable range, currently 15 to 3600 seconds.
738         </p>
739       </column>
740
741       <column name="other_config" key="mcast-snooping-table-size"
742               type='{"type": "integer", "minInteger": 1}'>
743         <p>
744           The maximum number of multicast snooping addresses to learn.  The
745           default is currently 2048.  The value, if specified, is forced into
746           a reasonable range, currently 10 to 1,000,000.
747         </p>
748       </column>
749       <column name="other_config" key="mcast-snooping-disable-flood-unregistered"
750               type='{"type": "boolean"}'>
751         <p>
752           If set to <code>false</code>, unregistered multicast packets are forwarded
753           to all ports.
754           If set to <code>true</code>, unregistered multicast packets are forwarded
755           to ports connected to multicast routers.
756         </p>
757       </column>
758     </group>
759
760     <group title="Multicast Snooping Configuration">
761       Multicast snooping (RFC 4541) monitors the Internet Group Management
762       Protocol (IGMP) traffic between hosts and multicast routers.  The
763       switch uses what IGMP snooping learns to forward multicast traffic
764       only to interfaces that are connected to interested receivers.
765       Currently it supports IGMPv1 and IGMPv2 protocols.
766
767       <column name="mcast_snooping_enable">
768         Enable multicast snooping on the bridge. For now, the default
769         is disabled.
770       </column>
771     </group>
772
773     <group title="Rapid Spanning Tree Configuration">
774       In IEEE Std 802.1D, 1998 Edition, and prior editions of this standard,
775       Clause 8 specified the spanning tree algorithm and protocol (STP).  STP
776       has now been superseded by the Rapid Spanning Tree Protocol (RSTP)
777       specified in Clause 17 of the IEEE Std 802.1D, 2004 Edition.
778       The IEEE 802.1D-2004 Rapid Spanning Tree Algorithm Protocol configures
779       full, simple, and symmetric connectivity throughout a Bridged Local Area
780       Network that comprises individual LANs interconnected by Bridges.
781       Like STP, RSTP is a network protocol that ensures loop-free topologies.
782       It allows redundant links to be included in the network to provide
783       automatic backup paths if the active links fails.
784
785       <column name="rstp_enable" type='{"type": "boolean"}'>
786         Enable Rapid Spanning Tree on the bridge.  By default, RSTP is disabled
787         on bridges.  Bond, internal, and mirror ports are not supported
788         and will not participate in the spanning tree.
789       </column>
790
791       <column name="other_config" key="rstp-address">
792         The bridge's RSTP address (the lower 48 bits of the bridge-id)
793         in the form
794         <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
795         By default, the address is the MAC address of the bridge.
796       </column>
797
798       <column name="other_config" key="rstp-priority"
799               type='{"type": "integer", "minInteger": 0, "maxInteger": 61440}'>
800         The bridge's relative priority value for determining the root
801         bridge (the upper 16 bits of the bridge-id).  A bridge with the
802         lowest bridge-id is elected the root.  By default, the priority
803         is 0x8000 (32768).  This value needs to be a multiple of 4096,
804         otherwise it's rounded to the nearest inferior one.
805       </column>
806
807       <column name="other_config" key="rstp-ageing-time"
808               type='{"type": "integer", "minInteger": 10, "maxInteger": 1000000}'>
809         The Ageing Time parameter for the Bridge.  The default value
810         is 300 seconds.
811       </column>
812
813       <column name="other_config" key="rstp-force-protocol-version"
814               type='{"type": "integer"}'>
815         The Force Protocol Version parameter for the Bridge.  This
816         can take the value 0 (STP Compatibility mode) or 2
817         (the default, normal operation).
818       </column>
819
820       <column name="other_config" key="rstp-max-age"
821               type='{"type": "integer", "minInteger": 6, "maxInteger": 40}'>
822         The maximum age of the information transmitted by the Bridge
823         when it is the Root Bridge.  The default value is 20.
824       </column>
825
826       <column name="other_config" key="rstp-forward-delay"
827               type='{"type": "integer", "minInteger": 4, "maxInteger": 30}'>
828         The delay used by STP Bridges to transition Root and Designated
829         Ports to Forwarding.  The default value is 15.
830       </column>
831
832       <column name="other_config" key="rstp-transmit-hold-count"
833               type='{"type": "integer", "minInteger": 1, "maxInteger": 10}'>
834         The Transmit Hold Count used by the Port Transmit state machine
835         to limit transmission rate.  The default value is 6.
836       </column>
837
838     </group>
839
840     <group title="Other Features">
841       <column name="datapath_type">
842         Name of datapath provider.  The kernel datapath has
843         type <code>system</code>.  The userspace datapath has
844         type <code>netdev</code>.
845       </column>
846
847       <column name="external_ids" key="bridge-id">
848         A unique identifier of the bridge.  On Citrix XenServer this will
849         commonly be the same as
850         <ref column="external_ids" key="xs-network-uuids"/>.
851       </column>
852
853       <column name="external_ids" key="xs-network-uuids">
854         Semicolon-delimited set of universally unique identifier(s) for the
855         network with which this bridge is associated on a Citrix XenServer
856         host.  The network identifiers are RFC 4122 UUIDs as displayed by,
857         e.g., <code>xe network-list</code>.
858       </column>
859
860       <column name="other_config" key="hwaddr">
861         An Ethernet address in the form
862         <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
863         to set the hardware address of the local port and influence the
864         datapath ID.
865       </column>
866
867       <column name="other_config" key="forward-bpdu"
868               type='{"type": "boolean"}'>
869         Option to allow forwarding of BPDU frames when NORMAL action is
870         invoked.  Frames with reserved Ethernet addresses (e.g. STP
871         BPDU) will be forwarded when this option is enabled and the
872         switch is not providing that functionality.  If STP is enabled
873         on the port, STP BPDUs will never be forwarded.  If the Open
874         vSwitch bridge is used to connect different Ethernet networks,
875         and if Open vSwitch node does not run STP, then this option
876         should be enabled.  Default is disabled, set to
877         <code>true</code> to enable.
878
879         The following destination MAC addresss will not be forwarded when this
880         option is enabled.
881         <dl>
882           <dt><code>01:80:c2:00:00:00</code></dt>
883           <dd>IEEE 802.1D Spanning Tree Protocol (STP).</dd>
884
885           <dt><code>01:80:c2:00:00:01</code></dt>
886           <dd>IEEE Pause frame.</dd>
887
888           <dt><code>01:80:c2:00:00:0<var>x</var></code></dt>
889           <dd>Other reserved protocols.</dd>
890
891           <dt><code>00:e0:2b:00:00:00</code></dt>
892           <dd>Extreme Discovery Protocol (EDP).</dd>
893
894           <dt>
895             <code>00:e0:2b:00:00:04</code> and <code>00:e0:2b:00:00:06</code>
896           </dt>
897           <dd>Ethernet Automatic Protection Switching (EAPS).</dd>
898
899           <dt><code>01:00:0c:cc:cc:cc</code></dt>
900           <dd>
901             Cisco Discovery Protocol (CDP), VLAN Trunking Protocol (VTP),
902             Dynamic Trunking Protocol (DTP), Port Aggregation Protocol (PAgP),
903             and others.
904           </dd>
905
906           <dt><code>01:00:0c:cc:cc:cd</code></dt>
907           <dd>Cisco Shared Spanning Tree Protocol PVSTP+.</dd>
908
909           <dt><code>01:00:0c:cd:cd:cd</code></dt>
910           <dd>Cisco STP Uplink Fast.</dd>
911
912           <dt><code>01:00:0c:00:00:00</code></dt>
913           <dd>Cisco Inter Switch Link.</dd>
914
915           <dt><code>01:00:0c:cc:cc:c<var>x</var></code></dt>
916           <dd>Cisco CFM.</dd>
917         </dl>
918       </column>
919
920       <column name="other_config" key="mac-aging-time"
921               type='{"type": "integer", "minInteger": 1}'>
922         <p>
923           The maximum number of seconds to retain a MAC learning entry for
924           which no packets have been seen.  The default is currently 300
925           seconds (5 minutes).  The value, if specified, is forced into a
926           reasonable range, currently 15 to 3600 seconds.
927         </p>
928
929         <p>
930           A short MAC aging time allows a network to more quickly detect that a
931           host is no longer connected to a switch port.  However, it also makes
932           it more likely that packets will be flooded unnecessarily, when they
933           are addressed to a connected host that rarely transmits packets.  To
934           reduce the incidence of unnecessary flooding, use a MAC aging time
935           longer than the maximum interval at which a host will ordinarily
936           transmit packets.
937         </p>
938       </column>
939
940       <column name="other_config" key="mac-table-size"
941               type='{"type": "integer", "minInteger": 1}'>
942         <p>
943           The maximum number of MAC addresses to learn.  The default is
944           currently 2048.  The value, if specified, is forced into a reasonable
945           range, currently 10 to 1,000,000.
946         </p>
947       </column>
948     </group>
949
950     <group title="Bridge Status">
951       <p>
952         Status information about bridges.
953       </p>
954       <column name="status">
955         Key-value pairs that report bridge status.
956       </column>
957       <column name="status" key="stp_bridge_id">
958         <p>
959           The bridge-id (in hex) used in spanning tree advertisements.
960           Configuring the bridge-id is described in the
961           <code>stp-system-id</code> and <code>stp-priority</code> keys
962           of the <code>other_config</code> section earlier.
963         </p>
964       </column>
965       <column name="status" key="stp_designated_root">
966         <p>
967           The designated root (in hex) for this spanning tree.
968         </p>
969       </column>
970       <column name="status" key="stp_root_path_cost">
971         <p>
972           The path cost of reaching the designated bridge.  A lower
973           number is better.
974         </p>
975       </column>
976     </group>
977
978     <group title="Common Columns">
979       The overall purpose of these columns is described under <code>Common
980       Columns</code> at the beginning of this document.
981
982       <column name="other_config"/>
983       <column name="external_ids"/>
984     </group>
985   </table>
986  
987  <table name="Port" table="Port or bond configuration.">
988     <p>A port within a <ref table="Bridge"/>.</p>
989     <p>Most commonly, a port has exactly one ``interface,'' pointed to by its
990     <ref column="interfaces"/> column.  Such a port logically
991     corresponds to a port on a physical Ethernet switch.  A port
992     with more than one interface is a ``bonded port'' (see
993     <ref group="Bonding Configuration"/>).</p>
994     <p>Some properties that one might think as belonging to a port are actually
995     part of the port's <ref table="Interface"/> members.</p>
996
997     <column name="name">
998       Port name.  Should be alphanumeric and no more than about 8
999       bytes long.  May be the same as the interface name, for
1000       non-bonded ports.  Must otherwise be unique among the names of
1001       ports, interfaces, and bridges on a host.
1002     </column>
1003
1004     <column name="interfaces">
1005       The port's interfaces.  If there is more than one, this is a
1006       bonded Port.
1007     </column>
1008
1009     <group title="VLAN Configuration">
1010       <p>Bridge ports support the following types of VLAN configuration:</p>
1011       <dl>
1012         <dt>trunk</dt>
1013         <dd>
1014           <p>
1015             A trunk port carries packets on one or more specified VLANs
1016             specified in the <ref column="trunks"/> column (often, on every
1017             VLAN).  A packet that ingresses on a trunk port is in the VLAN
1018             specified in its 802.1Q header, or VLAN 0 if the packet has no
1019             802.1Q header.  A packet that egresses through a trunk port will
1020             have an 802.1Q header if it has a nonzero VLAN ID.
1021           </p>
1022
1023           <p>
1024             Any packet that ingresses on a trunk port tagged with a VLAN that
1025             the port does not trunk is dropped.
1026           </p>
1027         </dd>
1028
1029         <dt>access</dt>
1030         <dd>
1031           <p>
1032             An access port carries packets on exactly one VLAN specified in the
1033             <ref column="tag"/> column.  Packets egressing on an access port
1034             have no 802.1Q header.
1035           </p>
1036
1037           <p>
1038             Any packet with an 802.1Q header with a nonzero VLAN ID that
1039             ingresses on an access port is dropped, regardless of whether the
1040             VLAN ID in the header is the access port's VLAN ID.
1041           </p>
1042         </dd>
1043
1044         <dt>native-tagged</dt>
1045         <dd>
1046           A native-tagged port resembles a trunk port, with the exception that
1047           a packet without an 802.1Q header that ingresses on a native-tagged
1048           port is in the ``native VLAN'' (specified in the <ref column="tag"/>
1049           column).
1050         </dd>
1051
1052         <dt>native-untagged</dt>
1053         <dd>
1054           A native-untagged port resembles a native-tagged port, with the
1055           exception that a packet that egresses on a native-untagged port in
1056           the native VLAN will not have an 802.1Q header.
1057         </dd>
1058       </dl>
1059       <p>
1060         A packet will only egress through bridge ports that carry the VLAN of
1061         the packet, as described by the rules above.
1062       </p>
1063
1064       <column name="vlan_mode">
1065         <p>
1066           The VLAN mode of the port, as described above.  When this column is
1067           empty, a default mode is selected as follows:
1068         </p>
1069         <ul>
1070           <li>
1071             If <ref column="tag"/> contains a value, the port is an access
1072             port.  The <ref column="trunks"/> column should be empty.
1073           </li>
1074           <li>
1075             Otherwise, the port is a trunk port.  The <ref column="trunks"/>
1076             column value is honored if it is present.
1077           </li>
1078         </ul>
1079       </column>
1080
1081       <column name="tag">
1082         <p>
1083           For an access port, the port's implicitly tagged VLAN.  For a
1084           native-tagged or native-untagged port, the port's native VLAN.  Must
1085           be empty if this is a trunk port.
1086         </p>
1087       </column>
1088
1089       <column name="trunks">
1090         <p>
1091           For a trunk, native-tagged, or native-untagged port, the 802.1Q VLAN
1092           or VLANs that this port trunks; if it is empty, then the port trunks
1093           all VLANs.  Must be empty if this is an access port.
1094         </p>
1095         <p>
1096           A native-tagged or native-untagged port always trunks its native
1097           VLAN, regardless of whether <ref column="trunks"/> includes that
1098           VLAN.
1099         </p>
1100       </column>
1101
1102       <column name="other_config" key="priority-tags"
1103               type='{"type": "boolean"}'>
1104         <p>
1105           An 802.1Q header contains two important pieces of information: a VLAN
1106           ID and a priority.  A frame with a zero VLAN ID, called a
1107           ``priority-tagged'' frame, is supposed to be treated the same way as
1108           a frame without an 802.1Q header at all (except for the priority).
1109         </p>
1110
1111         <p>
1112           However, some network elements ignore any frame that has 802.1Q
1113           header at all, even when the VLAN ID is zero.  Therefore, by default
1114           Open vSwitch does not output priority-tagged frames, instead omitting
1115           the 802.1Q header entirely if the VLAN ID is zero.  Set this key to
1116           <code>true</code> to enable priority-tagged frames on a port.
1117         </p>
1118
1119         <p>
1120           Regardless of this setting, Open vSwitch omits the 802.1Q header on
1121           output if both the VLAN ID and priority would be zero.
1122         </p>
1123
1124         <p>
1125           All frames output to native-tagged ports have a nonzero VLAN ID, so
1126           this setting is not meaningful on native-tagged ports.
1127         </p>
1128       </column>
1129     </group>
1130
1131     <group title="Bonding Configuration">
1132       <p>A port that has more than one interface is a ``bonded port.'' Bonding
1133       allows for load balancing and fail-over.</p>
1134
1135       <p>
1136         The following types of bonding will work with any kind of upstream
1137         switch.  On the upstream switch, do not configure the interfaces as a
1138         bond:
1139       </p>
1140
1141       <dl>
1142         <dt><code>balance-slb</code></dt>
1143         <dd>
1144           Balances flows among slaves based on source MAC address and output
1145           VLAN, with periodic rebalancing as traffic patterns change.
1146         </dd>
1147
1148         <dt><code>active-backup</code></dt>
1149         <dd>
1150           Assigns all flows to one slave, failing over to a backup slave when
1151           the active slave is disabled.  This is the only bonding mode in which
1152           interfaces may be plugged into different upstream switches.
1153         </dd>
1154       </dl>
1155
1156       <p>
1157         The following modes require the upstream switch to support 802.3ad with
1158         successful LACP negotiation. If LACP negotiation fails and
1159         other-config:lacp-fallback-ab is true, then <code>active-backup</code>
1160         mode is used:
1161       </p>
1162
1163       <dl>
1164         <dt><code>balance-tcp</code></dt>
1165         <dd>
1166           Balances flows among slaves based on L2, L3, and L4 protocol
1167           information such as destination MAC address, IP address, and TCP
1168           port.
1169         </dd>
1170       </dl>
1171
1172       <p>These columns apply only to bonded ports.  Their values are
1173       otherwise ignored.</p>
1174
1175       <column name="bond_mode">
1176         <p>The type of bonding used for a bonded port.  Defaults to
1177         <code>active-backup</code> if unset.
1178         </p>
1179       </column>
1180
1181       <column name="other_config" key="bond-hash-basis"
1182               type='{"type": "integer"}'>
1183         An integer hashed along with flows when choosing output slaves in load
1184         balanced bonds.  When changed, all flows will be assigned different
1185         hash values possibly causing slave selection decisions to change.  Does
1186         not affect bonding modes which do not employ load balancing such as
1187         <code>active-backup</code>.
1188       </column>
1189
1190       <group title="Link Failure Detection">
1191         <p>
1192           An important part of link bonding is detecting that links are down so
1193           that they may be disabled.  These settings determine how Open vSwitch
1194           detects link failure.
1195         </p>
1196
1197         <column name="other_config" key="bond-detect-mode"
1198                 type='{"type": "string", "enum": ["set", ["carrier", "miimon"]]}'>
1199           The means used to detect link failures.  Defaults to
1200           <code>carrier</code> which uses each interface's carrier to detect
1201           failures.  When set to <code>miimon</code>, will check for failures
1202           by polling each interface's MII.
1203         </column>
1204
1205         <column name="other_config" key="bond-miimon-interval"
1206                 type='{"type": "integer"}'>
1207           The interval, in milliseconds, between successive attempts to poll
1208           each interface's MII.  Relevant only when <ref column="other_config"
1209           key="bond-detect-mode"/> is <code>miimon</code>.
1210         </column>
1211
1212         <column name="bond_updelay">
1213           <p>
1214             The number of milliseconds for which the link must stay up on an
1215             interface before the interface is considered to be up.  Specify
1216             <code>0</code> to enable the interface immediately.
1217           </p>
1218
1219           <p>
1220             This setting is honored only when at least one bonded interface is
1221             already enabled.  When no interfaces are enabled, then the first
1222             bond interface to come up is enabled immediately.
1223           </p>
1224         </column>
1225
1226         <column name="bond_downdelay">
1227           The number of milliseconds for which the link must stay down on an
1228           interface before the interface is considered to be down.  Specify
1229           <code>0</code> to disable the interface immediately.
1230         </column>
1231       </group>
1232
1233       <group title="LACP Configuration">
1234         <p>
1235           LACP, the Link Aggregation Control Protocol, is an IEEE standard that
1236           allows switches to automatically detect that they are connected by
1237           multiple links and aggregate across those links.  These settings
1238           control LACP behavior.
1239         </p>
1240
1241         <column name="lacp">
1242           Configures LACP on this port.  LACP allows directly connected
1243           switches to negotiate which links may be bonded.  LACP may be enabled
1244           on non-bonded ports for the benefit of any switches they may be
1245           connected to.  <code>active</code> ports are allowed to initiate LACP
1246           negotiations.  <code>passive</code> ports are allowed to participate
1247           in LACP negotiations initiated by a remote switch, but not allowed to
1248           initiate such negotiations themselves.  If LACP is enabled on a port
1249           whose partner switch does not support LACP, the bond will be
1250           disabled, unless other-config:lacp-fallback-ab is set to true.
1251           Defaults to <code>off</code> if unset.
1252         </column>
1253
1254         <column name="other_config" key="lacp-system-id">
1255           The LACP system ID of this <ref table="Port"/>.  The system ID of a
1256           LACP bond is used to identify itself to its partners.  Must be a
1257           nonzero MAC address. Defaults to the bridge Ethernet address if
1258           unset.
1259         </column>
1260
1261         <column name="other_config" key="lacp-system-priority"
1262                 type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
1263           The LACP system priority of this <ref table="Port"/>.  In LACP
1264           negotiations, link status decisions are made by the system with the
1265           numerically lower priority.
1266         </column>
1267
1268         <column name="other_config" key="lacp-time"
1269           type='{"type": "string", "enum": ["set", ["fast", "slow"]]}'>
1270           <p>
1271             The LACP timing which should be used on this <ref table="Port"/>.
1272             By default <code>slow</code> is used.  When configured to be
1273             <code>fast</code> LACP heartbeats are requested at a rate of once
1274             per second causing connectivity problems to be detected more
1275             quickly.  In <code>slow</code> mode, heartbeats are requested at a
1276             rate of once every 30 seconds.
1277           </p>
1278         </column>
1279
1280         <column name="other_config" key="lacp-fallback-ab"
1281           type='{"type": "boolean"}'>
1282           <p>
1283             Determines the behavior of openvswitch bond in LACP mode. If
1284             the partner switch does not support LACP, setting this option
1285             to <code>true</code> allows openvswitch to fallback to
1286             active-backup. If the option is set to <code>false</code>, the
1287             bond will be disabled. In both the cases, once the partner switch
1288             is configured to LACP mode, the bond will use LACP.
1289           </p>
1290         </column>
1291       </group>
1292
1293       <group title="Rebalancing Configuration">
1294         <p>
1295           These settings control behavior when a bond is in
1296           <code>balance-slb</code> or <code>balance-tcp</code> mode.
1297         </p>
1298
1299         <column name="other_config" key="bond-rebalance-interval"
1300                 type='{"type": "integer", "minInteger": 0, "maxInteger": 10000}'>
1301           For a load balanced bonded port, the number of milliseconds between
1302           successive attempts to rebalance the bond, that is, to move flows
1303           from one interface on the bond to another in an attempt to keep usage
1304           of each interface roughly equal.  If zero, load balancing is disabled
1305           on the bond (link failure still cause flows to move).  If
1306           less than 1000ms, the rebalance interval will be 1000ms.
1307         </column>
1308       </group>
1309
1310       <column name="bond_fake_iface">
1311         For a bonded port, whether to create a fake internal interface with the
1312         name of the port.  Use only for compatibility with legacy software that
1313         requires this.
1314       </column>
1315     </group>
1316
1317     <group title="Spanning Tree Configuration">
1318       <column name="other_config" key="stp-enable"
1319               type='{"type": "boolean"}'>
1320         If spanning tree is enabled on the bridge, member ports are
1321         enabled by default (with the exception of bond, internal, and
1322         mirror ports which do not work with STP).  If this column's
1323         value is <code>false</code> spanning tree is disabled on the
1324         port.
1325       </column>
1326
1327        <column name="other_config" key="stp-port-num"
1328                type='{"type": "integer", "minInteger": 1, "maxInteger": 255}'>
1329         The port number used for the lower 8 bits of the port-id.  By
1330         default, the numbers will be assigned automatically.  If any
1331         port's number is manually configured on a bridge, then they
1332         must all be.
1333       </column>
1334
1335        <column name="other_config" key="stp-port-priority"
1336                type='{"type": "integer", "minInteger": 0, "maxInteger": 255}'>
1337         The port's relative priority value for determining the root
1338         port (the upper 8 bits of the port-id).  A port with a lower
1339         port-id will be chosen as the root port.  By default, the
1340         priority is 0x80.
1341       </column>
1342
1343        <column name="other_config" key="stp-path-cost"
1344                type='{"type": "integer", "minInteger": 0, "maxInteger": 65535}'>
1345         Spanning tree path cost for the port.  A lower number indicates
1346         a faster link.  By default, the cost is based on the maximum
1347         speed of the link.
1348       </column>
1349     </group>
1350
1351     <group title="Rapid Spanning Tree Configuration">
1352       <column name="other_config" key="rstp-enable"
1353               type='{"type": "boolean"}'>
1354         If rapid spanning tree is enabled on the bridge, member ports are
1355         enabled by default (with the exception of bond, internal, and
1356         mirror ports which do not work with RSTP).  If this column's
1357         value is <code>false</code> rapid spanning tree is disabled on the
1358         port.
1359       </column>
1360
1361       <column name="other_config" key="rstp-port-priority"
1362               type='{"type": "integer", "minInteger": 0, "maxInteger": 240}'>
1363         The port's relative priority value for determining the root
1364         port, in multiples of 16.  By default, the port priority is 0x80
1365         (128).  Any value in the lower 4 bits is rounded off.  The significant
1366         upper 4 bits become the upper 4 bits of the port-id.  A port with the
1367         lowest port-id is elected as the root.
1368       </column>
1369
1370       <column name="other_config" key="rstp-port-num"
1371               type='{"type": "integer", "minInteger": 1, "maxInteger": 4095}'>
1372         The local RSTP port number, used as the lower 12 bits of the port-id.
1373         By default the port numbers are assigned automatically, and typically
1374         may not correspond to the OpenFlow port numbers.  A port with the
1375         lowest port-id is elected as the root.
1376       </column>
1377
1378       <column name="other_config" key="rstp-port-path-cost"
1379               type='{"type": "integer"}'>
1380         The port path cost.  The Port's contribution, when it is
1381         the Root Port, to the Root Path Cost for the Bridge.  By default the
1382         cost is automatically calculated from the port's speed.
1383       </column>
1384
1385       <column name="other_config" key="rstp-port-admin-edge"
1386               type='{"type": "boolean"}'>
1387         The admin edge port parameter for the Port.  Default is
1388         <code>false</code>.
1389       </column>
1390
1391       <column name="other_config" key="rstp-port-auto-edge"
1392               type='{"type": "boolean"}'>
1393         The auto edge port parameter for the Port.  Default is
1394         <code>true</code>.
1395       </column>
1396
1397       <column name="other_config" key="rstp-port-mcheck"
1398               type='{"type": "boolean"}'>
1399         <p>
1400           The mcheck port parameter for the Port.  Default is
1401           <code>false</code>.  May be set to force the Port Protocol
1402           Migration state machine to transmit RST BPDUs for a
1403           MigrateTime period, to test whether all STP Bridges on the
1404           attached LAN have been removed and the Port can continue to
1405           transmit RSTP BPDUs.  Setting mcheck has no effect if the
1406           Bridge is operating in STP Compatibility mode.
1407         </p>
1408         <p>
1409           Changing the value from <code>true</code> to
1410           <code>false</code> has no effect, but needs to be done if
1411           this behavior is to be triggered again by subsequently
1412           changing the value from <code>false</code> to
1413           <code>true</code>.
1414         </p>
1415       </column>
1416     </group>
1417
1418     <group title="Multicast Snooping">
1419       <column name="other_config" key="mcast-snooping-flood"
1420               type='{"type": "boolean"}'>
1421         <p>
1422           If set to <code>true</code>, multicast packets (except Reports) are
1423           unconditionally forwarded to the specific port.
1424         </p>
1425       </column>
1426       <column name="other_config" key="mcast-snooping-flood-reports"
1427               type='{"type": "boolean"}'>
1428         <p>
1429           If set to <code>true</code>, multicast Reports are unconditionally
1430           forwarded to the specific port.
1431         </p>
1432       </column>
1433     </group>
1434
1435     <group title="Other Features">
1436       <column name="qos">
1437         Quality of Service configuration for this port.
1438       </column>
1439
1440       <column name="mac">
1441         The MAC address to use for this port for the purpose of choosing the
1442         bridge's MAC address.  This column does not necessarily reflect the
1443         port's actual MAC address, nor will setting it change the port's actual
1444         MAC address.
1445       </column>
1446
1447       <column name="fake_bridge">
1448         Does this port represent a sub-bridge for its tagged VLAN within the
1449         Bridge?  See ovs-vsctl(8) for more information.
1450       </column>
1451
1452       <column name="external_ids" key="fake-bridge-id-*">
1453         External IDs for a fake bridge (see the <ref column="fake_bridge"/>
1454         column) are defined by prefixing a <ref table="Bridge"/> <ref
1455         table="Bridge" column="external_ids"/> key with
1456         <code>fake-bridge-</code>,
1457         e.g. <code>fake-bridge-xs-network-uuids</code>.
1458       </column>
1459     </group>
1460
1461     <group title="Port Status">
1462       <p>
1463         Status information about ports attached to bridges.
1464       </p>
1465       <column name="status">
1466         Key-value pairs that report port status.
1467       </column>
1468       <column name="status" key="stp_port_id">
1469         <p>
1470           The port-id (in hex) used in spanning tree advertisements for
1471           this port.  Configuring the port-id is described in the
1472           <code>stp-port-num</code> and <code>stp-port-priority</code>
1473           keys of the <code>other_config</code> section earlier.
1474         </p>
1475       </column>
1476       <column name="status" key="stp_state"
1477               type='{"type": "string", "enum": ["set",
1478                             ["disabled", "listening", "learning",
1479                              "forwarding", "blocking"]]}'>
1480         <p>
1481           STP state of the port.
1482         </p>
1483       </column>
1484       <column name="status" key="stp_sec_in_state"
1485               type='{"type": "integer", "minInteger": 0}'>
1486         <p>
1487           The amount of time (in seconds) port has been in the current
1488           STP state.
1489         </p>
1490       </column>
1491       <column name="status" key="stp_role"
1492               type='{"type": "string", "enum": ["set",
1493                             ["root", "designated", "alternate"]]}'>
1494         <p>
1495           STP role of the port.
1496         </p>
1497       </column>
1498
1499       <column name="status" key="bond_active_slave">
1500         <p>
1501           For a bonded port, record the mac address of the current active slave.
1502         </p>
1503       </column>
1504
1505     </group>
1506
1507     <group title="Port Statistics">
1508       <p>
1509         Key-value pairs that report port statistics.  The update period
1510         is controlled by <ref column="other_config"
1511         key="stats-update-interval"/> in the <code>Open_vSwitch</code> table.
1512       </p>
1513       <group title="Statistics: STP transmit and receive counters">
1514         <column name="statistics" key="stp_tx_count">
1515           Number of STP BPDUs sent on this port by the spanning
1516           tree library.
1517         </column>
1518         <column name="statistics" key="stp_rx_count">
1519           Number of STP BPDUs received on this port and accepted by the
1520           spanning tree library.
1521         </column>
1522         <column name="statistics" key="stp_error_count">
1523           Number of bad STP BPDUs received on this port.  Bad BPDUs
1524           include runt packets and those with an unexpected protocol ID.
1525         </column>
1526       </group>
1527     </group>
1528
1529     <group title="Common Columns">
1530       The overall purpose of these columns is described under <code>Common
1531       Columns</code> at the beginning of this document.
1532
1533       <column name="other_config"/>
1534       <column name="external_ids"/>
1535     </group>
1536   </table>
1537
1538   <table name="Interface" title="One physical network device in a Port.">
1539     An interface within a <ref table="Port"/>.
1540
1541     <group title="Core Features">
1542       <column name="name">
1543         Interface name.  Should be alphanumeric and no more than about 8 bytes
1544         long.  May be the same as the port name, for non-bonded ports.  Must
1545         otherwise be unique among the names of ports, interfaces, and bridges
1546         on a host.
1547       </column>
1548
1549       <column name="ifindex">
1550         A positive interface index as defined for SNMP MIB-II in RFCs 1213 and
1551         2863, if the interface has one, otherwise 0.  The ifindex is useful for
1552         seamless integration with protocols such as SNMP and sFlow.
1553       </column>
1554
1555       <column name="mac_in_use">
1556         The MAC address in use by this interface.
1557       </column>
1558
1559       <column name="mac">
1560         <p>Ethernet address to set for this interface.  If unset then the
1561         default MAC address is used:</p>
1562         <ul>
1563           <li>For the local interface, the default is the lowest-numbered MAC
1564           address among the other bridge ports, either the value of the
1565           <ref table="Port" column="mac"/> in its <ref table="Port"/> record,
1566           if set, or its actual MAC (for bonded ports, the MAC of its slave
1567           whose name is first in alphabetical order).  Internal ports and
1568           bridge ports that are used as port mirroring destinations (see the
1569           <ref table="Mirror"/> table) are ignored.</li>
1570           <li>For other internal interfaces, the default MAC is randomly
1571           generated.</li>
1572           <li>External interfaces typically have a MAC address associated with
1573           their hardware.</li>
1574         </ul>
1575         <p>Some interfaces may not have a software-controllable MAC
1576         address.</p>
1577       </column>
1578
1579       <column name="error">
1580         If the configuration of the port failed, as indicated by -1 in <ref
1581         column="ofport"/>, Open vSwitch sets this column to an error
1582         description in human readable form.  Otherwise, Open vSwitch clears
1583         this column.
1584       </column>
1585
1586       <group title="OpenFlow Port Number">
1587         <p>
1588           When a client adds a new interface, Open vSwitch chooses an OpenFlow
1589           port number for the new port.  If the client that adds the port fills
1590           in <ref column="ofport_request"/>, then Open vSwitch tries to use its
1591           value as the OpenFlow port number.  Otherwise, or if the requested
1592           port number is already in use or cannot be used for another reason,
1593           Open vSwitch automatically assigns a free port number.  Regardless of
1594           how the port number was obtained, Open vSwitch then reports in <ref
1595           column="ofport"/> the port number actually assigned.
1596         </p>
1597
1598         <p>
1599           Open vSwitch limits the port numbers that it automatically assigns to
1600           the range 1 through 32,767, inclusive.  Controllers therefore have
1601           free use of ports 32,768 and up.
1602         </p>
1603
1604         <column name="ofport">
1605           <p>
1606             OpenFlow port number for this interface.  Open vSwitch sets this
1607             column's value, so other clients should treat it as read-only.
1608           </p>
1609           <p>
1610             The OpenFlow ``local'' port (<code>OFPP_LOCAL</code>) is 65,534.
1611             The other valid port numbers are in the range 1 to 65,279,
1612             inclusive.  Value -1 indicates an error adding the interface.
1613           </p>
1614         </column>
1615
1616         <column name="ofport_request"
1617                 type='{"type": "integer", "minInteger": 1, "maxInteger": 65279}'>
1618           <p>
1619             Requested OpenFlow port number for this interface.
1620           </p>
1621
1622           <p>
1623             A client should ideally set this column's value in the same
1624             database transaction that it uses to create the interface.  Open
1625             vSwitch version 2.1 and later will honor a later request for a
1626             specific port number, althuogh it might confuse some controllers:
1627             OpenFlow does not have a way to announce a port number change, so
1628             Open vSwitch represents it over OpenFlow as a port deletion
1629             followed immediately by a port addition.
1630           </p>
1631
1632           <p>
1633             If <ref column="ofport_request"/> is set or changed to some other
1634             port's automatically assigned port number, Open vSwitch chooses a
1635             new port number for the latter port.
1636           </p>
1637         </column>
1638       </group>
1639     </group>
1640
1641     <group title="System-Specific Details">
1642       <column name="type">
1643         <p>
1644           The interface type, one of:
1645         </p>
1646
1647         <dl>
1648           <dt><code>system</code></dt>
1649           <dd>An ordinary network device, e.g. <code>eth0</code> on Linux.
1650           Sometimes referred to as ``external interfaces'' since they are
1651           generally connected to hardware external to that on which the Open
1652           vSwitch is running.  The empty string is a synonym for
1653           <code>system</code>.</dd>
1654
1655           <dt><code>internal</code></dt>
1656           <dd>A simulated network device that sends and receives traffic.  An
1657           internal interface whose <ref column="name"/> is the same as its
1658           bridge's <ref table="Open_vSwitch" column="name"/> is called the
1659           ``local interface.''  It does not make sense to bond an internal
1660           interface, so the terms ``port'' and ``interface'' are often used
1661           imprecisely for internal interfaces.</dd>
1662
1663           <dt><code>tap</code></dt>
1664           <dd>A TUN/TAP device managed by Open vSwitch.</dd>
1665
1666           <dt><code>geneve</code></dt>
1667           <dd>
1668             An Ethernet over Geneve (<code>http://tools.ietf.org/html/draft-gross-geneve-00</code>)
1669             IPv4 tunnel.
1670
1671             Geneve supports options as a means to transport additional metadata,
1672             however, currently only the 24-bit VNI is supported. This is planned
1673             to be extended in the future.
1674           </dd>
1675
1676           <dt><code>gre</code></dt>
1677           <dd>
1678             An Ethernet over RFC 2890 Generic Routing Encapsulation over IPv4
1679             tunnel.
1680           </dd>
1681
1682           <dt><code>ipsec_gre</code></dt>
1683           <dd>
1684             An Ethernet over RFC 2890 Generic Routing Encapsulation over IPv4
1685             IPsec tunnel.
1686           </dd>
1687
1688           <dt><code>gre64</code></dt>
1689           <dd>
1690             It is same as GRE, but it allows 64 bit key. To store higher 32-bits
1691             of key, it uses GRE protocol sequence number field. This is non
1692             standard use of GRE protocol since OVS does not increment
1693             sequence number for every packet at time of encap as expected by
1694             standard GRE implementation. See <ref group="Tunnel Options"/>
1695             for information on configuring GRE tunnels.
1696           </dd>
1697
1698           <dt><code>ipsec_gre64</code></dt>
1699           <dd>
1700             Same as IPSEC_GRE except 64 bit key.
1701           </dd>
1702
1703           <dt><code>vxlan</code></dt>
1704           <dd>
1705             <p>
1706               An Ethernet tunnel over the experimental, UDP-based VXLAN
1707               protocol described at
1708               <code>http://tools.ietf.org/html/draft-mahalingam-dutt-dcops-vxlan-03</code>.
1709             </p>
1710             <p>
1711               Open vSwitch uses UDP destination port 4789.  The source port used for
1712               VXLAN traffic varies on a per-flow basis and is in the ephemeral port
1713               range.
1714             </p>
1715           </dd>
1716
1717           <dt><code>lisp</code></dt>
1718           <dd>
1719             <p>
1720               A layer 3 tunnel over the experimental, UDP-based Locator/ID
1721               Separation Protocol (RFC 6830).
1722             </p>
1723             <p>
1724               Only IPv4 and IPv6 packets are supported by the protocol, and
1725               they are sent and received without an Ethernet header.  Traffic
1726               to/from LISP ports is expected to be configured explicitly, and
1727               the ports are not intended to participate in learning based
1728               switching.  As such, they are always excluded from packet
1729               flooding.
1730             </p>
1731           </dd>
1732
1733           <dt><code>patch</code></dt>
1734           <dd>
1735             A pair of virtual devices that act as a patch cable.
1736           </dd>
1737
1738           <dt><code>null</code></dt>
1739           <dd>An ignored interface. Deprecated and slated for removal in
1740               February 2013.</dd>
1741         </dl>
1742       </column>
1743     </group>
1744
1745     <group title="Tunnel Options">
1746       <p>
1747         These options apply to interfaces with <ref column="type"/> of
1748         <code>geneve</code>, <code>gre</code>, <code>ipsec_gre</code>,
1749         <code>gre64</code>, <code>ipsec_gre64</code>, <code>vxlan</code>,
1750         and <code>lisp</code>.
1751       </p>
1752
1753       <p>
1754         Each tunnel must be uniquely identified by the combination of <ref
1755         column="type"/>, <ref column="options" key="remote_ip"/>, <ref
1756         column="options" key="local_ip"/>, and <ref column="options"
1757         key="in_key"/>.  If two ports are defined that are the same except one
1758         has an optional identifier and the other does not, the more specific
1759         one is matched first.  <ref column="options" key="in_key"/> is
1760         considered more specific than <ref column="options" key="local_ip"/> if
1761         a port defines one and another port defines the other.
1762       </p>
1763
1764       <column name="options" key="remote_ip">
1765         <p>Required.  The remote tunnel endpoint, one of:</p>
1766
1767         <ul>
1768           <li>
1769             An IPv4 address (not a DNS name), e.g. <code>192.168.0.123</code>.
1770             Only unicast endpoints are supported.
1771           </li>
1772           <li>
1773             The word <code>flow</code>.  The tunnel accepts packets from any
1774             remote tunnel endpoint.  To process only packets from a specific
1775             remote tunnel endpoint, the flow entries may match on the
1776             <code>tun_src</code> field.  When sending packets to a
1777             <code>remote_ip=flow</code> tunnel, the flow actions must
1778             explicitly set the <code>tun_dst</code> field to the IP address of
1779             the desired remote tunnel endpoint, e.g. with a
1780             <code>set_field</code> action.
1781           </li>
1782         </ul>
1783
1784         <p>
1785          The remote tunnel endpoint for any packet received from a tunnel
1786          is available in the <code>tun_src</code> field for matching in the
1787          flow table.
1788         </p>
1789       </column>
1790
1791       <column name="options" key="local_ip">
1792         <p>
1793           Optional.  The tunnel destination IP that received packets must
1794           match.  Default is to match all addresses.  If specified, may be one
1795           of:
1796         </p>
1797
1798         <ul>
1799           <li>
1800             An IPv4 address (not a DNS name), e.g. <code>192.168.12.3</code>.
1801           </li>
1802           <li>
1803             The word <code>flow</code>.  The tunnel accepts packets sent to any
1804             of the local IP addresses of the system running OVS.  To process
1805             only packets sent to a specific IP address, the flow entries may
1806             match on the <code>tun_dst</code> field.  When sending packets to a
1807             <code>local_ip=flow</code> tunnel, the flow actions may
1808             explicitly set the <code>tun_src</code> field to the desired IP
1809             address, e.g. with a <code>set_field</code> action.  However, while
1810             routing the tunneled packet out, the local system may override the
1811             specified address with the local IP address configured for the
1812             outgoing system interface.
1813
1814             <p>
1815               This option is valid only for tunnels also configured with the
1816               <code>remote_ip=flow</code> option.
1817             </p>
1818           </li>
1819         </ul>
1820
1821         <p>
1822           The tunnel destination IP address for any packet received from a
1823           tunnel is available in the <code>tun_dst</code> field for matching in
1824           the flow table.
1825         </p>
1826       </column>
1827
1828       <column name="options" key="in_key">
1829         <p>Optional.  The key that received packets must contain, one of:</p>
1830
1831         <ul>
1832           <li>
1833             <code>0</code>.  The tunnel receives packets with no key or with a
1834             key of 0.  This is equivalent to specifying no <ref column="options"
1835             key="in_key"/> at all.
1836           </li>
1837           <li>
1838             A positive 24-bit (for Geneve, VXLAN, and LISP), 32-bit (for GRE)
1839             or 64-bit (for GRE64) number.  The tunnel receives only packets
1840             with the specified key.
1841           </li>
1842           <li>
1843             The word <code>flow</code>.  The tunnel accepts packets with any
1844             key.  The key will be placed in the <code>tun_id</code> field for
1845             matching in the flow table.  The <code>ovs-ofctl</code> manual page
1846             contains additional information about matching fields in OpenFlow
1847             flows.
1848           </li>
1849         </ul>
1850
1851         <p>
1852         </p>
1853       </column>
1854
1855       <column name="options" key="out_key">
1856         <p>Optional.  The key to be set on outgoing packets, one of:</p>
1857
1858         <ul>
1859           <li>
1860             <code>0</code>.  Packets sent through the tunnel will have no key.
1861             This is equivalent to specifying no <ref column="options"
1862             key="out_key"/> at all.
1863           </li>
1864           <li>
1865             A positive 24-bit (for Geneve, VXLAN and LISP), 32-bit (for GRE) or
1866             64-bit (for GRE64) number.  Packets sent through the tunnel will
1867             have the specified key.
1868           </li>
1869           <li>
1870             The word <code>flow</code>.  Packets sent through the tunnel will
1871             have the key set using the <code>set_tunnel</code> Nicira OpenFlow
1872             vendor extension (0 is used in the absence of an action).  The
1873             <code>ovs-ofctl</code> manual page contains additional information
1874             about the Nicira OpenFlow vendor extensions.
1875           </li>
1876         </ul>
1877       </column>
1878
1879       <column name="options" key="key">
1880         Optional.  Shorthand to set <code>in_key</code> and
1881         <code>out_key</code> at the same time.
1882       </column>
1883
1884       <column name="options" key="tos">
1885         Optional.  The value of the ToS bits to be set on the encapsulating
1886         packet.  ToS is interpreted as DSCP and ECN bits, ECN part must be
1887         zero.  It may also be the word <code>inherit</code>, in which case
1888         the ToS will be copied from the inner packet if it is IPv4 or IPv6
1889         (otherwise it will be 0).  The ECN fields are always inherited.
1890         Default is 0.
1891       </column>
1892
1893       <column name="options" key="ttl">
1894         Optional.  The TTL to be set on the encapsulating packet.  It may also
1895         be the word <code>inherit</code>, in which case the TTL will be copied
1896         from the inner packet if it is IPv4 or IPv6 (otherwise it will be the
1897         system default, typically 64).  Default is the system default TTL.
1898       </column>
1899
1900       <column name="options" key="df_default"
1901               type='{"type": "boolean"}'>
1902         Optional.  If enabled, the Don't Fragment bit will be set on tunnel
1903         outer headers to allow path MTU discovery. Default is enabled; set
1904         to <code>false</code> to disable.
1905       </column>
1906
1907       <group title="Tunnel Options: gre and ipsec_gre only">
1908         <p>
1909           Only <code>gre</code> and <code>ipsec_gre</code> interfaces support
1910           these options.
1911         </p>
1912
1913         <column name="options" key="csum" type='{"type": "boolean"}'>
1914           <p>
1915             Optional.  Compute GRE checksums on outgoing packets.  Default is
1916             disabled, set to <code>true</code> to enable.  Checksums present on
1917             incoming packets will be validated regardless of this setting.
1918           </p>
1919
1920           <p>
1921             GRE checksums impose a significant performance penalty because they
1922             cover the entire packet.  The encapsulated L3, L4, and L7 packet
1923             contents typically have their own checksums, so this additional
1924             checksum only adds value for the GRE and encapsulated L2 headers.
1925           </p>
1926
1927           <p>
1928             This option is supported for <code>ipsec_gre</code>, but not useful
1929             because GRE checksums are weaker than, and redundant with, IPsec
1930             payload authentication.
1931           </p>
1932         </column>
1933       </group>
1934
1935       <group title="Tunnel Options: ipsec_gre only">
1936         <p>
1937           Only <code>ipsec_gre</code> interfaces support these options.
1938         </p>
1939
1940         <column name="options" key="peer_cert">
1941           Required for certificate authentication.  A string containing the
1942           peer's certificate in PEM format.  Additionally the host's
1943           certificate must be specified with the <code>certificate</code>
1944           option.
1945         </column>
1946
1947         <column name="options" key="certificate">
1948           Required for certificate authentication.  The name of a PEM file
1949           containing a certificate that will be presented to the peer during
1950           authentication.
1951         </column>
1952
1953         <column name="options" key="private_key">
1954           Optional for certificate authentication.  The name of a PEM file
1955           containing the private key associated with <code>certificate</code>.
1956           If <code>certificate</code> contains the private key, this option may
1957           be omitted.
1958         </column>
1959
1960         <column name="options" key="psk">
1961           Required for pre-shared key authentication.  Specifies a pre-shared
1962           key for authentication that must be identical on both sides of the
1963           tunnel.
1964         </column>
1965       </group>
1966     </group>
1967
1968     <group title="Patch Options">
1969       <p>
1970         Only <code>patch</code> interfaces support these options.
1971       </p>
1972
1973       <column name="options" key="peer">
1974         The <ref column="name"/> of the <ref table="Interface"/> for the other
1975         side of the patch.  The named <ref table="Interface"/>'s own
1976         <code>peer</code> option must specify this <ref table="Interface"/>'s
1977         name.  That is, the two patch interfaces must have reversed <ref
1978         column="name"/> and <code>peer</code> values.
1979       </column>
1980     </group>
1981
1982     <group title="Interface Status">
1983       <p>
1984         Status information about interfaces attached to bridges, updated every
1985         5 seconds.  Not all interfaces have all of these properties; virtual
1986         interfaces don't have a link speed, for example.  Non-applicable
1987         columns will have empty values.
1988       </p>
1989       <column name="admin_state">
1990         <p>
1991           The administrative state of the physical network link.
1992         </p>
1993       </column>
1994
1995       <column name="link_state">
1996         <p>
1997           The observed state of the physical network link.  This is ordinarily
1998           the link's carrier status.  If the interface's <ref table="Port"/> is
1999           a bond configured for miimon monitoring, it is instead the network
2000           link's miimon status.
2001         </p>
2002       </column>
2003
2004       <column name="link_resets">
2005         <p>
2006           The number of times Open vSwitch has observed the
2007           <ref column="link_state"/> of this <ref table="Interface"/> change.
2008         </p>
2009       </column>
2010
2011       <column name="link_speed">
2012         <p>
2013           The negotiated speed of the physical network link.
2014           Valid values are positive integers greater than 0.
2015         </p>
2016       </column>
2017
2018       <column name="duplex">
2019         <p>
2020           The duplex mode of the physical network link.
2021         </p>
2022       </column>
2023
2024       <column name="mtu">
2025         <p>
2026           The MTU (maximum transmission unit); i.e. the largest
2027           amount of data that can fit into a single Ethernet frame.
2028           The standard Ethernet MTU is 1500 bytes.  Some physical media
2029           and many kinds of virtual interfaces can be configured with
2030           higher MTUs.
2031         </p>
2032         <p>
2033           This column will be empty for an interface that does not
2034           have an MTU as, for example, some kinds of tunnels do not.
2035         </p>
2036       </column>
2037
2038       <column name="lacp_current">
2039         Boolean value indicating LACP status for this interface.  If true, this
2040         interface has current LACP information about its LACP partner.  This
2041         information may be used to monitor the health of interfaces in a LACP
2042         enabled port.  This column will be empty if LACP is not enabled.
2043       </column>
2044
2045       <column name="status">
2046         Key-value pairs that report port status.  Supported status values are
2047         <ref column="type"/>-dependent; some interfaces may not have a valid
2048         <ref column="status" key="driver_name"/>, for example.
2049       </column>
2050
2051       <column name="status" key="driver_name">
2052         The name of the device driver controlling the network adapter.
2053       </column>
2054
2055       <column name="status" key="driver_version">
2056         The version string of the device driver controlling the network
2057         adapter.
2058       </column>
2059
2060       <column name="status" key="firmware_version">
2061         The version string of the network adapter's firmware, if available.
2062       </column>
2063
2064       <column name="status" key="source_ip">
2065         The source IP address used for an IPv4 tunnel end-point, such as
2066         <code>gre</code>.
2067       </column>
2068
2069       <column name="status" key="tunnel_egress_iface">
2070         Egress interface for tunnels.  Currently only relevant for tunnels
2071         on Linux systems, this column will show the name of the interface
2072         which is responsible for routing traffic destined for the configured
2073         <ref column="options" key="remote_ip"/>.  This could be an internal
2074         interface such as a bridge port.
2075       </column>
2076
2077       <column name="status" key="tunnel_egress_iface_carrier"
2078               type='{"type": "string", "enum": ["set", ["down", "up"]]}'>
2079         Whether carrier is detected on <ref column="status"
2080         key="tunnel_egress_iface"/>.
2081       </column>
2082     </group>
2083
2084     <group title="Statistics">
2085       <p>
2086         Key-value pairs that report interface statistics.  The current
2087         implementation updates these counters periodically.  The update period
2088         is controlled by <ref column="other_config"
2089         key="stats-update-interval"/> in the <code>Open_vSwitch</code> table.
2090         Future implementations may update them when an interface is created,
2091         when they are queried (e.g. using an OVSDB <code>select</code>
2092         operation), and just before an interface is deleted due to virtual
2093         interface hot-unplug or VM shutdown, and perhaps at other times, but
2094         not on any regular periodic basis.
2095       </p>
2096       <p>
2097         These are the same statistics reported by OpenFlow in its <code>struct
2098         ofp_port_stats</code> structure.  If an interface does not support a
2099         given statistic, then that pair is omitted.
2100       </p>
2101       <group title="Statistics: Successful transmit and receive counters">
2102         <column name="statistics" key="rx_packets">
2103           Number of received packets.
2104         </column>
2105         <column name="statistics" key="rx_bytes">
2106           Number of received bytes.
2107         </column>
2108         <column name="statistics" key="tx_packets">
2109           Number of transmitted packets.
2110         </column>
2111         <column name="statistics" key="tx_bytes">
2112           Number of transmitted bytes.
2113         </column>
2114       </group>
2115       <group title="Statistics: Receive errors">
2116         <column name="statistics" key="rx_dropped">
2117           Number of packets dropped by RX.
2118         </column>
2119         <column name="statistics" key="rx_frame_err">
2120           Number of frame alignment errors.
2121         </column>
2122         <column name="statistics" key="rx_over_err">
2123           Number of packets with RX overrun.
2124         </column>
2125         <column name="statistics" key="rx_crc_err">
2126           Number of CRC errors.
2127         </column>
2128         <column name="statistics" key="rx_errors">
2129           Total number of receive errors, greater than or equal to the sum of
2130           the above.
2131         </column>
2132       </group>
2133       <group title="Statistics: Transmit errors">
2134         <column name="statistics" key="tx_dropped">
2135           Number of packets dropped by TX.
2136         </column>
2137         <column name="statistics" key="collisions">
2138           Number of collisions.
2139         </column>
2140         <column name="statistics" key="tx_errors">
2141           Total number of transmit errors, greater than or equal to the sum of
2142           the above.
2143         </column>
2144       </group>
2145     </group>
2146
2147     <group title="Ingress Policing">
2148       <p>
2149         These settings control ingress policing for packets received on this
2150         interface.  On a physical interface, this limits the rate at which
2151         traffic is allowed into the system from the outside; on a virtual
2152         interface (one connected to a virtual machine), this limits the rate at
2153         which the VM is able to transmit.
2154       </p>
2155       <p>
2156         Policing is a simple form of quality-of-service that simply drops
2157         packets received in excess of the configured rate.  Due to its
2158         simplicity, policing is usually less accurate and less effective than
2159         egress QoS (which is configured using the <ref table="QoS"/> and <ref
2160         table="Queue"/> tables).
2161       </p>
2162       <p>
2163         Policing is currently implemented only on Linux.  The Linux
2164         implementation uses a simple ``token bucket'' approach:
2165       </p>
2166       <ul>
2167         <li>
2168           The size of the bucket corresponds to <ref
2169           column="ingress_policing_burst"/>.  Initially the bucket is full.
2170         </li>
2171         <li>
2172           Whenever a packet is received, its size (converted to tokens) is
2173           compared to the number of tokens currently in the bucket.  If the
2174           required number of tokens are available, they are removed and the
2175           packet is forwarded.  Otherwise, the packet is dropped.
2176         </li>
2177         <li>
2178           Whenever it is not full, the bucket is refilled with tokens at the
2179           rate specified by <ref column="ingress_policing_rate"/>.
2180         </li>
2181       </ul>
2182       <p>
2183         Policing interacts badly with some network protocols, and especially
2184         with fragmented IP packets.  Suppose that there is enough network
2185         activity to keep the bucket nearly empty all the time.  Then this token
2186         bucket algorithm will forward a single packet every so often, with the
2187         period depending on packet size and on the configured rate.  All of the
2188         fragments of an IP packets are normally transmitted back-to-back, as a
2189         group.  In such a situation, therefore, only one of these fragments
2190         will be forwarded and the rest will be dropped.  IP does not provide
2191         any way for the intended recipient to ask for only the remaining
2192         fragments.  In such a case there are two likely possibilities for what
2193         will happen next: either all of the fragments will eventually be
2194         retransmitted (as TCP will do), in which case the same problem will
2195         recur, or the sender will not realize that its packet has been dropped
2196         and data will simply be lost (as some UDP-based protocols will do).
2197         Either way, it is possible that no forward progress will ever occur.
2198       </p>
2199       <column name="ingress_policing_rate">
2200         <p>
2201           Maximum rate for data received on this interface, in kbps.  Data
2202           received faster than this rate is dropped.  Set to <code>0</code>
2203           (the default) to disable policing.
2204         </p>
2205       </column>
2206
2207       <column name="ingress_policing_burst">
2208         <p>Maximum burst size for data received on this interface, in kb.  The
2209         default burst size if set to <code>0</code> is 1000 kb.  This value
2210         has no effect if <ref column="ingress_policing_rate"/>
2211         is <code>0</code>.</p>
2212         <p>
2213           Specifying a larger burst size lets the algorithm be more forgiving,
2214           which is important for protocols like TCP that react severely to
2215           dropped packets.  The burst size should be at least the size of the
2216           interface's MTU.  Specifying a value that is numerically at least as
2217           large as 10% of <ref column="ingress_policing_rate"/> helps TCP come
2218           closer to achieving the full rate.
2219         </p>
2220       </column>
2221     </group>
2222
2223     <group title="Bidirectional Forwarding Detection (BFD)">
2224       <p>
2225         BFD, defined in RFC 5880 and RFC 5881, allows point-to-point
2226         detection of connectivity failures by occasional transmission of
2227         BFD control messages.  Open vSwitch implements BFD to serve
2228         as a more popular and standards compliant alternative to CFM.
2229       </p>
2230
2231       <p>
2232         BFD operates by regularly transmitting BFD control messages at a rate
2233         negotiated independently in each direction.  Each endpoint specifies
2234         the rate at which it expects to receive control messages, and the rate
2235         at which it is willing to transmit them.  Open vSwitch uses a detection
2236         multiplier of three, meaning that an endpoint signals a connectivity
2237         fault if three consecutive BFD control messages fail to arrive.  In the
2238         case of a unidirectional connectivity issue, the system not receiving
2239         BFD control messages signals the problem to its peer in the messages it
2240         transmits.
2241       </p>
2242
2243       <p>
2244         The Open vSwitch implementation of BFD aims to comply faithfully
2245         with RFC 5880 requirements.  Open vSwitch does not implement the
2246         optional Authentication or ``Echo Mode'' features.
2247       </p>
2248
2249       <group title="BFD Configuration">
2250         <p>
2251           A controller sets up key-value pairs in the <ref column="bfd"/>
2252           column to enable and configure BFD.
2253         </p>
2254
2255         <column name="bfd" key="enable" type='{"type": "boolean"}'>
2256           True to enable BFD on this <ref table="Interface"/>.  If not
2257           specified, BFD will not be enabled by default.
2258         </column>
2259
2260         <column name="bfd" key="min_rx"
2261                 type='{"type": "integer", "minInteger": 1}'>
2262           The shortest interval, in milliseconds, at which this BFD session
2263           offers to receive BFD control messages.  The remote endpoint may
2264           choose to send messages at a slower rate.  Defaults to
2265           <code>1000</code>.
2266         </column>
2267
2268         <column name="bfd" key="min_tx"
2269                 type='{"type": "integer", "minInteger": 1}'>
2270           The shortest interval, in milliseconds, at which this BFD session is
2271           willing to transmit BFD control messages.  Messages will actually be
2272           transmitted at a slower rate if the remote endpoint is not willing to
2273           receive as quickly as specified.  Defaults to <code>100</code>.
2274         </column>
2275
2276         <column name="bfd" key="decay_min_rx" type='{"type": "integer"}'>
2277           An alternate receive interval, in milliseconds, that must be greater
2278           than or equal to <ref column="bfd" key="min_rx"/>.  The
2279           implementation switches from <ref column="bfd" key="min_rx"/> to <ref
2280           column="bfd" key="decay_min_rx"/> when there is no obvious incoming
2281           data traffic at the interface, to reduce the CPU and bandwidth cost
2282           of monitoring an idle interface.  This feature may be disabled by
2283           setting a value of 0.  This feature is reset whenever <ref
2284           column="bfd" key="decay_min_rx"/> or <ref column="bfd" key="min_rx"/>
2285           changes.
2286         </column>
2287
2288         <column name="bfd" key="forwarding_if_rx" type='{"type": "boolean"}'>
2289           When <code>true</code>, traffic received on the
2290           <ref table="Interface"/> is used to indicate the capability of packet
2291           I/O.  BFD control packets are still transmitted and received.  At
2292           least one BFD control packet must be received every 100 * <ref
2293           column="bfd" key="min_rx"/> amount of time.  Otherwise, even if
2294           traffic are received, the <ref column="bfd" key="forwarding"/>
2295           will be <code>false</code>.
2296         </column>
2297
2298         <column name="bfd" key="cpath_down" type='{"type": "boolean"}'>
2299           Set to true to notify the remote endpoint that traffic should not be
2300           forwarded to this system for some reason other than a connectivty
2301           failure on the interface being monitored.  The typical underlying
2302           reason is ``concatenated path down,'' that is, that connectivity
2303           beyond the local system is down.  Defaults to false.
2304         </column>
2305
2306         <column name="bfd" key="check_tnl_key" type='{"type": "boolean"}'>
2307           Set to true to make BFD accept only control messages with a tunnel
2308           key of zero.  By default, BFD accepts control messages with any
2309           tunnel key.
2310         </column>
2311
2312         <column name="bfd" key="bfd_local_src_mac">
2313           Set to an Ethernet address in the form
2314           <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
2315           to set the MAC used as source for transmitted BFD packets.  The
2316           default is the mac address of the BFD enabled interface.
2317         </column>
2318
2319         <column name="bfd" key="bfd_local_dst_mac">
2320           Set to an Ethernet address in the form
2321           <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
2322           to set the MAC used as destination for transmitted BFD packets.  The
2323           default is <code>00:23:20:00:00:01</code>.
2324         </column>
2325
2326         <column name="bfd" key="bfd_remote_dst_mac">
2327           Set to an Ethernet address in the form
2328           <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
2329           to set the MAC used for checking the destination of received BFD packets.
2330           Packets with different destination MAC will not be considered as BFD packets.
2331           If not specified the destination MAC address of received BFD packets
2332           are not checked.
2333         </column>
2334
2335         <column name="bfd" key="bfd_src_ip">
2336           Set to an IPv4 address to set the IP address used as source for
2337           transmitted BFD packets.  The default is <code>169.254.1.1</code>.
2338         </column>
2339
2340         <column name="bfd" key="bfd_dst_ip">
2341           Set to an IPv4 address to set the IP address used as destination
2342           for transmitted BFD packets.  The default is <code>169.254.1.0</code>.
2343         </column>
2344       </group>
2345
2346       <group title="BFD Status">
2347         <p>
2348           The switch sets key-value pairs in the <ref column="bfd_status"/>
2349           column to report the status of BFD on this interface.  When BFD is
2350           not enabled, with <ref column="bfd" key="enable"/>, the switch clears
2351           all key-value pairs from <ref column="bfd_status"/>.
2352         </p>
2353
2354         <column name="bfd_status" key="state"
2355                 type='{"type": "string",
2356                       "enum": ["set", ["admin_down", "down", "init", "up"]]}'>
2357           Reports the state of the BFD session.  The BFD session is fully
2358           healthy and negotiated if <code>UP</code>.
2359         </column>
2360
2361         <column name="bfd_status" key="forwarding" type='{"type": "boolean"}'>
2362           Reports whether the BFD session believes this <ref
2363           table="Interface"/> may be used to forward traffic.  Typically this
2364           means the local session is signaling <code>UP</code>, and the remote
2365           system isn't signaling a problem such as concatenated path down.
2366         </column>
2367
2368         <column name="bfd_status" key="diagnostic">
2369           In case of a problem, set to an error message that reports what the
2370           local BFD session thinks is wrong.  The error messages are defined
2371           in section 4.1 of [RFC 5880].
2372         </column>
2373
2374         <column name="bfd_status" key="remote_state"
2375                 type='{"type": "string",
2376                       "enum": ["set", ["admin_down", "down", "init", "up"]]}'>
2377           Reports the state of the remote endpoint's BFD session.
2378         </column>
2379
2380         <column name="bfd_status" key="remote_diagnostic">
2381           In case of a problem, set to an error message that reports what the
2382           remote endpoint's BFD session thinks is wrong.  The error messages
2383           are defined in section 4.1 of [RFC 5880].
2384         </column>
2385
2386         <column name="bfd_status" key="flap_count"
2387           type='{"type": "integer", "minInteger": 0}'>
2388           Counts the number of <ref column="bfd_status" key="forwarding" />
2389           flaps since start.  A flap is considered as a change of the
2390           <ref column="bfd_status" key="forwarding" /> value.
2391         </column>
2392       </group>
2393     </group>
2394
2395     <group title="Connectivity Fault Management">
2396       <p>
2397         802.1ag Connectivity Fault Management (CFM) allows a group of
2398         Maintenance Points (MPs) called a Maintenance Association (MA) to
2399         detect connectivity problems with each other.  MPs within a MA should
2400         have complete and exclusive interconnectivity.  This is verified by
2401         occasionally broadcasting Continuity Check Messages (CCMs) at a
2402         configurable transmission interval.
2403       </p>
2404
2405       <p>
2406         According to the 802.1ag specification, each Maintenance Point should
2407         be configured out-of-band with a list of Remote Maintenance Points it
2408         should have connectivity to.  Open vSwitch differs from the
2409         specification in this area.  It simply assumes the link is faulted if
2410         no Remote Maintenance Points are reachable, and considers it not
2411         faulted otherwise.
2412       </p>
2413
2414       <p>
2415           When operating over tunnels which have no <code>in_key</code>, or an
2416           <code>in_key</code> of <code>flow</code>.  CFM will only accept CCMs
2417           with a tunnel key of zero.
2418       </p>
2419
2420       <column name="cfm_mpid">
2421         <p>
2422           A Maintenance Point ID (MPID) uniquely identifies each endpoint
2423           within a Maintenance Association.  The MPID is used to identify this
2424           endpoint to other Maintenance Points in the MA.  Each end of a link
2425           being monitored should have a different MPID.  Must be configured to
2426           enable CFM on this <ref table="Interface"/>.
2427         </p>
2428         <p>
2429           According to the 802.1ag specification, MPIDs can only range between
2430           [1, 8191].  However, extended mode (see <ref column="other_config"
2431           key="cfm_extended"/>) supports eight byte MPIDs.
2432         </p>
2433       </column>
2434
2435       <column name="cfm_flap_count">
2436         Counts the number of cfm fault flapps since boot.  A flap is
2437         considered to be a change of the <ref column="cfm_fault"/> value.
2438       </column>
2439
2440       <column name="cfm_fault">
2441         <p>
2442           Indicates a connectivity fault triggered by an inability to receive
2443           heartbeats from any remote endpoint.  When a fault is triggered on
2444           <ref table="Interface"/>s participating in bonds, they will be
2445           disabled.
2446         </p>
2447         <p>
2448           Faults can be triggered for several reasons.  Most importantly they
2449           are triggered when no CCMs are received for a period of 3.5 times the
2450           transmission interval. Faults are also triggered when any CCMs
2451           indicate that a Remote Maintenance Point is not receiving CCMs but
2452           able to send them.  Finally, a fault is triggered if a CCM is
2453           received which indicates unexpected configuration.  Notably, this
2454           case arises when a CCM is received which advertises the local MPID.
2455         </p>
2456       </column>
2457
2458       <column name="cfm_fault_status" key="recv">
2459         Indicates a CFM fault was triggered due to a lack of CCMs received on
2460         the <ref table="Interface"/>.
2461       </column>
2462
2463       <column name="cfm_fault_status" key="rdi">
2464         Indicates a CFM fault was triggered due to the reception of a CCM with
2465         the RDI bit flagged.  Endpoints set the RDI bit in their CCMs when they
2466         are not receiving CCMs themselves.  This typically indicates a
2467         unidirectional connectivity failure.
2468       </column>
2469
2470       <column name="cfm_fault_status" key="maid">
2471         Indicates a CFM fault was triggered due to the reception of a CCM with
2472         a MAID other than the one Open vSwitch uses.  CFM broadcasts are tagged
2473         with an identification number in addition to the MPID called the MAID.
2474         Open vSwitch only supports receiving CCM broadcasts tagged with the
2475         MAID it uses internally.
2476       </column>
2477
2478       <column name="cfm_fault_status" key="loopback">
2479         Indicates a CFM fault was triggered due to the reception of a CCM
2480         advertising the same MPID configured in the <ref column="cfm_mpid"/>
2481         column of this <ref table="Interface"/>.  This may indicate a loop in
2482         the network.
2483       </column>
2484
2485       <column name="cfm_fault_status" key="overflow">
2486         Indicates a CFM fault was triggered because the CFM module received
2487         CCMs from more remote endpoints than it can keep track of.
2488       </column>
2489
2490       <column name="cfm_fault_status" key="override">
2491         Indicates a CFM fault was manually triggered by an administrator using
2492         an <code>ovs-appctl</code> command.
2493       </column>
2494
2495       <column name="cfm_fault_status" key="interval">
2496         Indicates a CFM fault was triggered due to the reception of a CCM
2497         frame having an invalid interval.
2498       </column>
2499
2500       <column name="cfm_remote_opstate">
2501         <p>When in extended mode, indicates the operational state of the
2502           remote endpoint as either <code>up</code> or <code>down</code>.  See
2503           <ref column="other_config" key="cfm_opstate"/>.
2504         </p>
2505       </column>
2506
2507       <column name="cfm_health">
2508         <p>
2509           Indicates the health of the interface as a percentage of CCM frames
2510           received over 21 <ref column="other_config" key="cfm_interval"/>s.
2511           The health of an interface is undefined if it is communicating with
2512           more than one <ref column="cfm_remote_mpids"/>.  It reduces if
2513           healthy heartbeats are not received at the expected rate, and
2514           gradually improves as healthy heartbeats are received at the desired
2515           rate. Every 21 <ref column="other_config" key="cfm_interval"/>s, the
2516           health of the interface is refreshed.
2517         </p>
2518         <p>
2519           As mentioned above, the faults can be triggered for several reasons.
2520           The link health will deteriorate even if heartbeats are received but
2521           they are reported to be unhealthy.  An unhealthy heartbeat in this
2522           context is a heartbeat for which either some fault is set or is out
2523           of sequence.  The interface health can be 100 only on receiving
2524           healthy heartbeats at the desired rate.
2525         </p>
2526       </column>
2527
2528       <column name="cfm_remote_mpids">
2529         When CFM is properly configured, Open vSwitch will occasionally
2530         receive CCM broadcasts.  These broadcasts contain the MPID of the
2531         sending Maintenance Point.  The list of MPIDs from which this
2532         <ref table="Interface"/> is receiving broadcasts from is regularly
2533         collected and written to this column.
2534       </column>
2535
2536       <column name="other_config" key="cfm_interval"
2537               type='{"type": "integer"}'>
2538         <p>
2539           The interval, in milliseconds, between transmissions of CFM
2540           heartbeats.  Three missed heartbeat receptions indicate a
2541           connectivity fault.
2542         </p>
2543
2544         <p>
2545           In standard operation only intervals of 3, 10, 100, 1,000, 10,000,
2546           60,000, or 600,000 ms are supported.  Other values will be rounded
2547           down to the nearest value on the list.  Extended mode (see <ref
2548           column="other_config" key="cfm_extended"/>) supports any interval up
2549           to 65,535 ms.  In either mode, the default is 1000 ms.
2550         </p>
2551
2552         <p>We do not recommend using intervals less than 100 ms.</p>
2553       </column>
2554
2555       <column name="other_config" key="cfm_extended"
2556               type='{"type": "boolean"}'>
2557         When <code>true</code>, the CFM module operates in extended mode. This
2558         causes it to use a nonstandard destination address to avoid conflicting
2559         with compliant implementations which may be running concurrently on the
2560         network. Furthermore, extended mode increases the accuracy of the
2561         <code>cfm_interval</code> configuration parameter by breaking wire
2562         compatibility with 802.1ag compliant implementations.  And extended
2563         mode allows eight byte MPIDs.  Defaults to <code>false</code>.
2564       </column>
2565
2566       <column name="other_config" key="cfm_demand" type='{"type": "boolean"}'>
2567         <p>
2568           When <code>true</code>, and
2569           <ref column="other_config" key="cfm_extended"/> is true, the CFM
2570           module operates in demand mode.  When in demand mode, traffic
2571           received on the <ref table="Interface"/> is used to indicate
2572           liveness.  CCMs are still transmitted and received.  At least one
2573           CCM must be received every 100 * <ref column="other_config"
2574           key="cfm_interval"/> amount of time.  Otherwise, even if traffic
2575           are received, the CFM module will raise the connectivity fault.
2576         </p>
2577
2578         <p>
2579             Demand mode has a couple of caveats:
2580           <ul>
2581             <li>
2582               To ensure that ovs-vswitchd has enough time to pull statistics
2583               from the datapath, the fault detection interval is set to
2584               3.5 * MAX(<ref column="other_config" key="cfm_interval"/>, 500)
2585               ms.
2586             </li>
2587
2588             <li>
2589               To avoid ambiguity, demand mode disables itself when there are
2590               multiple remote maintenance points.
2591             </li>
2592
2593             <li>
2594               If the <ref table="Interface"/> is heavily congested, CCMs
2595               containing the <ref column="other_config" key="cfm_opstate"/>
2596               status may be dropped causing changes in the operational state to
2597               be delayed.  Similarly, if CCMs containing the RDI bit are not
2598               received, unidirectional link failures may not be detected.
2599             </li>
2600           </ul>
2601         </p>
2602       </column>
2603
2604       <column name="other_config" key="cfm_opstate"
2605               type='{"type": "string", "enum": ["set", ["down", "up"]]}'>
2606         When <code>down</code>, the CFM module marks all CCMs it generates as
2607         operationally down without triggering a fault.  This allows remote
2608         maintenance points to choose not to forward traffic to the
2609         <ref table="Interface"/> on which this CFM module is running.
2610         Currently, in Open vSwitch, the opdown bit of CCMs affects
2611         <ref table="Interface"/>s participating in bonds, and the bundle
2612         OpenFlow action. This setting is ignored when CFM is not in extended
2613         mode.  Defaults to <code>up</code>.
2614       </column>
2615
2616       <column name="other_config" key="cfm_ccm_vlan"
2617         type='{"type": "integer", "minInteger": 1, "maxInteger": 4095}'>
2618         When set, the CFM module will apply a VLAN tag to all CCMs it generates
2619         with the given value.  May be the string <code>random</code> in which
2620         case each CCM will be tagged with a different randomly generated VLAN.
2621       </column>
2622
2623       <column name="other_config" key="cfm_ccm_pcp"
2624         type='{"type": "integer", "minInteger": 1, "maxInteger": 7}'>
2625         When set, the CFM module will apply a VLAN tag to all CCMs it generates
2626         with the given PCP value, the VLAN ID of the tag is governed by the
2627         value of <ref column="other_config" key="cfm_ccm_vlan"/>. If
2628         <ref column="other_config" key="cfm_ccm_vlan"/> is unset, a VLAN ID of
2629         zero is used.
2630       </column>
2631
2632     </group>
2633
2634     <group title="Bonding Configuration">
2635       <column name="other_config" key="lacp-port-id"
2636               type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
2637         The LACP port ID of this <ref table="Interface"/>.  Port IDs are
2638         used in LACP negotiations to identify individual ports
2639         participating in a bond.
2640       </column>
2641
2642       <column name="other_config" key="lacp-port-priority"
2643               type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
2644         The LACP port priority of this <ref table="Interface"/>.  In LACP
2645         negotiations <ref table="Interface"/>s with numerically lower
2646         priorities are preferred for aggregation.
2647       </column>
2648
2649       <column name="other_config" key="lacp-aggregation-key"
2650               type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
2651         The LACP aggregation key of this <ref table="Interface"/>.  <ref
2652         table="Interface"/>s with different aggregation keys may not be active
2653         within a given <ref table="Port"/> at the same time.
2654       </column>
2655     </group>
2656
2657     <group title="Virtual Machine Identifiers">
2658       <p>
2659         These key-value pairs specifically apply to an interface that
2660         represents a virtual Ethernet interface connected to a virtual
2661         machine.  These key-value pairs should not be present for other types
2662         of interfaces.  Keys whose names end in <code>-uuid</code> have
2663         values that uniquely identify the entity in question.  For a Citrix
2664         XenServer hypervisor, these values are UUIDs in RFC 4122 format.
2665         Other hypervisors may use other formats.
2666       </p>
2667
2668       <column name="external_ids" key="attached-mac">
2669         The MAC address programmed into the ``virtual hardware'' for this
2670         interface, in the form
2671         <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
2672         For Citrix XenServer, this is the value of the <code>MAC</code> field
2673         in the VIF record for this interface.
2674       </column>
2675
2676       <column name="external_ids" key="iface-id">
2677         A system-unique identifier for the interface.  On XenServer, this will
2678         commonly be the same as <ref column="external_ids" key="xs-vif-uuid"/>.
2679       </column>
2680
2681       <column name="external_ids" key="iface-status"
2682               type='{"type": "string",
2683                     "enum": ["set", ["active", "inactive"]]}'>
2684         <p>
2685           Hypervisors may sometimes have more than one interface associated
2686           with a given <ref column="external_ids" key="iface-id"/>, only one of
2687           which is actually in use at a given time.  For example, in some
2688           circumstances XenServer has both a ``tap'' and a ``vif'' interface
2689           for a single <ref column="external_ids" key="iface-id"/>, but only
2690           uses one of them at a time.  A hypervisor that behaves this way must
2691           mark the currently in use interface <code>active</code> and the
2692           others <code>inactive</code>.  A hypervisor that never has more than
2693           one interface for a given <ref column="external_ids" key="iface-id"/>
2694           may mark that interface <code>active</code> or omit <ref
2695           column="external_ids" key="iface-status"/> entirely.
2696         </p>
2697
2698         <p>
2699           During VM migration, a given <ref column="external_ids"
2700           key="iface-id"/> might transiently be marked <code>active</code> on
2701           two different hypervisors.  That is, <code>active</code> means that
2702           this <ref column="external_ids" key="iface-id"/> is the active
2703           instance within a single hypervisor, not in a broader scope.
2704           There is one exception: some hypervisors support ``migration'' from a
2705           given hypervisor to itself (most often for test purposes).  During
2706           such a ``migration,'' two instances of a single <ref
2707           column="external_ids" key="iface-id"/> might both be briefly marked
2708           <code>active</code> on a single hypervisor.
2709         </p>
2710       </column>
2711
2712       <column name="external_ids" key="xs-vif-uuid">
2713         The virtual interface associated with this interface.
2714       </column>
2715
2716       <column name="external_ids" key="xs-network-uuid">
2717         The virtual network to which this interface is attached.
2718       </column>
2719
2720       <column name="external_ids" key="vm-id">
2721         The VM to which this interface belongs. On XenServer, this will be the
2722         same as <ref column="external_ids" key="xs-vm-uuid"/>.
2723       </column>
2724
2725       <column name="external_ids" key="xs-vm-uuid">
2726         The VM to which this interface belongs.
2727       </column>
2728     </group>
2729
2730     <group title="VLAN Splinters">
2731       <p>
2732         The ``VLAN splinters'' feature increases Open vSwitch compatibility
2733         with buggy network drivers in old versions of Linux that do not
2734         properly support VLANs when VLAN devices are not used, at some cost
2735         in memory and performance.
2736       </p>
2737
2738       <p>
2739         When VLAN splinters are enabled on a particular interface, Open vSwitch
2740         creates a VLAN device for each in-use VLAN.  For sending traffic tagged
2741         with a VLAN on the interface, it substitutes the VLAN device.  Traffic
2742         received on the VLAN device is treated as if it had been received on
2743         the interface on the particular VLAN.
2744       </p>
2745
2746       <p>
2747         VLAN splinters consider a VLAN to be in use if:
2748       </p>
2749
2750       <ul>
2751         <li>
2752           The VLAN is the <ref table="Port" column="tag"/> value in any <ref
2753           table="Port"/> record.
2754         </li>
2755
2756         <li>
2757           The VLAN is listed within the <ref table="Port" column="trunks"/>
2758           column of the <ref table="Port"/> record of an interface on which
2759           VLAN splinters are enabled.
2760
2761           An empty <ref table="Port" column="trunks"/> does not influence the
2762           in-use VLANs: creating 4,096 VLAN devices is impractical because it
2763           will exceed the current 1,024 port per datapath limit.
2764         </li>
2765
2766         <li>
2767           An OpenFlow flow within any bridge matches the VLAN.
2768         </li>
2769       </ul>
2770
2771       <p>
2772         The same set of in-use VLANs applies to every interface on which VLAN
2773         splinters are enabled.  That is, the set is not chosen separately for
2774         each interface but selected once as the union of all in-use VLANs based
2775         on the rules above.
2776       </p>
2777
2778       <p>
2779         It does not make sense to enable VLAN splinters on an interface for an
2780         access port, or on an interface that is not a physical port.
2781       </p>
2782
2783       <p>
2784         VLAN splinters are deprecated.  When broken device drivers are no
2785         longer in widespread use, we will delete this feature.
2786       </p>
2787
2788       <column name="other_config" key="enable-vlan-splinters"
2789               type='{"type": "boolean"}'>
2790         <p>
2791           Set to <code>true</code> to enable VLAN splinters on this interface.
2792           Defaults to <code>false</code>.
2793         </p>
2794
2795         <p>
2796           VLAN splinters increase kernel and userspace memory overhead, so do
2797           not use them unless they are needed.
2798         </p>
2799
2800         <p>
2801           VLAN splinters do not support 802.1p priority tags.  Received
2802           priorities will appear to be 0, regardless of their actual values,
2803           and priorities on transmitted packets will also be cleared to 0.
2804         </p>
2805       </column>
2806     </group>
2807
2808     <group title="Common Columns">
2809       The overall purpose of these columns is described under <code>Common
2810       Columns</code> at the beginning of this document.
2811
2812       <column name="other_config"/>
2813       <column name="external_ids"/>
2814     </group>
2815   </table>
2816
2817   <table name="Flow_Table" title="OpenFlow table configuration">
2818     <p>Configuration for a particular OpenFlow table.</p>
2819
2820     <column name="name">
2821       The table's name.  Set this column to change the name that controllers
2822       will receive when they request table statistics, e.g. <code>ovs-ofctl
2823       dump-tables</code>.  The name does not affect switch behavior.
2824     </column>
2825
2826     <column name="flow_limit">
2827       If set, limits the number of flows that may be added to the table.  Open
2828       vSwitch may limit the number of flows in a table for other reasons,
2829       e.g. due to hardware limitations or for resource availability or
2830       performance reasons.
2831     </column>
2832
2833     <column name="overflow_policy">
2834       <p>
2835         Controls the switch's behavior when an OpenFlow flow table modification
2836         request would add flows in excess of <ref column="flow_limit"/>.  The
2837         supported values are:
2838       </p>
2839
2840       <dl>
2841         <dt><code>refuse</code></dt>
2842         <dd>
2843           Refuse to add the flow or flows.  This is also the default policy
2844           when <ref column="overflow_policy"/> is unset.
2845         </dd>
2846
2847         <dt><code>evict</code></dt>
2848         <dd>
2849           Delete the flow that will expire soonest.  See <ref column="groups"/>
2850           for details.
2851         </dd>
2852       </dl>
2853     </column>
2854
2855     <column name="groups">
2856       <p>
2857         When <ref column="overflow_policy"/> is <code>evict</code>, this
2858         controls how flows are chosen for eviction when the flow table would
2859         otherwise exceed <ref column="flow_limit"/> flows.  Its value is a set
2860         of NXM fields or sub-fields, each of which takes one of the forms
2861         <code><var>field</var>[]</code> or
2862         <code><var>field</var>[<var>start</var>..<var>end</var>]</code>,
2863         e.g. <code>NXM_OF_IN_PORT[]</code>.  Please see
2864         <code>nicira-ext.h</code> for a complete list of NXM field names.
2865       </p>
2866
2867       <p>
2868         When a flow must be evicted due to overflow, the flow to evict is
2869         chosen through an approximation of the following algorithm:
2870       </p>
2871
2872       <ol>
2873         <li>
2874           Divide the flows in the table into groups based on the values of the
2875           specified fields or subfields, so that all of the flows in a given
2876           group have the same values for those fields.  If a flow does not
2877           specify a given field, that field's value is treated as 0.
2878         </li>
2879
2880         <li>
2881           Consider the flows in the largest group, that is, the group that
2882           contains the greatest number of flows.  If two or more groups all
2883           have the same largest number of flows, consider the flows in all of
2884           those groups.
2885         </li>
2886
2887         <li>
2888           Among the flows under consideration, choose the flow that expires
2889           soonest for eviction.
2890         </li>
2891       </ol>
2892
2893       <p>
2894         The eviction process only considers flows that have an idle timeout or
2895         a hard timeout.  That is, eviction never deletes permanent flows.
2896         (Permanent flows do count against <ref column="flow_limit"/>.)
2897       </p>
2898
2899       <p>
2900         Open vSwitch ignores any invalid or unknown field specifications.
2901       </p>
2902
2903       <p>
2904         When <ref column="overflow_policy"/> is not <code>evict</code>, this
2905         column has no effect.
2906       </p>
2907     </column>
2908
2909     <column name="prefixes">
2910       <p>
2911         This string set specifies which fields should be used for
2912         address prefix tracking.  Prefix tracking allows the
2913         classifier to skip rules with longer than necessary prefixes,
2914         resulting in better wildcarding for datapath flows.
2915       </p>
2916       <p>
2917         Prefix tracking may be beneficial when a flow table contains
2918         matches on IP address fields with different prefix lengths.
2919         For example, when a flow table contains IP address matches on
2920         both full addresses and proper prefixes, the full address
2921         matches will typically cause the datapath flow to un-wildcard
2922         the whole address field (depending on flow entry priorities).
2923         In this case each packet with a different address gets handed
2924         to the userspace for flow processing and generates its own
2925         datapath flow.  With prefix tracking enabled for the address
2926         field in question packets with addresses matching shorter
2927         prefixes would generate datapath flows where the irrelevant
2928         address bits are wildcarded, allowing the same datapath flow
2929         to handle all the packets within the prefix in question.  In
2930         this case many userspace upcalls can be avoided and the
2931         overall performance can be better.
2932       </p>
2933       <p>
2934         This is a performance optimization only, so packets will
2935         receive the same treatment with or without prefix tracking.
2936       </p>
2937       <p>
2938         The supported fields are: <code>tun_id</code>,
2939         <code>tun_src</code>, <code>tun_dst</code>,
2940         <code>nw_src</code>, <code>nw_dst</code> (or aliases
2941         <code>ip_src</code> and <code>ip_dst</code>),
2942         <code>ipv6_src</code>, and <code>ipv6_dst</code>.  (Using this
2943         feature for <code>tun_id</code> would only make sense if the
2944         tunnel IDs have prefix structure similar to IP addresses.)
2945       </p>
2946
2947       <p>
2948         By default, the <code>prefixes=ip_dst,ip_src</code> are used
2949         on each flow table.  This instructs the flow classifier to
2950         track the IP destination and source addresses used by the
2951         rules in this specific flow table.
2952       </p>
2953
2954       <p>
2955         The keyword <code>none</code> is recognized as an explicit
2956         override of the default values, causing no prefix fields to be
2957         tracked.
2958       </p>
2959
2960       <p>
2961         To set the prefix fields, the flow table record needs to
2962         exist:
2963       </p>
2964
2965       <dl>
2966         <dt><code>ovs-vsctl set Bridge br0 flow_tables:0=@N1 -- --id=@N1 create Flow_Table name=table0</code></dt>
2967         <dd>
2968           Creates a flow table record for the OpenFlow table number 0.
2969         </dd>
2970
2971         <dt><code>ovs-vsctl set Flow_Table table0 prefixes=ip_dst,ip_src</code></dt>
2972         <dd>
2973           Enables prefix tracking for IP source and destination
2974           address fields.
2975         </dd>
2976       </dl>
2977
2978       <p>
2979         There is a maximum number of fields that can be enabled for any
2980         one flow table.  Currently this limit is 3.
2981       </p>
2982     </column>
2983
2984     <group title="Common Columns">
2985       The overall purpose of these columns is described under <code>Common
2986       Columns</code> at the beginning of this document.
2987
2988       <column name="external_ids"/>
2989     </group>
2990   </table>
2991
2992   <table name="QoS" title="Quality of Service configuration">
2993     <p>Quality of Service (QoS) configuration for each Port that
2994     references it.</p>
2995
2996     <column name="type">
2997       <p>The type of QoS to implement. The currently defined types are
2998       listed below:</p>
2999       <dl>
3000         <dt><code>linux-htb</code></dt>
3001         <dd>
3002           Linux ``hierarchy token bucket'' classifier.  See tc-htb(8) (also at
3003           <code>http://linux.die.net/man/8/tc-htb</code>) and the HTB manual
3004           (<code>http://luxik.cdi.cz/~devik/qos/htb/manual/userg.htm</code>)
3005           for information on how this classifier works and how to configure it.
3006         </dd>
3007       </dl>
3008       <dl>
3009         <dt><code>linux-hfsc</code></dt>
3010         <dd>
3011           Linux "Hierarchical Fair Service Curve" classifier.
3012           See <code>http://linux-ip.net/articles/hfsc.en/</code> for
3013           information on how this classifier works.
3014         </dd>
3015       </dl>
3016     </column>
3017
3018     <column name="queues">
3019       <p>A map from queue numbers to <ref table="Queue"/> records.  The
3020       supported range of queue numbers depend on <ref column="type"/>.  The
3021       queue numbers are the same as the <code>queue_id</code> used in
3022       OpenFlow in <code>struct ofp_action_enqueue</code> and other
3023       structures.</p>
3024
3025       <p>
3026         Queue 0 is the ``default queue.''  It is used by OpenFlow output
3027         actions when no specific queue has been set.  When no configuration for
3028         queue 0 is present, it is automatically configured as if a <ref
3029         table="Queue"/> record with empty <ref table="Queue" column="dscp"/>
3030         and <ref table="Queue" column="other_config"/> columns had been
3031         specified.
3032         (Before version 1.6, Open vSwitch would leave queue 0 unconfigured in
3033         this case.  With some queuing disciplines, this dropped all packets
3034         destined for the default queue.)
3035       </p>
3036     </column>
3037
3038     <group title="Configuration for linux-htb and linux-hfsc">
3039       <p>
3040         The <code>linux-htb</code> and <code>linux-hfsc</code> classes support
3041         the following key-value pair:
3042       </p>
3043
3044       <column name="other_config" key="max-rate" type='{"type": "integer"}'>
3045         Maximum rate shared by all queued traffic, in bit/s.  Optional.  If not
3046         specified, for physical interfaces, the default is the link rate.  For
3047         other interfaces or if the link rate cannot be determined, the default
3048         is currently 100 Mbps.
3049       </column>
3050     </group>
3051
3052     <group title="Common Columns">
3053       The overall purpose of these columns is described under <code>Common
3054       Columns</code> at the beginning of this document.
3055
3056       <column name="other_config"/>
3057       <column name="external_ids"/>
3058     </group>
3059   </table>
3060
3061   <table name="Queue" title="QoS output queue.">
3062     <p>A configuration for a port output queue, used in configuring Quality of
3063     Service (QoS) features.  May be referenced by <ref column="queues"
3064     table="QoS"/> column in <ref table="QoS"/> table.</p>
3065
3066     <column name="dscp">
3067       If set, Open vSwitch will mark all traffic egressing this
3068       <ref table="Queue"/> with the given DSCP bits.  Traffic egressing the
3069       default <ref table="Queue"/> is only marked if it was explicitly selected
3070       as the <ref table="Queue"/> at the time the packet was output.  If unset,
3071       the DSCP bits of traffic egressing this <ref table="Queue"/> will remain
3072       unchanged.
3073     </column>
3074
3075     <group title="Configuration for linux-htb QoS">
3076       <p>
3077         <ref table="QoS"/> <ref table="QoS" column="type"/>
3078         <code>linux-htb</code> may use <code>queue_id</code>s less than 61440.
3079         It has the following key-value pairs defined.
3080       </p>
3081
3082       <column name="other_config" key="min-rate"
3083               type='{"type": "integer", "minInteger": 1}'>
3084         Minimum guaranteed bandwidth, in bit/s.
3085       </column>
3086
3087       <column name="other_config" key="max-rate"
3088               type='{"type": "integer", "minInteger": 1}'>
3089         Maximum allowed bandwidth, in bit/s.  Optional.  If specified, the
3090         queue's rate will not be allowed to exceed the specified value, even
3091         if excess bandwidth is available.  If unspecified, defaults to no
3092         limit.
3093       </column>
3094
3095       <column name="other_config" key="burst"
3096               type='{"type": "integer", "minInteger": 1}'>
3097         Burst size, in bits.  This is the maximum amount of ``credits'' that a
3098         queue can accumulate while it is idle.  Optional.  Details of the
3099         <code>linux-htb</code> implementation require a minimum burst size, so
3100         a too-small <code>burst</code> will be silently ignored.
3101       </column>
3102
3103       <column name="other_config" key="priority"
3104               type='{"type": "integer", "minInteger": 0, "maxInteger": 4294967295}'>
3105         A queue with a smaller <code>priority</code> will receive all the
3106         excess bandwidth that it can use before a queue with a larger value
3107         receives any.  Specific priority values are unimportant; only relative
3108         ordering matters.  Defaults to 0 if unspecified.
3109       </column>
3110     </group>
3111
3112     <group title="Configuration for linux-hfsc QoS">
3113       <p>
3114         <ref table="QoS"/> <ref table="QoS" column="type"/>
3115         <code>linux-hfsc</code> may use <code>queue_id</code>s less than 61440.
3116         It has the following key-value pairs defined.
3117       </p>
3118
3119       <column name="other_config" key="min-rate"
3120               type='{"type": "integer", "minInteger": 1}'>
3121         Minimum guaranteed bandwidth, in bit/s.
3122       </column>
3123
3124       <column name="other_config" key="max-rate"
3125               type='{"type": "integer", "minInteger": 1}'>
3126         Maximum allowed bandwidth, in bit/s.  Optional.  If specified, the
3127         queue's rate will not be allowed to exceed the specified value, even if
3128         excess bandwidth is available.  If unspecified, defaults to no
3129         limit.
3130       </column>
3131     </group>
3132
3133     <group title="Common Columns">
3134       The overall purpose of these columns is described under <code>Common
3135       Columns</code> at the beginning of this document.
3136
3137       <column name="other_config"/>
3138       <column name="external_ids"/>
3139     </group>
3140   </table>
3141
3142   <table name="Mirror" title="Port mirroring.">
3143     <p>A port mirror within a <ref table="Bridge"/>.</p>
3144     <p>A port mirror configures a bridge to send selected frames to special
3145     ``mirrored'' ports, in addition to their normal destinations.  Mirroring
3146     traffic may also be referred to as SPAN or RSPAN, depending on how
3147     the mirrored traffic is sent.</p>
3148
3149     <column name="name">
3150       Arbitrary identifier for the <ref table="Mirror"/>.
3151     </column>
3152
3153     <group title="Selecting Packets for Mirroring">
3154       <p>
3155         To be selected for mirroring, a given packet must enter or leave the
3156         bridge through a selected port and it must also be in one of the
3157         selected VLANs.
3158       </p>
3159
3160       <column name="select_all">
3161         If true, every packet arriving or departing on any port is
3162         selected for mirroring.
3163       </column>
3164
3165       <column name="select_dst_port">
3166         Ports on which departing packets are selected for mirroring.
3167       </column>
3168
3169       <column name="select_src_port">
3170         Ports on which arriving packets are selected for mirroring.
3171       </column>
3172
3173       <column name="select_vlan">
3174         VLANs on which packets are selected for mirroring.  An empty set
3175         selects packets on all VLANs.
3176       </column>
3177     </group>
3178
3179     <group title="Mirroring Destination Configuration">
3180       <p>
3181         These columns are mutually exclusive.  Exactly one of them must be
3182         nonempty.
3183       </p>
3184
3185       <column name="output_port">
3186         <p>Output port for selected packets, if nonempty.</p>
3187         <p>Specifying a port for mirror output reserves that port exclusively
3188         for mirroring.  No frames other than those selected for mirroring
3189         via this column
3190         will be forwarded to the port, and any frames received on the port
3191         will be discarded.</p>
3192         <p>
3193           The output port may be any kind of port supported by Open vSwitch.
3194           It may be, for example, a physical port (sometimes called SPAN) or a
3195           GRE tunnel.
3196         </p>
3197       </column>
3198
3199       <column name="output_vlan">
3200         <p>Output VLAN for selected packets, if nonempty.</p>
3201         <p>The frames will be sent out all ports that trunk
3202         <ref column="output_vlan"/>, as well as any ports with implicit VLAN
3203         <ref column="output_vlan"/>.  When a mirrored frame is sent out a
3204         trunk port, the frame's VLAN tag will be set to
3205         <ref column="output_vlan"/>, replacing any existing tag; when it is
3206         sent out an implicit VLAN port, the frame will not be tagged.  This
3207         type of mirroring is sometimes called RSPAN.</p>
3208         <p>
3209           See the documentation for
3210           <ref column="other_config" key="forward-bpdu"/> in the
3211           <ref table="Interface"/> table for a list of destination MAC
3212           addresses which will not be mirrored to a VLAN to avoid confusing
3213           switches that interpret the protocols that they represent.
3214         </p>
3215         <p><em>Please note:</em> Mirroring to a VLAN can disrupt a network that
3216         contains unmanaged switches.  Consider an unmanaged physical switch
3217         with two ports: port 1, connected to an end host, and port 2,
3218         connected to an Open vSwitch configured to mirror received packets
3219         into VLAN 123 on port 2.  Suppose that the end host sends a packet on
3220         port 1 that the physical switch forwards to port 2.  The Open vSwitch
3221         forwards this packet to its destination and then reflects it back on
3222         port 2 in VLAN 123.  This reflected packet causes the unmanaged
3223         physical switch to replace the MAC learning table entry, which
3224         correctly pointed to port 1, with one that incorrectly points to port
3225         2.  Afterward, the physical switch will direct packets destined for
3226         the end host to the Open vSwitch on port 2, instead of to the end
3227         host on port 1, disrupting connectivity.  If mirroring to a VLAN is
3228         desired in this scenario, then the physical switch must be replaced
3229         by one that learns Ethernet addresses on a per-VLAN basis.  In
3230         addition, learning should be disabled on the VLAN containing mirrored
3231         traffic. If this is not done then intermediate switches will learn
3232         the MAC address of each end host from the mirrored traffic.  If
3233         packets being sent to that end host are also mirrored, then they will
3234         be dropped since the switch will attempt to send them out the input
3235         port. Disabling learning for the VLAN will cause the switch to
3236         correctly send the packet out all ports configured for that VLAN.  If
3237         Open vSwitch is being used as an intermediate switch, learning can be
3238         disabled by adding the mirrored VLAN to <ref column="flood_vlans"/>
3239         in the appropriate <ref table="Bridge"/> table or tables.</p>
3240         <p>
3241           Mirroring to a GRE tunnel has fewer caveats than mirroring to a
3242           VLAN and should generally be preferred.
3243         </p>
3244       </column>
3245     </group>
3246
3247     <group title="Statistics: Mirror counters">
3248       <p>
3249         Key-value pairs that report mirror statistics.  The update period
3250         is controlled by <ref column="other_config"
3251         key="stats-update-interval"/> in the <code>Open_vSwitch</code> table.
3252       </p>
3253       <column name="statistics" key="tx_packets">
3254         Number of packets transmitted through this mirror.
3255       </column>
3256       <column name="statistics" key="tx_bytes">
3257         Number of bytes transmitted through this mirror.
3258       </column>
3259     </group>
3260
3261     <group title="Common Columns">
3262       The overall purpose of these columns is described under <code>Common
3263       Columns</code> at the beginning of this document.
3264
3265       <column name="external_ids"/>
3266     </group>
3267   </table>
3268
3269   <table name="Controller" title="OpenFlow controller configuration.">
3270     <p>An OpenFlow controller.</p>
3271
3272     <p>
3273       Open vSwitch supports two kinds of OpenFlow controllers:
3274     </p>
3275
3276     <dl>
3277       <dt>Primary controllers</dt>
3278       <dd>
3279         <p>
3280           This is the kind of controller envisioned by the OpenFlow 1.0
3281           specification.  Usually, a primary controller implements a network
3282           policy by taking charge of the switch's flow table.
3283         </p>
3284
3285         <p>
3286           Open vSwitch initiates and maintains persistent connections to
3287           primary controllers, retrying the connection each time it fails or
3288           drops.  The <ref table="Bridge" column="fail_mode"/> column in the
3289           <ref table="Bridge"/> table applies to primary controllers.
3290         </p>
3291
3292         <p>
3293           Open vSwitch permits a bridge to have any number of primary
3294           controllers.  When multiple controllers are configured, Open
3295           vSwitch connects to all of them simultaneously.  Because
3296           OpenFlow 1.0 does not specify how multiple controllers
3297           coordinate in interacting with a single switch, more than
3298           one primary controller should be specified only if the
3299           controllers are themselves designed to coordinate with each
3300           other.  (The Nicira-defined <code>NXT_ROLE</code> OpenFlow
3301           vendor extension may be useful for this.)
3302         </p>
3303       </dd>
3304       <dt>Service controllers</dt>
3305       <dd>
3306         <p>
3307           These kinds of OpenFlow controller connections are intended for
3308           occasional support and maintenance use, e.g. with
3309           <code>ovs-ofctl</code>.  Usually a service controller connects only
3310           briefly to inspect or modify some of a switch's state.
3311         </p>
3312
3313         <p>
3314           Open vSwitch listens for incoming connections from service
3315           controllers.  The service controllers initiate and, if necessary,
3316           maintain the connections from their end.  The <ref table="Bridge"
3317           column="fail_mode"/> column in the <ref table="Bridge"/> table does
3318           not apply to service controllers.
3319         </p>
3320
3321         <p>
3322           Open vSwitch supports configuring any number of service controllers.
3323         </p>
3324       </dd>
3325     </dl>
3326
3327     <p>
3328       The <ref column="target"/> determines the type of controller.
3329     </p>
3330
3331     <group title="Core Features">
3332       <column name="target">
3333         <p>Connection method for controller.</p>
3334         <p>
3335           The following connection methods are currently supported for primary
3336           controllers:
3337         </p>
3338         <dl>
3339           <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
3340           <dd>
3341             <p>The specified SSL <var>port</var> on the host at the
3342             given <var>ip</var>, which must be expressed as an IP
3343             address (not a DNS name).  The <ref table="Open_vSwitch"
3344             column="ssl"/> column in the <ref table="Open_vSwitch"/>
3345             table must point to a valid SSL configuration when this form
3346             is used.</p>
3347             <p>If <var>port</var> is not specified, it currently
3348             defaults to 6633.  In the future, the default will change to
3349             6653, which is the IANA-defined value.</p>
3350             <p>SSL support is an optional feature that is not always built as
3351             part of Open vSwitch.</p>
3352           </dd>
3353           <dt><code>tcp:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
3354           <dd>
3355             <p>
3356               The specified TCP <var>port</var> on the host at the given
3357               <var>ip</var>, which must be expressed as an IP address (not a
3358               DNS name), where <var>ip</var> can be IPv4 or IPv6 address.  If
3359               <var>ip</var> is an IPv6 address, wrap it in square brackets,
3360               e.g. <code>tcp:[::1]:6632</code>.
3361             </p>
3362             <p>
3363               If <var>port</var> is not specified, it currently defaults to
3364               6633.  In the future, the default will change to 6653, which is
3365               the IANA-defined value.
3366             </p>
3367           </dd>
3368         </dl>
3369         <p>
3370           The following connection methods are currently supported for service
3371           controllers:
3372         </p>
3373         <dl>
3374           <dt><code>pssl:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
3375           <dd>
3376             <p>
3377               Listens for SSL connections on the specified TCP <var>port</var>.
3378               If <var>ip</var>, which must be expressed as an IP address (not a
3379               DNS name), is specified, then connections are restricted to the
3380               specified local IP address (either IPv4 or IPv6).  If
3381               <var>ip</var> is an IPv6 address, wrap it in square brackets,
3382               e.g. <code>pssl:6632:[::1]</code>.
3383             </p>
3384             <p>
3385               If <var>port</var> is not specified, it currently defaults to
3386               6633.  If <var>ip</var> is not specified then it listens only on
3387               IPv4 (but not IPv6) addresses.  The
3388               <ref table="Open_vSwitch" column="ssl"/>
3389               column in the <ref table="Open_vSwitch"/> table must point to a
3390               valid SSL configuration when this form is used.
3391             </p>
3392             <p>
3393               If <var>port</var> is not specified, it currently defaults to
3394               6633.  In the future, the default will change to 6653, which is
3395               the IANA-defined value.
3396             </p>
3397             <p>
3398               SSL support is an optional feature that is not always built as
3399               part of Open vSwitch.
3400             </p>
3401           </dd>
3402           <dt><code>ptcp:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
3403           <dd>
3404             <p>
3405               Listens for connections on the specified TCP <var>port</var>.  If
3406               <var>ip</var>, which must be expressed as an IP address (not a
3407               DNS name), is specified, then connections are restricted to the
3408               specified local IP address (either IPv4 or IPv6).  If
3409               <var>ip</var> is an IPv6 address, wrap it in square brackets,
3410               e.g. <code>ptcp:6632:[::1]</code>. If <var>ip</var> is not
3411               specified then it listens only on IPv4 addresses.
3412             </p>
3413             <p>
3414               If <var>port</var> is not specified, it currently defaults to
3415               6633.  In the future, the default will change to 6653, which is
3416               the IANA-defined value.
3417             </p>
3418           </dd>
3419         </dl>
3420         <p>When multiple controllers are configured for a single bridge, the
3421         <ref column="target"/> values must be unique.  Duplicate
3422         <ref column="target"/> values yield unspecified results.</p>
3423       </column>
3424
3425       <column name="connection_mode">
3426         <p>If it is specified, this setting must be one of the following
3427         strings that describes how Open vSwitch contacts this OpenFlow
3428         controller over the network:</p>
3429
3430         <dl>
3431           <dt><code>in-band</code></dt>
3432           <dd>In this mode, this controller's OpenFlow traffic travels over the
3433           bridge associated with the controller.  With this setting, Open
3434           vSwitch allows traffic to and from the controller regardless of the
3435           contents of the OpenFlow flow table.  (Otherwise, Open vSwitch
3436           would never be able to connect to the controller, because it did
3437           not have a flow to enable it.)  This is the most common connection
3438           mode because it is not necessary to maintain two independent
3439           networks.</dd>
3440           <dt><code>out-of-band</code></dt>
3441           <dd>In this mode, OpenFlow traffic uses a control network separate
3442           from the bridge associated with this controller, that is, the
3443           bridge does not use any of its own network devices to communicate
3444           with the controller.  The control network must be configured
3445           separately, before or after <code>ovs-vswitchd</code> is started.
3446           </dd>
3447         </dl>
3448
3449         <p>If not specified, the default is implementation-specific.</p>
3450       </column>
3451     </group>
3452
3453     <group title="Controller Failure Detection and Handling">
3454       <column name="max_backoff">
3455         Maximum number of milliseconds to wait between connection attempts.
3456         Default is implementation-specific.
3457       </column>
3458
3459       <column name="inactivity_probe">
3460         Maximum number of milliseconds of idle time on connection to
3461         controller before sending an inactivity probe message.  If Open
3462         vSwitch does not communicate with the controller for the specified
3463         number of seconds, it will send a probe.  If a response is not
3464         received for the same additional amount of time, Open vSwitch
3465         assumes the connection has been broken and attempts to reconnect.
3466         Default is implementation-specific.  A value of 0 disables
3467         inactivity probes.
3468       </column>
3469     </group>
3470
3471     <group title="Asynchronous Messages">
3472       <p>
3473         OpenFlow switches send certain messages to controllers spontanenously,
3474         that is, not in response to any request from the controller.  These
3475         messages are called ``asynchronous messages.''  These columns allow
3476         asynchronous messages to be limited or disabled to ensure the best use
3477         of network resources.
3478       </p>
3479
3480       <column name="enable_async_messages">
3481         The OpenFlow protocol enables asynchronous messages at time of
3482         connection establishment, which means that a controller can receive
3483         asynchronous messages, potentially many of them, even if it turns them
3484         off immediately after connecting.  Set this column to
3485         <code>false</code> to change Open vSwitch behavior to disable, by
3486         default, all asynchronous messages.  The controller can use the
3487         <code>NXT_SET_ASYNC_CONFIG</code> Nicira extension to OpenFlow to turn
3488         on any messages that it does want to receive, if any.
3489       </column>
3490
3491       <group title="Controller Rate Limiting">
3492         <p>
3493           A switch can forward packets to a controller over the OpenFlow
3494           protocol.  Forwarding packets this way at too high a rate can
3495           overwhelm a controller, frustrate use of the OpenFlow connection for
3496           other purposes, increase the latency of flow setup, and use an
3497           unreasonable amount of bandwidth.  Therefore, Open vSwitch supports
3498           limiting the rate of packet forwarding to a controller.
3499         </p>
3500
3501         <p>
3502           There are two main reasons in OpenFlow for a packet to be sent to a
3503           controller: either the packet ``misses'' in the flow table, that is,
3504           there is no matching flow, or a flow table action says to send the
3505           packet to the controller.  Open vSwitch limits the rate of each kind
3506           of packet separately at the configured rate.  Therefore, the actual
3507           rate that packets are sent to the controller can be up to twice the
3508           configured rate, when packets are sent for both reasons.
3509         </p>
3510
3511         <p>
3512           This feature is specific to forwarding packets over an OpenFlow
3513           connection.  It is not general-purpose QoS.  See the <ref
3514           table="QoS"/> table for quality of service configuration, and <ref
3515           column="ingress_policing_rate" table="Interface"/> in the <ref
3516           table="Interface"/> table for ingress policing configuration.
3517         </p>
3518
3519         <column name="controller_rate_limit">
3520           <p>
3521             The maximum rate at which the switch will forward packets to the
3522             OpenFlow controller, in packets per second.  If no value is
3523             specified, rate limiting is disabled.
3524           </p>
3525         </column>
3526
3527         <column name="controller_burst_limit">
3528           <p>
3529             When a high rate triggers rate-limiting, Open vSwitch queues
3530             packets to the controller for each port and transmits them to the
3531             controller at the configured rate.  This value limits the number of
3532             queued packets.  Ports on a bridge share the packet queue fairly.
3533           </p>
3534
3535           <p>
3536             This value has no effect unless <ref
3537             column="controller_rate_limit"/> is configured.  The current
3538             default when this value is not specified is one-quarter of <ref
3539             column="controller_rate_limit"/>, meaning that queuing can delay
3540             forwarding a packet to the controller by up to 250 ms.
3541           </p>
3542         </column>
3543
3544         <group title="Controller Rate Limiting Statistics">
3545           <p>
3546             These values report the effects of rate limiting.  Their values are
3547             relative to establishment of the most recent OpenFlow connection,
3548             or since rate limiting was enabled, whichever happened more
3549             recently.  Each consists of two values, one with <code>TYPE</code>
3550             replaced by <code>miss</code> for rate limiting flow table misses,
3551             and the other with <code>TYPE</code> replaced by
3552             <code>action</code> for rate limiting packets sent by OpenFlow
3553             actions.
3554           </p>
3555
3556           <p>
3557             These statistics are reported only when controller rate limiting is
3558             enabled.
3559           </p>
3560
3561           <column name="status" key="packet-in-TYPE-bypassed"
3562                   type='{"type": "integer", "minInteger": 0}'>
3563             Number of packets sent directly to the controller, without queuing,
3564             because the rate did not exceed the configured maximum.
3565           </column>
3566
3567           <column name="status" key="packet-in-TYPE-queued"
3568                   type='{"type": "integer", "minInteger": 0}'>
3569             Number of packets added to the queue to send later.
3570           </column>
3571
3572           <column name="status" key="packet-in-TYPE-dropped"
3573                   type='{"type": "integer", "minInteger": 0}'>
3574             Number of packets added to the queue that were later dropped due to
3575             overflow.  This value is less than or equal to <ref column="status"
3576             key="packet-in-TYPE-queued"/>.
3577           </column>
3578
3579           <column name="status" key="packet-in-TYPE-backlog"
3580                   type='{"type": "integer", "minInteger": 0}'>
3581             Number of packets currently queued.  The other statistics increase
3582             monotonically, but this one fluctuates between 0 and the <ref
3583             column="controller_burst_limit"/> as conditions change.
3584           </column>
3585         </group>
3586       </group>
3587     </group>
3588
3589     <group title="Additional In-Band Configuration">
3590       <p>These values are considered only in in-band control mode (see
3591       <ref column="connection_mode"/>).</p>
3592
3593       <p>When multiple controllers are configured on a single bridge, there
3594       should be only one set of unique values in these columns.  If different
3595       values are set for these columns in different controllers, the effect
3596       is unspecified.</p>
3597
3598       <column name="local_ip">
3599         The IP address to configure on the local port,
3600         e.g. <code>192.168.0.123</code>.  If this value is unset, then
3601         <ref column="local_netmask"/> and <ref column="local_gateway"/> are
3602         ignored.
3603       </column>
3604
3605       <column name="local_netmask">
3606         The IP netmask to configure on the local port,
3607         e.g. <code>255.255.255.0</code>.  If <ref column="local_ip"/> is set
3608         but this value is unset, then the default is chosen based on whether
3609         the IP address is class A, B, or C.
3610       </column>
3611
3612       <column name="local_gateway">
3613         The IP address of the gateway to configure on the local port, as a
3614         string, e.g. <code>192.168.0.1</code>.  Leave this column unset if
3615         this network has no gateway.
3616       </column>
3617     </group>
3618
3619     <group title="Controller Status">
3620       <column name="is_connected">
3621         <code>true</code> if currently connected to this controller,
3622         <code>false</code> otherwise.
3623       </column>
3624
3625       <column name="role"
3626               type='{"type": "string", "enum": ["set", ["other", "master", "slave"]]}'>
3627         <p>The level of authority this controller has on the associated
3628         bridge. Possible values are:</p>
3629         <dl>
3630           <dt><code>other</code></dt>
3631           <dd>Allows the controller access to all OpenFlow features.</dd>
3632           <dt><code>master</code></dt>
3633           <dd>Equivalent to <code>other</code>, except that there may be at
3634           most one master controller at a time.  When a controller configures
3635           itself as <code>master</code>, any existing master is demoted to
3636           the <code>slave</code> role.</dd>
3637           <dt><code>slave</code></dt>
3638           <dd>Allows the controller read-only access to OpenFlow features.
3639           Attempts to modify the flow table will be rejected with an
3640           error.  Slave controllers do not receive OFPT_PACKET_IN or
3641           OFPT_FLOW_REMOVED messages, but they do receive OFPT_PORT_STATUS
3642           messages.</dd>
3643         </dl>
3644       </column>
3645
3646       <column name="status" key="last_error">
3647         A human-readable description of the last error on the connection
3648         to the controller; i.e. <code>strerror(errno)</code>.  This key
3649         will exist only if an error has occurred.
3650       </column>
3651
3652       <column name="status" key="state"
3653               type='{"type": "string", "enum": ["set", ["VOID", "BACKOFF", "CONNECTING", "ACTIVE", "IDLE"]]}'>
3654         <p>
3655           The state of the connection to the controller:
3656         </p>
3657         <dl>
3658           <dt><code>VOID</code></dt>
3659           <dd>Connection is disabled.</dd>
3660
3661           <dt><code>BACKOFF</code></dt>
3662           <dd>Attempting to reconnect at an increasing period.</dd>
3663
3664           <dt><code>CONNECTING</code></dt>
3665           <dd>Attempting to connect.</dd>
3666
3667           <dt><code>ACTIVE</code></dt>
3668           <dd>Connected, remote host responsive.</dd>
3669
3670           <dt><code>IDLE</code></dt>
3671           <dd>Connection is idle.  Waiting for response to keep-alive.</dd>
3672         </dl>
3673         <p>
3674           These values may change in the future.  They are provided only for
3675           human consumption.
3676         </p>
3677       </column>
3678
3679       <column name="status" key="sec_since_connect"
3680               type='{"type": "integer", "minInteger": 0}'>
3681         The amount of time since this controller last successfully connected to
3682         the switch (in seconds).  Value is empty if controller has never
3683         successfully connected.
3684       </column>
3685
3686       <column name="status" key="sec_since_disconnect"
3687               type='{"type": "integer", "minInteger": 1}'>
3688         The amount of time since this controller last disconnected from
3689         the switch (in seconds). Value is empty if controller has never
3690         disconnected.
3691       </column>
3692     </group>
3693
3694     <group title="Connection Parameters">
3695       <p>
3696         Additional configuration for a connection between the controller
3697         and the Open vSwitch.
3698       </p>
3699
3700       <column name="other_config" key="dscp"
3701                 type='{"type": "integer"}'>
3702         The Differentiated Service Code Point (DSCP) is specified using 6 bits
3703         in the Type of Service (TOS) field in the IP header. DSCP provides a
3704         mechanism to classify the network traffic and provide Quality of
3705         Service (QoS) on IP networks.
3706
3707         The DSCP value specified here is used when establishing the connection
3708         between the controller and the Open vSwitch.  If no value is specified,
3709         a default value of 48 is chosen.  Valid DSCP values must be in the
3710         range 0 to 63.
3711       </column>
3712     </group>
3713
3714
3715     <group title="Common Columns">
3716       The overall purpose of these columns is described under <code>Common
3717       Columns</code> at the beginning of this document.
3718
3719       <column name="external_ids"/>
3720       <column name="other_config"/>
3721     </group>
3722   </table>
3723
3724   <table name="Manager" title="OVSDB management connection.">
3725     <p>
3726       Configuration for a database connection to an Open vSwitch database
3727       (OVSDB) client.
3728     </p>
3729
3730     <p>
3731       This table primarily configures the Open vSwitch database
3732       (<code>ovsdb-server</code>), not the Open vSwitch switch
3733       (<code>ovs-vswitchd</code>).  The switch does read the table to determine
3734       what connections should be treated as in-band.
3735     </p>
3736
3737     <p>
3738       The Open vSwitch database server can initiate and maintain active
3739       connections to remote clients.  It can also listen for database
3740       connections.
3741     </p>
3742
3743     <group title="Core Features">
3744       <column name="target">
3745         <p>Connection method for managers.</p>
3746         <p>
3747           The following connection methods are currently supported:
3748         </p>
3749         <dl>
3750           <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
3751           <dd>
3752             <p>
3753               The specified SSL <var>port</var> on the host at the given
3754               <var>ip</var>, which must be expressed as an IP address
3755               (not a DNS name).  The <ref table="Open_vSwitch"
3756               column="ssl"/> column in the <ref table="Open_vSwitch"/>
3757               table must point to a valid SSL configuration when this
3758               form is used.
3759             </p>
3760             <p>
3761               If <var>port</var> is not specified, it currently defaults
3762               to 6632.  In the future, the default will change to 6640,
3763               which is the IANA-defined value.
3764             </p>
3765             <p>
3766               SSL support is an optional feature that is not always
3767               built as part of Open vSwitch.
3768             </p>
3769           </dd>
3770
3771           <dt><code>tcp:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
3772           <dd>
3773             <p>
3774               The specified TCP <var>port</var> on the host at the given
3775               <var>ip</var>, which must be expressed as an IP address (not a
3776               DNS name), where <var>ip</var> can be IPv4 or IPv6 address.  If
3777               <var>ip</var> is an IPv6 address, wrap it in square brackets,
3778               e.g. <code>tcp:[::1]:6632</code>.
3779             </p>
3780             <p>
3781               If <var>port</var> is not specified, it currently defaults
3782               to 6632.  In the future, the default will change to 6640,
3783               which is the IANA-defined value.
3784             </p>
3785           </dd>
3786           <dt><code>pssl:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
3787           <dd>
3788             <p>
3789               Listens for SSL connections on the specified TCP <var>port</var>.
3790               Specify 0 for <var>port</var> to have the kernel automatically
3791               choose an available port.  If <var>ip</var>, which must be
3792               expressed as an IP address (not a DNS name), is specified, then
3793               connections are restricted to the specified local IP address
3794               (either IPv4 or IPv6 address).  If <var>ip</var> is an IPv6
3795               address, wrap in square brackets,
3796               e.g. <code>pssl:6632:[::1]</code>.  If <var>ip</var> is not
3797               specified then it listens only on IPv4 (but not IPv6) addresses.
3798               The <ref table="Open_vSwitch" column="ssl"/> column in the <ref
3799               table="Open_vSwitch"/> table must point to a valid SSL
3800               configuration when this form is used.
3801             </p>
3802             <p>
3803               If <var>port</var> is not specified, it currently defaults
3804               to 6632.  In the future, the default will change to 6640,
3805               which is the IANA-defined value.
3806             </p>
3807             <p>
3808               SSL support is an optional feature that is not always built as
3809               part of Open vSwitch.
3810             </p>
3811           </dd>
3812           <dt><code>ptcp:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
3813           <dd>
3814             <p>
3815               Listens for connections on the specified TCP <var>port</var>.
3816               Specify 0 for <var>port</var> to have the kernel automatically
3817               choose an available port.  If <var>ip</var>, which must be
3818               expressed as an IP address (not a DNS name), is specified, then
3819               connections are restricted to the specified local IP address
3820               (either IPv4 or IPv6 address).  If <var>ip</var> is an IPv6
3821               address, wrap it in square brackets,
3822               e.g. <code>ptcp:6632:[::1]</code>.  If <var>ip</var> is not
3823               specified then it listens only on IPv4 addresses.
3824             </p>
3825             <p>
3826               If <var>port</var> is not specified, it currently defaults
3827               to 6632.  In the future, the default will change to 6640,
3828               which is the IANA-defined value.
3829             </p>
3830           </dd>
3831         </dl>
3832         <p>When multiple managers are configured, the <ref column="target"/>
3833         values must be unique.  Duplicate <ref column="target"/> values yield
3834         unspecified results.</p>
3835       </column>
3836
3837       <column name="connection_mode">
3838         <p>
3839           If it is specified, this setting must be one of the following strings
3840           that describes how Open vSwitch contacts this OVSDB client over the
3841           network:
3842         </p>
3843
3844         <dl>
3845           <dt><code>in-band</code></dt>
3846           <dd>
3847             In this mode, this connection's traffic travels over a bridge
3848             managed by Open vSwitch.  With this setting, Open vSwitch allows
3849             traffic to and from the client regardless of the contents of the
3850             OpenFlow flow table.  (Otherwise, Open vSwitch would never be able
3851             to connect to the client, because it did not have a flow to enable
3852             it.)  This is the most common connection mode because it is not
3853             necessary to maintain two independent networks.
3854           </dd>
3855           <dt><code>out-of-band</code></dt>
3856           <dd>
3857             In this mode, the client's traffic uses a control network separate
3858             from that managed by Open vSwitch, that is, Open vSwitch does not
3859             use any of its own network devices to communicate with the client.
3860             The control network must be configured separately, before or after
3861             <code>ovs-vswitchd</code> is started.
3862           </dd>
3863         </dl>
3864
3865         <p>
3866           If not specified, the default is implementation-specific.
3867         </p>
3868       </column>
3869     </group>
3870
3871     <group title="Client Failure Detection and Handling">
3872       <column name="max_backoff">
3873         Maximum number of milliseconds to wait between connection attempts.
3874         Default is implementation-specific.
3875       </column>
3876
3877       <column name="inactivity_probe">
3878         Maximum number of milliseconds of idle time on connection to the client
3879         before sending an inactivity probe message.  If Open vSwitch does not
3880         communicate with the client for the specified number of seconds, it
3881         will send a probe.  If a response is not received for the same
3882         additional amount of time, Open vSwitch assumes the connection has been
3883         broken and attempts to reconnect.  Default is implementation-specific.
3884         A value of 0 disables inactivity probes.
3885       </column>
3886     </group>
3887
3888     <group title="Status">
3889       <column name="is_connected">
3890         <code>true</code> if currently connected to this manager,
3891         <code>false</code> otherwise.
3892       </column>
3893
3894       <column name="status" key="last_error">
3895         A human-readable description of the last error on the connection
3896         to the manager; i.e. <code>strerror(errno)</code>.  This key
3897         will exist only if an error has occurred.
3898       </column>
3899
3900       <column name="status" key="state"
3901               type='{"type": "string", "enum": ["set", ["VOID", "BACKOFF", "CONNECTING", "ACTIVE", "IDLE"]]}'>
3902         <p>
3903           The state of the connection to the manager:
3904         </p>
3905         <dl>
3906           <dt><code>VOID</code></dt>
3907           <dd>Connection is disabled.</dd>
3908
3909           <dt><code>BACKOFF</code></dt>
3910           <dd>Attempting to reconnect at an increasing period.</dd>
3911
3912           <dt><code>CONNECTING</code></dt>
3913           <dd>Attempting to connect.</dd>
3914
3915           <dt><code>ACTIVE</code></dt>
3916           <dd>Connected, remote host responsive.</dd>
3917
3918           <dt><code>IDLE</code></dt>
3919           <dd>Connection is idle.  Waiting for response to keep-alive.</dd>
3920         </dl>
3921         <p>
3922           These values may change in the future.  They are provided only for
3923           human consumption.
3924         </p>
3925       </column>
3926
3927       <column name="status" key="sec_since_connect"
3928               type='{"type": "integer", "minInteger": 0}'>
3929         The amount of time since this manager last successfully connected
3930         to the database (in seconds). Value is empty if manager has never
3931         successfully connected.
3932       </column>
3933
3934       <column name="status" key="sec_since_disconnect"
3935               type='{"type": "integer", "minInteger": 0}'>
3936         The amount of time since this manager last disconnected from the
3937         database (in seconds). Value is empty if manager has never
3938         disconnected.
3939       </column>
3940
3941       <column name="status" key="locks_held">
3942         Space-separated list of the names of OVSDB locks that the connection
3943         holds.  Omitted if the connection does not hold any locks.
3944       </column>
3945
3946       <column name="status" key="locks_waiting">
3947         Space-separated list of the names of OVSDB locks that the connection is
3948         currently waiting to acquire.  Omitted if the connection is not waiting
3949         for any locks.
3950       </column>
3951
3952       <column name="status" key="locks_lost">
3953         Space-separated list of the names of OVSDB locks that the connection
3954         has had stolen by another OVSDB client.  Omitted if no locks have been
3955         stolen from this connection.
3956       </column>
3957
3958       <column name="status" key="n_connections"
3959               type='{"type": "integer", "minInteger": 2}'>
3960         <p>
3961           When <ref column="target"/> specifies a connection method that
3962           listens for inbound connections (e.g. <code>ptcp:</code> or
3963           <code>pssl:</code>) and more than one connection is actually active,
3964           the value is the number of active connections.  Otherwise, this
3965           key-value pair is omitted.
3966         </p>
3967         <p>
3968           When multiple connections are active, status columns and key-value
3969           pairs (other than this one) report the status of one arbitrarily
3970           chosen connection.
3971         </p>
3972       </column>
3973
3974       <column name="status" key="bound_port" type='{"type": "integer"}'>
3975           When <ref column="target"/> is <code>ptcp:</code> or
3976           <code>pssl:</code>, this is the TCP port on which the OVSDB server is
3977           listening.  (This is is particularly useful when <ref
3978           column="target"/> specifies a port of 0, allowing the kernel to
3979           choose any available port.)
3980       </column>
3981     </group>
3982
3983     <group title="Connection Parameters">
3984       <p>
3985         Additional configuration for a connection between the manager
3986         and the Open vSwitch Database.
3987       </p>
3988
3989       <column name="other_config" key="dscp"
3990                 type='{"type": "integer"}'>
3991         The Differentiated Service Code Point (DSCP) is specified using 6 bits
3992         in the Type of Service (TOS) field in the IP header. DSCP provides a
3993         mechanism to classify the network traffic and provide Quality of
3994         Service (QoS) on IP networks.
3995
3996         The DSCP value specified here is used when establishing the connection
3997         between the manager and the Open vSwitch.  If no value is specified, a
3998         default value of 48 is chosen.  Valid DSCP values must be in the range
3999         0 to 63.
4000       </column>
4001     </group>
4002
4003     <group title="Common Columns">
4004       The overall purpose of these columns is described under <code>Common
4005       Columns</code> at the beginning of this document.
4006
4007       <column name="external_ids"/>
4008       <column name="other_config"/>
4009     </group>
4010   </table>
4011
4012   <table name="NetFlow">
4013     A NetFlow target.  NetFlow is a protocol that exports a number of
4014     details about terminating IP flows, such as the principals involved
4015     and duration.
4016
4017     <column name="targets">
4018       NetFlow targets in the form
4019       <code><var>ip</var>:<var>port</var></code>.  The <var>ip</var>
4020       must be specified numerically, not as a DNS name.
4021     </column>
4022
4023     <column name="engine_id">
4024       Engine ID to use in NetFlow messages.  Defaults to datapath index
4025       if not specified.
4026     </column>
4027
4028     <column name="engine_type">
4029       Engine type to use in NetFlow messages.  Defaults to datapath
4030       index if not specified.
4031     </column>
4032
4033     <column name="active_timeout">
4034       <p>
4035         The interval at which NetFlow records are sent for flows that
4036         are still active, in seconds.  A value of <code>0</code>
4037         requests the default timeout (currently 600 seconds); a value
4038         of <code>-1</code> disables active timeouts.
4039       </p>
4040
4041       <p>
4042         The NetFlow passive timeout, for flows that become inactive,
4043         is not configurable.  It will vary depending on the Open
4044         vSwitch version, the forms and contents of the OpenFlow flow
4045         tables, CPU and memory usage, and network activity.  A typical
4046         passive timeout is about a second.
4047       </p>
4048     </column>
4049
4050     <column name="add_id_to_interface">
4051       <p>If this column's value is <code>false</code>, the ingress and egress
4052       interface fields of NetFlow flow records are derived from OpenFlow port
4053       numbers.  When it is <code>true</code>, the 7 most significant bits of
4054       these fields will be replaced by the least significant 7 bits of the
4055       engine id.  This is useful because many NetFlow collectors do not
4056       expect multiple switches to be sending messages from the same host, so
4057       they do not store the engine information which could be used to
4058       disambiguate the traffic.</p>
4059       <p>When this option is enabled, a maximum of 508 ports are supported.</p>
4060     </column>
4061
4062     <group title="Common Columns">
4063       The overall purpose of these columns is described under <code>Common
4064       Columns</code> at the beginning of this document.
4065
4066       <column name="external_ids"/>
4067     </group>
4068   </table>
4069
4070   <table name="SSL">
4071     SSL configuration for an Open_vSwitch.
4072
4073     <column name="private_key">
4074       Name of a PEM file containing the private key used as the switch's
4075       identity for SSL connections to the controller.
4076     </column>
4077
4078     <column name="certificate">
4079       Name of a PEM file containing a certificate, signed by the
4080       certificate authority (CA) used by the controller and manager,
4081       that certifies the switch's private key, identifying a trustworthy
4082       switch.
4083     </column>
4084
4085     <column name="ca_cert">
4086       Name of a PEM file containing the CA certificate used to verify
4087       that the switch is connected to a trustworthy controller.
4088     </column>
4089
4090     <column name="bootstrap_ca_cert">
4091       If set to <code>true</code>, then Open vSwitch will attempt to
4092       obtain the CA certificate from the controller on its first SSL
4093       connection and save it to the named PEM file. If it is successful,
4094       it will immediately drop the connection and reconnect, and from then
4095       on all SSL connections must be authenticated by a certificate signed
4096       by the CA certificate thus obtained.  <em>This option exposes the
4097       SSL connection to a man-in-the-middle attack obtaining the initial
4098       CA certificate.</em>  It may still be useful for bootstrapping.
4099     </column>
4100
4101     <group title="Common Columns">
4102       The overall purpose of these columns is described under <code>Common
4103       Columns</code> at the beginning of this document.
4104
4105       <column name="external_ids"/>
4106     </group>
4107   </table>
4108
4109   <table name="sFlow">
4110     <p>A set of sFlow(R) targets.  sFlow is a protocol for remote
4111     monitoring of switches.</p>
4112
4113     <column name="agent">
4114       Name of the network device whose IP address should be reported as the
4115       ``agent address'' to collectors.  If not specified, the agent device is
4116       figured from the first target address and the routing table.  If the
4117       routing table does not contain a route to the target, the IP address
4118       defaults to the <ref table="Controller" column="local_ip"/> in the
4119       collector's <ref table="Controller"/>.  If an agent IP address cannot be
4120       determined any of these ways, sFlow is disabled.
4121     </column>
4122
4123     <column name="header">
4124       Number of bytes of a sampled packet to send to the collector.
4125       If not specified, the default is 128 bytes.
4126     </column>
4127
4128     <column name="polling">
4129       Polling rate in seconds to send port statistics to the collector.
4130       If not specified, defaults to 30 seconds.
4131     </column>
4132
4133     <column name="sampling">
4134       Rate at which packets should be sampled and sent to the collector.
4135       If not specified, defaults to 400, which means one out of 400
4136       packets, on average, will be sent to the collector.
4137     </column>
4138
4139     <column name="targets">
4140       sFlow targets in the form
4141       <code><var>ip</var>:<var>port</var></code>.
4142     </column>
4143
4144     <group title="Common Columns">
4145       The overall purpose of these columns is described under <code>Common
4146       Columns</code> at the beginning of this document.
4147
4148       <column name="external_ids"/>
4149     </group>
4150   </table>
4151
4152   <table name="IPFIX">
4153     <p>Configuration for sending packets to IPFIX collectors.</p>
4154
4155     <p>
4156       IPFIX is a protocol that exports a number of details about flows.  The
4157       IPFIX implementation in Open vSwitch samples packets at a configurable
4158       rate, extracts flow information from those packets, optionally caches and
4159       aggregates the flow information, and sends the result to one or more
4160       collectors.
4161     </p>
4162
4163     <p>
4164       IPFIX in Open vSwitch can be configured two different ways:
4165     </p>
4166
4167     <ul>
4168       <li>
4169         With <em>per-bridge sampling</em>, Open vSwitch performs IPFIX sampling
4170         automatically on all packets that pass through a bridge.  To configure
4171         per-bridge sampling, create an <ref table="IPFIX"/> record and point a
4172         <ref table="Bridge"/> table's <ref table="Bridge" column="ipfix"/>
4173         column to it.  The <ref table="Flow_Sample_Collector_Set"/> table is
4174         not used for per-bridge sampling.
4175       </li>
4176
4177       <li>
4178         <p>
4179           With <em>flow-based sampling</em>, <code>sample</code> actions in the
4180           OpenFlow flow table drive IPFIX sampling.  See
4181           <code>ovs-ofctl</code>(8) for a description of the
4182           <code>sample</code> action.
4183         </p>
4184
4185         <p>
4186           Flow-based sampling also requires database configuration: create a
4187           <ref table="IPFIX"/> record that describes the IPFIX configuration
4188           and a <ref table="Flow_Sample_Collector_Set"/> record that points to
4189           the <ref table="Bridge"/> whose flow table holds the
4190           <code>sample</code> actions and to <ref table="IPFIX"/> record.  The
4191           <ref table="Bridge" column="ipfix"/> in the <ref table="Bridge"/>
4192           table is not used for flow-based sampling.
4193         </p>
4194       </li>
4195     </ul>
4196
4197     <column name="targets">
4198       IPFIX target collectors in the form
4199       <code><var>ip</var>:<var>port</var></code>.
4200     </column>
4201
4202     <column name="cache_active_timeout">
4203       The maximum period in seconds for which an IPFIX flow record is
4204       cached and aggregated before being sent.  If not specified,
4205       defaults to 0.  If 0, caching is disabled.
4206     </column>
4207
4208     <column name="cache_max_flows">
4209       The maximum number of IPFIX flow records that can be cached at a
4210       time.  If not specified, defaults to 0.  If 0, caching is
4211       disabled.
4212     </column>
4213
4214     <group title="Per-Bridge Sampling">
4215       <p>
4216         These values affect only per-bridge sampling.  See above for a
4217         description of the differences between per-bridge and flow-based
4218         sampling.
4219       </p>
4220
4221       <column name="sampling">
4222         The rate at which packets should be sampled and sent to each target
4223         collector.  If not specified, defaults to 400, which means one out of
4224         400 packets, on average, will be sent to each target collector.
4225       </column>
4226
4227       <column name="obs_domain_id">
4228         The IPFIX Observation Domain ID sent in each IPFIX packet.  If not
4229         specified, defaults to 0.
4230       </column>
4231
4232       <column name="obs_point_id">
4233         The IPFIX Observation Point ID sent in each IPFIX flow record.  If not
4234         specified, defaults to 0.
4235       </column>
4236
4237       <column name="other_config" key="enable-tunnel-sampling"
4238               type='{"type": "boolean"}'>
4239         <p>
4240           Set to <code>true</code> to enable sampling and reporting tunnel
4241           header 7-tuples in IPFIX flow records.  Tunnel sampling is disabled
4242           by default.
4243         </p>
4244
4245         <p>
4246           The following enterprise entities report the sampled tunnel info:
4247         </p>
4248
4249         <dl>
4250           <dt>tunnelType:</dt>
4251           <dd>
4252             <p>ID: 891, and enterprise ID 6876 (VMware).</p>
4253             <p>type: unsigned 8-bit integer.</p>
4254             <p>data type semantics: identifier.</p>
4255             <p>description: Identifier of the layer 2 network overlay network
4256             encapsulation type: 0x01 VxLAN, 0x02 GRE, 0x03 LISP, 0x05 IPsec+GRE,
4257             0x07 GENEVE.</p>
4258           </dd>
4259           <dt>tunnelKey:</dt>
4260           <dd>
4261             <p>ID: 892, and enterprise ID 6876 (VMware).</p>
4262             <p>type: variable-length octetarray.</p>
4263             <p>data type semantics: identifier.</p>
4264             <p>description: Key which is used for identifying an individual
4265             traffic flow within a VxLAN (24-bit VNI), GENEVE (24-bit VNI),
4266             GRE (32- or 64-bit key), or LISP (24-bit instance ID) tunnel. The
4267             key is encoded in this octetarray as a 3-, 4-, or 8-byte integer
4268             ID in network byte order.</p>
4269           </dd>
4270           <dt>tunnelSourceIPv4Address:</dt>
4271           <dd>
4272             <p>ID: 893, and enterprise ID 6876 (VMware).</p>
4273             <p>type: unsigned 32-bit integer.</p>
4274             <p>data type semantics: identifier.</p>
4275             <p>description: The IPv4 source address in the tunnel IP packet
4276             header.</p>
4277           </dd>
4278           <dt>tunnelDestinationIPv4Address:</dt>
4279           <dd>
4280             <p>ID: 894, and enterprise ID 6876 (VMware).</p>
4281             <p>type: unsigned 32-bit integer.</p>
4282             <p>data type semantics: identifier.</p>
4283             <p>description: The IPv4 destination address in the tunnel IP
4284             packet header.</p>
4285           </dd>
4286           <dt>tunnelProtocolIdentifier:</dt>
4287           <dd>
4288             <p>ID: 895, and enterprise ID 6876 (VMware).</p>
4289             <p>type: unsigned 8-bit integer.</p>
4290             <p>data type semantics: identifier.</p>
4291             <p>description: The value of the protocol number in the tunnel
4292             IP packet header. The protocol number identifies the tunnel IP
4293             packet payload type.</p>
4294           </dd>
4295           <dt>tunnelSourceTransportPort:</dt>
4296           <dd>
4297             <p>ID: 896, and enterprise ID 6876 (VMware).</p>
4298             <p>type: unsigned 16-bit integer.</p>
4299             <p>data type semantics: identifier.</p>
4300             <p>description: The source port identifier in the tunnel transport
4301             header. For the transport protocols UDP, TCP, and SCTP, this is
4302             the source port number given in the respective header.</p>
4303           </dd>
4304           <dt>tunnelDestinationTransportPort:</dt>
4305           <dd>
4306             <p>ID: 897, and enterprise ID 6876 (VMware).</p>
4307             <p>type: unsigned 16-bit integer.</p>
4308             <p>data type semantics: identifier.</p>
4309             <p>description: The destination port identifier in the tunnel
4310             transport header. For the transport protocols UDP, TCP, and SCTP,
4311             this is the destination port number given in the respective header.
4312             </p>
4313           </dd>
4314         </dl>
4315       </column>
4316
4317       <column name="other_config" key="enable-input-sampling"
4318               type='{"type": "boolean"}'>
4319         By default, Open vSwitch samples and reports flows at bridge port input
4320         in IPFIX flow records.  Set this column to <code>false</code> to
4321         disable input sampling.
4322       </column>
4323
4324       <column name="other_config" key="enable-output-sampling"
4325               type='{"type": "boolean"}'>
4326         By default, Open vSwitch samples and reports flows at bridge port
4327         output in IPFIX flow records.  Set this column to <code>false</code> to
4328         disable output sampling.
4329       </column>
4330     </group>
4331
4332     <group title="Common Columns">
4333       The overall purpose of these columns is described under <code>Common
4334       Columns</code> at the beginning of this document.
4335
4336       <column name="external_ids"/>
4337     </group>
4338   </table>
4339
4340   <table name="Flow_Sample_Collector_Set">
4341     <p>
4342       A set of IPFIX collectors of packet samples generated by OpenFlow
4343       <code>sample</code> actions.  This table is used only for IPFIX
4344       flow-based sampling, not for per-bridge sampling (see the <ref
4345       table="IPFIX"/> table for a description of the two forms).
4346     </p>
4347
4348     <column name="id">
4349       The ID of this collector set, unique among the bridge's
4350       collector sets, to be used as the <code>collector_set_id</code>
4351       in OpenFlow <code>sample</code> actions.
4352     </column>
4353
4354     <column name="bridge">
4355       The bridge into which OpenFlow <code>sample</code> actions can
4356       be added to send packet samples to this set of IPFIX collectors.
4357     </column>
4358
4359     <column name="ipfix">
4360       Configuration of the set of IPFIX collectors to send one flow
4361       record per sampled packet to.
4362     </column>
4363
4364     <group title="Common Columns">
4365       The overall purpose of these columns is described under <code>Common
4366       Columns</code> at the beginning of this document.
4367
4368       <column name="external_ids"/>
4369     </group>
4370   </table>
4371
4372 </database>