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