7a70909e1363c4a02d3c7c1aaa7da88ffc4b2795
[openvswitch] / vswitchd / vswitch.xml
1 <?xml version="1.0" encoding="utf-8"?>
2 <database title="Open vSwitch Configuration Database">
3   <p>A database with this schema holds the configuration for one Open
4     vSwitch daemon.  The root of the configuration for the daemon is
5     the <ref table="Open_vSwitch"/> table, which must have exactly one
6     record.  Records in other tables are significant only when they
7     can be reached directly or indirectly from the
8     <ref table="Open_vSwitch"/> table.</p>
9
10   <table name="Open_vSwitch" title="Open vSwitch configuration.">
11     Configuration for an Open vSwitch daemon.  There must be exactly one record
12     in the <ref table="Open_vSwitch"/> table.
13
14     <group title="Configuration">
15       <column name="bridges">
16         Set of bridges managed by the daemon.
17       </column>
18
19       <column name="ssl">
20         SSL used globally by the daemon.
21       </column>
22
23       <column name="external_ids">
24         Key-value pairs for use by external frameworks that integrate
25         with Open vSwitch, rather than by Open vSwitch itself.  System
26         integrators should either use the Open vSwitch development
27         mailing list to coordinate on common key-value definitions, or
28         choose key names that are likely to be unique.  The currently
29         defined common key-value pairs are:
30         <dl>
31           <dt><code>system-id</code></dt>
32           <dd>A unique identifier for the Open vSwitch's physical host.
33             The form of the identifier depends on the type of the host.
34             On a Citrix XenServer, this will likely be the same as
35             <code>xs-system-uuid</code>.</dd>
36           <dt><code>xs-system-uuid</code></dt>
37           <dd>The Citrix XenServer universally unique identifier for the
38             physical host as displayed by <code>xe host-list</code>.</dd>
39         </dl>
40       </column>
41     </group>
42
43     <group title="Status">
44       <column name="next_cfg">
45         Sequence number for client to increment.  When a client modifies
46         any part of the database configuration and wishes to wait for
47         Open vSwitch to finish applying the changes, it may increment
48         this sequence number.
49       </column>
50
51       <column name="cur_cfg">
52         Sequence number that Open vSwitch sets to the current value of
53         <ref column="next_cfg"/> after it finishes applying a set of
54         configuration changes.
55       </column>
56
57       <column name="capabilities">
58         Describes functionality supported by the hardware and software platform
59         on which this Open vSwitch is based.  Clients should not modify this
60         column.  See the <ref table="Capability"/> description for defined
61         capability categories and the meaning of associated
62         <ref table="Capability"/> records.
63       </column>
64
65       <column name="statistics">
66         <p>
67           Key-value pairs that report statistics about a system running an Open
68           vSwitch.  These are updated periodically (currently, every 5
69           seconds).  Key-value pairs that cannot be determined or that do not
70           apply to a platform are omitted.
71         </p>
72
73         <dl>
74           <dt><code>cpu</code></dt>
75           <dd>
76             <p>
77               Number of CPU processors, threads, or cores currently online and
78               available to the operating system on which Open vSwitch is
79               running, as an integer.  This may be less than the number
80               installed, if some are not online or if they are not available to
81               the operating system.
82             </p>
83             <p>
84               Open vSwitch userspace processes are not multithreaded, but the
85               Linux kernel-based datapath is.
86             </p>
87           </dd>
88
89           <dt><code>load_average</code></dt>
90           <dd>
91             <p>
92               A comma-separated list of three floating-point numbers,
93               representing the system load average over the last 1, 5, and 15
94               minutes, respectively.
95             </p>
96           </dd>
97
98           <dt><code>memory</code></dt>
99           <dd>
100             <p>
101               A comma-separated list of integers, each of which represents a
102               quantity of memory in kilobytes that describes the operating
103               system on which Open vSwitch is running.  In respective order,
104               these values are:
105             </p>
106
107             <ol>
108               <li>Total amount of RAM allocated to the OS.</li>
109               <li>RAM allocated to the OS that is in use.</li>
110               <li>RAM that can be flushed out to disk or otherwise discarded
111               if that space is needed for another purpose.  This number is
112               necessarily less than or equal to the previous value.</li>
113               <li>Total disk space allocated for swap.</li>
114               <li>Swap space currently in use.</li>
115             </ol>
116
117             <p>
118               On Linux, all five values can be determined and are included.  On
119               other operating systems, only the first two values can be
120               determined, so the list will only have two values.
121             </p>
122           </dd>
123
124           <dt><code>process_</code><var>name</var></dt>
125           <dd>
126             <p>
127               One such key-value pair will exist for each running Open vSwitch
128               daemon process, with <var>name</var> replaced by the daemon's
129               name (e.g. <code>process_ovs-vswitchd</code>).  The value is a
130               comma-separated list of integers.  The integers represent the
131               following, with memory measured in kilobytes and durations in
132               milliseconds:
133             </p>
134
135             <ol>
136               <li>The process's virtual memory size.</li>
137               <li>The process's resident set size.</li>
138               <li>The amount of user and system CPU time consumed by the
139               process.</li>
140               <li>The number of times that the process has crashed and been
141               automatically restarted by the monitor.</li>
142               <li>The duration since the process was started.</li>
143               <li>The duration for which the process has been running.</li>
144             </ol>
145
146             <p>
147               The interpretation of some of these values depends on whether the
148               process was started with the <option>--monitor</option>.  If it
149               was not, then the crash count will always be 0 and the two
150               durations will always be the same.  If <option>--monitor</option>
151               was given, then the crash count may be positive; if it is, the
152               latter duration is the amount of time since the most recent crash
153               and restart.
154             </p>
155
156             <p>
157               There will be one key-value pair for each file in Open vSwitch's
158               ``run directory'' (usually <code>/var/run/openvswitch</code>)
159               whose name ends in <code>.pid</code>, whose contents are a
160               process ID, and which is locked by a running process.  The
161               <var>name</var> is taken from the pidfile's name.
162             </p>
163
164             <p>
165               Currently Open vSwitch is only able to obtain all of the above
166               detail on Linux systems.  On other systems, the same key-value
167               pairs will be present but the values will always be the empty
168               string.
169             </p>
170           </dd>
171
172           <dt><code>file_systems</code></dt>
173           <dd>
174             <p>
175               A space-separated list of information on local, writable file
176               systems.  Each item in the list describes one file system and
177               consists in turn of a comma-separated list of the following:
178             </p>
179
180             <ol>
181               <li>Mount point, e.g. <code>/</code> or <code>/var/log</code>.
182               Any spaces or commas in the mount point are replaced by
183               underscores.</li>
184               <li>Total size, in kilobytes, as an integer.</li>
185               <li>Amount of storage in use, in kilobytes, as an integer.</li>
186             </ol>
187
188             <p>
189               This key-value pair is omitted if there are no local, writable
190               file systems or if Open vSwitch cannot obtain the needed
191               information.
192             </p>
193           </dd>
194         </dl>
195       </column>
196     </group>
197
198     <group title="Version Reporting">
199       <p>
200         These columns report the types and versions of the hardware and
201         software running Open vSwitch.  We recommend in general that software
202         should test whether specific features are supported instead of relying
203         on version number checks.  These values are primarily intended for
204         reporting to human administrators.
205       </p>
206
207       <column name="ovs_version">
208         The Open vSwitch version number, e.g. <code>1.1.0pre2</code>.
209         If Open vSwitch was configured with a build number, then it is
210         also included, e.g. <code>1.1.0pre2+build4948</code>.
211       </column>
212
213       <column name="db_version">
214         <p>
215           The database schema version number in the form
216           <code><var>major</var>.<var>minor</var>.<var>tweak</var></code>,
217           e.g. <code>1.2.3</code>.  Whenever the database schema is changed in
218           a non-backward compatible way (e.g. deleting a column or a table),
219           <var>major</var> is incremented.  When the database schema is changed
220           in a backward compatible way (e.g. adding a new column),
221           <var>minor</var> is incremented.  When the database schema is changed
222           cosmetically (e.g. reindenting its syntax), <var>tweak</var> is
223           incremented.
224         </p>
225
226         <p>
227           The schema version is part of the database schema, so it can also be
228           retrieved by fetching the schema using the Open vSwitch database
229           protocol.
230         </p>
231       </column>
232
233       <column name="system_type">
234         <p>
235           An identifier for the type of system on top of which Open vSwitch
236           runs, e.g. <code>XenServer</code> or <code>KVM</code>.
237         </p>
238         <p>
239           System integrators are responsible for choosing and setting an
240           appropriate value for this column.
241         </p>
242       </column>
243
244       <column name="system_version">
245         <p>
246           The version of the system identified by <ref column="system_type"/>,
247           e.g. <code>5.5.0-24648p</code> on XenServer 5.5.0 build 24648.
248         </p>
249         <p>
250           System integrators are responsible for choosing and setting an
251           appropriate value for this column.
252         </p>
253       </column>
254
255     </group>
256
257     <group title="Database Configuration">
258       <p>
259         These columns primarily configure the Open vSwitch database
260         (<code>ovsdb-server</code>), not the Open vSwitch switch
261         (<code>ovs-vswitchd</code>).  The OVSDB database also uses the <ref
262         column="ssl"/> settings.
263       </p>
264
265       <p>
266         The Open vSwitch switch does read the database configuration to
267         determine remote IP addresses to which in-band control should apply.
268       </p>
269
270       <column name="manager_options">
271         Database clients to which the Open vSwitch database server should
272         connect or to which it should listen, along with options for how these
273         connection should be configured.  See the <ref table="Manager"/> table
274         for more information.
275       </column>
276
277       <column name="managers">
278         <p>
279           Remote database clients to which the Open vSwitch's database server
280           should connect or to which it should listen.  Adding an OVSDB target
281           to this set is equivalent to adding it to <ref
282           column="manager_options"/> with all of the default options.
283         </p>
284
285         <p>
286           Use of this column is deprecated and may be removed sometime in the
287           future.  New applications should use and set <ref
288           column="manager_options"/> instead.
289         </p>
290       </column>
291     </group>
292   </table>
293
294   <table name="Bridge">
295     <p>
296       Configuration for a bridge within an
297       <ref table="Open_vSwitch"/>.
298     </p>
299     <p>
300       A <ref table="Bridge"/> record represents an Ethernet switch with one or
301       more ``ports,'' which are the <ref table="Port"/> records pointed to by
302       the <ref table="Bridge"/>'s <ref column="ports"/> column.
303     </p>
304
305     <group title="Core Features">
306       <column name="name">
307         Bridge identifier.  Should be alphanumeric and no more than about 8
308         bytes long.  Must be unique among the names of ports, interfaces, and
309         bridges on a host.
310       </column>
311
312       <column name="ports">
313         Ports included in the bridge.
314       </column>
315
316       <column name="mirrors">
317         Port mirroring configuration.
318       </column>
319
320       <column name="netflow">
321         NetFlow configuration.
322       </column>
323
324       <column name="sflow">
325         sFlow configuration.
326       </column>
327
328       <column name="flood_vlans">
329         VLAN IDs of VLANs on which MAC address learning should be disabled, so
330         that packets are flooded instead of being sent to specific ports that
331         are believed to contain packets' destination MACs.  This should
332         ordinarily be used to disable MAC learning on VLANs used for mirroring
333         (RSPAN VLANs).  It may also be useful for debugging.
334       </column>
335     </group>
336
337     <group title="OpenFlow Configuration">
338       <column name="controller">
339         OpenFlow controller set.  If unset, then no OpenFlow controllers
340         will be used.
341       </column>
342
343       <column name="fail_mode">
344         <p>When a controller is configured, it is, ordinarily, responsible
345           for setting up all flows on the switch.  Thus, if the connection to
346           the controller fails, no new network connections can be set up.
347           If the connection to the controller stays down long enough,
348           no packets can pass through the switch at all.  This setting
349           determines the switch's response to such a situation.  It may be set
350           to one of the following:
351           <dl>
352             <dt><code>standalone</code></dt>
353             <dd>If no message is received from the controller for three
354               times the inactivity probe interval
355               (see <ref column="inactivity_probe"/>), then Open vSwitch
356               will take over responsibility for setting up flows.  In
357               this mode, Open vSwitch causes the bridge to act like an
358               ordinary MAC-learning switch.  Open vSwitch will continue
359               to retry connecting to the controller in the background
360               and, when the connection succeeds, it will discontinue its
361               standalone behavior.</dd>
362             <dt><code>secure</code></dt>
363             <dd>Open vSwitch will not set up flows on its own when the
364               controller connection fails or when no controllers are
365               defined.  The bridge will continue to retry connecting to
366               any defined controllers forever.</dd>
367           </dl>
368         </p>
369         <p>If this value is unset, the default is implementation-specific.</p>
370         <p>When more than one controller is configured,
371           <ref column="fail_mode"/> is considered only when none of the
372           configured controllers can be contacted.</p>
373       </column>
374
375       <column name="datapath_id">
376         Reports the OpenFlow datapath ID in use.  Exactly 16 hex
377         digits.  (Setting this column will have no useful effect.  Set
378         <ref column="other_config"/>:<code>other-config</code>
379         instead.)
380       </column>
381     </group>
382
383     <group title="Other Features">
384       <column name="datapath_type">
385         Name of datapath provider.  The kernel datapath has
386         type <code>system</code>.  The userspace datapath has
387         type <code>netdev</code>.
388       </column>
389
390       <column name="external_ids">
391         Key-value pairs for use by external frameworks that integrate
392         with Open vSwitch, rather than by Open vSwitch itself.  System
393         integrators should either use the Open vSwitch development
394         mailing list to coordinate on common key-value definitions, or
395         choose key names that are likely to be unique.  The currently
396         defined key-value pairs are:
397         <dl>
398           <dt><code>bridge-id</code></dt>
399           <dd>A unique identifier of the bridge.  On Citrix XenServer this
400             will commonly be the same as <code>xs-network-uuids</code>.</dd>
401           <dt><code>xs-network-uuids</code></dt>
402           <dd>Semicolon-delimited set of universally unique identifier(s) for
403             the network with which this bridge is associated on a Citrix
404             XenServer host.  The network identifiers are RFC 4122 UUIDs as
405             displayed by, e.g., <code>xe network-list</code>.</dd>
406         </dl>
407       </column>
408
409       <column name="other_config">
410         Key-value pairs for configuring rarely used bridge
411         features.  The currently defined key-value pairs are:
412         <dl>
413           <dt><code>datapath-id</code></dt>
414           <dd>Exactly 16 hex
415             digits to set the OpenFlow datapath ID to a specific
416             value.  May not be all-zero.</dd>
417           <dt><code>disable-in-band</code></dt>
418           <dd>If set to <code>true</code>, disable in-band control on
419             the bridge regardless of controller and manager settings.</dd>
420           <dt><code>hwaddr</code></dt>
421           <dd>An Ethernet address in the form
422             <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
423             to set the hardware address of the local port and influence the
424             datapath ID.</dd>
425           <dt><code>in-band-queue</code></dt>
426           <dd>
427             A queue ID as a nonnegative integer.  This sets the OpenFlow queue
428             ID that will be used by flows set up by in-band control on this
429             bridge.  If unset, or if the port used by an in-band control flow
430             does not have QoS configured, or if the port does not have a queue
431             with the specified ID, the default queue is used instead.
432           </dd>
433         </dl>
434       </column>
435     </group>
436   </table>
437
438   <table name="Port" table="Port or bond configuration.">
439     <p>A port within a <ref table="Bridge"/>.</p>
440     <p>Most commonly, a port has exactly one ``interface,'' pointed to by its
441       <ref column="interfaces"/> column.  Such a port logically
442       corresponds to a port on a physical Ethernet switch.  A port
443       with more than one interface is a ``bonded port'' (see
444       <ref group="Bonding Configuration"/>).</p>
445     <p>Some properties that one might think as belonging to a port are actually
446       part of the port's <ref table="Interface"/> members.</p>
447
448     <column name="name">
449       Port name.  Should be alphanumeric and no more than about 8
450       bytes long.  May be the same as the interface name, for
451       non-bonded ports.  Must otherwise be unique among the names of
452       ports, interfaces, and bridges on a host.
453     </column>
454
455     <column name="interfaces">
456       The port's interfaces.  If there is more than one, this is a
457       bonded Port.
458     </column>
459
460     <group title="VLAN Configuration">
461       <p>A bridge port must be configured for VLANs in one of two
462         mutually exclusive ways:
463         <ul>
464           <li>A ``trunk port'' has an empty value for <ref
465             column="tag"/>.  Its <ref column="trunks"/> value may be
466             empty or non-empty.</li>
467           <li>An ``implicitly tagged VLAN port'' or ``access port''
468             has an nonempty value for <ref column="tag"/>.  Its
469             <ref column="trunks"/> value must be empty.</li>
470         </ul>
471         If <ref column="trunks"/> and <ref column="tag"/> are both
472         nonempty, the configuration is ill-formed.
473       </p>
474
475       <column name="tag">
476         <p>
477           If this is an access port (see above), the port's implicitly
478           tagged VLAN.  Must be empty if this is a trunk port.
479         </p>
480         <p>
481           Frames arriving on trunk ports will be forwarded to this
482           port only if they are tagged with the given VLAN (or, if
483           <ref column="tag"/> is 0, then if they lack a VLAN header).
484           Frames arriving on other access ports will be forwarded to
485           this port only if they have the same <ref column="tag"/>
486           value.  Frames forwarded to this port will not have an
487           802.1Q header.
488         </p>
489         <p>
490           When a frame with a 802.1Q header that indicates a nonzero
491           VLAN is received on an access port, it is discarded.
492         </p>
493       </column>
494
495       <column name="trunks">
496         <p>
497           If this is a trunk port (see above), the 802.1Q VLAN(s) that
498           this port trunks; if it is empty, then the port trunks all
499           VLANs.  Must be empty if this is an access port.
500         </p>
501         <p>
502           Frames arriving on trunk ports are dropped if they are not
503           in one of the specified VLANs.  For this purpose, packets
504           that have no VLAN header are treated as part of VLAN 0.
505         </p>
506       </column>
507     </group>
508
509     <group title="Bonding Configuration">
510       <p>A port that has more than one interface is a ``bonded port.'' Bonding
511         allows for load balancing and fail-over.  Open vSwitch supports
512         ``source load balancing'' (SLB) and "active backup" bonding.  SLB
513         bonding assigns flows to slaves based on source MAC address and output
514         VLAN, with periodic rebalancing as traffic patterns change.  Active
515         backup bonding assigns all flows to one slave, failing over to a backup
516         slave when the active slave is disabled.  Neither form of bonding
517         require 802.3ad or other special support from the upstream switch to
518         which the slave devices are connected.</p>
519
520       <p>These columns apply only to bonded ports.  Their values are
521         otherwise ignored.</p>
522
523       <column name="bond_type">
524         <p>The type of bonding used for a bonded port.  Currently supported
525           values are <code>slb</code> and <code>active-backup</code>.  Defaults
526           to SLB if unset.</p>
527       </column>
528
529       <column name="bond_updelay">
530         <p>For a bonded port, the number of milliseconds for which carrier must
531           stay up on an interface before the interface is considered to be up.
532           Specify <code>0</code> to enable the interface immediately.</p>
533         <p>This setting is honored only when at least one bonded interface is
534           already enabled.  When no interfaces are enabled, then the first bond
535           interface to come up is enabled immediately.</p>
536       </column>
537
538       <column name="bond_downdelay">
539         For a bonded port, the number of milliseconds for which carrier must
540         stay down on an interface before the interface is considered to be
541         down.  Specify <code>0</code> to disable the interface immediately.
542       </column>
543
544       <column name="bond_fake_iface">
545         For a bonded port, whether to create a fake internal interface with the
546         name of the port.  Use only for compatibility with legacy software that
547         requires this.
548       </column>
549     </group>
550
551     <group title="Other Features">
552       <column name="qos">
553         Quality of Service configuration for this port.
554       </column>
555
556       <column name="mac">
557         The MAC address to use for this port for the purpose of choosing the
558         bridge's MAC address.  This column does not necessarily reflect the
559         port's actual MAC address, nor will setting it change the port's actual
560         MAC address.
561       </column>
562
563       <column name="fake_bridge">
564         Does this port represent a sub-bridge for its tagged VLAN within the
565         Bridge?  See ovs-vsctl(8) for more information.
566       </column>
567
568       <column name="external_ids">
569         <p>
570           Key-value pairs for use by external frameworks that integrate with
571           Open vSwitch, rather than by Open vSwitch itself.  System integrators
572           should either use the Open vSwitch development mailing list to
573           coordinate on common key-value definitions, or choose key names that
574           are likely to be unique.
575         </p>
576         <p>
577           No key-value pairs native to <ref table="Port"/> are currently
578           defined.  For fake bridges (see the <ref column="fake_bridge"/>
579           column), external IDs for the fake bridge are defined here by
580           prefixing a <ref table="Bridge"/> <ref table="Bridge"
581           column="external_ids"/> key with <code>fake-bridge-</code>,
582           e.g. <code>fake-bridge-xs-network-uuids</code>.
583         </p>
584       </column>
585
586       <column name="other_config">
587         Key-value pairs for configuring rarely used port features.  The
588         currently defined key-value pairs are:
589         <dl>
590           <dt><code>hwaddr</code></dt>
591           <dd>An Ethernet address in the form
592             <code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code>.</dd>
593           <dt><code>bond-rebalance-interval</code></dt>
594           <dd>For an SLB bonded port, the number of milliseconds between
595             successive attempts to rebalance the bond, that is, to
596             move source MACs and their flows from one interface on
597             the bond to another in an attempt to keep usage of each
598             interface roughly equal.  The default is 10000 (10
599             seconds), and the minimum is 1000 (1 second).</dd>
600         </dl>
601       </column>
602     </group>
603   </table>
604
605   <table name="Interface" title="One physical network device in a Port.">
606     An interface within a <ref table="Port"/>.
607
608     <group title="Core Features">
609       <column name="name">
610         Interface name.  Should be alphanumeric and no more than about 8 bytes
611         long.  May be the same as the port name, for non-bonded ports.  Must
612         otherwise be unique among the names of ports, interfaces, and bridges
613         on a host.
614       </column>
615
616       <column name="mac">
617         <p>Ethernet address to set for this interface.  If unset then the
618           default MAC address is used:</p>
619         <ul>
620           <li>For the local interface, the default is the lowest-numbered MAC
621             address among the other bridge ports, either the value of the
622             <ref table="Port" column="mac"/> in its <ref table="Port"/> record,
623             if set, or its actual MAC (for bonded ports, the MAC of its slave
624             whose name is first in alphabetical order).  Internal ports and
625             bridge ports that are used as port mirroring destinations (see the
626             <ref table="Mirror"/> table) are ignored.</li>
627           <li>For other internal interfaces, the default MAC is randomly
628             generated.</li>
629           <li>External interfaces typically have a MAC address associated with
630             their hardware.</li>
631         </ul>
632         <p>Some interfaces may not have a software-controllable MAC
633         address.</p>
634       </column>
635
636       <column name="ofport">
637         <p>OpenFlow port number for this interface.  Unlike most columns, this
638           column's value should be set only by Open vSwitch itself.  Other
639           clients should set this column to an empty set (the default) when
640           creating an <ref table="Interface"/>.</p>
641         <p>Open vSwitch populates this column when the port number becomes
642           known.  If the interface is successfully added,
643           <ref column="ofport"/> will be set to a number between 1 and 65535
644           (generally either in the range 1 to 65279, inclusive, or 65534, the
645           port number for the OpenFlow ``local port'').  If the interface
646           cannot be added then Open vSwitch sets this column
647           to -1.</p>
648       </column>
649     </group>
650
651     <group title="System-Specific Details">
652       <column name="type">
653         The interface type, one of:
654         <dl>
655           <dt><code>system</code></dt>
656           <dd>An ordinary network device, e.g. <code>eth0</code> on Linux.
657             Sometimes referred to as ``external interfaces'' since they are
658             generally connected to hardware external to that on which the Open
659             vSwitch is running.  The empty string is a synonym for
660             <code>system</code>.</dd>
661           <dt><code>internal</code></dt>
662           <dd>A simulated network device that sends and receives traffic.  An
663             internal interface whose <ref column="name"/> is the same as its
664             bridge's <ref table="Open_vSwitch" column="name"/> is called the
665             ``local interface.''  It does not make sense to bond an internal
666             interface, so the terms ``port'' and ``interface'' are often used
667             imprecisely for internal interfaces.</dd>
668           <dt><code>tap</code></dt>
669           <dd>A TUN/TAP device managed by Open vSwitch.</dd>
670           <dt><code>gre</code></dt>
671           <dd>An Ethernet over RFC 2890 Generic Routing Encapsulation over IPv4
672              tunnel.  Each tunnel must be uniquely identified by the
673              combination of <code>remote_ip</code>, <code>local_ip</code>, and
674              <code>in_key</code>.  Note that if two ports are defined that are
675              the same except one has an optional identifier and the other does
676              not, the more specific one is matched first.  <code>in_key</code>
677              is considered more specific than <code>local_ip</code> if a port
678              defines one and another port defines the other.  The following
679              options may be specified in the <ref column="options"/> column:
680             <dl>
681               <dt><code>remote_ip</code></dt>
682               <dd>Required.  The tunnel endpoint.</dd>
683             </dl>
684             <dl>
685               <dt><code>local_ip</code></dt>
686               <dd>Optional.  The destination IP that received packets must
687                 match.  Default is to match all addresses.</dd>
688             </dl>
689             <dl>
690               <dt><code>in_key</code></dt>
691               <dd>Optional.  The GRE key that received packets must contain.
692                 It may either be a 32-bit number (no key and a key of 0 are
693                 treated as equivalent) or the word <code>flow</code>.  If
694                 <code>flow</code> is specified then any key will be accepted
695                 and the key will be placed in the <code>tun_id</code> field
696                 for matching in the flow table.  The ovs-ofctl manual page
697                 contains additional information about matching fields in
698                 OpenFlow flows.  Default is no key.</dd>
699             </dl>
700             <dl>
701               <dt><code>out_key</code></dt>
702               <dd>Optional.  The GRE key to be set on outgoing packets.  It may
703                 either be a 32-bit number or the word <code>flow</code>.  If
704                 <code>flow</code> is specified then the key may be set using
705                 the <code>set_tunnel</code> Nicira OpenFlow vendor extension (0
706                 is used in the absence of an action).  The ovs-ofctl manual
707                 page contains additional information about the Nicira OpenFlow
708                 vendor extensions.  Default is no key.</dd>
709             </dl>
710             <dl>
711               <dt><code>key</code></dt>
712               <dd>Optional.  Shorthand to set <code>in_key</code> and
713                 <code>out_key</code> at the same time.</dd>
714             </dl>
715             <dl>
716               <dt><code>tos</code></dt>
717               <dd>Optional.  The value of the ToS bits to be set on the
718                 encapsulating packet.  It may also be the word
719                 <code>inherit</code>, in which case the ToS will be copied from
720                 the inner packet if it is IPv4 or IPv6 (otherwise it will be
721                 0).  Note that the ECN fields are always inherited.  Default is
722                 0.</dd>
723             </dl>
724             <dl>
725               <dt><code>ttl</code></dt>
726               <dd>Optional.  The TTL to be set on the encapsulating packet.
727                 It may also be the word <code>inherit</code>, in which case the
728                 TTL will be copied from the inner packet if it is IPv4 or IPv6
729                 (otherwise it will be the system default, typically 64).
730                 Default is the system default TTL.</dd>
731             </dl>
732             <dl>
733               <dt><code>csum</code></dt>
734               <dd>Optional.  Compute GRE checksums on outgoing packets.
735                 Checksums present on incoming packets will be validated
736                 regardless of this setting.  Note that GRE checksums
737                 impose a significant performance penalty as they cover the
738                 entire packet.  As the contents of the packet is typically
739                 covered by L3 and L4 checksums, this additional checksum only
740                 adds value for the GRE and encapsulated Ethernet headers.
741                 Default is disabled, set to <code>true</code> to enable.</dd>
742             </dl>
743             <dl>
744               <dt><code>pmtud</code></dt>
745               <dd>Optional.  Enable tunnel path MTU discovery.  If enabled
746                 ``ICMP destination unreachable - fragmentation'' needed
747                 messages will be generated for IPv4 packets with the DF bit set
748                 and IPv6 packets above the minimum MTU if the packet size
749                 exceeds the path MTU minus the size of the tunnel headers.  It
750                 also forces the encapsulating packet DF bit to be set (it is
751                 always set if the inner packet implies path MTU discovery).
752                 Note that this option causes behavior that is typically
753                 reserved for routers and therefore is not entirely in
754                 compliance with the IEEE 802.1D specification for bridges.
755                 Default is enabled, set to <code>false</code> to disable.</dd>
756             </dl>
757             <dl>
758               <dt><code>header_cache</code></dt>
759               <dd>Optional.  Enable caching of tunnel headers and the output
760                 path.  This can lead to a significant performance increase
761                 without changing behavior.  In general it should not be
762                 necessary to adjust this setting.  However, the caching can
763                 bypass certain components of the IP stack (such as IP tables)
764                 and it may be useful to disable it if these features are
765                 required or as a debugging measure.  Default is enabled, set to
766                 <code>false</code> to disable.</dd>
767             </dl>
768           </dd>
769           <dt><code>ipsec_gre</code></dt>
770           <dd>An Ethernet over RFC 2890 Generic Routing Encapsulation
771             over IPv4 IPsec tunnel.  Each tunnel (including those of type
772             <code>gre</code>) must be uniquely identified by the
773             combination of <code>remote_ip</code> and
774             <code>local_ip</code>.  Note that if two ports are defined
775             that are the same except one has an optional identifier and
776             the other does not, the more specific one is matched first.
777             An authentication method of <code>peer_cert</code> or
778             <code>psk</code> must be defined.  The following options may
779             be specified in the <ref column="options"/> column:
780             <dl>
781               <dt><code>remote_ip</code></dt>
782               <dd>Required.  The tunnel endpoint.</dd>
783             </dl>
784             <dl>
785               <dt><code>local_ip</code></dt>
786               <dd>Optional.  The destination IP that received packets must
787                 match.  Default is to match all addresses.</dd>
788             </dl>
789             <dl>
790               <dt><code>peer_cert</code></dt>
791               <dd>Required for certificate authentication.  A string
792                 containing the peer's certificate in PEM format.
793                 Additionally the host's certificate must be specified
794                 with the <code>certificate</code> option.</dd>
795             </dl>
796             <dl>
797               <dt><code>certificate</code></dt>
798               <dd>Required for certificate authentication.  The name of a
799                 PEM file containing a certificate that will be presented
800                 to the peer during authentication.</dd>
801             </dl>
802             <dl>
803               <dt><code>private_key</code></dt>
804               <dd>Optional for certificate authentication.  The name of
805                 a PEM file containing the private key associated with
806                 <code>certificate</code>.  If <code>certificate</code>
807                 contains the private key, this option may be omitted.</dd>
808             </dl>
809             <dl>
810               <dt><code>psk</code></dt>
811               <dd>Required for pre-shared key authentication.  Specifies a
812                 pre-shared key for authentication that must be identical on
813                 both sides of the tunnel.</dd>
814             </dl>
815             <dl>
816               <dt><code>in_key</code></dt>
817               <dd>Optional.  The GRE key that received packets must contain.
818                 It may either be a 32-bit number (no key and a key of 0 are
819                 treated as equivalent) or the word <code>flow</code>.  If
820                 <code>flow</code> is specified then any key will be accepted
821                 and the key will be placed in the <code>tun_id</code> field
822                 for matching in the flow table.  The ovs-ofctl manual page
823                 contains additional information about matching fields in
824                 OpenFlow flows.  Default is no key.</dd>
825             </dl>
826             <dl>
827               <dt><code>out_key</code></dt>
828               <dd>Optional.  The GRE key to be set on outgoing packets.  It may
829                 either be a 32-bit number or the word <code>flow</code>.  If
830                 <code>flow</code> is specified then the key may be set using
831                 the <code>set_tunnel</code> Nicira OpenFlow vendor extension (0
832                 is used in the absence of an action).  The ovs-ofctl manual
833                 page contains additional information about the Nicira OpenFlow
834                 vendor extensions.  Default is no key.</dd>
835             </dl>
836             <dl>
837               <dt><code>key</code></dt>
838               <dd>Optional.  Shorthand to set <code>in_key</code> and
839                 <code>out_key</code> at the same time.</dd>
840             </dl>
841             <dl>
842               <dt><code>tos</code></dt>
843               <dd>Optional.  The value of the ToS bits to be set on the
844                 encapsulating packet.  It may also be the word
845                 <code>inherit</code>, in which case the ToS will be copied from
846                 the inner packet if it is IPv4 or IPv6 (otherwise it will be
847                 0).  Note that the ECN fields are always inherited.  Default is
848                 0.</dd>
849             </dl>
850             <dl>
851               <dt><code>ttl</code></dt>
852               <dd>Optional.  The TTL to be set on the encapsulating packet.
853                 It may also be the word <code>inherit</code>, in which case the
854                 TTL will be copied from the inner packet if it is IPv4 or IPv6
855                 (otherwise it will be the system default, typically 64).
856                 Default is the system default TTL.</dd>
857             </dl>
858             <dl>
859               <dt><code>csum</code></dt>
860               <dd>Optional.  Compute GRE checksums on outgoing packets.
861                 Checksums present on incoming packets will be validated
862                 regardless of this setting.  Note that GRE checksums
863                 impose a significant performance penalty as they cover the
864                 entire packet.  As the contents of the packet is typically
865                 covered by L3 and L4 checksums, this additional checksum only
866                 adds value for the GRE and encapsulated Ethernet headers.
867                 Default is disabled, set to <code>true</code> to enable.</dd>
868             </dl>
869             <dl>
870               <dt><code>pmtud</code></dt>
871               <dd>Optional.  Enable tunnel path MTU discovery.  If enabled
872                 ``ICMP destination unreachable - fragmentation'' needed
873                 messages will be generated for IPv4 packets with the DF bit set
874                 and IPv6 packets above the minimum MTU if the packet size
875                 exceeds the path MTU minus the size of the tunnel headers.  It
876                 also forces the encapsulating packet DF bit to be set (it is
877                 always set if the inner packet implies path MTU discovery).
878                 Note that this option causes behavior that is typically
879                 reserved for routers and therefore is not entirely in
880                 compliance with the IEEE 802.1D specification for bridges.
881                 Default is enabled, set to <code>false</code> to disable.</dd>
882             </dl>
883           </dd>
884           <dt><code>capwap</code></dt>
885           <dd>Ethernet tunneling over the UDP transport portion of CAPWAP
886              (RFC 5415).  This allows interoperability with certain switches
887              where GRE is not available.  Note that only the tunneling component
888              of the protocol is implemented.  Due to the non-standard use of
889              CAPWAP, UDP ports 58881 and 58882 are used as the source and
890              destinations ports respectivedly.  Each tunnel must be uniquely
891              identified by the combination of <code>remote_ip</code> and
892              <code>local_ip</code>.  If two ports are defined that are the same
893              except one includes <code>local_ip</code> and the other does not,
894              the more specific one is matched first.  CAPWAP support is not
895              available on all platforms.  Currently it is only supported in the
896              Linux kernel module with kernel versions >= 2.6.25.  The following
897              options may be specified in the <ref column="options"/> column:
898             <dl>
899               <dt><code>remote_ip</code></dt>
900               <dd>Required.  The tunnel endpoint.</dd>
901             </dl>
902             <dl>
903               <dt><code>local_ip</code></dt>
904               <dd>Optional.  The destination IP that received packets must
905                 match.  Default is to match all addresses.</dd>
906             </dl>
907             <dl>
908               <dt><code>tos</code></dt>
909               <dd>Optional.  The value of the ToS bits to be set on the
910                 encapsulating packet.  It may also be the word
911                 <code>inherit</code>, in which case the ToS will be copied from
912                 the inner packet if it is IPv4 or IPv6 (otherwise it will be
913                 0).  Note that the ECN fields are always inherited.  Default is
914                 0.</dd>
915             </dl>
916             <dl>
917               <dt><code>ttl</code></dt>
918               <dd>Optional.  The TTL to be set on the encapsulating packet.
919                 It may also be the word <code>inherit</code>, in which case the
920                 TTL will be copied from the inner packet if it is IPv4 or IPv6
921                 (otherwise it will be the system default, typically 64).
922                 Default is the system default TTL.</dd>
923             </dl>
924             <dl>
925               <dt><code>pmtud</code></dt>
926               <dd>Optional.  Enable tunnel path MTU discovery.  If enabled
927                 ``ICMP destination unreachable - fragmentation'' needed
928                 messages will be generated for IPv4 packets with the DF bit set
929                 and IPv6 packets above the minimum MTU if the packet size
930                 exceeds the path MTU minus the size of the tunnel headers.  It
931                 also forces the encapsulating packet DF bit to be set (it is
932                 always set if the inner packet implies path MTU discovery).
933                 Note that this option causes behavior that is typically
934                 reserved for routers and therefore is not entirely in
935                 compliance with the IEEE 802.1D specification for bridges.
936                 Default is enabled, set to <code>false</code> to disable.</dd>
937             </dl>
938             <dl>
939               <dt><code>header_cache</code></dt>
940               <dd>Optional.  Enable caching of tunnel headers and the output
941                 path.  This can lead to a significant performance increase
942                 without changing behavior.  In general it should not be
943                 necessary to adjust this setting.  However, the caching can
944                 bypass certain components of the IP stack (such as IP tables)
945                 and it may be useful to disable it if these features are
946                 required or as a debugging measure.  Default is enabled, set to
947                 <code>false</code> to disable.</dd>
948             </dl>
949           </dd>
950           <dt><code>patch</code></dt>
951           <dd>
952             <p>
953               A pair of virtual devices that act as a patch cable.  The <ref
954               column="options"/> column must have the following key-value pair:
955             </p>
956             <dl>
957               <dt><code>peer</code></dt>
958               <dd>
959                 The <ref column="name"/> of the <ref table="Interface"/> for
960                 the other side of the patch.  The named <ref
961                 table="Interface"/>'s own <code>peer</code> option must specify
962                 this <ref table="Interface"/>'s name.  That is, the two patch
963                 interfaces must have reversed <ref column="name"/> and
964                 <code>peer</code> values.
965               </dd>
966             </dl>
967           </dd>
968         </dl>
969       </column>
970
971       <column name="options">
972         Configuration options whose interpretation varies based on
973         <ref column="type"/>.
974       </column>
975
976       <column name="status">
977         <p>
978           Key-value pairs that report port status.  Supported status
979           values are <code>type</code>-dependent.
980         </p>
981         <p>The only currently defined key-value pair is:</p>
982         <dl>
983           <dt><code>source_ip</code></dt>
984           <dd>The source IP address used for an IPv4 tunnel end-point,
985             such as <code>gre</code> or <code>capwap</code>.  Not
986             supported by all implementations.</dd>
987         </dl>
988       </column>
989     </group>
990
991     <group title="Ingress Policing">
992       <p>
993         These settings control ingress policing for packets received on this
994         interface.  On a physical interface, this limits the rate at which
995         traffic is allowed into the system from the outside; on a virtual
996         interface (one connected to a virtual machine), this limits the rate at
997         which the VM is able to transmit.
998       </p>
999       <p>
1000         Policing is a simple form of quality-of-service that simply drops
1001         packets received in excess of the configured rate.  Due to its
1002         simplicity, policing is usually less accurate and less effective than
1003         egress QoS (which is configured using the <ref table="QoS"/> and <ref
1004         table="Queue"/> tables).
1005       </p>
1006       <p>
1007         Policing is currently implemented only on Linux.  The Linux
1008         implementation uses a simple ``token bucket'' approach:
1009       </p>
1010       <ul>
1011         <li>
1012           The size of the bucket corresponds to <ref
1013           column="ingress_policing_burst"/>.  Initially the bucket is full.
1014         </li>
1015         <li>
1016           Whenever a packet is received, its size (converted to tokens) is
1017           compared to the number of tokens currently in the bucket.  If the
1018           required number of tokens are available, they are removed and the
1019           packet is forwarded.  Otherwise, the packet is dropped.
1020         </li>
1021         <li>
1022           Whenever it is not full, the bucket is refilled with tokens at the
1023           rate specified by <ref column="ingress_policing_rate"/>.
1024         </li>
1025       </ul>
1026       <p>
1027         Policing interacts badly with some network protocols, and especially
1028         with fragmented IP packets.  Suppose that there is enough network
1029         activity to keep the bucket nearly empty all the time.  Then this token
1030         bucket algorithm will forward a single packet every so often, with the
1031         period depending on packet size and on the configured rate.  All of the
1032         fragments of an IP packets are normally transmitted back-to-back, as a
1033         group.  In such a situation, therefore, only one of these fragments
1034         will be forwarded and the rest will be dropped.  IP does not provide
1035         any way for the intended recipient to ask for only the remaining
1036         fragments.  In such a case there are two likely possibilities for what
1037         will happen next: either all of the fragments will eventually be
1038         retransmitted (as TCP will do), in which case the same problem will
1039         recur, or the sender will not realize that its packet has been dropped
1040         and data will simply be lost (as some UDP-based protocols will do).
1041         Either way, it is possible that no forward progress will ever occur.
1042       </p>
1043       <column name="ingress_policing_rate">
1044         <p>
1045           Maximum rate for data received on this interface, in kbps.  Data
1046           received faster than this rate is dropped.  Set to <code>0</code>
1047           (the default) to disable policing.
1048         </p>
1049       </column>
1050
1051       <column name="ingress_policing_burst">
1052         <p>Maximum burst size for data received on this interface, in kb.  The
1053           default burst size if set to <code>0</code> is 1000 kb.  This value
1054           has no effect if <ref column="ingress_policing_rate"/>
1055           is <code>0</code>.</p>
1056         <p>
1057           Specifying a larger burst size lets the algorithm be more forgiving,
1058           which is important for protocols like TCP that react severely to
1059           dropped packets.  The burst size should be at least the size of the
1060           interface's MTU.  Specifying a value that is numerically at least as
1061           large as 10% of <ref column="ingress_policing_rate"/> helps TCP come
1062           closer to achieving the full rate.
1063         </p>
1064       </column>
1065     </group>
1066
1067     <group title="Other Features">
1068
1069       <column name="monitor">
1070         Connectivity monitor configuration for this interface.
1071       </column>
1072
1073       <column name="external_ids">
1074         Key-value pairs for use by external frameworks that integrate
1075         with Open vSwitch, rather than by Open vSwitch itself.  System
1076         integrators should either use the Open vSwitch development
1077         mailing list to coordinate on common key-value definitions, or
1078         choose key names that are likely to be unique.  The currently
1079         defined common key-value pairs are:
1080         <dl>
1081           <dt><code>attached-mac</code></dt>
1082           <dd>
1083             The MAC address programmed into the ``virtual hardware'' for this
1084             interface, in the form
1085             <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
1086             For Citrix XenServer, this is the value of the <code>MAC</code>
1087             field in the VIF record for this interface.</dd>
1088           <dt><code>iface-id</code></dt>
1089           <dd>A system-unique identifier for the interface.  On XenServer,
1090             this will commonly be the same as <code>xs-vif-uuid</code>.</dd>
1091         </dl>
1092         <p>
1093           Additionally the following key-value pairs specifically
1094           apply to an interface that represents a virtual Ethernet interface
1095           connected to a virtual machine.  These key-value pairs should not be
1096           present for other types of interfaces.  Keys whose names end
1097           in <code>-uuid</code> have values that uniquely identify the entity
1098           in question.  For a Citrix XenServer hypervisor, these values are
1099           UUIDs in RFC 4122 format.  Other hypervisors may use other
1100           formats.
1101         </p>
1102         <p>The currently defined key-value pairs for XenServer are:</p>
1103         <dl>
1104           <dt><code>xs-vif-uuid</code></dt>
1105           <dd>The virtual interface associated with this interface.</dd>
1106           <dt><code>xs-network-uuid</code></dt>
1107           <dd>The virtual network to which this interface is attached.</dd>
1108           <dt><code>xs-vm-uuid</code></dt>
1109           <dd>The VM to which this interface belongs.</dd>
1110         </dl>
1111       </column>
1112
1113       <column name="tunnel_egress_iface">
1114         Egress interface for tunnels.  Currently only relevant for GRE and
1115         CAPWAP tunnels.  On Linux systems, this column will show the name of
1116         the interface which is responsible for routing traffic destined for the
1117         configured <code>remote_ip</code>.  This could be an internal interface
1118         such as a bridge port.
1119       </column>
1120
1121       <column name="other_config">
1122         Key-value pairs for rarely used interface features.  Currently,
1123         there are none defined.
1124       </column>
1125
1126       <column name="statistics">
1127         <p>
1128           Key-value pairs that report interface statistics.  The current
1129           implementation updates these counters periodically.  In the future,
1130           we plan to, instead, update them when an interface is created, when
1131           they are queried (e.g. using an OVSDB <code>select</code> operation),
1132           and just before an interface is deleted due to virtual interface
1133           hot-unplug or VM shutdown, and perhaps at other times, but not on any
1134           regular periodic basis.</p>
1135         <p>
1136           The currently defined key-value pairs are listed below.  These are
1137           the same statistics reported by OpenFlow in its <code>struct
1138           ofp_port_stats</code> structure.  If an interface does not support a
1139           given statistic, then that pair is omitted.</p>
1140         <ul>
1141           <li>
1142             Successful transmit and receive counters:
1143             <dl>
1144               <dt><code>rx_packets</code></dt>
1145               <dd>Number of received packets.</dd>
1146               <dt><code>rx_bytes</code></dt>
1147               <dd>Number of received bytes.</dd>
1148               <dt><code>tx_packets</code></dt>
1149               <dd>Number of transmitted packets.</dd>
1150               <dt><code>tx_bytes</code></dt>
1151               <dd>Number of transmitted bytes.</dd>
1152             </dl>
1153           </li>
1154           <li>
1155             Receive errors:
1156             <dl>
1157               <dt><code>rx_dropped</code></dt>
1158               <dd>Number of packets dropped by RX.</dd>
1159               <dt><code>rx_frame_err</code></dt>
1160               <dd>Number of frame alignment errors.</dd>
1161               <dt><code>rx_over_err</code></dt>
1162               <dd>Number of packets with RX overrun.</dd>
1163               <dt><code>rx_crc_err</code></dt>
1164               <dd>Number of CRC errors.</dd>
1165               <dt><code>rx_errors</code></dt>
1166               <dd>
1167                 Total number of receive errors, greater than or equal
1168                 to the sum of the above.
1169               </dd>
1170             </dl>
1171           </li>
1172           <li>
1173             Transmit errors:
1174             <dl>
1175               <dt><code>tx_dropped</code></dt>
1176               <dd>Number of packets dropped by TX.</dd>
1177               <dt><code>collisions</code></dt>
1178               <dd>Number of collisions.</dd>
1179               <dt><code>tx_errors</code></dt>
1180               <dd>
1181                 Total number of transmit errors, greater
1182                 than or equal to the sum of the above.
1183               </dd>
1184             </dl>
1185           </li>
1186         </ul>
1187       </column>
1188     </group>
1189   </table>
1190
1191   <table name="QoS" title="Quality of Service configuration">
1192     <p>Quality of Service (QoS) configuration for each Port that
1193       references it.</p>
1194
1195     <column name="type">
1196       <p>The type of QoS to implement.  The <ref table="Open_vSwitch"
1197         column="capabilities"/> column in the <ref table="Open_vSwitch"/> table
1198         identifies the types that a switch actually supports.  The currently
1199         defined types are listed below:</p>
1200       <dl>
1201         <dt><code>linux-htb</code></dt>
1202         <dd>
1203           Linux ``hierarchy token bucket'' classifier.  See tc-htb(8) (also at
1204           <code>http://linux.die.net/man/8/tc-htb</code>) and the HTB manual
1205           (<code>http://luxik.cdi.cz/~devik/qos/htb/manual/userg.htm</code>)
1206           for information on how this classifier works and how to configure it.
1207         </dd>
1208       </dl>
1209       <dl>
1210         <dt><code>linux-hfsc</code></dt>
1211         <dd>
1212           Linux "Hierarchical Fair Service Curve" classifier.
1213           See <code>http://linux-ip.net/articles/hfsc.en/</code> for
1214           information on how this classifier works.
1215         </dd>
1216       </dl>
1217     </column>
1218
1219     <column name="queues">
1220       <p>A map from queue numbers to <ref table="Queue"/> records.  The
1221         supported range of queue numbers depend on <ref column="type"/>.  The
1222         queue numbers are the same as the <code>queue_id</code> used in
1223         OpenFlow in <code>struct ofp_action_enqueue</code> and other
1224         structures.  Queue 0 is used by OpenFlow output actions that do not
1225         specify a specific queue.</p>
1226     </column>
1227
1228     <column name="other_config">
1229       <p>Key-value pairs for configuring QoS features that depend on
1230         <ref column="type"/>.</p>
1231       <p>The <code>linux-htb</code> and <code>linux-hfsc</code> classes support
1232           the following key-value pairs:</p>
1233       <dl>
1234         <dt><code>max-rate</code></dt>
1235         <dd>Maximum rate shared by all queued traffic, in bit/s.
1236           Optional.  If not specified, for physical interfaces, the
1237           default is the link rate.  For other interfaces or if the
1238           link rate cannot be determined, the default is currently 100
1239           Mbps.</dd>
1240       </dl>
1241     </column>
1242
1243     <column name="external_ids">
1244       Key-value pairs for use by external frameworks that integrate with Open
1245       vSwitch, rather than by Open vSwitch itself.  System integrators should
1246       either use the Open vSwitch development mailing list to coordinate on
1247       common key-value definitions, or choose key names that are likely to be
1248       unique.  No common key-value pairs are currently defined.
1249     </column>
1250   </table>
1251
1252   <table name="Queue" title="QoS output queue.">
1253     <p>A configuration for a port output queue, used in configuring Quality of
1254       Service (QoS) features.  May be referenced by <ref column="queues"
1255       table="QoS"/> column in <ref table="QoS"/> table.</p>
1256
1257     <column name="other_config">
1258       <p>Key-value pairs for configuring the output queue.  The supported
1259         key-value pairs and their meanings depend on the <ref column="type"/>
1260         of the <ref column="QoS"/> records that reference this row.</p>
1261       <p>The key-value pairs defined for <ref table="QoS"/> <ref table="QoS"
1262         column="type"/> of <code>min-rate</code> are:</p>
1263       <dl>
1264         <dt><code>min-rate</code></dt>
1265         <dd>Minimum guaranteed bandwidth, in bit/s.  Required.  The
1266           floor value is 1500 bytes/s (12,000 bit/s).</dd>
1267       </dl>
1268       <p>The key-value pairs defined for <ref table="QoS"/> <ref table="QoS"
1269         column="type"/> of <code>linux-htb</code> are:</p>
1270       <dl>
1271         <dt><code>min-rate</code></dt>
1272         <dd>Minimum guaranteed bandwidth, in bit/s.  Required.</dd>
1273         <dt><code>max-rate</code></dt>
1274         <dd>Maximum allowed bandwidth, in bit/s.  Optional.  If specified, the
1275           queue's rate will not be allowed to exceed the specified value, even
1276           if excess bandwidth is available.  If unspecified, defaults to no
1277           limit.</dd>
1278         <dt><code>burst</code></dt>
1279         <dd>Burst size, in bits.  This is the maximum amount of ``credits''
1280           that a queue can accumulate while it is idle.  Optional.  Details of
1281           the <code>linux-htb</code> implementation require a minimum burst
1282           size, so a too-small <code>burst</code> will be silently
1283           ignored.</dd>
1284         <dt><code>priority</code></dt>
1285         <dd>A nonnegative 32-bit integer.  Defaults to 0 if
1286           unspecified.  A queue with a smaller <code>priority</code>
1287           will receive all the excess bandwidth that it can use before
1288           a queue with a larger value receives any.  Specific priority
1289           values are unimportant; only relative ordering matters.</dd>
1290       </dl>
1291       <p>The key-value pairs defined for <ref table="QoS"/> <ref table="QoS"
1292         column="type"/> of <code>linux-hfsc</code> are:</p>
1293       <dl>
1294         <dt><code>min-rate</code></dt>
1295         <dd>Minimum guaranteed bandwidth, in bit/s.  Required.</dd>
1296         <dt><code>max-rate</code></dt>
1297         <dd>Maximum allowed bandwidth, in bit/s.  Optional.  If specified, the
1298           queue's rate will not be allowed to exceed the specified value, even
1299           if excess bandwidth is available.  If unspecified, defaults to no
1300           limit.</dd>
1301       </dl>
1302     </column>
1303
1304     <column name="external_ids">
1305       Key-value pairs for use by external frameworks that integrate with Open
1306       vSwitch, rather than by Open vSwitch itself.  System integrators should
1307       either use the Open vSwitch development mailing list to coordinate on
1308       common key-value definitions, or choose key names that are likely to be
1309       unique.  No common key-value pairs are currently defined.
1310     </column>
1311   </table>
1312
1313   <table name="Monitor" title="Connectivity Monitor configuration">
1314     <p>
1315       A <ref table="Monitor"/> attaches to an <ref table="Interface"/> to
1316       implement 802.1ag Connectivity Fault Management (CFM).  CFM allows a
1317       group of Maintenance Points (MPs) called a Maintenance Association (MA)
1318       to detect connectivity problems with each other.  MPs within a MA should
1319       have complete and exclusive interconnectivity.  This is verified by
1320       occasionally broadcasting Continuity Check Messages (CCMs) at a
1321       configurable transmission interval.  A <ref table="Monitor"/> is
1322       responsible for collecting data about other MPs in its MA and
1323       broadcasting CCMs.
1324     </p>
1325
1326     <group title="Monitor Configuration">
1327       <column name="mpid">
1328         A Maintenance Point ID (MPID) uniquely identifies each endpoint within
1329         a Maintenance Association (see <ref column="ma_name"/>).  The MPID is
1330         used to identify this <ref table="Monitor"/> to other endpoints in the
1331         MA.
1332       </column>
1333
1334       <column name="remote_mps">
1335         A set of <ref table="Maintenance_Points"/> which this
1336         <ref table="Monitor"/> should have connectivity to.  If this
1337         <ref table="Monitor"/> does not have connectivity to any MPs in this
1338         set, or has connectivity to any MPs not in this set, a fault is
1339         signaled.
1340       </column>
1341
1342       <column name="ma_name">
1343         A Maintenance Association (MA) name pairs with a Maintenance Domain
1344         (MD) name to uniquely identify a MA.  A MA is a group of endpoints who
1345         have complete and exclusive interconnectivity. Defaults to
1346         <code>ovs</code> if unset.
1347       </column>
1348
1349       <column name="md_name">
1350         A Maintenance Domain name pairs with a Maintenance Association name to
1351         uniquely identify a MA. Defaults to <code>ovs</code> if unset.
1352       </column>
1353
1354       <column name="interval">
1355         The transmission interval of CCMs in milliseconds.  Three missed CCMs
1356         indicate a connectivity fault.  Defaults to 1000ms.
1357       </column>
1358     </group>
1359
1360     <group title="Monitor Status">
1361       <column name="unexpected_remote_mpids">
1362         A set of MPIDs representing MPs to which this <ref table="Monitor"/>
1363         has detected connectivity that are not in the
1364         <ref column="remote_mps"/> set.  This <ref table="Monitor"/> should not
1365         have connectivity to any MPs not listed in <ref column="remote_mps"/>.
1366         Thus, if this set is non-empty a fault is indicated.
1367       </column>
1368
1369       <column name="unexpected_remote_maids">
1370         A set of MAIDs representing foreign Maintenance Associations (MAs)
1371         which this <ref table="Monitor"/> has detected connectivity to. A
1372         <ref table="Monitor"/> should not have connectivity to a Maintenance
1373         Association other than its own.  Thus, if this set is non-empty a fault
1374         is indicated.
1375       </column>
1376
1377       <column name="fault">
1378         Indicates a Connectivity Fault caused by a configuration error, a down
1379         remote MP, or unexpected connectivity to a remote MAID or remote MP.
1380       </column>
1381     </group>
1382   </table>
1383
1384   <table name="Maintenance_Point" title="Maintenance Point configuration">
1385     <p>
1386       A <ref table="Maintenance_Point"/> represents a MP which a
1387       <ref table="Monitor"/> has or should have connectivity to.
1388     </p>
1389
1390     <group title="Maintenance_Point Configuration">
1391       <column name="mpid">
1392         A Maintenance Point ID (MPID) uniquely identifies each endpoint within
1393         a Maintenance Association. All MPs within a MA should have a unique
1394         MPID.
1395       </column>
1396     </group>
1397
1398     <group title="Maintenance_Point Status">
1399       <column name="fault">
1400         Indicates a connectivity fault.
1401       </column>
1402     </group>
1403   </table>
1404
1405   <table name="Mirror" title="Port mirroring (SPAN/RSPAN).">
1406     <p>A port mirror within a <ref table="Bridge"/>.</p>
1407     <p>A port mirror configures a bridge to send selected frames to special
1408       ``mirrored'' ports, in addition to their normal destinations.  Mirroring
1409       traffic may also be referred to as SPAN or RSPAN, depending on the
1410       mechanism used for delivery.</p>
1411
1412     <column name="name">
1413       Arbitrary identifier for the <ref table="Mirror"/>.
1414     </column>
1415
1416     <group title="Selecting Packets for Mirroring">
1417       <column name="select_all">
1418         If true, every packet arriving or departing on any port is
1419         selected for mirroring.
1420       </column>
1421
1422       <column name="select_dst_port">
1423         Ports on which departing packets are selected for mirroring.
1424       </column>
1425
1426       <column name="select_src_port">
1427         Ports on which arriving packets are selected for mirroring.
1428       </column>
1429
1430       <column name="select_vlan">
1431         VLANs on which packets are selected for mirroring.  An empty set
1432         selects packets on all VLANs.
1433       </column>
1434     </group>
1435
1436     <group title="Mirroring Destination Configuration">
1437       <column name="output_port">
1438         <p>Output port for selected packets, if nonempty.  Mutually exclusive
1439           with <ref column="output_vlan"/>.</p>
1440         <p>Specifying a port for mirror output reserves that port exclusively
1441           for mirroring.  No frames other than those selected for mirroring
1442           will be forwarded to the port, and any frames received on the port
1443           will be discarded.</p>
1444         <p>This type of mirroring is sometimes called SPAN.</p>
1445       </column>
1446
1447       <column name="output_vlan">
1448         <p>Output VLAN for selected packets, if nonempty.  Mutually exclusive
1449           with <ref column="output_port"/>.</p>
1450         <p>The frames will be sent out all ports that trunk
1451           <ref column="output_vlan"/>, as well as any ports with implicit VLAN
1452           <ref column="output_vlan"/>.  When a mirrored frame is sent out a
1453           trunk port, the frame's VLAN tag will be set to
1454           <ref column="output_vlan"/>, replacing any existing tag; when it is
1455           sent out an implicit VLAN port, the frame will not be tagged.  This
1456           type of mirroring is sometimes called RSPAN.</p>
1457         <p><em>Please note:</em> Mirroring to a VLAN can disrupt a network that
1458           contains unmanaged switches.  Consider an unmanaged physical switch
1459           with two ports: port 1, connected to an end host, and port 2,
1460           connected to an Open vSwitch configured to mirror received packets
1461           into VLAN 123 on port 2.  Suppose that the end host sends a packet on
1462           port 1 that the physical switch forwards to port 2.  The Open vSwitch
1463           forwards this packet to its destination and then reflects it back on
1464           port 2 in VLAN 123.  This reflected packet causes the unmanaged
1465           physical switch to replace the MAC learning table entry, which
1466           correctly pointed to port 1, with one that incorrectly points to port
1467           2.  Afterward, the physical switch will direct packets destined for
1468           the end host to the Open vSwitch on port 2, instead of to the end
1469           host on port 1, disrupting connectivity.  If mirroring to a VLAN is
1470           desired in this scenario, then the physical switch must be replaced
1471           by one that learns Ethernet addresses on a per-VLAN basis.  In
1472           addition, learning should be disabled on the VLAN containing mirrored
1473           traffic. If this is not done then intermediate switches will learn
1474           the MAC address of each end host from the mirrored traffic.  If
1475           packets being sent to that end host are also mirrored, then they will
1476           be dropped since the switch will attempt to send them out the input
1477           port. Disabling learning for the VLAN will cause the switch to
1478           correctly send the packet out all ports configured for that VLAN.  If
1479           Open vSwitch is being used as an intermediate switch, learning can be
1480           disabled by adding the mirrored VLAN to <ref column="flood_vlans"/>
1481           in the appropriate <ref table="Bridge"/> table or tables.</p>
1482       </column>
1483     </group>
1484
1485     <group title="Other Features">
1486       <column name="external_ids">
1487         Key-value pairs for use by external frameworks that integrate with Open
1488         vSwitch, rather than by Open vSwitch itself.  System integrators should
1489         either use the Open vSwitch development mailing list to coordinate on
1490         common key-value definitions, or choose key names that are likely to be
1491         unique.  No common key-value pairs are currently defined.
1492       </column>
1493     </group>
1494   </table>
1495
1496   <table name="Controller" title="OpenFlow controller configuration.">
1497     <p>An OpenFlow controller.</p>
1498
1499     <p>
1500       Open vSwitch supports two kinds of OpenFlow controllers:
1501     </p>
1502
1503     <dl>
1504       <dt>Primary controllers</dt>
1505       <dd>
1506         <p>
1507           This is the kind of controller envisioned by the OpenFlow 1.0
1508           specification.  Usually, a primary controller implements a network
1509           policy by taking charge of the switch's flow table.
1510         </p>
1511
1512         <p>
1513           Open vSwitch initiates and maintains persistent connections to
1514           primary controllers, retrying the connection each time it fails or
1515           drops.  The <ref table="Bridge" column="fail_mode"/> column in the
1516           <ref table="Bridge"/> table applies to primary controllers.
1517         </p>
1518
1519         <p>
1520           Open vSwitch permits a bridge to have any number of primary
1521           controllers.  When multiple controllers are configured, Open
1522           vSwitch connects to all of them simultaneously.  Because
1523           OpenFlow 1.0 does not specify how multiple controllers
1524           coordinate in interacting with a single switch, more than
1525           one primary controller should be specified only if the
1526           controllers are themselves designed to coordinate with each
1527           other.  (The Nicira-defined <code>NXT_ROLE</code> OpenFlow
1528           vendor extension may be useful for this.)
1529         </p>
1530       </dd>
1531       <dt>Service controllers</dt>
1532       <dd>
1533         <p>
1534           These kinds of OpenFlow controller connections are intended for
1535           occasional support and maintenance use, e.g. with
1536           <code>ovs-ofctl</code>.  Usually a service controller connects only
1537           briefly to inspect or modify some of a switch's state.
1538         </p>
1539
1540         <p>
1541           Open vSwitch listens for incoming connections from service
1542           controllers.  The service controllers initiate and, if necessary,
1543           maintain the connections from their end.  The <ref table="Bridge"
1544           column="fail_mode"/> column in the <ref table="Bridge"/> table does
1545           not apply to service controllers.
1546         </p>
1547
1548         <p>
1549           Open vSwitch supports configuring any number of service controllers.
1550         </p>
1551       </dd>
1552     </dl>
1553
1554     <p>
1555       The <ref column="target"/> determines the type of controller.
1556     </p>
1557
1558     <group title="Core Features">
1559       <column name="target">
1560         <p>Connection method for controller.</p>
1561         <p>
1562           The following connection methods are currently supported for primary
1563           controllers:
1564         </p>
1565         <dl>
1566           <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
1567           <dd>
1568             <p>The specified SSL <var>port</var> (default: 6633) on the host at
1569             the given <var>ip</var>, which must be expressed as an IP address
1570             (not a DNS name).  The <ref table="Open_vSwitch" column="ssl"/>
1571             column in the <ref table="Open_vSwitch"/> table must point to a
1572             valid SSL configuration when this form is used.</p>
1573             <p>SSL support is an optional feature that is not always built as
1574               part of Open vSwitch.</p>
1575           </dd>
1576           <dt><code>tcp:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
1577           <dd>The specified TCP <var>port</var> (default: 6633) on the host at
1578             the given <var>ip</var>, which must be expressed as an IP address
1579             (not a DNS name).</dd>
1580           <dt><code>discover</code></dt>
1581           <dd>
1582             <p>Enables controller discovery.</p>
1583             <p>In controller discovery mode, Open vSwitch broadcasts a DHCP
1584               request with vendor class identifier <code>OpenFlow</code> across
1585               all of the bridge's network devices.  It will accept any valid
1586               DHCP reply that has the same vendor class identifier and includes
1587               a vendor-specific option with code 1 whose contents are a string
1588               specifying the location of the controller in the same format as
1589               <ref column="target"/>.</p>
1590             <p>The DHCP reply may also, optionally, include a vendor-specific
1591               option with code 2 whose contents are a string specifying the URI
1592               to the base of the OpenFlow PKI
1593               (e.g. <code>http://192.168.0.1/openflow/pki</code>).  This URI is
1594               used only for bootstrapping the OpenFlow PKI at initial switch
1595               setup; <code>ovs-vswitchd</code> does not use it at all.</p>
1596           </dd>
1597         </dl>
1598         <p>
1599           The following connection methods are currently supported for service
1600           controllers:
1601         </p>
1602         <dl>
1603           <dt><code>pssl:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
1604           <dd>
1605             <p>
1606               Listens for SSL connections on the specified TCP <var>port</var>
1607               (default: 6633).  If <var>ip</var>, which must be expressed as an
1608               IP address (not a DNS name), is specified, then connections are
1609               restricted to the specified local IP address.
1610             </p>
1611             <p>
1612               The <ref table="Open_vSwitch" column="ssl"/> column in the <ref
1613               table="Open_vSwitch"/> table must point to a valid SSL
1614               configuration when this form is used.
1615             </p>
1616             <p>SSL support is an optional feature that is not always built as
1617               part of Open vSwitch.</p>
1618           </dd>
1619           <dt><code>ptcp:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
1620           <dd>
1621             Listens for connections on the specified TCP <var>port</var>
1622             (default: 6633).  If <var>ip</var>, which must be expressed as an
1623             IP address (not a DNS name), is specified, then connections are
1624             restricted to the specified local IP address.
1625           </dd>
1626         </dl>
1627         <p>When multiple controllers are configured for a single bridge, the
1628           <ref column="target"/> values must be unique.  Duplicate
1629           <ref column="target"/> values yield unspecified results.</p>
1630       </column>
1631
1632       <column name="connection_mode">
1633         <p>If it is specified, this setting must be one of the following
1634         strings that describes how Open vSwitch contacts this OpenFlow
1635         controller over the network:</p>
1636
1637         <dl>
1638           <dt><code>in-band</code></dt>
1639           <dd>In this mode, this controller's OpenFlow traffic travels over the
1640             bridge associated with the controller.  With this setting, Open
1641             vSwitch allows traffic to and from the controller regardless of the
1642             contents of the OpenFlow flow table.  (Otherwise, Open vSwitch
1643             would never be able to connect to the controller, because it did
1644             not have a flow to enable it.)  This is the most common connection
1645             mode because it is not necessary to maintain two independent
1646             networks.</dd>
1647           <dt><code>out-of-band</code></dt>
1648           <dd>In this mode, OpenFlow traffic uses a control network separate
1649             from the bridge associated with this controller, that is, the
1650             bridge does not use any of its own network devices to communicate
1651             with the controller.  The control network must be configured
1652             separately, before or after <code>ovs-vswitchd</code> is started.
1653           </dd>
1654         </dl>
1655
1656         <p>If not specified, the default is implementation-specific.  If
1657           <ref column="target"/> is <code>discover</code>, the connection mode
1658           is always treated as <code>in-band</code> regardless of the actual
1659           setting.</p>
1660       </column>
1661     </group>
1662
1663     <group title="Controller Failure Detection and Handling">
1664       <column name="max_backoff">
1665         Maximum number of milliseconds to wait between connection attempts.
1666         Default is implementation-specific.
1667       </column>
1668
1669       <column name="inactivity_probe">
1670         Maximum number of milliseconds of idle time on connection to
1671         controller before sending an inactivity probe message.  If Open
1672         vSwitch does not communicate with the controller for the specified
1673         number of seconds, it will send a probe.  If a response is not
1674         received for the same additional amount of time, Open vSwitch
1675         assumes the connection has been broken and attempts to reconnect.
1676         Default is implementation-specific.
1677       </column>
1678     </group>
1679
1680     <group title="OpenFlow Rate Limiting">
1681         <column name="controller_rate_limit">
1682           <p>The maximum rate at which packets in unknown flows will be
1683             forwarded to the OpenFlow controller, in packets per second.  This
1684             feature prevents a single bridge from overwhelming the controller.
1685             If not specified, the default is implementation-specific.</p>
1686           <p>In addition, when a high rate triggers rate-limiting, Open
1687             vSwitch queues controller packets for each port and transmits
1688             them to the controller at the configured rate.  The number of
1689             queued packets is limited by
1690             the <ref column="controller_burst_limit"/> value.  The packet
1691             queue is shared fairly among the ports on a bridge.</p><p>Open
1692             vSwitch maintains two such packet rate-limiters per bridge.
1693             One of these applies to packets sent up to the controller
1694             because they do not correspond to any flow.  The other applies
1695             to packets sent up to the controller by request through flow
1696             actions. When both rate-limiters are filled with packets, the
1697             actual rate that packets are sent to the controller is up to
1698             twice the specified rate.</p>
1699         </column>
1700
1701         <column name="controller_burst_limit">
1702           In conjunction with <ref column="controller_rate_limit"/>,
1703           the maximum number of unused packet credits that the bridge will
1704           allow to accumulate, in packets.  If not specified, the default
1705           is implementation-specific.
1706         </column>
1707     </group>
1708
1709     <group title="Additional Discovery Configuration">
1710       <p>These values are considered only when <ref column="target"/>
1711         is <code>discover</code>.</p>
1712
1713       <column name="discover_accept_regex">
1714         A POSIX
1715         extended regular expression against which the discovered controller
1716         location is validated.  The regular expression is implicitly
1717         anchored at the beginning of the controller location string, as
1718         if it begins with <code>^</code>.  If not specified, the default
1719         is implementation-specific.
1720       </column>
1721
1722       <column name="discover_update_resolv_conf">
1723         Whether to update <code>/etc/resolv.conf</code> when the
1724         controller is discovered.  If not specified, the default
1725         is implementation-specific.  Open vSwitch will only modify
1726         <code>/etc/resolv.conf</code> if the DHCP response that it receives
1727         specifies one or more DNS servers.
1728       </column>
1729     </group>
1730
1731     <group title="Additional In-Band Configuration">
1732       <p>These values are considered only in in-band control mode (see
1733         <ref column="connection_mode"/>) and only when <ref column="target"/>
1734         is not <code>discover</code>.  (For controller discovery, the network
1735         configuration obtained via DHCP is used instead.)</p>
1736
1737       <p>When multiple controllers are configured on a single bridge, there
1738         should be only one set of unique values in these columns.  If different
1739         values are set for these columns in different controllers, the effect
1740         is unspecified.</p>
1741
1742       <column name="local_ip">
1743         The IP address to configure on the local port,
1744         e.g. <code>192.168.0.123</code>.  If this value is unset, then
1745         <ref column="local_netmask"/> and <ref column="local_gateway"/> are
1746         ignored.
1747       </column>
1748
1749       <column name="local_netmask">
1750         The IP netmask to configure on the local port,
1751         e.g. <code>255.255.255.0</code>.  If <ref column="local_ip"/> is set
1752         but this value is unset, then the default is chosen based on whether
1753         the IP address is class A, B, or C.
1754       </column>
1755
1756       <column name="local_gateway">
1757         The IP address of the gateway to configure on the local port, as a
1758         string, e.g. <code>192.168.0.1</code>.  Leave this column unset if
1759         this network has no gateway.
1760       </column>
1761     </group>
1762
1763     <group title="Other Features">
1764       <column name="external_ids">
1765         Key-value pairs for use by external frameworks that integrate with Open
1766         vSwitch, rather than by Open vSwitch itself.  System integrators should
1767         either use the Open vSwitch development mailing list to coordinate on
1768         common key-value definitions, or choose key names that are likely to be
1769         unique.  No common key-value pairs are currently defined.
1770       </column>
1771     </group>
1772   </table>
1773
1774   <table name="Manager" title="OVSDB management connection.">
1775     <p>
1776       Configuration for a database connection to an Open vSwitch database
1777       (OVSDB) client.
1778     </p>
1779
1780     <p>
1781       This table primarily configures the Open vSwitch database
1782       (<code>ovsdb-server</code>), not the Open vSwitch switch
1783       (<code>ovs-vswitchd</code>).  The switch does read the table to determine
1784       what connections should be treated as in-band.
1785     </p>
1786
1787     <p>
1788       The Open vSwitch database server can initiate and maintain active
1789       connections to remote clients.  It can also listen for database
1790       connections.
1791     </p>
1792
1793     <group title="Core Features">
1794       <column name="target">
1795         <p>Connection method for managers.</p>
1796         <p>
1797           The following connection methods are currently supported:
1798         </p>
1799         <dl>
1800           <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
1801           <dd>
1802             <p>
1803               The specified SSL <var>port</var> (default: 6632) on the host at
1804               the given <var>ip</var>, which must be expressed as an IP address
1805               (not a DNS name).  The <ref table="Open_vSwitch" column="ssl"/>
1806               column in the <ref table="Open_vSwitch"/> table must point to a
1807               valid SSL configuration when this form is used.
1808             </p>
1809             <p>
1810               SSL support is an optional feature that is not always built as
1811               part of Open vSwitch.
1812             </p>
1813           </dd>
1814
1815           <dt><code>tcp:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
1816           <dd>
1817             The specified TCP <var>port</var> (default: 6632) on the host at
1818             the given <var>ip</var>, which must be expressed as an IP address
1819             (not a DNS name).
1820           </dd>
1821           <dt><code>pssl:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
1822           <dd>
1823             <p>
1824               Listens for SSL connections on the specified TCP <var>port</var>
1825               (default: 6632).  If <var>ip</var>, which must be expressed as an
1826               IP address (not a DNS name), is specified, then connections are
1827               restricted to the specified local IP address.
1828             </p>
1829             <p>
1830               The <ref table="Open_vSwitch" column="ssl"/> column in the <ref
1831               table="Open_vSwitch"/> table must point to a valid SSL
1832               configuration when this form is used.
1833             </p>
1834             <p>
1835               SSL support is an optional feature that is not always built as
1836               part of Open vSwitch.
1837             </p>
1838           </dd>
1839           <dt><code>ptcp:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
1840           <dd>
1841             Listens for connections on the specified TCP <var>port</var>
1842             (default: 6632).  If <var>ip</var>, which must be expressed as an
1843             IP address (not a DNS name), is specified, then connections are
1844             restricted to the specified local IP address.
1845           </dd>
1846         </dl>
1847         <p>When multiple managers are configured, the <ref column="target"/>
1848         values must be unique.  Duplicate <ref column="target"/> values yield
1849         unspecified results.</p>
1850       </column>
1851
1852       <column name="connection_mode">
1853         <p>
1854           If it is specified, this setting must be one of the following strings
1855           that describes how Open vSwitch contacts this OVSDB client over the
1856           network:
1857         </p>
1858
1859         <dl>
1860           <dt><code>in-band</code></dt>
1861           <dd>
1862             In this mode, this connection's traffic travels over a bridge
1863             managed by Open vSwitch.  With this setting, Open vSwitch allows
1864             traffic to and from the client regardless of the contents of the
1865             OpenFlow flow table.  (Otherwise, Open vSwitch would never be able
1866             to connect to the client, because it did not have a flow to enable
1867             it.)  This is the most common connection mode because it is not
1868             necessary to maintain two independent networks.
1869           </dd>
1870           <dt><code>out-of-band</code></dt>
1871           <dd>
1872             In this mode, the client's traffic uses a control network separate
1873             from that managed by Open vSwitch, that is, Open vSwitch does not
1874             use any of its own network devices to communicate with the client.
1875             The control network must be configured separately, before or after
1876             <code>ovs-vswitchd</code> is started.
1877           </dd>
1878         </dl>
1879
1880         <p>
1881           If not specified, the default is implementation-specific.
1882         </p>
1883       </column>
1884     </group>
1885
1886     <group title="Client Failure Detection and Handling">
1887       <column name="max_backoff">
1888         Maximum number of milliseconds to wait between connection attempts.
1889         Default is implementation-specific.
1890       </column>
1891
1892       <column name="inactivity_probe">
1893         Maximum number of milliseconds of idle time on connection to the client
1894         before sending an inactivity probe message.  If Open vSwitch does not
1895         communicate with the client for the specified number of seconds, it
1896         will send a probe.  If a response is not received for the same
1897         additional amount of time, Open vSwitch assumes the connection has been
1898         broken and attempts to reconnect.  Default is implementation-specific.
1899       </column>
1900     </group>
1901
1902     <group title="Other Features">
1903       <column name="external_ids">
1904         Key-value pairs for use by external frameworks that integrate with Open
1905         vSwitch, rather than by Open vSwitch itself.  System integrators should
1906         either use the Open vSwitch development mailing list to coordinate on
1907         common key-value definitions, or choose key names that are likely to be
1908         unique.  No common key-value pairs are currently defined.
1909       </column>
1910     </group>
1911   </table>
1912
1913   <table name="NetFlow">
1914     A NetFlow target.  NetFlow is a protocol that exports a number of
1915     details about terminating IP flows, such as the principals involved
1916     and duration.
1917
1918     <column name="targets">
1919       NetFlow targets in the form
1920       <code><var>ip</var>:<var>port</var></code>.  The <var>ip</var>
1921       must be specified numerically, not as a DNS name.
1922     </column>
1923
1924     <column name="engine_id">
1925       Engine ID to use in NetFlow messages.  Defaults to datapath index
1926       if not specified.
1927     </column>
1928
1929     <column name="engine_type">
1930       Engine type to use in NetFlow messages.  Defaults to datapath
1931       index if not specified.
1932     </column>
1933
1934     <column name="active_timeout">
1935       The interval at which NetFlow records are sent for flows that are
1936       still active, in seconds.  A value of <code>0</code> requests the
1937       default timeout (currently 600 seconds); a value of <code>-1</code>
1938       disables active timeouts.
1939     </column>
1940
1941     <column name="add_id_to_interface">
1942       <p>If this column's value is <code>false</code>, the ingress and egress
1943         interface fields of NetFlow flow records are derived from OpenFlow port
1944         numbers.  When it is <code>true</code>, the 7 most significant bits of
1945         these fields will be replaced by the least significant 7 bits of the
1946         engine id.  This is useful because many NetFlow collectors do not
1947         expect multiple switches to be sending messages from the same host, so
1948         they do not store the engine information which could be used to
1949         disambiguate the traffic.</p>
1950       <p>When this option is enabled, a maximum of 508 ports are supported.</p>
1951     </column>
1952
1953     <column name="external_ids">
1954       Key-value pairs for use by external frameworks that integrate with Open
1955       vSwitch, rather than by Open vSwitch itself.  System integrators should
1956       either use the Open vSwitch development mailing list to coordinate on
1957       common key-value definitions, or choose key names that are likely to be
1958       unique.  No common key-value pairs are currently defined.
1959     </column>
1960   </table>
1961
1962   <table name="SSL">
1963     SSL configuration for an Open_vSwitch.
1964
1965     <column name="private_key">
1966       Name of a PEM file containing the private key used as the switch's
1967       identity for SSL connections to the controller.
1968     </column>
1969
1970     <column name="certificate">
1971       Name of a PEM file containing a certificate, signed by the
1972       certificate authority (CA) used by the controller and manager,
1973       that certifies the switch's private key, identifying a trustworthy
1974       switch.
1975     </column>
1976
1977     <column name="ca_cert">
1978       Name of a PEM file containing the CA certificate used to verify
1979       that the switch is connected to a trustworthy controller.
1980     </column>
1981
1982     <column name="bootstrap_ca_cert">
1983       If set to <code>true</code>, then Open vSwitch will attempt to
1984       obtain the CA certificate from the controller on its first SSL
1985       connection and save it to the named PEM file. If it is successful,
1986       it will immediately drop the connection and reconnect, and from then
1987       on all SSL connections must be authenticated by a certificate signed
1988       by the CA certificate thus obtained.  <em>This option exposes the
1989         SSL connection to a man-in-the-middle attack obtaining the initial
1990         CA certificate.</em>  It may still be useful for bootstrapping.
1991     </column>
1992
1993     <column name="external_ids">
1994       Key-value pairs for use by external frameworks that integrate with Open
1995       vSwitch, rather than by Open vSwitch itself.  System integrators should
1996       either use the Open vSwitch development mailing list to coordinate on
1997       common key-value definitions, or choose key names that are likely to be
1998       unique.  No common key-value pairs are currently defined.
1999     </column>
2000   </table>
2001
2002   <table name="sFlow">
2003     <p>An sFlow(R) target.  sFlow is a protocol for remote monitoring
2004       of switches.</p>
2005
2006     <column name="agent">
2007       Name of the network device whose IP address should be reported as the
2008       ``agent address'' to collectors.  If not specified, the IP address
2009       defaults to the <ref table="Controller" column="local_ip"/> in the
2010       collector's <ref table="Controller"/>.  If an agent IP address cannot be
2011       determined either way, sFlow is disabled.
2012     </column>
2013
2014     <column name="header">
2015       Number of bytes of a sampled packet to send to the collector.
2016       If not specified, the default is 128 bytes.
2017     </column>
2018
2019     <column name="polling">
2020       Polling rate in seconds to send port statistics to the collector.
2021       If not specified, defaults to 30 seconds.
2022     </column>
2023
2024     <column name="sampling">
2025       Rate at which packets should be sampled and sent to the collector.
2026       If not specified, defaults to 400, which means one out of 400
2027       packets, on average, will be sent to the collector.
2028     </column>
2029
2030     <column name="targets">
2031       sFlow targets in the form
2032       <code><var>ip</var>:<var>port</var></code>.
2033     </column>
2034
2035     <column name="external_ids">
2036       Key-value pairs for use by external frameworks that integrate with Open
2037       vSwitch, rather than by Open vSwitch itself.  System integrators should
2038       either use the Open vSwitch development mailing list to coordinate on
2039       common key-value definitions, or choose key names that are likely to be
2040       unique.  No common key-value pairs are currently defined.
2041     </column>
2042   </table>
2043
2044   <table name="Capability">
2045     <p>Records in this table describe functionality supported by the hardware
2046       and software platform on which this Open vSwitch is based.  Clients
2047       should not modify this table.</p>
2048
2049     <p>A record in this table is meaningful only if it is referenced by the
2050       <ref table="Open_vSwitch" column="capabilities"/> column in the
2051       <ref table="Open_vSwitch"/> table.  The key used to reference it, called
2052       the record's ``category,'' determines the meanings of the
2053       <ref column="details"/> column.  The following general forms of
2054       categories are currently defined:</p>
2055
2056     <dl>
2057       <dt><code>qos-<var>type</var></code></dt>
2058       <dd><var>type</var> is supported as the value for
2059         <ref column="type" table="QoS"/> in the <ref table="QoS"/> table.
2060       </dd>
2061     </dl>
2062
2063     <column name="details">
2064       <p>Key-value pairs that describe capabilities.  The meaning of the pairs
2065       depends on the category key that the <ref table="Open_vSwitch"
2066       column="capabilities"/> column in the <ref table="Open_vSwitch"/> table
2067       uses to reference this record, as described above.</p>
2068
2069       <p>The presence of a record for category <code>qos-<var>type</var></code>
2070           indicates that the switch supports <var>type</var> as the value of
2071           the <ref table="QoS" column="type"/> column in the <ref table="QoS"/>
2072           table.  The following key-value pairs are defined to further describe
2073           QoS capabilities:</p>
2074
2075       <dl>
2076         <dt><code>n-queues</code></dt>
2077         <dd>Number of supported queues, as a positive integer.  Keys in the
2078           <ref table="QoS" column="queues"/> column for <ref table="QoS"/>
2079           records whose <ref table="QoS" column="type"/> value
2080           equals <var>type</var> must range between 0 and this value minus one,
2081           inclusive.</dd>
2082       </dl>
2083     </column>
2084   </table>
2085 </database>