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