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       Name of the network device whose IP address should be reported as the
 893       ``agent address'' to collectors.  If not specified, the IP address
 894       defaults to the <ref table="Controller" column="local_ip"/> in the
 895       collector's <ref table="Controller"/>.  If an agent IP address cannot be
 896       determined either way, sFlow is disabled.
 897     </column>
 898
 899     <column name="header">
 900       Number of bytes of a sampled packet to send to the collector.
 901       If not specified, the default is 128 bytes.
 902     </column>
 903
 904     <column name="polling">
 905       Polling rate in seconds to send port statistics to the collector.
 906       If not specified, defaults to 30 seconds.
 907     </column>
 908
 909     <column name="sampling">
 910       Rate at which packets should be sampled and sent to the collector.
 911       If not specified, defaults to 400, which means one out of 400
 912       packets, on average, will be sent to the collector.
 913     </column>
 914
 915     <column name="targets">
 916       sFlow targets in the form
 917       <code><var>ip</var>:<var>port</var></code>.
 918     </column>
 919   </table>
 920 </database>