socket-util: Move get_mtime() here from stream-ssl.
[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="controller">
19         Default OpenFlow <ref table="Controller"/> set used by bridges.  May be
20         overridden on a per-bridge basis by the <ref table="Bridge"
21         column="controller"/> column in <ref table="Bridge"/>.
22       </column>
23
24       <column name="managers">
25         Remote database clients to which the Open vSwitch's database server
26         should connect or to which it should listen.
27       </column>
28
29       <column name="ssl">
30         SSL used globally by the daemon.
31       </column>
32
33       <column name="external_ids">
34         Key-value pairs that identify this Open vSwitch's role in
35         external systems.  The currently defined key-value pairs are:
36         <dl>
37           <dt><code>system-uuid</code></dt>
38           <dd>A universally unique identifier for the Open vSwitch's
39             physical host.  The form of the identifier depends on the
40             type of the host.  On a Citrix XenServer, this is the host
41             UUID displayed by, e.g., <code>xe host-list</code>.</dd>
42         </dl>
43       </column>
44     </group>
45
46     <group title="Status">
47       <column name="next_cfg">
48         Sequence number for client to increment.  When a client modifies
49         any part of the database configuration and wishes to wait for
50         Open vSwitch to finish applying the changes, it may increment
51         this sequence number.
52       </column>
53
54       <column name="cur_cfg">
55         Sequence number that Open vSwitch sets to the current value of
56         <ref column="next_cfg"/> after it finishes applying a set of
57         configuration changes.
58       </column>
59     </group>
60   </table>
61
62   <table name="Bridge">
63     <p>
64       Configuration for a bridge within an
65       <ref table="Open_vSwitch"/>.
66     </p>
67     <p>
68       A <ref table="Bridge"/> record represents an Ethernet switch with one or
69       more ``ports,'' which are the <ref table="Port"/> records pointed to by
70       the <ref table="Bridge"/>'s <ref column="ports"/> column.
71     </p>
72
73     <group title="Core Features">
74       <column name="name">
75         Bridge identifier.  Should be alphanumeric and no more than about 8
76         bytes long.  Must be unique among the names of ports, interfaces, and
77         bridges on a host.
78       </column>
79
80       <column name="ports">
81         Ports included in the bridge.
82       </column>
83
84       <column name="mirrors">
85         Port mirroring configuration.
86       </column>
87
88       <column name="netflow">
89         NetFlow configuration.
90       </column>
91
92       <column name="sflow">
93         sFlow configuration.
94       </column>
95
96       <column name="flood_vlans">
97         VLAN IDs of VLANs on which MAC address learning should be disabled, so
98         that packets are flooded instead of being sent to specific ports that
99         are believed to contain packets' destination MACs.  This should
100         ordinarily be used to disable MAC learning on VLANs used for mirroring
101         (RSPAN VLANs).  It may also be useful for debugging.
102       </column>
103     </group>
104
105     <group title="OpenFlow Configuration">
106       <column name="controller">
107         OpenFlow controller set.  If unset, defaults to the set of
108         controllers specified by <ref column="controller"
109         table="Open_vSwitch"/> in the <ref table="Open_vSwitch"/>
110         table.  If the default is also unset, then no OpenFlow
111         controllers will be used.
112       </column>
113
114       <column name="datapath_id">
115         Reports the OpenFlow datapath ID in use.  Exactly 16 hex digits.
116       </column>
117     </group>
118
119     <group title="Other Features">
120       <column name="datapath_type">
121         Name of datapath provider.  The kernel datapath has
122         type <code>system</code>.  The userspace datapath has
123         type <code>netdev</code>.
124       </column>
125
126       <column name="external_ids">
127         Key-value pairs that identify this bridge's role in external systems.
128         The currently defined key-value pairs are:
129         <dl>
130           <dt><code>network-uuids</code></dt>
131           <dd>Semicolon-delimited set of universally unique identifier(s) for
132             the network with which this bridge is associated.  The form of the
133             identifier(s) depends on the type of the host.  On a Citrix
134             XenServer host, the network identifiers are RFC 4122 UUIDs as
135             displayed by, e.g., <code>xe network-list</code>.</dd>
136         </dl>
137       </column>
138
139       <column name="other_config">
140         Key-value pairs for configuring rarely used bridge
141         features.  The currently defined key-value pairs are:
142         <dl>
143           <dt><code>datapath-id</code></dt>
144           <dd>Exactly 16 hex
145             digits to set the OpenFlow datapath ID to a specific
146             value.</dd>
147           <dt><code>hwaddr</code></dt>
148           <dd>An Ethernet address in the form
149             <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
150             to set the hardware address of the local port and influence the
151             datapath ID.</dd>
152         </dl>
153       </column>
154     </group>
155   </table>
156
157   <table name="Port" table="Port or bond configuration.">
158     <p>A port within a <ref table="Bridge"/>.</p>
159     <p>Most commonly, a port has exactly one ``interface,'' pointed to by its
160       <ref column="interfaces"/> column.  Such a port logically
161       corresponds to a port on a physical Ethernet switch.  A port
162       with more than one interface is a ``bonded port'' (see
163       <ref group="Bonding Configuration"/>).</p>
164     <p>Some properties that one might think as belonging to a port are actually
165       part of the port's <ref table="Interface"/> members.</p>
166
167     <column name="name">
168       Port name.  Should be alphanumeric and no more than about 8
169       bytes long.  May be the same as the interface name, for
170       non-bonded ports.  Must otherwise be unique among the names of
171       ports, interfaces, and bridges on a host.
172     </column>
173
174     <column name="interfaces">
175       The port's interfaces.  If there is more than one, this is a
176       bonded Port.
177     </column>
178
179     <group title="VLAN Configuration">
180       <p>A bridge port must be configured for VLANs in one of two
181         mutually exclusive ways:
182         <ul>
183           <li>A ``trunk port'' has an empty value for
184             <ref column="tag"/> and a possibly non-empty
185             <ref column="trunks"/> value.</li>
186           <li>An ``implicitly tagged VLAN port'' or ``access port''
187             has an nonempty value for <ref column="tag"/> and an empty
188             <ref column="trunks"/> value.</li>
189         </ul>
190         If <ref column="trunks"/> and <ref column="tag"/> are both
191         nonempty, the configuration is ill-formed.
192       </p>
193
194       <column name="tag">
195         <p>If nonempty, this port's implicitly tagged VLAN.  Frames
196           arriving on trunk ports will be forwarded to this port only
197           if they are tagged with the given VLAN.  Frames arriving on
198           other VLAN ports will be forwarded to this port only if they
199           have the same <ref column="tag"/> value.  Frames forwarded
200           to this port will not have an 802.1Q header.</p>
201         <p>When a frame with a 802.1Q header that indicates a nonzero VLAN is
202           received on an implicit VLAN port, it is discarded.</p>
203         <p>Must be empty if this is a trunk port.</p>
204       </column>
205
206       <column name="trunks">
207         <p>The 802.1Q VLAN(s) that this port trunks.  If the column is
208           empty, then the port trunks all VLANs as well as packets that
209           have no VLAN header.  Otherwise, only frames that have an
210           802.1Q header with one of the specified VLANs are accepted.
211           If <code>0</code> is included, then frames without an 802.1Q
212           header are also accepted.</p>
213         <p>Must be empty unless this is a trunk port.</p>
214       </column>
215     </group>
216
217     <group title="Bonding Configuration">
218       <p>A port that has more than one interface is a ``bonded port.''
219         Bonding allows for load balancing and fail-over.  Open vSwitch
220         supports ``source load balancing'' (SLB) bonding, which
221         assigns flows to slaves based on source MAC address, with
222         periodic rebalancing as traffic patterns change.  This form of
223         bonding does not require 802.3ad or other special support from
224         the upstream switch to which the slave devices are
225         connected.</p>
226
227       <p>These columns apply only to bonded ports.  Their values are
228         otherwise ignored.</p>
229
230       <column name="bond_updelay">
231         <p>For a bonded port, the number of milliseconds for which carrier must
232           stay up on an interface before the interface is considered to be up.
233           Specify <code>0</code> to enable the interface immediately.</p>
234         <p>This setting is honored only when at least one bonded interface is
235           already enabled.  When no interfaces are enabled, then the first bond
236           interface to come up is enabled immediately.</p>
237       </column>
238
239       <column name="bond_downdelay">
240         For a bonded port, the number of milliseconds for which carrier must
241         stay down on an interface before the interface is considered to be
242         down.  Specify <code>0</code> to disable the interface immediately.
243       </column>
244
245       <column name="bond_fake_iface">
246         For a bonded port, whether to create a fake internal interface with the
247         name of the port.  Use only for compatibility with legacy software that
248         requires this.
249       </column>
250     </group>
251
252     <group title="Other Features">
253       <column name="mac">
254         The MAC address to use for this port for the purpose of choosing the
255         bridge's MAC address.  This column does not necessarily reflect the
256         port's actual MAC address, nor will setting it change the port's actual
257         MAC address.
258       </column>
259
260       <column name="fake_bridge">
261         Does this port represent a sub-bridge for its tagged VLAN within the
262         Bridge?  See ovs-vsctl(8) for more information.
263       </column>
264
265       <column name="external_ids">
266         Key-value pairs that identify this port's role in external systems.  No
267         key-value pairs native to <ref table="Port"/> are currently defined.
268         For fake bridges (see the <ref column="fake_bridge"/> column), external
269         IDs for the fake bridge are defined here by prefixing a
270         <ref table="Bridge"/> <ref table="Bridge" column="external_ids"/> key
271         with <code>fake-bridge-</code>,
272         e.g. <code>fake-bridge-network-uuids</code>.
273       </column>
274
275       <column name="other_config">
276         Key-value pairs for configuring rarely used port features.  The
277         currently defined key-value pairs are:
278         <dl>
279           <dt><code>hwaddr</code></dt>
280           <dd>An Ethernet address in the form
281             <code><var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var></code>.</dd>
282           <dt><code>bond-rebalance-interval</code></dt>
283           <dd>For a bonded port, the number of milliseconds between
284             successive attempts to rebalance the bond, that is, to
285             move source MACs and their flows from one interface on
286             the bond to another in an attempt to keep usage of each
287             interface roughly equal.  The default is 10000 (10
288             seconds), and the minimum is 1000 (1 second).</dd>
289         </dl>
290       </column>
291     </group>
292   </table>
293
294   <table name="Interface" title="One physical network device in a Port.">
295     An interface within a <ref table="Port"/>.
296
297     <group title="Core Features">
298       <column name="name">
299         Interface name.  Should be alphanumeric and no more than about 8 bytes
300         long.  May be the same as the port name, for non-bonded ports.  Must
301         otherwise be unique among the names of ports, interfaces, and bridges
302         on a host.
303       </column>
304
305       <column name="mac">
306         <p>Ethernet address to set for this interface.  If unset then the
307           default MAC address is used:</p>
308         <ul>
309           <li>For the local interface, the default is the lowest-numbered MAC
310             address among the other bridge ports, either the value of the
311             <ref table="Port" column="mac"/> in its <ref table="Port"/> record,
312             if set, or its actual MAC (for bonded ports, the MAC of its slave
313             whose name is first in alphabetical order).  Internal ports and
314             bridge ports that are used as port mirroring destinations (see the
315             <ref table="Mirror"/> table) are ignored.</li>
316           <li>For other internal interfaces, the default MAC is randomly
317             generated.</li>
318           <li>External interfaces typically have a MAC address associated with
319             their hardware.</li>
320         </ul>
321         <p>Some interfaces may not have a software-controllable MAC
322         address.</p>
323       </column>
324
325       <column name="ofport">
326         <p>OpenFlow port number for this interface.  Unlike most columns, this
327           column's value should be set only by Open vSwitch itself.  Other
328           clients should set this column to an empty set (the default) when
329           creating an <ref table="Interface"/>.</p>
330         <p>Open vSwitch populates this column when the port number becomes
331           known.  If the interface is successfully added,
332           <ref column="ofport"/> will be set to a number between 1 and 65535
333           (generally either in the range 1 to 65280, exclusive, or 65534, the
334           port number for the OpenFlow ``local port'').  If the interface
335           cannot be added then Open vSwitch sets this column
336           to -1.</p>
337       </column>
338     </group>
339
340     <group title="System-Specific Details">
341       <column name="type">
342         The interface type, one of:
343         <dl>
344           <dt><code>system</code></dt>
345           <dd>An ordinary network device, e.g. <code>eth0</code> on Linux.
346             Sometimes referred to as ``external interfaces'' since they are
347             generally connected to hardware external to that on which the Open
348             vSwitch is running.  The empty string is a synonym for
349             <code>system</code>.</dd>
350           <dt><code>internal</code></dt>
351           <dd>A simulated network device that sends and receives traffic.  An
352             internal interface whose <ref column="name"/> is the same as its
353             bridge's <ref table="Open_vSwitch" column="name"/> is called the
354             ``local interface.''  It does not make sense to bond an internal
355             interface, so the terms ``port'' and ``interface'' are often used
356             imprecisely for internal interfaces.</dd>
357           <dt><code>tap</code></dt>
358           <dd>A TUN/TAP device managed by Open vSwitch.</dd>
359           <dt><code>gre</code></dt>
360           <dd>An Ethernet over RFC 1702 Generic Routing Encapsulation over IPv4
361              tunnel.  Each tunnel must be uniquely identified by the
362              combination of <code>remote_ip</code>, <code>local_ip</code>, and
363              <code>in_key</code>.  Note that if two ports are defined that are
364              the same except one has an optional identifier and the other does
365              not, the more specific one is matched first.  <code>in_key</code>
366              is considered more specific than <code>local_ip</code> if a port
367              defines one and another port defines the other.  The arguments
368              are:
369             <dl>
370               <dt><code>remote_ip</code></dt>
371               <dd>Required.  The tunnel endpoint.</dd>
372             </dl>
373             <dl>
374               <dt><code>local_ip</code></dt>
375               <dd>Optional.  The destination IP that received packets must
376                 match.  Default is to match all addresses.</dd>
377             </dl>
378             <dl>
379               <dt><code>in_key</code></dt>
380               <dd>Optional.  The GRE key that received packets must contain.
381                 It may either be a 32-bit number (no key and a key of 0 are
382                 treated as equivalent) or the word <code>flow</code>.  If
383                 <code>flow</code> is specified then any key will be accepted
384                 and the key will be placed in the <code>tun_id</code> field
385                 for matching in the flow table.  The ovs-ofctl manual page
386                 contains additional information about matching fields in
387                 OpenFlow flows.  Default is no key.</dd>
388             </dl>
389             <dl>
390               <dt><code>out_key</code></dt>
391               <dd>Optional.  The GRE key to be set on outgoing packets.  It may
392                 either be a 32-bit number or the word <code>flow</code>.  If
393                 <code>flow</code> is specified then the key may be set using
394                 the <code>set_tunnel</code> Nicira OpenFlow vendor extension (0
395                 is used in the absense of an action).  The ovs-ofctl manual
396                 page contains additional information about the Nicira OpenFlow
397                 vendor extensions.  Default is no key.</dd>
398             </dl>
399             <dl>
400               <dt><code>key</code></dt>
401               <dd>Optional.  Shorthand to set <code>in_key</code> and
402                 <code>out_key</code> at the same time.</dd>
403             </dl>
404             <dl>
405               <dt><code>tos</code></dt>
406               <dd>Optional.  The value of the ToS bits to be set on the
407                 encapsulating packet.  It may also be the word
408                 <code>inherit</code>, in which case the ToS will be copied from
409                 the inner packet if it is IPv4 or IPv6 (otherwise it will be
410                 0).  Note that the ECN fields are always inherited.  Default is
411                 0.</dd>
412             </dl>
413             <dl>
414               <dt><code>ttl</code></dt>
415               <dd>Optional.  The TTL to be set on the encapsulating packet.
416                 It may also be the word <code>inherit</code>, in which case the
417                 TTL will be copied from the inner packet if it is IPv4 or IPv6
418                 (otherwise it will be the system default, typically 64).
419                 Default is the system default TTL.</dd>
420             </dl>
421             <dl>
422               <dt><code>csum</code></dt>
423               <dd>Optional.  Compute GRE checksums for outgoing packets and
424                 require checksums for incoming packets.  Default is enabled,
425                 set to <code>false</code> to disable.</dd>
426             </dl>
427             <dl>
428               <dt><code>pmtud</code></dt>
429               <dd>Optional.  Enable tunnel path MTU discovery.  If enabled
430                 ``ICMP destination unreachable - fragmentation'' needed
431                 messages will be generated for IPv4 packets with the DF bit set
432                 and IPv6 packets above the minimum MTU if the packet size
433                 exceeds the path MTU minus the size of the tunnel headers.  It
434                 also forces the encapsulating packet DF bit to be set (it is
435                 always set if the inner packet implies path MTU discovery).
436                 Note that this option causes behavior that is typically
437                 reserved for routers and therefore is not entirely in
438                 compliance with the IEEE 802.1D specification for bridges.
439                 Default is enabled, set to <code>false</code> to disable.</dd>
440             </dl>
441           </dd>
442           <dt><code>patch</code></dt>
443           <dd>A pair of virtual devices that act as a patch cable.  A 
444             <code>peer</code> argument is required that indicates the name
445             of the other side of the patch.  Since a patch must work in
446             pairs, a second patch interface must be declared with the
447             <code>name</code> and <code>peer</code> arguments reversed.</dd>
448         </dl>
449       </column>
450
451       <column name="options">
452         Configuration options whose interpretation varies based on
453         <ref column="type"/>.
454       </column>
455     </group>
456
457     <group title="Ingress Policing">
458       <column name="ingress_policing_burst">
459         <p>Maximum burst size for data received on this interface, in kb.  The
460           default burst size if set to <code>0</code> is 1000 kb.  This value
461           has no effect if <ref column="ingress_policing_rate"/>
462           is <code>0</code>.</p>
463         <p>The burst size should be at least the size of the interface's
464           MTU.</p>
465       </column>
466
467       <column name="ingress_policing_rate">
468         <p>Maximum rate for data received on this interface, in kbps.  Data
469           received faster than this rate is dropped.  Set to <code>0</code> to
470           disable policing.</p>
471         <p>The meaning of ``ingress'' is from Open vSwitch's perspective.  If
472           configured on a physical interface, then it limits the rate at which
473           traffic is allowed into the system from the outside.  If configured
474           on a virtual interface that is connected to a virtual machine, then
475           it limits the rate at which the guest is able to transmit.</p>
476       </column>
477     </group>
478
479     <group title="Other Features">
480       <column name="external_ids">
481         <p>Key-value pairs that identify this interface's role in external
482           systems.  All of the currently defined key-value pairs specifically
483           apply to an interface that represents a virtual Ethernet interface
484           connected to a virtual machine.  These key-value pairs should not be
485           present for other types of interfaces.  Keys whose names end
486           in <code>-uuid</code> have values that uniquely identify the entity
487           in question.  For a Citrix XenServer hypervisor, these values are
488           UUIDs in RFC 4122 format.  Other hypervisors may use other
489           formats.</p>
490         <p>The currently defined key-value pairs are:</p>
491         <dl>
492           <dt><code>vif-uuid</code></dt>
493           <dd>The virtual interface associated with this interface.</dd>
494           <dt><code>network-uuid</code></dt>
495           <dd>The virtual network to which this interface is attached.</dd>
496           <dt><code>vm-uuid</code></dt>
497           <dd>The VM to which this interface belongs.</dd>
498           <dt><code>vif-mac</code></dt>
499           <dd>The MAC address programmed into the "virtual hardware" for this
500               interface, in the
501               form <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
502               For Citrix XenServer, this is the value of the <code>MAC</code>
503               field in the VIF record for this interface.</dd>
504         </dl>
505       </column>
506     </group>
507   </table>
508
509   <table name="Mirror" title="Port mirroring (SPAN/RSPAN).">
510     <p>A port mirror within a <ref table="Bridge"/>.</p>
511     <p>A port mirror configures a bridge to send selected frames to special
512       ``mirrored'' ports, in addition to their normal destinations.  Mirroring
513       traffic may also be referred to as SPAN or RSPAN, depending on the
514       mechanism used for delivery.</p>
515
516     <column name="name">
517       Arbitrary identifier for the <ref table="Mirror"/>.
518     </column>
519
520     <group title="Selecting Packets for Mirroring">
521       <column name="select_all">
522         If true, every packet arriving or departing on any port is
523         selected for mirroring.
524       </column>
525
526       <column name="select_dst_port">
527         Ports on which departing packets are selected for mirroring.
528       </column>
529
530       <column name="select_src_port">
531         Ports on which arriving packets are selected for mirroring.
532       </column>
533
534       <column name="select_vlan">
535         VLANs on which packets are selected for mirroring.  An empty set
536         selects packets on all VLANs.
537       </column>
538     </group>
539
540     <group title="Mirroring Destination Configuration">
541       <column name="output_port">
542         <p>Output port for selected packets, if nonempty.  Mutually exclusive
543           with <ref column="output_vlan"/>.</p>
544         <p>Specifying a port for mirror output reserves that port exclusively
545           for mirroring.  No frames other than those selected for mirroring
546           will be forwarded to the port, and any frames received on the port
547           will be discarded.</p>
548         <p>This type of mirroring is sometimes called SPAN.</p>
549       </column>
550
551       <column name="output_vlan">
552         <p>Output VLAN for selected packets, if nonempty.  Mutually exclusive
553           with <ref column="output_port"/>.</p>
554         <p>The frames will be sent out all ports that trunk
555           <ref column="output_vlan"/>, as well as any ports with implicit VLAN
556           <ref column="output_vlan"/>.  When a mirrored frame is sent out a
557           trunk port, the frame's VLAN tag will be set to
558           <ref column="output_vlan"/>, replacing any existing tag; when it is
559           sent out an implicit VLAN port, the frame will not be tagged.  This
560           type of mirroring is sometimes called RSPAN.</p>
561         <p><em>Please note:</em> Mirroring to a VLAN can disrupt a network that
562           contains unmanaged switches.  Consider an unmanaged physical switch
563           with two ports: port 1, connected to an end host, and port 2,
564           connected to an Open vSwitch configured to mirror received packets
565           into VLAN 123 on port 2.  Suppose that the end host sends a packet on
566           port 1 that the physical switch forwards to port 2.  The Open vSwitch
567           forwards this packet to its destination and then reflects it back on
568           port 2 in VLAN 123.  This reflected packet causes the unmanaged
569           physical switch to replace the MAC learning table entry, which
570           correctly pointed to port 1, with one that incorrectly points to port
571           2.  Afterward, the physical switch will direct packets destined for
572           the end host to the Open vSwitch on port 2, instead of to the end
573           host on port 1, disrupting connectivity.  If mirroring to a VLAN is
574           desired in this scenario, then the physical switch must be replaced
575           by one that learns Ethernet addresses on a per-VLAN basis.  In
576           addition, learning should be disabled on the VLAN containing mirrored
577           traffic. If this is not done then intermediate switches will learn
578           the MAC address of each end host from the mirrored traffic.  If
579           packets being sent to that end host are also mirrored, then they will
580           be dropped since the switch will attempt to send them out the input
581           port. Disabling learning for the VLAN will cause the switch to
582           correctly send the packet out all ports configured for that VLAN.  If
583           Open vSwitch is being used as an intermediate switch, learning can be
584           disabled by adding the mirrored VLAN to <ref column="flood_vlans"/>
585           in the appropriate <ref table="Bridge"/> table or tables.</p>
586       </column>
587     </group>
588   </table>
589
590   <table name="Controller" title="OpenFlow controller configuration.">
591     <p>An OpenFlow controller.</p>
592
593     <p>Open vSwitch permits a bridge to have any number of OpenFlow
594        controllers.  When multiple controllers are configured, Open vSwitch
595        connects to all of them simultaneously.  OpenFlow 1.0 does not specify
596        how multiple controllers coordinate in interacting with a single switch,
597        so more than one controller should be specified only if the controllers
598        are themselves designed to coordinate with each other.</p>
599
600     <group title="Core Features">
601       <column name="target">
602         <p>Connection method for controller.
603           The following connection methods are currently
604           supported:</p>
605         <dl>
606           <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
607           <dd>
608             <p>The specified SSL <var>port</var> (default: 6633) on the host at
609               the given <var>ip</var>, which must be expressed as an IP address
610               (not a DNS name).  The <ref table="Open_vSwitch" column="ssl"/>
611               column in the <ref table="Open_vSwitch"/> must point to a valid
612               SSL configuration when this form is used.</p>
613             <p>SSL support is an optional feature that is not always built as
614               part of Open vSwitch.</p>
615           </dd>
616           <dt><code>tcp:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
617           <dd>The specified TCP <var>port</var> (default: 6633) on the host at
618             the given <var>ip</var>, which must be expressed as an IP address
619             (not a DNS name).</dd>
620           <dt><code>discover</code></dt>
621           <dd>
622             <p>Enables controller discovery.</p>
623             <p>In controller discovery mode, Open vSwitch broadcasts a DHCP
624               request with vendor class identifier <code>OpenFlow</code> across
625               all of the bridge's network devices.  It will accept any valid
626               DHCP reply that has the same vendor class identifier and includes
627               a vendor-specific option with code 1 whose contents are a string
628               specifying the location of the controller in the same format as
629               <ref column="target"/>.</p>
630             <p>The DHCP reply may also, optionally, include a vendor-specific
631               option with code 2 whose contents are a string specifying the URI
632               to the base of the OpenFlow PKI
633               (e.g. <code>http://192.168.0.1/openflow/pki</code>).  This URI is
634               used only for bootstrapping the OpenFlow PKI at initial switch
635               setup; <code>ovs-vswitchd</code> does not use it at all.</p>
636           </dd>
637           <dt><code>none</code></dt>
638           <dd>Disables the controller.</dd>
639         </dl>
640         <p>When multiple controllers are configured for a single bridge, the
641           <ref column="target"/> values must be unique.  Duplicate
642           <ref column="target"/> values yield unspecified results.</p>
643       </column>
644
645       <column name="connection_mode">
646         <p>If it is specified, this setting must be one of the following
647         strings that describes how Open vSwitch contacts this OpenFlow
648         controller over the network:</p>
649
650         <dl>
651           <dt><code>in-band</code></dt>
652           <dd>In this mode, this controller's OpenFlow traffic travels over the
653             bridge associated with the controller.  With this setting, Open
654             vSwitch allows traffic to and from the controller regardless of the
655             contents of the OpenFlow flow table.  (Otherwise, Open vSwitch
656             would never be able to connect to the controller, because it did
657             not have a flow to enable it.)  This is the most common connection
658             mode because it is not necessary to maintain two independent
659             networks.</dd>
660           <dt><code>out-of-band</code></dt>
661           <dd>In this mode, OpenFlow traffic uses a control network separate
662             from the bridge associated with this controller, that is, the
663             bridge does not use any of its own network devices to communicate
664             with the controller.  The control network must be configured
665             separately, before or after <code>ovs-vswitchd</code> is started.
666           </dd>
667         </dl>
668
669         <p>If not specified, the default is implementation-specific.  If
670           <ref column="target"/> is <code>discover</code>, the connection mode
671           is always treated as <code>in-band</code> regardless of the actual
672           setting.</p>
673       </column>
674     </group>
675
676     <group title="Controller Failure Detection and Handling">
677       <column name="max_backoff">
678         Maximum number of milliseconds to wait between connection attempts.
679         Default is implementation-specific.
680       </column>
681
682       <column name="inactivity_probe">
683         Maximum number of milliseconds of idle time on connection to
684         controller before sending an inactivity probe message.  If Open
685         vSwitch does not communicate with the controller for the specified
686         number of seconds, it will send a probe.  If a response is not
687         received for the same additional amount of time, Open vSwitch
688         assumes the connection has been broken and attempts to reconnect.
689         Default is implementation-specific.
690       </column>
691
692       <column name="fail_mode">
693         <p>When a controller is configured, it is, ordinarily, responsible
694           for setting up all flows on the switch.  Thus, if the connection to
695           the controller fails, no new network connections can be set up.
696           If the connection to the controller stays down long enough,
697           no packets can pass through the switch at all.  This setting
698           determines the switch's response to such a situation.  It may be set
699           to one of the following:
700           <dl>
701             <dt><code>standalone</code></dt>
702             <dd>If no message is received from the controller for three
703               times the inactivity probe interval
704               (see <ref column="inactivity_probe"/>), then Open vSwitch
705               will take over responsibility for setting up flows.  In
706               this mode, Open vSwitch causes the bridge to act like an
707               ordinary MAC-learning switch.  Open vSwitch will continue
708               to retry connecting to the controller in the background
709               and, when the connection succeeds, it will discontinue its
710               standalone behavior.</dd>
711             <dt><code>secure</code></dt>
712             <dd>Open vSwitch will not set up flows on its own when the
713               controller connection fails.  It will continue retry
714               connecting to the controller forever.</dd>
715           </dl>
716         </p>
717         <p>If this value is unset, the default is implementation-specific.</p>
718         <p>When more than one controller is configured,
719           <ref column="fail_mode"/> is considered only when none of the
720           configured controllers can be contacted.  At that point, the bridge
721           enters secure mode if any of the controllers'
722           <ref column="fail_mode"/> is set to <code>secure</code>.  Otherwise,
723           it enters standalone mode if at least one <ref column="fail_mode"/>
724           is set to <code>standalone</code>.  If none of the
725           <ref column="fail_mode"/> values are set, the default is
726           implementation-defined.</p>
727       </column>
728     </group>
729
730     <group title="OpenFlow Rate Limiting">
731         <column name="controller_rate_limit">
732           <p>The maximum rate at which packets in unknown flows will be
733             forwarded to the OpenFlow controller, in packets per second.  This
734             feature prevents a single bridge from overwhelming the controller.
735             If not specified, the default is implementation-specific.</p>
736           <p>In addition, when a high rate triggers rate-limiting, Open
737             vSwitch queues controller packets for each port and transmits
738             them to the controller at the configured rate.  The number of
739             queued packets is limited by
740             the <ref column="controller_burst_limit"/> value.  The packet
741             queue is shared fairly among the ports on a bridge.</p><p>Open
742             vSwitch maintains two such packet rate-limiters per bridge.
743             One of these applies to packets sent up to the controller
744             because they do not correspond to any flow.  The other applies
745             to packets sent up to the controller by request through flow
746             actions. When both rate-limiters are filled with packets, the
747             actual rate that packets are sent to the controller is up to
748             twice the specified rate.</p>
749         </column>
750
751         <column name="controller_burst_limit">
752           In conjunction with <ref column="controller_rate_limit"/>,
753           the maximum number of unused packet credits that the bridge will
754           allow to accumulate, in packets.  If not specified, the default
755           is implementation-specific.
756         </column>
757     </group>
758
759     <group title="Additional Discovery Configuration">
760       <p>These values are considered only when <ref column="target"/>
761         is <code>discover</code>.</p>
762
763       <column name="discover_accept_regex">
764         A POSIX
765         extended regular expression against which the discovered controller
766         location is validated.  The regular expression is implicitly
767         anchored at the beginning of the controller location string, as
768         if it begins with <code>^</code>.  If not specified, the default
769         is implementation-specific.
770       </column>
771
772       <column name="discover_update_resolv_conf">
773         Whether to update <code>/etc/resolv.conf</code> when the
774         controller is discovered.  If not specified, the default
775         is implementation-specific.  Open vSwitch will only modify
776         <code>/etc/resolv.conf</code> if the DHCP response that it receives
777         specifies one or more DNS servers.
778       </column>
779     </group>
780
781     <group title="Additional In-Band Configuration">
782       <p>These values are considered only in in-band control mode (see
783         <ref column="connection_mode"/>) and only when <ref column="target"/>
784         is not <code>discover</code>.  (For controller discovery, the network
785         configuration obtained via DHCP is used instead.)</p>
786
787       <p>When multiple controllers are configured on a single bridge, there
788         should be only one set of unique values in these columns.  If different
789         values are set for these columns in different controllers, the effect
790         is unspecified.</p>
791
792       <column name="local_ip">
793         The IP address to configure on the local port,
794         e.g. <code>192.168.0.123</code>.  If this value is unset, then
795         <ref column="local_netmask"/> and <ref column="local_gateway"/> are
796         ignored.
797       </column>
798
799       <column name="local_netmask">
800         The IP netmask to configure on the local port,
801         e.g. <code>255.255.255.0</code>.  If <ref column="local_ip"/> is set
802         but this value is unset, then the default is chosen based on whether
803         the IP address is class A, B, or C.
804       </column>
805
806       <column name="local_gateway">
807         The IP address of the gateway to configure on the local port, as a
808         string, e.g. <code>192.168.0.1</code>.  Leave this column unset if
809         this network has no gateway.
810       </column>
811     </group>
812   </table>
813
814   <table name="NetFlow">
815     A NetFlow target.  NetFlow is a protocol that exports a number of
816     details about terminating IP flows, such as the principals involved
817     and duration.
818
819     <column name="targets">
820       NetFlow targets in the form
821       <code><var>ip</var>:<var>port</var></code>.  The <var>ip</var>
822       must be specified numerically, not as a DNS name.
823     </column>
824
825     <column name="engine_id">
826       Engine ID to use in NetFlow messages.  Defaults to datapath index
827       if not specified.
828     </column>
829
830     <column name="engine_type">
831       Engine type to use in NetFlow messages.  Defaults to datapath
832       index if not specified.
833     </column>
834
835     <column name="active_timeout">
836       The interval at which NetFlow records are sent for flows that are
837       still active, in seconds.  A value of <code>0</code> requests the
838       default timeout (currently 600 seconds); a value of <code>-1</code>
839       disables active timeouts.
840     </column>
841
842     <column name="add_id_to_interface">
843       <p>If this column's value is <code>false</code>, the ingress and egress
844         interface fields of NetFlow flow records are derived from OpenFlow port
845         numbers.  When it is <code>true</code>, the 7 most significant bits of
846         these fields will be replaced by the least significant 7 bits of the
847         engine id.  This is useful because many NetFlow collectors do not
848         expect multiple switches to be sending messages from the same host, so
849         they do not store the engine information which could be used to
850         disambiguate the traffic.</p>
851       <p>When this option is enabled, a maximum of 508 ports are supported.</p>
852     </column>
853   </table>
854
855   <table name="SSL">
856     SSL configuration for an Open_vSwitch.
857
858     <column name="private_key">
859       Name of a PEM file containing the private key used as the switch's
860       identity for SSL connections to the controller.
861     </column>
862
863     <column name="certificate">
864       Name of a PEM file containing a certificate, signed by the
865       certificate authority (CA) used by the controller and manager,
866       that certifies the switch's private key, identifying a trustworthy
867       switch.
868     </column>
869
870     <column name="ca_cert">
871       Name of a PEM file containing the CA certificate used to verify
872       that the switch is connected to a trustworthy controller.
873     </column>
874
875     <column name="bootstrap_ca_cert">
876       If set to <code>true</code>, then Open vSwitch will attempt to
877       obtain the CA certificate from the controller on its first SSL
878       connection and save it to the named PEM file. If it is successful,
879       it will immediately drop the connection and reconnect, and from then
880       on all SSL connections must be authenticated by a certificate signed
881       by the CA certificate thus obtained.  <em>This option exposes the
882         SSL connection to a man-in-the-middle attack obtaining the initial
883         CA certificate.</em>  It may still be useful for bootstrapping.
884     </column>
885   </table>
886
887   <table name="sFlow">
888     <p>An sFlow(R) target.  sFlow is a protocol for remote monitoring
889       of switches.</p>
890
891     <column name="agent">
892       IP address to report as ``agent address'' to collectors.  If not
893       specified, defaults to the <ref table="Controller" column="local_ip"/> in
894       the collector's <ref table="Controller"/>.  If neither is specified,
895       sFlow is disabled.
896     </column>
897
898     <column name="header">
899       Number of bytes of a sampled packet to send to the collector.
900       If not specified, the default is 128 bytes.
901     </column>
902
903     <column name="polling">
904       Polling rate in seconds to send port statistics to the collector.
905       If not specified, defaults to 30 seconds.
906     </column>
907
908     <column name="sampling">
909       Rate at which packets should be sampled and sent to the collector.
910       If not specified, defaults to 400, which means one out of 400
911       packets, on average, will be sent to the collector.
912     </column>
913
914     <column name="targets">
915       sFlow targets in the form
916       <code><var>ip</var>:<var>port</var></code>.
917     </column>
918   </table>
919 </database>