+ <group title="Tunnel Options: gre only">
+ <p>
+ Only <code>gre</code> interfaces support these options.
+ </p>
+
+ <column name="options" key="header_cache" type='{"type": "boolean"}'>
+ Enable caching of tunnel headers and the output path. This can lead
+ to a significant performance increase without changing behavior. In
+ general it should not be necessary to adjust this setting. However,
+ the caching can bypass certain components of the IP stack (such as
+ <code>iptables</code>) and it may be useful to disable it if these
+ features are required or as a debugging measure. Default is enabled,
+ set to <code>false</code> to disable.
+ </column>
+ </group>
+
+ <group title="Tunnel Options: gre and ipsec_gre only">
+ <p>
+ Only <code>gre</code> and <code>ipsec_gre</code> interfaces support
+ these options.
+ </p>
+
+ <column name="options" key="csum" type='{"type": "boolean"}'>
+ <p>
+ Optional. Compute GRE checksums on outgoing packets. Default is
+ disabled, set to <code>true</code> to enable. Checksums present on
+ incoming packets will be validated regardless of this setting.
+ </p>
+
+ <p>
+ GRE checksums impose a significant performance penalty because they
+ cover the entire packet. The encapsulated L3, L4, and L7 packet
+ contents typically have their own checksums, so this additional
+ checksum only adds value for the GRE and encapsulated L2 headers.
+ </p>
+
+ <p>
+ This option is supported for <code>ipsec_gre</code>, but not useful
+ because GRE checksums are weaker than, and redundant with, IPsec
+ payload authentication.
+ </p>
+ </column>
+ </group>
+
+ <group title="Tunnel Options: ipsec_gre only">
+ <p>
+ Only <code>ipsec_gre</code> interfaces support these options.
+ </p>
+
+ <column name="options" key="peer_cert">
+ Required for certificate authentication. A string containing the
+ peer's certificate in PEM format. Additionally the host's
+ certificate must be specified with the <code>certificate</code>
+ option.
+ </column>
+
+ <column name="options" key="certificate">
+ Required for certificate authentication. The name of a PEM file
+ containing a certificate that will be presented to the peer during
+ authentication.
+ </column>
+
+ <column name="options" key="private_key">
+ Optional for certificate authentication. The name of a PEM file
+ containing the private key associated with <code>certificate</code>.
+ If <code>certificate</code> contains the private key, this option may
+ be omitted.
+ </column>
+
+ <column name="options" key="psk">
+ Required for pre-shared key authentication. Specifies a pre-shared
+ key for authentication that must be identical on both sides of the
+ tunnel.
+ </column>
+ </group>
+ </group>
+
+ <group title="Patch Options">
+ <p>
+ Only <code>patch</code> interfaces support these options.
+ </p>
+
+ <column name="options" key="peer">
+ The <ref column="name"/> of the <ref table="Interface"/> for the other
+ side of the patch. The named <ref table="Interface"/>'s own
+ <code>peer</code> option must specify this <ref table="Interface"/>'s
+ name. That is, the two patch interfaces must have reversed <ref
+ column="name"/> and <code>peer</code> values.
+ </column>
+ </group>
+
+ <group title="Interface Status">
+ <p>
+ Status information about interfaces attached to bridges, updated every
+ 5 seconds. Not all interfaces have all of these properties; virtual
+ interfaces don't have a link speed, for example. Non-applicable
+ columns will have empty values.
+ </p>
+ <column name="admin_state">
+ <p>
+ The administrative state of the physical network link.
+ </p>
+ </column>
+
+ <column name="link_state">
+ <p>
+ The observed state of the physical network link. This is ordinarily
+ the link's carrier status. If the interface's <ref table="Port"/> is
+ a bond configured for miimon monitoring, it is instead the network
+ link's miimon status.
+ </p>
+ </column>
+
+ <column name="link_resets">
+ <p>
+ The number of times Open vSwitch has observed the
+ <ref column="link_state"/> of this <ref table="Interface"/> change.
+ </p>
+ </column>
+
+ <column name="link_speed">
+ <p>
+ The negotiated speed of the physical network link.
+ Valid values are positive integers greater than 0.
+ </p>
+ </column>
+
+ <column name="duplex">
+ <p>
+ The duplex mode of the physical network link.
+ </p>
+ </column>
+
+ <column name="mtu">
+ <p>
+ The MTU (maximum transmission unit); i.e. the largest
+ amount of data that can fit into a single Ethernet frame.
+ The standard Ethernet MTU is 1500 bytes. Some physical media
+ and many kinds of virtual interfaces can be configured with
+ higher MTUs.
+ </p>
+ <p>
+ This column will be empty for an interface that does not
+ have an MTU as, for example, some kinds of tunnels do not.
+ </p>
+ </column>
+
+ <column name="lacp_current">
+ Boolean value indicating LACP status for this interface. If true, this
+ interface has current LACP information about its LACP partner. This
+ information may be used to monitor the health of interfaces in a LACP
+ enabled port. This column will be empty if LACP is not enabled.
+ </column>
+
+ <column name="status">
+ Key-value pairs that report port status. Supported status values are
+ <ref column="type"/>-dependent; some interfaces may not have a valid
+ <ref column="status" key="driver_name"/>, for example.
+ </column>
+
+ <column name="status" key="driver_name">
+ The name of the device driver controlling the network adapter.
+ </column>
+
+ <column name="status" key="driver_version">
+ The version string of the device driver controlling the network
+ adapter.
+ </column>
+
+ <column name="status" key="firmware_version">
+ The version string of the network adapter's firmware, if available.
+ </column>
+
+ <column name="status" key="source_ip">
+ The source IP address used for an IPv4 tunnel end-point, such as
+ <code>gre</code> or <code>capwap</code>.
+ </column>
+
+ <column name="status" key="tunnel_egress_iface">
+ Egress interface for tunnels. Currently only relevant for GRE and
+ CAPWAP tunnels. On Linux systems, this column will show the name of
+ the interface which is responsible for routing traffic destined for the
+ configured <ref column="options" key="remote_ip"/>. This could be an
+ internal interface such as a bridge port.
+ </column>
+
+ <column name="status" key="tunnel_egress_iface_carrier"
+ type='{"type": "string", "enum": ["set", ["down", "up"]]}'>
+ Whether carrier is detected on <ref column="status"
+ key="tunnel_egress_iface"/>.
+ </column>
+ </group>
+
+ <group title="Statistics">
+ <p>
+ Key-value pairs that report interface statistics. The current
+ implementation updates these counters periodically. Future
+ implementations may update them when an interface is created, when they
+ are queried (e.g. using an OVSDB <code>select</code> operation), and
+ just before an interface is deleted due to virtual interface hot-unplug
+ or VM shutdown, and perhaps at other times, but not on any regular
+ periodic basis.
+ </p>
+ <p>
+ These are the same statistics reported by OpenFlow in its <code>struct
+ ofp_port_stats</code> structure. If an interface does not support a
+ given statistic, then that pair is omitted.
+ </p>
+ <group title="Statistics: Successful transmit and receive counters">
+ <column name="statistics" key="rx_packets">
+ Number of received packets.
+ </column>
+ <column name="statistics" key="rx_bytes">
+ Number of received bytes.
+ </column>
+ <column name="statistics" key="tx_packets">
+ Number of transmitted packets.
+ </column>
+ <column name="statistics" key="tx_bytes">
+ Number of transmitted bytes.
+ </column>
+ </group>
+ <group title="Statistics: Receive errors">
+ <column name="statistics" key="rx_dropped">
+ Number of packets dropped by RX.
+ </column>
+ <column name="statistics" key="rx_frame_err">
+ Number of frame alignment errors.
+ </column>
+ <column name="statistics" key="rx_over_err">
+ Number of packets with RX overrun.
+ </column>
+ <column name="statistics" key="rx_crc_err">
+ Number of CRC errors.
+ </column>
+ <column name="statistics" key="rx_errors">
+ Total number of receive errors, greater than or equal to the sum of
+ the above.
+ </column>
+ </group>
+ <group title="Statistics: Transmit errors">
+ <column name="statistics" key="tx_dropped">
+ Number of packets dropped by TX.
+ </column>
+ <column name="statistics" key="collisions">
+ Number of collisions.
+ </column>
+ <column name="statistics" key="tx_errors">
+ Total number of transmit errors, greater than or equal to the sum of
+ the above.
+ </column>
+ </group>
+ </group>
+
+ <group title="Ingress Policing">
+ <p>
+ These settings control ingress policing for packets received on this
+ interface. On a physical interface, this limits the rate at which
+ traffic is allowed into the system from the outside; on a virtual
+ interface (one connected to a virtual machine), this limits the rate at
+ which the VM is able to transmit.
+ </p>
+ <p>
+ Policing is a simple form of quality-of-service that simply drops
+ packets received in excess of the configured rate. Due to its
+ simplicity, policing is usually less accurate and less effective than
+ egress QoS (which is configured using the <ref table="QoS"/> and <ref
+ table="Queue"/> tables).
+ </p>
+ <p>
+ Policing is currently implemented only on Linux. The Linux
+ implementation uses a simple ``token bucket'' approach:
+ </p>
+ <ul>
+ <li>
+ The size of the bucket corresponds to <ref
+ column="ingress_policing_burst"/>. Initially the bucket is full.
+ </li>
+ <li>
+ Whenever a packet is received, its size (converted to tokens) is
+ compared to the number of tokens currently in the bucket. If the
+ required number of tokens are available, they are removed and the
+ packet is forwarded. Otherwise, the packet is dropped.
+ </li>
+ <li>
+ Whenever it is not full, the bucket is refilled with tokens at the
+ rate specified by <ref column="ingress_policing_rate"/>.
+ </li>
+ </ul>
+ <p>
+ Policing interacts badly with some network protocols, and especially
+ with fragmented IP packets. Suppose that there is enough network
+ activity to keep the bucket nearly empty all the time. Then this token
+ bucket algorithm will forward a single packet every so often, with the
+ period depending on packet size and on the configured rate. All of the
+ fragments of an IP packets are normally transmitted back-to-back, as a
+ group. In such a situation, therefore, only one of these fragments
+ will be forwarded and the rest will be dropped. IP does not provide
+ any way for the intended recipient to ask for only the remaining
+ fragments. In such a case there are two likely possibilities for what
+ will happen next: either all of the fragments will eventually be
+ retransmitted (as TCP will do), in which case the same problem will
+ recur, or the sender will not realize that its packet has been dropped
+ and data will simply be lost (as some UDP-based protocols will do).
+ Either way, it is possible that no forward progress will ever occur.
+ </p>
+ <column name="ingress_policing_rate">
+ <p>
+ Maximum rate for data received on this interface, in kbps. Data
+ received faster than this rate is dropped. Set to <code>0</code>
+ (the default) to disable policing.
+ </p>
+ </column>
+
+ <column name="ingress_policing_burst">
+ <p>Maximum burst size for data received on this interface, in kb. The
+ default burst size if set to <code>0</code> is 1000 kb. This value
+ has no effect if <ref column="ingress_policing_rate"/>
+ is <code>0</code>.</p>
+ <p>
+ Specifying a larger burst size lets the algorithm be more forgiving,
+ which is important for protocols like TCP that react severely to
+ dropped packets. The burst size should be at least the size of the
+ interface's MTU. Specifying a value that is numerically at least as
+ large as 10% of <ref column="ingress_policing_rate"/> helps TCP come
+ closer to achieving the full rate.
+ </p>
+ </column>
+ </group>
+
+ <group title="Connectivity Fault Management">
+ <p>
+ 802.1ag Connectivity Fault Management (CFM) allows a group of
+ Maintenance Points (MPs) called a Maintenance Association (MA) to
+ detect connectivity problems with each other. MPs within a MA should
+ have complete and exclusive interconnectivity. This is verified by
+ occasionally broadcasting Continuity Check Messages (CCMs) at a
+ configurable transmission interval.
+ </p>
+
+ <p>
+ According to the 802.1ag specification, each Maintenance Point should
+ be configured out-of-band with a list of Remote Maintenance Points it
+ should have connectivity to. Open vSwitch differs from the
+ specification in this area. It simply assumes the link is faulted if
+ no Remote Maintenance Points are reachable, and considers it not
+ faulted otherwise.
+ </p>
+
+ <column name="cfm_mpid">
+ A Maintenance Point ID (MPID) uniquely identifies each endpoint within
+ a Maintenance Association. The MPID is used to identify this endpoint
+ to other Maintenance Points in the MA. Each end of a link being
+ monitored should have a different MPID. Must be configured to enable
+ CFM on this <ref table="Interface"/>.
+ </column>
+
+ <column name="cfm_fault">
+ <p>
+ Indicates a connectivity fault triggered by an inability to receive
+ heartbeats from any remote endpoint. When a fault is triggered on
+ <ref table="Interface"/>s participating in bonds, they will be
+ disabled.
+ </p>
+ <p>
+ Faults can be triggered for several reasons. Most importantly they
+ are triggered when no CCMs are received for a period of 3.5 times the
+ transmission interval. Faults are also triggered when any CCMs
+ indicate that a Remote Maintenance Point is not receiving CCMs but
+ able to send them. Finally, a fault is triggered if a CCM is
+ received which indicates unexpected configuration. Notably, this
+ case arises when a CCM is received which advertises the local MPID.
+ </p>
+ </column>
+
+ <column name="cfm_remote_mpids">
+ When CFM is properly configured, Open vSwitch will occasionally
+ receive CCM broadcasts. These broadcasts contain the MPID of the
+ sending Maintenance Point. The list of MPIDs from which this
+ <ref table="Interface"/> is receiving broadcasts from is regularly
+ collected and written to this column.
+ </column>
+
+ <column name="other_config" key="cfm_interval"
+ type='{"type": "integer"}'>
+ The interval, in milliseconds, between transmissions of CFM heartbeats.
+ Three missed heartbeat receptions indicate a connectivity fault.
+ Defaults to 1000.
+ </column>
+
+ <column name="other_config" key="cfm_extended"
+ type='{"type": "boolean"}'>
+ When <code>true</code>, the CFM module operates in extended mode. This
+ causes it to use a nonstandard destination address to avoid conflicting
+ with compliant implementations which may be running concurrently on the
+ network. Furthermore, extended mode increases the accuracy of the
+ <code>cfm_interval</code> configuration parameter by breaking wire
+ compatibility with 802.1ag compliant implementations. Defaults to
+ <code>false</code>.
+ </column>
+ <column name="other_config" key="cfm_opstate"
+ type='{"type": "string", "enum": ["set", ["down", "up"]]}'>
+ When <code>down</code>, the CFM module marks all CCMs it generates as
+ operationally down without triggering a fault. This allows remote
+ maintenance points to choose not to forward traffic to the
+ <ref table="Interface"/> on which this CFM module is running.
+ Currently, in Open vSwitch, the opdown bit of CCMs affects
+ <ref table="Interface"/>s participating in bonds, and the bundle
+ OpenFlow action. This setting is ignored when CFM is not in extended
+ mode. Defaults to <code>up</code>.
+ </column>
+
+ <column name="other_config" key="cfm_ccm_vlan"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 4095}'>
+ When set, the CFM module will apply a VLAN tag to all CCMs it generates
+ with the given value.
+ </column>
+
+ </group>
+
+ <group title="Bonding Configuration">
+ <column name="other_config" key="bond-stable-id"
+ type='{"type": "integer", "minInteger": 1}'>
+ Used in <code>stable</code> bond mode to make slave
+ selection decisions. Allocating <ref column="other_config"
+ key="bond-stable-id"/> values consistently across interfaces
+ participating in a bond will guarantee consistent slave selection
+ decisions across <code>ovs-vswitchd</code> instances when using
+ <code>stable</code> bonding mode.
+ </column>
+
+ <column name="other_config" key="lacp-port-id"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
+ The LACP port ID of this <ref table="Interface"/>. Port IDs are
+ used in LACP negotiations to identify individual ports
+ participating in a bond.
+ </column>
+
+ <column name="other_config" key="lacp-port-priority"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
+ The LACP port priority of this <ref table="Interface"/>. In LACP
+ negotiations <ref table="Interface"/>s with numerically lower
+ priorities are preferred for aggregation.
+ </column>
+
+ <column name="other_config" key="lacp-aggregation-key"
+ type='{"type": "integer", "minInteger": 1, "maxInteger": 65535}'>
+ The LACP aggregation key of this <ref table="Interface"/>. <ref
+ table="Interface"/>s with different aggregation keys may not be active
+ within a given <ref table="Port"/> at the same time.
+ </column>
+ </group>
+
+ <group title="Virtual Machine Identifiers">
+ <p>
+ These key-value pairs specifically apply to an interface that
+ represents a virtual Ethernet interface connected to a virtual
+ machine. These key-value pairs should not be present for other types
+ of interfaces. Keys whose names end in <code>-uuid</code> have
+ values that uniquely identify the entity in question. For a Citrix
+ XenServer hypervisor, these values are UUIDs in RFC 4122 format.
+ Other hypervisors may use other formats.
+ </p>
+
+ <column name="external_ids" key="attached-mac">
+ The MAC address programmed into the ``virtual hardware'' for this
+ interface, in the form
+ <var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>.
+ For Citrix XenServer, this is the value of the <code>MAC</code> field
+ in the VIF record for this interface.
+ </column>
+
+ <column name="external_ids" key="iface-id">
+ A system-unique identifier for the interface. On XenServer, this will
+ commonly be the same as <ref column="external_ids" key="xs-vif-uuid"/>.
+ </column>
+
+ <column name="external_ids" key="xs-vif-uuid">
+ The virtual interface associated with this interface.
+ </column>
+
+ <column name="external_ids" key="xs-network-uuid">
+ The virtual network to which this interface is attached.
+ </column>
+
+ <column name="external_ids" key="xs-vm-uuid">
+ The VM to which this interface belongs.
+ </column>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="other_config"/>
+ <column name="external_ids"/>
+ </group>
+ </table>
+
+ <table name="QoS" title="Quality of Service configuration">
+ <p>Quality of Service (QoS) configuration for each Port that
+ references it.</p>
+
+ <column name="type">
+ <p>The type of QoS to implement. The <ref table="Open_vSwitch"
+ column="capabilities"/> column in the <ref table="Open_vSwitch"/> table
+ identifies the types that a switch actually supports. The currently
+ defined types are listed below:</p>
+ <dl>
+ <dt><code>linux-htb</code></dt>
+ <dd>
+ Linux ``hierarchy token bucket'' classifier. See tc-htb(8) (also at
+ <code>http://linux.die.net/man/8/tc-htb</code>) and the HTB manual
+ (<code>http://luxik.cdi.cz/~devik/qos/htb/manual/userg.htm</code>)
+ for information on how this classifier works and how to configure it.
+ </dd>
+ </dl>
+ <dl>
+ <dt><code>linux-hfsc</code></dt>
+ <dd>
+ Linux "Hierarchical Fair Service Curve" classifier.
+ See <code>http://linux-ip.net/articles/hfsc.en/</code> for
+ information on how this classifier works.
+ </dd>
+ </dl>
+ </column>
+
+ <column name="queues">
+ <p>A map from queue numbers to <ref table="Queue"/> records. The
+ supported range of queue numbers depend on <ref column="type"/>. The
+ queue numbers are the same as the <code>queue_id</code> used in
+ OpenFlow in <code>struct ofp_action_enqueue</code> and other
+ structures. Queue 0 is used by OpenFlow output actions that do not
+ specify a specific queue.</p>
+ </column>
+
+ <group title="Configuration for linux-htb and linux-hfsc">
+ <p>
+ The <code>linux-htb</code> and <code>linux-hfsc</code> classes support
+ the following key-value pair:
+ </p>
+
+ <column name="other_config" key="max-rate" type='{"type": "integer"}'>
+ Maximum rate shared by all queued traffic, in bit/s. Optional. If not
+ specified, for physical interfaces, the default is the link rate. For
+ other interfaces or if the link rate cannot be determined, the default
+ is currently 100 Mbps.
+ </column>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="other_config"/>
+ <column name="external_ids"/>
+ </group>
+ </table>
+
+ <table name="Queue" title="QoS output queue.">
+ <p>A configuration for a port output queue, used in configuring Quality of
+ Service (QoS) features. May be referenced by <ref column="queues"
+ table="QoS"/> column in <ref table="QoS"/> table.</p>
+
+ <group title="Configuration for min-rate QoS">
+ <p>
+ These key-value pairs are defined for <ref table="QoS"/> <ref
+ table="QoS" column="type"/> of <code>min-rate</code>.
+ </p>
+
+ <column name="other_config" key="min-rate"
+ type='{"type": "integer", "minInteger": 12000}'>
+ Minimum guaranteed bandwidth, in bit/s. Required. The floor value is
+ 1500 bytes/s (12,000 bit/s).
+ </column>
+ </group>
+
+ <group title="Configuration for linux-htb QoS">
+ <p>
+ These key-value pairs are defined for <ref table="QoS"/> <ref
+ table="QoS" column="type"/> of <code>linux-htb</code>.
+ </p>
+
+ <column name="other_config" key="min-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Minimum guaranteed bandwidth, in bit/s.
+ </column>
+
+ <column name="other_config" key="max-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Maximum allowed bandwidth, in bit/s. Optional. If specified, the
+ queue's rate will not be allowed to exceed the specified value, even
+ if excess bandwidth is available. If unspecified, defaults to no
+ limit.
+ </column>
+
+ <column name="other_config" key="burst"
+ type='{"type": "integer", "minInteger": 1}'>
+ Burst size, in bits. This is the maximum amount of ``credits'' that a
+ queue can accumulate while it is idle. Optional. Details of the
+ <code>linux-htb</code> implementation require a minimum burst size, so
+ a too-small <code>burst</code> will be silently ignored.
+ </column>
+
+ <column name="other_config" key="priority"
+ type='{"type": "integer", "minInteger": 0, "maxInteger": 4294967295}'>
+ A queue with a smaller <code>priority</code> will receive all the
+ excess bandwidth that it can use before a queue with a larger value
+ receives any. Specific priority values are unimportant; only relative
+ ordering matters. Defaults to 0 if unspecified.
+ </column>
+ </group>
+
+ <group title="Configuration for linux-hfsc QoS">
+ <p>
+ These key-value pairs are defined for <ref table="QoS"/> <ref
+ table="QoS" column="type"/> of <code>linux-hfsc</code>.
+ </p>
+
+ <column name="other_config" key="min-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Minimum guaranteed bandwidth, in bit/s.
+ </column>
+
+ <column name="other_config" key="max-rate"
+ type='{"type": "integer", "minInteger": 1}'>
+ Maximum allowed bandwidth, in bit/s. Optional. If specified, the
+ queue's rate will not be allowed to exceed the specified value, even if
+ excess bandwidth is available. If unspecified, defaults to no
+ limit.
+ </column>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="other_config"/>
+ <column name="external_ids"/>
+ </group>
+ </table>
+
+ <table name="Mirror" title="Port mirroring (SPAN/RSPAN/ERSPAN).">
+ <p>A port mirror within a <ref table="Bridge"/>.</p>
+ <p>A port mirror configures a bridge to send selected frames to special
+ ``mirrored'' ports, in addition to their normal destinations. Mirroring
+ traffic may also be referred to as SPAN, RSPAN, or ERSPAN, depending on how
+ the mirrored traffic is sent.</p>
+
+ <column name="name">
+ Arbitrary identifier for the <ref table="Mirror"/>.
+ </column>
+
+ <group title="Selecting Packets for Mirroring">
+ <p>
+ To be selected for mirroring, a given packet must enter or leave the
+ bridge through a selected port and it must also be in one of the
+ selected VLANs.
+ </p>
+
+ <column name="select_all">
+ If true, every packet arriving or departing on any port is
+ selected for mirroring.
+ </column>
+
+ <column name="select_dst_port">
+ Ports on which departing packets are selected for mirroring.
+ </column>
+
+ <column name="select_src_port">
+ Ports on which arriving packets are selected for mirroring.
+ </column>
+
+ <column name="select_vlan">
+ VLANs on which packets are selected for mirroring. An empty set
+ selects packets on all VLANs.
+ </column>
+ </group>
+
+ <group title="Mirroring Destination Configuration">
+ <p>
+ These columns are mutually exclusive. Exactly one of them must be
+ nonempty.
+ </p>
+
+ <column name="output_port">
+ <p>Output port for selected packets, if nonempty.</p>
+ <p>Specifying a port for mirror output reserves that port exclusively
+ for mirroring. No frames other than those selected for mirroring
+ will be forwarded to the port, and any frames received on the port
+ will be discarded.</p>
+ <p>
+ The output port may be any kind of port supported by Open vSwitch.
+ It may be, for example, a physical port (sometimes called SPAN), or a
+ GRE tunnel (sometimes called ERSPAN).
+ </p>
+ </column>
+
+ <column name="output_vlan">
+ <p>Output VLAN for selected packets, if nonempty.</p>
+ <p>The frames will be sent out all ports that trunk
+ <ref column="output_vlan"/>, as well as any ports with implicit VLAN
+ <ref column="output_vlan"/>. When a mirrored frame is sent out a
+ trunk port, the frame's VLAN tag will be set to
+ <ref column="output_vlan"/>, replacing any existing tag; when it is
+ sent out an implicit VLAN port, the frame will not be tagged. This
+ type of mirroring is sometimes called RSPAN.</p>
+ <p>
+ The following destination MAC addresses will not be mirrored to a
+ VLAN to avoid confusing switches that interpret the protocols that
+ they represent:
+ </p>
+ <dl>
+ <dt><code>01:80:c2:00:00:00</code></dt>
+ <dd>IEEE 802.1D Spanning Tree Protocol (STP).</dd>
+
+ <dt><code>01:80:c2:00:00:01</code></dt>
+ <dd>IEEE Pause frame.</dd>
+
+ <dt><code>01:80:c2:00:00:0<var>x</var></code></dt>
+ <dd>Other reserved protocols.</dd>
+
+ <dt><code>01:00:0c:cc:cc:cc</code></dt>
+ <dd>
+ Cisco Discovery Protocol (CDP), VLAN Trunking Protocol (VTP),
+ Dynamic Trunking Protocol (DTP), Port Aggregation Protocol (PAgP),
+ and others.
+ </dd>
+
+ <dt><code>01:00:0c:cc:cc:cd</code></dt>
+ <dd>Cisco Shared Spanning Tree Protocol PVSTP+.</dd>
+
+ <dt><code>01:00:0c:cd:cd:cd</code></dt>
+ <dd>Cisco STP Uplink Fast.</dd>
+
+ <dt><code>01:00:0c:00:00:00</code></dt>
+ <dd>Cisco Inter Switch Link.</dd>
+ </dl>
+ <p><em>Please note:</em> Mirroring to a VLAN can disrupt a network that
+ contains unmanaged switches. Consider an unmanaged physical switch
+ with two ports: port 1, connected to an end host, and port 2,
+ connected to an Open vSwitch configured to mirror received packets
+ into VLAN 123 on port 2. Suppose that the end host sends a packet on
+ port 1 that the physical switch forwards to port 2. The Open vSwitch
+ forwards this packet to its destination and then reflects it back on
+ port 2 in VLAN 123. This reflected packet causes the unmanaged
+ physical switch to replace the MAC learning table entry, which
+ correctly pointed to port 1, with one that incorrectly points to port
+ 2. Afterward, the physical switch will direct packets destined for
+ the end host to the Open vSwitch on port 2, instead of to the end
+ host on port 1, disrupting connectivity. If mirroring to a VLAN is
+ desired in this scenario, then the physical switch must be replaced
+ by one that learns Ethernet addresses on a per-VLAN basis. In
+ addition, learning should be disabled on the VLAN containing mirrored
+ traffic. If this is not done then intermediate switches will learn
+ the MAC address of each end host from the mirrored traffic. If
+ packets being sent to that end host are also mirrored, then they will
+ be dropped since the switch will attempt to send them out the input
+ port. Disabling learning for the VLAN will cause the switch to
+ correctly send the packet out all ports configured for that VLAN. If
+ Open vSwitch is being used as an intermediate switch, learning can be
+ disabled by adding the mirrored VLAN to <ref column="flood_vlans"/>
+ in the appropriate <ref table="Bridge"/> table or tables.</p>
+ <p>
+ Mirroring to a GRE tunnel has fewer caveats than mirroring to a
+ VLAN and should generally be preferred.
+ </p>
+ </column>
+ </group>
+
+ <group title="Common Columns">
+ The overall purpose of these columns is described under <code>Common
+ Columns</code> at the beginning of this document.
+
+ <column name="external_ids"/>
+ </group>
+ </table>
+
+ <table name="Controller" title="OpenFlow controller configuration.">
+ <p>An OpenFlow controller.</p>
+
+ <p>
+ Open vSwitch supports two kinds of OpenFlow controllers:
+ </p>
+
+ <dl>
+ <dt>Primary controllers</dt>
+ <dd>
+ <p>
+ This is the kind of controller envisioned by the OpenFlow 1.0
+ specification. Usually, a primary controller implements a network
+ policy by taking charge of the switch's flow table.
+ </p>
+
+ <p>
+ Open vSwitch initiates and maintains persistent connections to
+ primary controllers, retrying the connection each time it fails or
+ drops. The <ref table="Bridge" column="fail_mode"/> column in the
+ <ref table="Bridge"/> table applies to primary controllers.
+ </p>
+
+ <p>
+ Open vSwitch permits a bridge to have any number of primary
+ controllers. When multiple controllers are configured, Open
+ vSwitch connects to all of them simultaneously. Because
+ OpenFlow 1.0 does not specify how multiple controllers
+ coordinate in interacting with a single switch, more than
+ one primary controller should be specified only if the
+ controllers are themselves designed to coordinate with each
+ other. (The Nicira-defined <code>NXT_ROLE</code> OpenFlow
+ vendor extension may be useful for this.)
+ </p>
+ </dd>
+ <dt>Service controllers</dt>
+ <dd>
+ <p>
+ These kinds of OpenFlow controller connections are intended for
+ occasional support and maintenance use, e.g. with
+ <code>ovs-ofctl</code>. Usually a service controller connects only
+ briefly to inspect or modify some of a switch's state.
+ </p>
+
+ <p>
+ Open vSwitch listens for incoming connections from service
+ controllers. The service controllers initiate and, if necessary,
+ maintain the connections from their end. The <ref table="Bridge"
+ column="fail_mode"/> column in the <ref table="Bridge"/> table does
+ not apply to service controllers.
+ </p>
+
+ <p>
+ Open vSwitch supports configuring any number of service controllers.
+ </p>
+ </dd>
+ </dl>
+
+ <p>
+ The <ref column="target"/> determines the type of controller.
+ </p>
+
+ <group title="Core Features">
+ <column name="target">
+ <p>Connection method for controller.</p>
+ <p>
+ The following connection methods are currently supported for primary
+ controllers:
+ </p>
+ <dl>
+ <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
+ <dd>
+ <p>The specified SSL <var>port</var> (default: 6633) on the host at
+ the given <var>ip</var>, which must be expressed as an IP address
+ (not a DNS name). The <ref table="Open_vSwitch" column="ssl"/>
+ column in the <ref table="Open_vSwitch"/> table must point to a
+ valid SSL configuration when this form is used.</p>