bb3f648fb254875246ed5fc96b6c72d5d30a5692
[openvswitch] / vswitchd / vswitch.xml
1 <database title="Open vSwitch Configuration Database">
2   <p>A database with this schema holds the configuration for one Open
3     vSwitch daemon.  The root of the configuration for the daemon is
4     the <ref table="Open_vSwitch"/> table, which must have exactly one
5     record.  Records in other tables are significant only when they
6     can be reached directly or indirectly from the
7     <ref table="Open_vSwitch"/> table.</p>
8
9   <table name="Open_vSwitch" title="Open vSwitch configuration.">
10     Configuration for an Open vSwitch daemon.  There must be exactly one record
11     in the <ref table="Open_vSwitch"/> table.
12
13     <group title="Configuration">
14       <column name="bridges">
15         Set of bridges managed by the daemon.
16       </column>
17
18       <column name="managers">
19         Remote database clients to which the Open vSwitch's database server
20         should connect or to which it should listen.
21       </column>
22
23       <column name="ssl">
24         SSL used globally by the daemon.
25       </column>
26
27       <column name="external_ids">
28         Key-value pairs for use by external frameworks that integrate
29         with Open vSwitch, rather than by Open vSwitch itself.  System
30         integrators should either use the Open vSwitch development
31         mailing list to coordinate on common key-value definitions, or
32         choose key names that are likely to be unique.  The currently
33         defined common key-value pairs are:
34         <dl>
35           <dt><code>system-type</code></dt>
36           <dd>An identifier for the switch type, such as
37             <code>XenServer</code> or <code>KVM</code>.</dd>
38           <dt><code>system-version</code></dt>
39           <dd>The version of the switch software, such as
40             <code>5.6.0</code> on XenServer.</dd>
41           <dt><code>system-id</code></dt>
42           <dd>A unique identifier for the Open vSwitch's physical host.
43             The form of the identifier depends on the type of the host.
44             On a Citrix XenServer, this will likely be the same as
45             <code>xs-system-uuid</code>.</dd>
46           <dt><code>xs-system-uuid</code></dt>
47           <dd>The Citrix XenServer universally unique identifier for the
48             physical host as displayed by <code>xe host-list</code>.</dd>
49         </dl>
50       </column>
51     </group>
52
53     <group title="Status">
54       <column name="next_cfg">
55         Sequence number for client to increment.  When a client modifies
56         any part of the database configuration and wishes to wait for
57         Open vSwitch to finish applying the changes, it may increment
58         this sequence number.
59       </column>
60
61       <column name="cur_cfg">
62         Sequence number that Open vSwitch sets to the current value of
63         <ref column="next_cfg"/> after it finishes applying a set of
64         configuration changes.
65       </column>
66
67       <column name="capabilities">
68         Describes functionality supported by the hardware and software platform
69         on which this Open vSwitch is based.  Clients should not modify this
70         column.  See the <ref table="Capability"/> description for defined
71         capability categories and the meaning of associated
72         <ref table="Capability"/> records.
73       </column>
74
75       <column name="statistics">
76         <p>
77           Key-value pairs that report statistics about a running Open_vSwitch
78           daemon.  The current implementation updates these counters
79           periodically.  In the future, we plan to, instead, update them only
80           when they are queried (e.g. using an OVSDB <code>select</code>
81           operation) and perhaps at other times, but not on any regular
82           periodic basis.</p>
83         <p>
84           The currently defined key-value pairs are listed below.  Some Open
85           vSwitch implementations may not support some statistics, in which
86           case those key-value pairs are omitted.</p>
87         <dl>
88           <dt><code>load-average</code></dt>
89           <dd>
90             System load average multiplied by 100 and rounded to the nearest
91             integer.</dd>
92         </dl>
93       </column>
94     </group>
95   </table>
96
97   <table name="Bridge">
98     <p>
99       Configuration for a bridge within an
100       <ref table="Open_vSwitch"/>.
101     </p>
102     <p>
103       A <ref table="Bridge"/> record represents an Ethernet switch with one or
104       more ``ports,'' which are the <ref table="Port"/> records pointed to by
105       the <ref table="Bridge"/>'s <ref column="ports"/> column.
106     </p>
107
108     <group title="Core Features">
109       <column name="name">
110         Bridge identifier.  Should be alphanumeric and no more than about 8
111         bytes long.  Must be unique among the names of ports, interfaces, and
112         bridges on a host.
113       </column>
114
115       <column name="ports">
116         Ports included in the bridge.
117       </column>
118
119       <column name="mirrors">
120         Port mirroring configuration.
121       </column>
122
123       <column name="netflow">
124         NetFlow configuration.
125       </column>
126
127       <column name="sflow">
128         sFlow configuration.
129       </column>
130
131       <column name="flood_vlans">
132         VLAN IDs of VLANs on which MAC address learning should be disabled, so
133         that packets are flooded instead of being sent to specific ports that
134         are believed to contain packets' destination MACs.  This should
135         ordinarily be used to disable MAC learning on VLANs used for mirroring
136         (RSPAN VLANs).  It may also be useful for debugging.
137       </column>
138     </group>
139
140     <group title="OpenFlow Configuration">
141       <column name="controller">
142         OpenFlow controller set.  If unset, then no OpenFlow controllers
143         will be used.
144       </column>
145
146       <column name="fail_mode">
147         <p>When a controller is configured, it is, ordinarily, responsible
148           for setting up all flows on the switch.  Thus, if the connection to
149           the controller fails, no new network connections can be set up.
150           If the connection to the controller stays down long enough,
151           no packets can pass through the switch at all.  This setting
152           determines the switch's response to such a situation.  It may be set
153           to one of the following:
154           <dl>
155             <dt><code>standalone</code></dt>
156             <dd>If no message is received from the controller for three
157               times the inactivity probe interval
158               (see <ref column="inactivity_probe"/>), then Open vSwitch
159               will take over responsibility for setting up flows.  In
160               this mode, Open vSwitch causes the bridge to act like an
161               ordinary MAC-learning switch.  Open vSwitch will continue
162               to retry connecting to the controller in the background
163               and, when the connection succeeds, it will discontinue its
164               standalone behavior.</dd>
165             <dt><code>secure</code></dt>
166             <dd>Open vSwitch will not set up flows on its own when the
167               controller connection fails or when no controllers are
168               defined.  The bridge will continue to retry connecting to
169               any defined controllers forever.</dd>
170           </dl>
171         </p>
172         <p>If this value is unset, the default is implementation-specific.</p>
173         <p>When more than one controller is configured, 
174           <ref column="fail_mode"/> is considered only when none of the
175           configured controllers can be contacted.</p>
176       </column>
177
178       <column name="datapath_id">
179         Reports the OpenFlow datapath ID in use.  Exactly 16 hex
180         digits.  (Setting this column will have no useful effect.  Set
181         <ref column="other_config"/>:<code>other-config</code>
182         instead.)
183       </column>
184     </group>
185
186     <group title="Other Features">
187       <column name="datapath_type">
188         Name of datapath provider.  The kernel datapath has
189         type <code>system</code>.  The userspace datapath has
190         type <code>netdev</code>.
191       </column>
192
193       <column name="external_ids">
194         Key-value pairs for use by external frameworks that integrate
195         with Open vSwitch, rather than by Open vSwitch itself.  System
196         integrators should either use the Open vSwitch development
197         mailing list to coordinate on common key-value definitions, or
198         choose key names that are likely to be unique.  The currently
199         defined key-value pairs are:
200         <dl>
201           <dt><code>bridge-id</code></dt>
202           <dd>A unique identifier of the bridge.  On Citrix XenServer this 
203             will commonly be the same as <code>xs-network-uuids</code>.</dd>
204           <dt><code>xs-network-uuids</code></dt>
205           <dd>Semicolon-delimited set of universally unique identifier(s) for
206             the network with which this bridge is associated on a Citrix
207             XenServer host.  The network identifiers are RFC 4122 UUIDs as
208             displayed by, e.g., <code>xe network-list</code>.</dd>
209         </dl>
210       </column>
211
212       <column name="other_config">
213         Key-value pairs for configuring rarely used bridge
214         features.  The currently defined key-value pairs are:
215         <dl>
216           <dt><code>datapath-id</code></dt>
217           <dd>Exactly 16 hex
218             digits to set the OpenFlow datapath ID to a specific
219             value.</dd>
220           <dt><code>hwaddr</code></dt>
221           <dd>An Ethernet address in the form
222             <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
223             to set the hardware address of the local port and influence the
224             datapath ID.</dd>
225         </dl>
226       </column>
227     </group>
228   </table>
229
230   <table name="Port" table="Port or bond configuration.">
231     <p>A port within a <ref table="Bridge"/>.</p>
232     <p>Most commonly, a port has exactly one ``interface,'' pointed to by its
233       <ref column="interfaces"/> column.  Such a port logically
234       corresponds to a port on a physical Ethernet switch.  A port
235       with more than one interface is a ``bonded port'' (see
236       <ref group="Bonding Configuration"/>).</p>
237     <p>Some properties that one might think as belonging to a port are actually
238       part of the port's <ref table="Interface"/> members.</p>
239
240     <column name="name">
241       Port name.  Should be alphanumeric and no more than about 8
242       bytes long.  May be the same as the interface name, for
243       non-bonded ports.  Must otherwise be unique among the names of
244       ports, interfaces, and bridges on a host.
245     </column>
246
247     <column name="interfaces">
248       The port's interfaces.  If there is more than one, this is a
249       bonded Port.
250     </column>
251
252     <group title="VLAN Configuration">
253       <p>A bridge port must be configured for VLANs in one of two
254         mutually exclusive ways:
255         <ul>
256           <li>A ``trunk port'' has an empty value for <ref
257             column="tag"/>.  Its <ref column="trunks"/> value may be
258             empty or non-empty.</li>
259           <li>An ``implicitly tagged VLAN port'' or ``access port''
260             has an nonempty value for <ref column="tag"/>.  Its
261             <ref column="trunks"/> value must be empty.</li>
262         </ul>
263         If <ref column="trunks"/> and <ref column="tag"/> are both
264         nonempty, the configuration is ill-formed.
265       </p>
266
267       <column name="tag">
268         <p>
269           If this is an access port (see above), the port's implicitly
270           tagged VLAN.  Must be empty if this is a trunk port.
271         </p>
272         <p>
273           Frames arriving on trunk ports will be forwarded to this
274           port only if they are tagged with the given VLAN (or, if
275           <ref column="tag"/> is 0, then if they lack a VLAN header).
276           Frames arriving on other access ports will be forwarded to
277           this port only if they have the same <ref column="tag"/>
278           value.  Frames forwarded to this port will not have an
279           802.1Q header.
280         </p>
281         <p>
282           When a frame with a 802.1Q header that indicates a nonzero
283           VLAN is received on an access port, it is discarded.
284         </p>
285       </column>
286
287       <column name="trunks">
288         <p>
289           If this is a trunk port (see above), the 802.1Q VLAN(s) that
290           this port trunks; if it is empty, then the port trunks all
291           VLANs.  Must be empty if this is an access port.
292         </p>
293         <p>
294           Frames arriving on trunk ports are dropped if they are not
295           in one of the specified VLANs.  For this purpose, packets
296           that have no VLAN header are treated as part of VLAN 0.
297         </p>
298       </column>
299     </group>
300
301     <group title="Bonding Configuration">
302       <p>A port that has more than one interface is a ``bonded port.''
303         Bonding allows for load balancing and fail-over.  Open vSwitch
304         supports ``source load balancing'' (SLB) bonding, which
305         assigns flows to slaves based on source MAC address, with
306         periodic rebalancing as traffic patterns change.  This form of
307         bonding does not require 802.3ad or other special support from
308         the upstream switch to which the slave devices are
309         connected.</p>
310
311       <p>These columns apply only to bonded ports.  Their values are
312         otherwise ignored.</p>
313
314       <column name="bond_updelay">
315         <p>For a bonded port, the number of milliseconds for which carrier must
316           stay up on an interface before the interface is considered to be up.
317           Specify <code>0</code> to enable the interface immediately.</p>
318         <p>This setting is honored only when at least one bonded interface is
319           already enabled.  When no interfaces are enabled, then the first bond
320           interface to come up is enabled immediately.</p>
321       </column>
322
323       <column name="bond_downdelay">
324         For a bonded port, the number of milliseconds for which carrier must
325         stay down on an interface before the interface is considered to be
326         down.  Specify <code>0</code> to disable the interface immediately.
327       </column>
328
329       <column name="bond_fake_iface">
330         For a bonded port, whether to create a fake internal interface with the
331         name of the port.  Use only for compatibility with legacy software that
332         requires this.
333       </column>
334     </group>
335
336     <group title="Other Features">
337       <column name="qos">
338         Quality of Service configuration for this port.
339       </column>
340       
341       <column name="mac">
342         The MAC address to use for this port for the purpose of choosing the
343         bridge's MAC address.  This column does not necessarily reflect the
344         port's actual MAC address, nor will setting it change the port's actual
345         MAC address.
346       </column>
347
348       <column name="fake_bridge">
349         Does this port represent a sub-bridge for its tagged VLAN within the
350         Bridge?  See ovs-vsctl(8) for more information.
351       </column>
352
353       <column name="external_ids">
354         <p>
355           Key-value pairs for use by external frameworks that integrate with
356           Open vSwitch, rather than by Open vSwitch itself.  System integrators
357           should either use the Open vSwitch development mailing list to
358           coordinate on common key-value definitions, or choose key names that
359           are likely to be unique.
360         </p>
361         <p>
362           No key-value pairs native to <ref table="Port"/> are currently
363           defined.  For fake bridges (see the <ref column="fake_bridge"/>
364           column), external IDs for the fake bridge are defined here by
365           prefixing a <ref table="Bridge"/> <ref table="Bridge"
366           column="external_ids"/> key with <code>fake-bridge-</code>,
367           e.g. <code>fake-bridge-xs-network-uuids</code>.
368         </p>
369       </column>
370
371       <column name="other_config">
372         Key-value pairs for configuring rarely used port features.  The
373         currently defined key-value pairs are:
374         <dl>
375           <dt><code>hwaddr</code></dt>
376           <dd>An Ethernet address in the form
377             <code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code>.</dd>
378           <dt><code>bond-rebalance-interval</code></dt>
379           <dd>For a bonded port, the number of milliseconds between
380             successive attempts to rebalance the bond, that is, to
381             move source MACs and their flows from one interface on
382             the bond to another in an attempt to keep usage of each
383             interface roughly equal.  The default is 10000 (10
384             seconds), and the minimum is 1000 (1 second).</dd>
385         </dl>
386       </column>
387     </group>
388   </table>
389
390   <table name="Interface" title="One physical network device in a Port.">
391     An interface within a <ref table="Port"/>.
392
393     <group title="Core Features">
394       <column name="name">
395         Interface name.  Should be alphanumeric and no more than about 8 bytes
396         long.  May be the same as the port name, for non-bonded ports.  Must
397         otherwise be unique among the names of ports, interfaces, and bridges
398         on a host.
399       </column>
400
401       <column name="mac">
402         <p>Ethernet address to set for this interface.  If unset then the
403           default MAC address is used:</p>
404         <ul>
405           <li>For the local interface, the default is the lowest-numbered MAC
406             address among the other bridge ports, either the value of the
407             <ref table="Port" column="mac"/> in its <ref table="Port"/> record,
408             if set, or its actual MAC (for bonded ports, the MAC of its slave
409             whose name is first in alphabetical order).  Internal ports and
410             bridge ports that are used as port mirroring destinations (see the
411             <ref table="Mirror"/> table) are ignored.</li>
412           <li>For other internal interfaces, the default MAC is randomly
413             generated.</li>
414           <li>External interfaces typically have a MAC address associated with
415             their hardware.</li>
416         </ul>
417         <p>Some interfaces may not have a software-controllable MAC
418         address.</p>
419       </column>
420
421       <column name="ofport">
422         <p>OpenFlow port number for this interface.  Unlike most columns, this
423           column's value should be set only by Open vSwitch itself.  Other
424           clients should set this column to an empty set (the default) when
425           creating an <ref table="Interface"/>.</p>
426         <p>Open vSwitch populates this column when the port number becomes
427           known.  If the interface is successfully added,
428           <ref column="ofport"/> will be set to a number between 1 and 65535
429           (generally either in the range 1 to 65280, exclusive, or 65534, the
430           port number for the OpenFlow ``local port'').  If the interface
431           cannot be added then Open vSwitch sets this column
432           to -1.</p>
433       </column>
434     </group>
435
436     <group title="System-Specific Details">
437       <column name="type">
438         The interface type, one of:
439         <dl>
440           <dt><code>system</code></dt>
441           <dd>An ordinary network device, e.g. <code>eth0</code> on Linux.
442             Sometimes referred to as ``external interfaces'' since they are
443             generally connected to hardware external to that on which the Open
444             vSwitch is running.  The empty string is a synonym for
445             <code>system</code>.</dd>
446           <dt><code>internal</code></dt>
447           <dd>A simulated network device that sends and receives traffic.  An
448             internal interface whose <ref column="name"/> is the same as its
449             bridge's <ref table="Open_vSwitch" column="name"/> is called the
450             ``local interface.''  It does not make sense to bond an internal
451             interface, so the terms ``port'' and ``interface'' are often used
452             imprecisely for internal interfaces.</dd>
453           <dt><code>tap</code></dt>
454           <dd>A TUN/TAP device managed by Open vSwitch.</dd>
455           <dt><code>gre</code></dt>
456           <dd>An Ethernet over RFC 2890 Generic Routing Encapsulation over IPv4
457              tunnel.  Each tunnel must be uniquely identified by the
458              combination of <code>remote_ip</code>, <code>local_ip</code>, and
459              <code>in_key</code>.  Note that if two ports are defined that are
460              the same except one has an optional identifier and the other does
461              not, the more specific one is matched first.  <code>in_key</code>
462              is considered more specific than <code>local_ip</code> if a port
463              defines one and another port defines the other.  The following 
464              options may be specified in the <ref column="options"/> column:
465             <dl>
466               <dt><code>remote_ip</code></dt>
467               <dd>Required.  The tunnel endpoint.</dd>
468             </dl>
469             <dl>
470               <dt><code>local_ip</code></dt>
471               <dd>Optional.  The destination IP that received packets must
472                 match.  Default is to match all addresses.</dd>
473             </dl>
474             <dl>
475               <dt><code>in_key</code></dt>
476               <dd>Optional.  The GRE key that received packets must contain.
477                 It may either be a 32-bit number (no key and a key of 0 are
478                 treated as equivalent) or the word <code>flow</code>.  If
479                 <code>flow</code> is specified then any key will be accepted
480                 and the key will be placed in the <code>tun_id</code> field
481                 for matching in the flow table.  The ovs-ofctl manual page
482                 contains additional information about matching fields in
483                 OpenFlow flows.  Default is no key.</dd>
484             </dl>
485             <dl>
486               <dt><code>out_key</code></dt>
487               <dd>Optional.  The GRE key to be set on outgoing packets.  It may
488                 either be a 32-bit number or the word <code>flow</code>.  If
489                 <code>flow</code> is specified then the key may be set using
490                 the <code>set_tunnel</code> Nicira OpenFlow vendor extension (0
491                 is used in the absence of an action).  The ovs-ofctl manual
492                 page contains additional information about the Nicira OpenFlow
493                 vendor extensions.  Default is no key.</dd>
494             </dl>
495             <dl>
496               <dt><code>key</code></dt>
497               <dd>Optional.  Shorthand to set <code>in_key</code> and
498                 <code>out_key</code> at the same time.</dd>
499             </dl>
500             <dl>
501               <dt><code>tos</code></dt>
502               <dd>Optional.  The value of the ToS bits to be set on the
503                 encapsulating packet.  It may also be the word
504                 <code>inherit</code>, in which case the ToS will be copied from
505                 the inner packet if it is IPv4 or IPv6 (otherwise it will be
506                 0).  Note that the ECN fields are always inherited.  Default is
507                 0.</dd>
508             </dl>
509             <dl>
510               <dt><code>ttl</code></dt>
511               <dd>Optional.  The TTL to be set on the encapsulating packet.
512                 It may also be the word <code>inherit</code>, in which case the
513                 TTL will be copied from the inner packet if it is IPv4 or IPv6
514                 (otherwise it will be the system default, typically 64).
515                 Default is the system default TTL.</dd>
516             </dl>
517             <dl>
518               <dt><code>csum</code></dt>
519               <dd>Optional.  Compute GRE checksums on outgoing packets.
520                 Checksums present on incoming packets will be validated
521                 regardless of this setting.  Note that GRE checksums
522                 impose a significant performance penalty as they cover the
523                 entire packet.  As the contents of the packet is typically
524                 covered by L3 and L4 checksums, this additional checksum only
525                 adds value for the GRE and encapsulated Ethernet headers.
526                 Default is disabled, set to <code>true</code> to enable.</dd>
527             </dl>
528             <dl>
529               <dt><code>pmtud</code></dt>
530               <dd>Optional.  Enable tunnel path MTU discovery.  If enabled
531                 ``ICMP destination unreachable - fragmentation'' needed
532                 messages will be generated for IPv4 packets with the DF bit set
533                 and IPv6 packets above the minimum MTU if the packet size
534                 exceeds the path MTU minus the size of the tunnel headers.  It
535                 also forces the encapsulating packet DF bit to be set (it is
536                 always set if the inner packet implies path MTU discovery).
537                 Note that this option causes behavior that is typically
538                 reserved for routers and therefore is not entirely in
539                 compliance with the IEEE 802.1D specification for bridges.
540                 Default is enabled, set to <code>false</code> to disable.</dd>
541             </dl>
542             <dl>
543               <dt><code>header_cache</code></dt>
544               <dd>Optional.  Enable caching of tunnel headers and the output
545                 path.  This can lead to a significant performance increase
546                 without changing behavior.  In general it should not be
547                 necessary to adjust this setting.  However, the caching can
548                 bypass certain components of the IP stack (such as IP tables)
549                 and it may be useful to disable it if these features are
550                 required or as a debugging measure.  Default is enabled, set to
551                 <code>false</code> to disable.</dd>
552             </dl>
553           </dd>
554           <dt><code>capwap</code></dt>
555           <dd>Ethernet tunneling over the UDP transport portion of CAPWAP
556              (RFC 5415).  This allows interoperability with certain switches
557              where GRE is not available.  Note that only the tunneling component
558              of the protocol is implemented.  Due to the non-standard use of
559              CAPWAP, UDP ports 58881 and 58882 are used as the source and
560              destinations ports respectivedly.  Each tunnel must be uniquely
561              identified by the combination of <code>remote_ip</code> and
562              <code>local_ip</code>.  If two ports are defined that are the same
563              except one includes <code>local_ip</code> and the other does not,
564              the more specific one is matched first.  CAPWAP support is not
565              available on all platforms.  Currently it is only supported in the
566              Linux kernel module with kernel versions >= 2.6.25.  The following
567              options may be specified in the <ref column="options"/> column:
568             <dl>
569               <dt><code>remote_ip</code></dt>
570               <dd>Required.  The tunnel endpoint.</dd>
571             </dl>
572             <dl>
573               <dt><code>local_ip</code></dt>
574               <dd>Optional.  The destination IP that received packets must
575                 match.  Default is to match all addresses.</dd>
576             </dl>
577             <dl>
578               <dt><code>tos</code></dt>
579               <dd>Optional.  The value of the ToS bits to be set on the
580                 encapsulating packet.  It may also be the word
581                 <code>inherit</code>, in which case the ToS will be copied from
582                 the inner packet if it is IPv4 or IPv6 (otherwise it will be
583                 0).  Note that the ECN fields are always inherited.  Default is
584                 0.</dd>
585             </dl>
586             <dl>
587               <dt><code>ttl</code></dt>
588               <dd>Optional.  The TTL to be set on the encapsulating packet.
589                 It may also be the word <code>inherit</code>, in which case the
590                 TTL will be copied from the inner packet if it is IPv4 or IPv6
591                 (otherwise it will be the system default, typically 64).
592                 Default is the system default TTL.</dd>
593             </dl>
594             <dl>
595               <dt><code>pmtud</code></dt>
596               <dd>Optional.  Enable tunnel path MTU discovery.  If enabled
597                 ``ICMP destination unreachable - fragmentation'' needed
598                 messages will be generated for IPv4 packets with the DF bit set
599                 and IPv6 packets above the minimum MTU if the packet size
600                 exceeds the path MTU minus the size of the tunnel headers.  It
601                 also forces the encapsulating packet DF bit to be set (it is
602                 always set if the inner packet implies path MTU discovery).
603                 Note that this option causes behavior that is typically
604                 reserved for routers and therefore is not entirely in
605                 compliance with the IEEE 802.1D specification for bridges.
606                 Default is enabled, set to <code>false</code> to disable.</dd>
607             </dl>
608             <dl>
609               <dt><code>header_cache</code></dt>
610               <dd>Optional.  Enable caching of tunnel headers and the output
611                 path.  This can lead to a significant performance increase
612                 without changing behavior.  In general it should not be
613                 necessary to adjust this setting.  However, the caching can
614                 bypass certain components of the IP stack (such as IP tables)
615                 and it may be useful to disable it if these features are
616                 required or as a debugging measure.  Default is enabled, set to
617                 <code>false</code> to disable.</dd>
618             </dl>
619           </dd>
620           <dt><code>patch</code></dt>
621           <dd>
622             <p>
623               A pair of virtual devices that act as a patch cable.  The <ref
624               column="options"/> column must have the following key-value pair:
625             </p>
626             <dl>
627               <dt><code>peer</code></dt>
628               <dd>
629                 The <ref column="name"/> of the <ref table="Interface"/> for
630                 the other side of the patch.  The named <ref
631                 table="Interface"/>'s own <code>peer</code> option must specify
632                 this <ref table="Interface"/>'s name.  That is, the two patch
633                 interfaces must have reversed <ref column="name"/> and
634                 <code>peer</code> values.
635               </dd>
636             </dl>
637           </dd>
638         </dl>
639       </column>
640
641       <column name="options">
642         Configuration options whose interpretation varies based on
643         <ref column="type"/>.
644       </column>
645
646       <column name="status">
647         <p>
648           Key-value pairs that report port status.  Supported status
649           values are <code>type</code>-dependent.
650         </p>
651         <p>The only currently defined key-value pair is:</p>
652         <dl>
653           <dt><code>source_ip</code></dt>
654           <dd>The source IP address used for an IPv4 tunnel end-point,
655             such as <code>gre</code> or <code>capwap</code>.  Not
656             supported by all implementations.</dd>
657         </dl>
658       </column>
659     </group>
660
661     <group title="Ingress Policing">
662       <p>
663         These settings control ingress policing for packets received on this
664         interface.  On a physical interface, this limits the rate at which
665         traffic is allowed into the system from the outside; on a virtual
666         interface (one connected to a virtual machine), this limits the rate at
667         which the VM is able to transmit.
668       </p>
669       <p>
670         Policing is a simple form of quality-of-service that simply drops
671         packets received in excess of the configured rate.  Due to its
672         simplicity, policing is usually less accurate and less effective than
673         egress QoS (which is configured using the <ref table="QoS"/> and <ref
674         table="Queue"/> tables).
675       </p>
676       <p>
677         Policing is currently implemented only on Linux.  The Linux
678         implementation uses a simple ``token bucket'' approach:
679       </p>
680       <ul>
681         <li>
682           The size of the bucket corresponds to <ref
683           column="ingress_policing_burst"/>.  Initially the bucket is full.
684         </li>
685         <li>
686           Whenever a packet is received, its size (converted to tokens) is
687           compared to the number of tokens currently in the bucket.  If the
688           required number of tokens are available, they are removed and the
689           packet is forwarded.  Otherwise, the packet is dropped.
690         </li>
691         <li>
692           Whenever it is not full, the bucket is refilled with tokens at the
693           rate specified by <ref column="ingress_policing_rate"/>.
694         </li>
695       </ul>
696       <p>
697         Policing interacts badly with some network protocols, and especially
698         with fragmented IP packets.  Suppose that there is enough network
699         activity to keep the bucket nearly empty all the time.  Then this token
700         bucket algorithm will forward a single packet every so often, with the
701         period depending on packet size and on the configured rate.  All of the
702         fragments of an IP packets are normally transmitted back-to-back, as a
703         group.  In such a situation, therefore, only one of these fragments
704         will be forwarded and the rest will be dropped.  IP does not provide
705         any way for the intended recipient to ask for only the remaining
706         fragments.  In such a case there are two likely possibilities for what
707         will happen next: either all of the fragments will eventually be
708         retransmitted (as TCP will do), in which case the same problem will
709         recur, or the sender will not realize that its packet has been dropped
710         and data will simply be lost (as some UDP-based protocols will do).
711         Either way, it is possible that no forward progress will ever occur.
712       </p>
713       <column name="ingress_policing_rate">
714         <p>
715           Maximum rate for data received on this interface, in kbps.  Data
716           received faster than this rate is dropped.  Set to <code>0</code>
717           (the default) to disable policing.
718         </p>
719       </column>
720
721       <column name="ingress_policing_burst">
722         <p>Maximum burst size for data received on this interface, in kb.  The
723           default burst size if set to <code>0</code> is 1000 kb.  This value
724           has no effect if <ref column="ingress_policing_rate"/>
725           is <code>0</code>.</p>
726         <p>
727           Specifying a larger burst size lets the algorithm be more forgiving,
728           which is important for protocols like TCP that react severely to
729           dropped packets.  The burst size should be at least the size of the
730           interface's MTU.  Specifying a value that is numerically at least as
731           large as 10% of <ref column="ingress_policing_rate"/> helps TCP come
732           closer to achieving the full rate.
733         </p>
734       </column>
735     </group>
736
737     <group title="Other Features">
738       <column name="external_ids">
739         Key-value pairs for use by external frameworks that integrate
740         with Open vSwitch, rather than by Open vSwitch itself.  System
741         integrators should either use the Open vSwitch development
742         mailing list to coordinate on common key-value definitions, or
743         choose key names that are likely to be unique.  The currently
744         defined common key-value pairs are:
745         <dl>
746           <dt><code>attached-mac</code></dt>
747           <dd>
748             The MAC address programmed into the ``virtual hardware'' for this
749             interface, in the form
750             <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
751             For Citrix XenServer, this is the value of the <code>MAC</code>
752             field in the VIF record for this interface.</dd>
753           <dt><code>iface-id</code></dt>
754           <dd>A system-unique identifier for the interface.  On XenServer, 
755             this will commonly be the same as <code>xs-vif-uuid</code>.</dd>
756         </dl>
757         <p>
758           Additionally the following key-value pairs specifically
759           apply to an interface that represents a virtual Ethernet interface
760           connected to a virtual machine.  These key-value pairs should not be
761           present for other types of interfaces.  Keys whose names end
762           in <code>-uuid</code> have values that uniquely identify the entity
763           in question.  For a Citrix XenServer hypervisor, these values are
764           UUIDs in RFC 4122 format.  Other hypervisors may use other
765           formats.
766         </p>
767         <p>The currently defined key-value pairs for XenServer are:</p>
768         <dl>
769           <dt><code>xs-vif-uuid</code></dt>
770           <dd>The virtual interface associated with this interface.</dd>
771           <dt><code>xs-network-uuid</code></dt>
772           <dd>The virtual network to which this interface is attached.</dd>
773           <dt><code>xs-vm-uuid</code></dt>
774           <dd>The VM to which this interface belongs.</dd>
775         </dl>
776       </column>
777
778       <column name="other_config">
779         Key-value pairs for rarely used interface features.  Currently,
780         the only keys are for configuring GRE-over-IPsec, which is only
781         available through the <code>openvswitch-ipsec</code> package for
782         Debian.  The currently defined key-value pairs are:
783         <dl>
784           <dt><code>ipsec_local_ip</code></dt>
785           <dd>Required key for GRE-over-IPsec interfaces.  Additionally,
786             the <ref column="type"/> must be <code>gre</code> and the
787             <code>ipsec_psk</code> <ref column="other_config"/> key must
788             be set.  The <code>in_key</code>, <code>out_key</code>, and
789             <code>key</code> <ref column="options"/> must not be
790             set.</dd>
791           <dt><code>ipsec_psk</code></dt>
792           <dd>Required key for GRE-over-IPsec interfaces.  Specifies a
793             pre-shared key for authentication that must be identical on 
794             both sides of the tunnel.  Additionally, the
795             <code>ipsec_local_ip</code> key must also be set.</dd>
796         </dl>
797       </column>
798
799       <column name="statistics">
800         <p>
801           Key-value pairs that report interface statistics.  The current
802           implementation updates these counters periodically.  In the future,
803           we plan to, instead, update them when an interface is created, when
804           they are queried (e.g. using an OVSDB <code>select</code> operation),
805           and just before an interface is deleted due to virtual interface
806           hot-unplug or VM shutdown, and perhaps at other times, but not on any
807           regular periodic basis.</p>
808         <p>
809           The currently defined key-value pairs are listed below.  These are
810           the same statistics reported by OpenFlow in its <code>struct
811           ofp_port_stats</code> structure.  If an interface does not support a
812           given statistic, then that pair is omitted.</p>
813         <ul>
814           <li>
815             Successful transmit and receive counters:
816             <dl>
817               <dt><code>rx_packets</code></dt>
818               <dd>Number of received packets.</dd>
819               <dt><code>rx_bytes</code></dt>
820               <dd>Number of received bytes.</dd>
821               <dt><code>tx_packets</code></dt>
822               <dd>Number of transmitted packets.</dd>
823               <dt><code>tx_bytes</code></dt>
824               <dd>Number of transmitted bytes.</dd>
825             </dl>
826           </li>
827           <li>
828             Receive errors:
829             <dl>
830               <dt><code>rx_dropped</code></dt>
831               <dd>Number of packets dropped by RX.</dd>
832               <dt><code>rx_frame_err</code></dt>
833               <dd>Number of frame alignment errors.</dd>
834               <dt><code>rx_over_err</code></dt>
835               <dd>Number of packets with RX overrun.</dd>
836               <dt><code>rx_crc_err</code></dt>
837               <dd>Number of CRC errors.</dd>
838               <dt><code>rx_errors</code></dt>
839               <dd>
840                 Total number of receive errors, greater than or equal
841                 to the sum of the above.
842               </dd>
843             </dl>
844           </li>
845           <li>
846             Transmit errors:
847             <dl>
848               <dt><code>tx_dropped</code></dt>
849               <dd>Number of packets dropped by TX.</dd>
850               <dt><code>collisions</code></dt>
851               <dd>Number of collisions.</dd>
852               <dt><code>tx_errors</code></dt>
853               <dd>
854                 Total number of transmit errors, greater
855                 than or equal to the sum of the above.
856               </dd>
857             </dl>
858           </li>
859         </ul>
860       </column>
861     </group>
862   </table>
863
864   <table name="QoS" title="Quality of Service configuration">
865     <p>Quality of Service (QoS) configuration for each Port that
866       references it.</p>
867
868     <column name="type">
869       <p>The type of QoS to implement.  The <ref table="Open_vSwitch"
870         column="capabilities"/> column in the <ref table="Open_vSwitch"/> table
871         identifies the types that a switch actually supports.  The currently
872         defined types are listed below:</p>
873       <dl>
874         <dt><code>linux-htb</code></dt>
875         <dd>
876           Linux ``hierarchy token bucket'' classifier.  See tc-htb(8) (also at
877           <code>http://linux.die.net/man/8/tc-htb</code>) and the HTB manual
878           (<code>http://luxik.cdi.cz/~devik/qos/htb/manual/userg.htm</code>)
879           for information on how this classifier works and how to configure it.
880         </dd>
881       </dl>
882     </column>
883
884     <column name="queues">
885       <p>A map from queue numbers to <ref table="Queue"/> records.  The
886         supported range of queue numbers depend on <ref column="type"/>.  The
887         queue numbers are the same as the <code>queue_id</code> used in
888         OpenFlow in <code>struct ofp_action_enqueue</code> and other
889         structures.  Queue 0 is used by OpenFlow output actions that do not
890         specify a specific queue.</p>
891     </column>
892
893     <column name="other_config">
894       <p>Key-value pairs for configuring QoS features that depend on
895         <ref column="type"/>.</p>
896       <p>The <code>linux-htb</code> class supports the following key-value
897         pairs:</p>
898       <dl>
899         <dt><code>max-rate</code></dt>
900         <dd>Maximum rate shared by all queued traffic, in bit/s.
901           Optional.  If not specified, for physical interfaces, the
902           default is the link rate.  For other interfaces or if the
903           link rate cannot be determined, the default is currently 100
904           Mbps.</dd>
905       </dl>
906     </column>
907
908     <column name="external_ids">
909       Key-value pairs for use by external frameworks that integrate with Open
910       vSwitch, rather than by Open vSwitch itself.  System integrators should
911       either use the Open vSwitch development mailing list to coordinate on
912       common key-value definitions, or choose key names that are likely to be
913       unique.  No common key-value pairs are currently defined.
914     </column>
915   </table>
916
917   <table name="Queue" title="QoS output queue.">
918     <p>A configuration for a port output queue, used in configuring Quality of
919       Service (QoS) features.  May be referenced by <ref column="queues"
920       table="QoS"/> column in <ref table="QoS"/> table.</p>
921
922     <column name="other_config">
923       <p>Key-value pairs for configuring the output queue.  The supported
924         key-value pairs and their meanings depend on the <ref column="type"/>
925         of the <ref column="QoS"/> records that reference this row.</p>
926       <p>The key-value pairs defined for <ref table="QoS"/> <ref table="QoS"
927         column="type"/> of <code>min-rate</code> are:</p>
928       <dl>
929         <dt><code>min-rate</code></dt>
930         <dd>Minimum guaranteed bandwidth, in bit/s.  Required.</dd>
931       </dl>
932       <p>The key-value pairs defined for <ref table="QoS"/> <ref table="QoS"
933         column="type"/> of <code>linux-htb</code> are:</p>
934       <dl>
935         <dt><code>min-rate</code></dt>
936         <dd>Minimum guaranteed bandwidth, in bit/s.  Required.</dd>
937         <dt><code>max-rate</code></dt>
938         <dd>Maximum allowed bandwidth, in bit/s.  Optional.  If specified, the
939           queue's rate will not be allowed to exceed the specified value, even
940           if excess bandwidth is available.  If unspecified, defaults to no
941           limit.</dd>
942         <dt><code>burst</code></dt>
943         <dd>Burst size, in bits.  This is the maximum amount of ``credits''
944           that a queue can accumulate while it is idle.  Optional.  Details of
945           the <code>linux-htb</code> implementation require a minimum burst
946           size, so a too-small <code>burst</code> will be silently
947           ignored.</dd>
948         <dt><code>priority</code></dt>
949         <dd>A nonnegative 32-bit integer.  Defaults to 0 if
950           unspecified.  A queue with a smaller <code>priority</code>
951           will receive all the excess bandwidth that it can use before
952           a queue with a larger value receives any.  Specific priority
953           values are unimportant; only relative ordering matters.</dd>
954       </dl>
955     </column>
956
957     <column name="external_ids">
958       Key-value pairs for use by external frameworks that integrate with Open
959       vSwitch, rather than by Open vSwitch itself.  System integrators should
960       either use the Open vSwitch development mailing list to coordinate on
961       common key-value definitions, or choose key names that are likely to be
962       unique.  No common key-value pairs are currently defined.
963     </column>
964   </table>
965
966   <table name="Mirror" title="Port mirroring (SPAN/RSPAN).">
967     <p>A port mirror within a <ref table="Bridge"/>.</p>
968     <p>A port mirror configures a bridge to send selected frames to special
969       ``mirrored'' ports, in addition to their normal destinations.  Mirroring
970       traffic may also be referred to as SPAN or RSPAN, depending on the
971       mechanism used for delivery.</p>
972
973     <column name="name">
974       Arbitrary identifier for the <ref table="Mirror"/>.
975     </column>
976
977     <group title="Selecting Packets for Mirroring">
978       <column name="select_all">
979         If true, every packet arriving or departing on any port is
980         selected for mirroring.
981       </column>
982
983       <column name="select_dst_port">
984         Ports on which departing packets are selected for mirroring.
985       </column>
986
987       <column name="select_src_port">
988         Ports on which arriving packets are selected for mirroring.
989       </column>
990
991       <column name="select_vlan">
992         VLANs on which packets are selected for mirroring.  An empty set
993         selects packets on all VLANs.
994       </column>
995     </group>
996
997     <group title="Mirroring Destination Configuration">
998       <column name="output_port">
999         <p>Output port for selected packets, if nonempty.  Mutually exclusive
1000           with <ref column="output_vlan"/>.</p>
1001         <p>Specifying a port for mirror output reserves that port exclusively
1002           for mirroring.  No frames other than those selected for mirroring
1003           will be forwarded to the port, and any frames received on the port
1004           will be discarded.</p>
1005         <p>This type of mirroring is sometimes called SPAN.</p>
1006       </column>
1007
1008       <column name="output_vlan">
1009         <p>Output VLAN for selected packets, if nonempty.  Mutually exclusive
1010           with <ref column="output_port"/>.</p>
1011         <p>The frames will be sent out all ports that trunk
1012           <ref column="output_vlan"/>, as well as any ports with implicit VLAN
1013           <ref column="output_vlan"/>.  When a mirrored frame is sent out a
1014           trunk port, the frame's VLAN tag will be set to
1015           <ref column="output_vlan"/>, replacing any existing tag; when it is
1016           sent out an implicit VLAN port, the frame will not be tagged.  This
1017           type of mirroring is sometimes called RSPAN.</p>
1018         <p><em>Please note:</em> Mirroring to a VLAN can disrupt a network that
1019           contains unmanaged switches.  Consider an unmanaged physical switch
1020           with two ports: port 1, connected to an end host, and port 2,
1021           connected to an Open vSwitch configured to mirror received packets
1022           into VLAN 123 on port 2.  Suppose that the end host sends a packet on
1023           port 1 that the physical switch forwards to port 2.  The Open vSwitch
1024           forwards this packet to its destination and then reflects it back on
1025           port 2 in VLAN 123.  This reflected packet causes the unmanaged
1026           physical switch to replace the MAC learning table entry, which
1027           correctly pointed to port 1, with one that incorrectly points to port
1028           2.  Afterward, the physical switch will direct packets destined for
1029           the end host to the Open vSwitch on port 2, instead of to the end
1030           host on port 1, disrupting connectivity.  If mirroring to a VLAN is
1031           desired in this scenario, then the physical switch must be replaced
1032           by one that learns Ethernet addresses on a per-VLAN basis.  In
1033           addition, learning should be disabled on the VLAN containing mirrored
1034           traffic. If this is not done then intermediate switches will learn
1035           the MAC address of each end host from the mirrored traffic.  If
1036           packets being sent to that end host are also mirrored, then they will
1037           be dropped since the switch will attempt to send them out the input
1038           port. Disabling learning for the VLAN will cause the switch to
1039           correctly send the packet out all ports configured for that VLAN.  If
1040           Open vSwitch is being used as an intermediate switch, learning can be
1041           disabled by adding the mirrored VLAN to <ref column="flood_vlans"/>
1042           in the appropriate <ref table="Bridge"/> table or tables.</p>
1043       </column>
1044     </group>
1045
1046     <group title="Other Features">
1047       <column name="external_ids">
1048         Key-value pairs for use by external frameworks that integrate with Open
1049         vSwitch, rather than by Open vSwitch itself.  System integrators should
1050         either use the Open vSwitch development mailing list to coordinate on
1051         common key-value definitions, or choose key names that are likely to be
1052         unique.  No common key-value pairs are currently defined.
1053       </column>
1054     </group>
1055   </table>
1056
1057   <table name="Controller" title="OpenFlow controller configuration.">
1058     <p>An OpenFlow controller.</p>
1059
1060     <p>
1061       Open vSwitch supports two kinds of OpenFlow controllers:
1062     </p>
1063     
1064     <dl>
1065       <dt>Primary controllers</dt>
1066       <dd>
1067         <p>
1068           This is the kind of controller envisioned by the OpenFlow 1.0
1069           specification.  Usually, a primary controller implements a network
1070           policy by taking charge of the switch's flow table.
1071         </p>
1072
1073         <p>
1074           Open vSwitch initiates and maintains persistent connections to
1075           primary controllers, retrying the connection each time it fails or
1076           drops.  The <ref table="Bridge" column="fail_mode"/> column in the
1077           <ref table="Bridge"/> table applies to primary controllers.
1078         </p>
1079
1080         <p>
1081           Open vSwitch permits a bridge to have any number of primary
1082           controllers.  When multiple controllers are configured, Open
1083           vSwitch connects to all of them simultaneously.  Because
1084           OpenFlow 1.0 does not specify how multiple controllers
1085           coordinate in interacting with a single switch, more than
1086           one primary controller should be specified only if the
1087           controllers are themselves designed to coordinate with each
1088           other.  (The Nicira-defined <code>NXT_ROLE</code> OpenFlow
1089           vendor extension may be useful for this.)
1090         </p>
1091       </dd>
1092       <dt>Service controllers</dt>
1093       <dd>
1094         <p>
1095           These kinds of OpenFlow controller connections are intended for
1096           occasional support and maintenance use, e.g. with
1097           <code>ovs-ofctl</code>.  Usually a service controller connects only
1098           briefly to inspect or modify some of a switch's state.
1099         </p>
1100
1101         <p>
1102           Open vSwitch listens for incoming connections from service
1103           controllers.  The service controllers initiate and, if necessary,
1104           maintain the connections from their end.  The <ref table="Bridge"
1105           column="fail_mode"/> column in the <ref table="Bridge"/> table does
1106           not apply to service controllers.
1107         </p>
1108
1109         <p>
1110           Open vSwitch supports configuring any number of service controllers.
1111         </p>
1112       </dd>
1113     </dl>
1114
1115     <p>
1116       The <ref column="target"/> determines the type of controller.
1117     </p>
1118
1119     <group title="Core Features">
1120       <column name="target">
1121         <p>Connection method for controller.</p>
1122         <p>
1123           The following connection methods are currently supported for primary
1124           controllers:
1125         </p>
1126         <dl>
1127           <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
1128           <dd>
1129             <p>The specified SSL <var>port</var> (default: 6633) on the host at
1130             the given <var>ip</var>, which must be expressed as an IP address
1131             (not a DNS name).  The <ref table="Open_vSwitch" column="ssl"/>
1132             column in the <ref table="Open_vSwitch"/> table must point to a
1133             valid SSL configuration when this form is used.</p>
1134             <p>SSL support is an optional feature that is not always built as
1135               part of Open vSwitch.</p>
1136           </dd>
1137           <dt><code>tcp:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
1138           <dd>The specified TCP <var>port</var> (default: 6633) on the host at
1139             the given <var>ip</var>, which must be expressed as an IP address
1140             (not a DNS name).</dd>
1141           <dt><code>discover</code></dt>
1142           <dd>
1143             <p>Enables controller discovery.</p>
1144             <p>In controller discovery mode, Open vSwitch broadcasts a DHCP
1145               request with vendor class identifier <code>OpenFlow</code> across
1146               all of the bridge's network devices.  It will accept any valid
1147               DHCP reply that has the same vendor class identifier and includes
1148               a vendor-specific option with code 1 whose contents are a string
1149               specifying the location of the controller in the same format as
1150               <ref column="target"/>.</p>
1151             <p>The DHCP reply may also, optionally, include a vendor-specific
1152               option with code 2 whose contents are a string specifying the URI
1153               to the base of the OpenFlow PKI
1154               (e.g. <code>http://192.168.0.1/openflow/pki</code>).  This URI is
1155               used only for bootstrapping the OpenFlow PKI at initial switch
1156               setup; <code>ovs-vswitchd</code> does not use it at all.</p>
1157           </dd>
1158         </dl>
1159         <p>
1160           The following connection methods are currently supported for service
1161           controllers:
1162         </p>
1163         <dl>
1164           <dt><code>pssl:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
1165           <dd>
1166             <p>
1167               Listens for SSL connections on the specified TCP <var>port</var>
1168               (default: 6633).  If <var>ip</var>, which must be expressed as an
1169               IP address (not a DNS name), is specified, then connections are
1170               restricted to the specified local IP address.
1171             </p>
1172             <p>
1173               The <ref table="Open_vSwitch" column="ssl"/> column in the <ref
1174               table="Open_vSwitch"/> table must point to a valid SSL
1175               configuration when this form is used.
1176             </p>
1177             <p>SSL support is an optional feature that is not always built as
1178               part of Open vSwitch.</p>
1179           </dd>
1180           <dt><code>ptcp:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
1181           <dd>
1182             Listens for connections on the specified TCP <var>port</var>
1183             (default: 6633).  If <var>ip</var>, which must be expressed as an
1184             IP address (not a DNS name), is specified, then connections are
1185             restricted to the specified local IP address.
1186           </dd>
1187         </dl>
1188         <p>When multiple controllers are configured for a single bridge, the
1189           <ref column="target"/> values must be unique.  Duplicate
1190           <ref column="target"/> values yield unspecified results.</p>
1191       </column>
1192
1193       <column name="connection_mode">
1194         <p>If it is specified, this setting must be one of the following
1195         strings that describes how Open vSwitch contacts this OpenFlow
1196         controller over the network:</p>
1197
1198         <dl>
1199           <dt><code>in-band</code></dt>
1200           <dd>In this mode, this controller's OpenFlow traffic travels over the
1201             bridge associated with the controller.  With this setting, Open
1202             vSwitch allows traffic to and from the controller regardless of the
1203             contents of the OpenFlow flow table.  (Otherwise, Open vSwitch
1204             would never be able to connect to the controller, because it did
1205             not have a flow to enable it.)  This is the most common connection
1206             mode because it is not necessary to maintain two independent
1207             networks.</dd>
1208           <dt><code>out-of-band</code></dt>
1209           <dd>In this mode, OpenFlow traffic uses a control network separate
1210             from the bridge associated with this controller, that is, the
1211             bridge does not use any of its own network devices to communicate
1212             with the controller.  The control network must be configured
1213             separately, before or after <code>ovs-vswitchd</code> is started.
1214           </dd>
1215         </dl>
1216
1217         <p>If not specified, the default is implementation-specific.  If
1218           <ref column="target"/> is <code>discover</code>, the connection mode
1219           is always treated as <code>in-band</code> regardless of the actual
1220           setting.</p>
1221       </column>
1222     </group>
1223
1224     <group title="Controller Failure Detection and Handling">
1225       <column name="max_backoff">
1226         Maximum number of milliseconds to wait between connection attempts.
1227         Default is implementation-specific.
1228       </column>
1229
1230       <column name="inactivity_probe">
1231         Maximum number of milliseconds of idle time on connection to
1232         controller before sending an inactivity probe message.  If Open
1233         vSwitch does not communicate with the controller for the specified
1234         number of seconds, it will send a probe.  If a response is not
1235         received for the same additional amount of time, Open vSwitch
1236         assumes the connection has been broken and attempts to reconnect.
1237         Default is implementation-specific.
1238       </column>
1239     </group>
1240
1241     <group title="OpenFlow Rate Limiting">
1242         <column name="controller_rate_limit">
1243           <p>The maximum rate at which packets in unknown flows will be
1244             forwarded to the OpenFlow controller, in packets per second.  This
1245             feature prevents a single bridge from overwhelming the controller.
1246             If not specified, the default is implementation-specific.</p>
1247           <p>In addition, when a high rate triggers rate-limiting, Open
1248             vSwitch queues controller packets for each port and transmits
1249             them to the controller at the configured rate.  The number of
1250             queued packets is limited by
1251             the <ref column="controller_burst_limit"/> value.  The packet
1252             queue is shared fairly among the ports on a bridge.</p><p>Open
1253             vSwitch maintains two such packet rate-limiters per bridge.
1254             One of these applies to packets sent up to the controller
1255             because they do not correspond to any flow.  The other applies
1256             to packets sent up to the controller by request through flow
1257             actions. When both rate-limiters are filled with packets, the
1258             actual rate that packets are sent to the controller is up to
1259             twice the specified rate.</p>
1260         </column>
1261
1262         <column name="controller_burst_limit">
1263           In conjunction with <ref column="controller_rate_limit"/>,
1264           the maximum number of unused packet credits that the bridge will
1265           allow to accumulate, in packets.  If not specified, the default
1266           is implementation-specific.
1267         </column>
1268     </group>
1269
1270     <group title="Additional Discovery Configuration">
1271       <p>These values are considered only when <ref column="target"/>
1272         is <code>discover</code>.</p>
1273
1274       <column name="discover_accept_regex">
1275         A POSIX
1276         extended regular expression against which the discovered controller
1277         location is validated.  The regular expression is implicitly
1278         anchored at the beginning of the controller location string, as
1279         if it begins with <code>^</code>.  If not specified, the default
1280         is implementation-specific.
1281       </column>
1282
1283       <column name="discover_update_resolv_conf">
1284         Whether to update <code>/etc/resolv.conf</code> when the
1285         controller is discovered.  If not specified, the default
1286         is implementation-specific.  Open vSwitch will only modify
1287         <code>/etc/resolv.conf</code> if the DHCP response that it receives
1288         specifies one or more DNS servers.
1289       </column>
1290     </group>
1291
1292     <group title="Additional In-Band Configuration">
1293       <p>These values are considered only in in-band control mode (see
1294         <ref column="connection_mode"/>) and only when <ref column="target"/>
1295         is not <code>discover</code>.  (For controller discovery, the network
1296         configuration obtained via DHCP is used instead.)</p>
1297
1298       <p>When multiple controllers are configured on a single bridge, there
1299         should be only one set of unique values in these columns.  If different
1300         values are set for these columns in different controllers, the effect
1301         is unspecified.</p>
1302
1303       <column name="local_ip">
1304         The IP address to configure on the local port,
1305         e.g. <code>192.168.0.123</code>.  If this value is unset, then
1306         <ref column="local_netmask"/> and <ref column="local_gateway"/> are
1307         ignored.
1308       </column>
1309
1310       <column name="local_netmask">
1311         The IP netmask to configure on the local port,
1312         e.g. <code>255.255.255.0</code>.  If <ref column="local_ip"/> is set
1313         but this value is unset, then the default is chosen based on whether
1314         the IP address is class A, B, or C.
1315       </column>
1316
1317       <column name="local_gateway">
1318         The IP address of the gateway to configure on the local port, as a
1319         string, e.g. <code>192.168.0.1</code>.  Leave this column unset if
1320         this network has no gateway.
1321       </column>
1322     </group>
1323
1324     <group title="Other Features">
1325       <column name="external_ids">
1326         Key-value pairs for use by external frameworks that integrate with Open
1327         vSwitch, rather than by Open vSwitch itself.  System integrators should
1328         either use the Open vSwitch development mailing list to coordinate on
1329         common key-value definitions, or choose key names that are likely to be
1330         unique.  No common key-value pairs are currently defined.
1331       </column>
1332     </group>
1333   </table>
1334
1335   <table name="NetFlow">
1336     A NetFlow target.  NetFlow is a protocol that exports a number of
1337     details about terminating IP flows, such as the principals involved
1338     and duration.
1339
1340     <column name="targets">
1341       NetFlow targets in the form
1342       <code><var>ip</var>:<var>port</var></code>.  The <var>ip</var>
1343       must be specified numerically, not as a DNS name.
1344     </column>
1345
1346     <column name="engine_id">
1347       Engine ID to use in NetFlow messages.  Defaults to datapath index
1348       if not specified.
1349     </column>
1350
1351     <column name="engine_type">
1352       Engine type to use in NetFlow messages.  Defaults to datapath
1353       index if not specified.
1354     </column>
1355
1356     <column name="active_timeout">
1357       The interval at which NetFlow records are sent for flows that are
1358       still active, in seconds.  A value of <code>0</code> requests the
1359       default timeout (currently 600 seconds); a value of <code>-1</code>
1360       disables active timeouts.
1361     </column>
1362
1363     <column name="add_id_to_interface">
1364       <p>If this column's value is <code>false</code>, the ingress and egress
1365         interface fields of NetFlow flow records are derived from OpenFlow port
1366         numbers.  When it is <code>true</code>, the 7 most significant bits of
1367         these fields will be replaced by the least significant 7 bits of the
1368         engine id.  This is useful because many NetFlow collectors do not
1369         expect multiple switches to be sending messages from the same host, so
1370         they do not store the engine information which could be used to
1371         disambiguate the traffic.</p>
1372       <p>When this option is enabled, a maximum of 508 ports are supported.</p>
1373     </column>
1374
1375     <column name="external_ids">
1376       Key-value pairs for use by external frameworks that integrate with Open
1377       vSwitch, rather than by Open vSwitch itself.  System integrators should
1378       either use the Open vSwitch development mailing list to coordinate on
1379       common key-value definitions, or choose key names that are likely to be
1380       unique.  No common key-value pairs are currently defined.
1381     </column>
1382   </table>
1383
1384   <table name="SSL">
1385     SSL configuration for an Open_vSwitch.
1386
1387     <column name="private_key">
1388       Name of a PEM file containing the private key used as the switch's
1389       identity for SSL connections to the controller.
1390     </column>
1391
1392     <column name="certificate">
1393       Name of a PEM file containing a certificate, signed by the
1394       certificate authority (CA) used by the controller and manager,
1395       that certifies the switch's private key, identifying a trustworthy
1396       switch.
1397     </column>
1398
1399     <column name="ca_cert">
1400       Name of a PEM file containing the CA certificate used to verify
1401       that the switch is connected to a trustworthy controller.
1402     </column>
1403
1404     <column name="bootstrap_ca_cert">
1405       If set to <code>true</code>, then Open vSwitch will attempt to
1406       obtain the CA certificate from the controller on its first SSL
1407       connection and save it to the named PEM file. If it is successful,
1408       it will immediately drop the connection and reconnect, and from then
1409       on all SSL connections must be authenticated by a certificate signed
1410       by the CA certificate thus obtained.  <em>This option exposes the
1411         SSL connection to a man-in-the-middle attack obtaining the initial
1412         CA certificate.</em>  It may still be useful for bootstrapping.
1413     </column>
1414
1415     <column name="external_ids">
1416       Key-value pairs for use by external frameworks that integrate with Open
1417       vSwitch, rather than by Open vSwitch itself.  System integrators should
1418       either use the Open vSwitch development mailing list to coordinate on
1419       common key-value definitions, or choose key names that are likely to be
1420       unique.  No common key-value pairs are currently defined.
1421     </column>
1422   </table>
1423
1424   <table name="sFlow">
1425     <p>An sFlow(R) target.  sFlow is a protocol for remote monitoring
1426       of switches.</p>
1427
1428     <column name="agent">
1429       Name of the network device whose IP address should be reported as the
1430       ``agent address'' to collectors.  If not specified, the IP address
1431       defaults to the <ref table="Controller" column="local_ip"/> in the
1432       collector's <ref table="Controller"/>.  If an agent IP address cannot be
1433       determined either way, sFlow is disabled.
1434     </column>
1435
1436     <column name="header">
1437       Number of bytes of a sampled packet to send to the collector.
1438       If not specified, the default is 128 bytes.
1439     </column>
1440
1441     <column name="polling">
1442       Polling rate in seconds to send port statistics to the collector.
1443       If not specified, defaults to 30 seconds.
1444     </column>
1445
1446     <column name="sampling">
1447       Rate at which packets should be sampled and sent to the collector.
1448       If not specified, defaults to 400, which means one out of 400
1449       packets, on average, will be sent to the collector.
1450     </column>
1451
1452     <column name="targets">
1453       sFlow targets in the form
1454       <code><var>ip</var>:<var>port</var></code>.
1455     </column>
1456
1457     <column name="external_ids">
1458       Key-value pairs for use by external frameworks that integrate with Open
1459       vSwitch, rather than by Open vSwitch itself.  System integrators should
1460       either use the Open vSwitch development mailing list to coordinate on
1461       common key-value definitions, or choose key names that are likely to be
1462       unique.  No common key-value pairs are currently defined.
1463     </column>
1464   </table>
1465
1466   <table name="Capability">
1467     <p>Records in this table describe functionality supported by the hardware
1468       and software platform on which this Open vSwitch is based.  Clients
1469       should not modify this table.</p>
1470
1471     <p>A record in this table is meaningful only if it is referenced by the
1472       <ref table="Open_vSwitch" column="capabilities"/> column in the
1473       <ref table="Open_vSwitch"/> table.  The key used to reference it, called
1474       the record's ``category,'' determines the meanings of the
1475       <ref column="details"/> column.  The following general forms of
1476       categories are currently defined:</p>
1477
1478     <dl>
1479       <dt><code>qos-<var>type</var></code></dt>
1480       <dd><var>type</var> is supported as the value for
1481         <ref column="type" table="QoS"/> in the <ref table="QoS"/> table.
1482       </dd>
1483     </dl>
1484
1485     <column name="details">
1486       <p>Key-value pairs that describe capabilities.  The meaning of the pairs
1487       depends on the category key that the <ref table="Open_vSwitch"
1488       column="capabilities"/> column in the <ref table="Open_vSwitch"/> table
1489       uses to reference this record, as described above.</p>
1490
1491       <p>The presence of a record for category <code>qos-<var>type</var></code>
1492           indicates that the switch supports <var>type</var> as the value of
1493           the <ref table="QoS" column="type"/> column in the <ref table="QoS"/>
1494           table.  The following key-value pairs are defined to further describe
1495           QoS capabilities:</p>
1496
1497       <dl>
1498         <dt><code>n-queues</code></dt>
1499         <dd>Number of supported queues, as a positive integer.  Keys in the
1500           <ref table="QoS" column="queues"/> column for <ref table="QoS"/>
1501           records whose <ref table="QoS" column="type"/> value
1502           equals <var>type</var> must range between 0 and this value minus one,
1503           inclusive.</dd>
1504       </dl>
1505     </column>
1506   </table>
1507 </database>