+<?xml version="1.0" encoding="utf-8"?>
<database title="Open vSwitch Configuration Database">
<p>A database with this schema holds the configuration for one Open
vSwitch daemon. The root of the configuration for the daemon is
Set of bridges managed by the daemon.
</column>
- <column name="controller">
- Default OpenFlow <ref table="Controller"/> set used by bridges. May be
- overridden on a per-bridge basis by the <ref table="Bridge"
- column="controller"/> column in <ref table="Bridge"/>.
- </column>
-
<column name="managers">
Remote database clients to which the Open vSwitch's database server
should connect or to which it should listen.
</column>
<column name="external_ids">
- Key-value pairs that identify this Open vSwitch's role in
- external systems. The currently defined key-value pairs are:
+ Key-value pairs for use by external frameworks that integrate
+ with Open vSwitch, rather than by Open vSwitch itself. System
+ integrators should either use the Open vSwitch development
+ mailing list to coordinate on common key-value definitions, or
+ choose key names that are likely to be unique. The currently
+ defined common key-value pairs are:
<dl>
- <dt><code>system-uuid</code></dt>
- <dd>A universally unique identifier for the Open vSwitch's
- physical host. The form of the identifier depends on the
- type of the host. On a Citrix XenServer, this is the host
- UUID displayed by, e.g., <code>xe host-list</code>.</dd>
+ <dt><code>system-type</code></dt>
+ <dd>An identifier for the switch type, such as
+ <code>XenServer</code> or <code>KVM</code>.</dd>
+ <dt><code>system-version</code></dt>
+ <dd>The version of the switch software, such as
+ <code>5.6.0</code> on XenServer.</dd>
+ <dt><code>system-id</code></dt>
+ <dd>A unique identifier for the Open vSwitch's physical host.
+ The form of the identifier depends on the type of the host.
+ On a Citrix XenServer, this will likely be the same as
+ <code>xs-system-uuid</code>.</dd>
+ <dt><code>xs-system-uuid</code></dt>
+ <dd>The Citrix XenServer universally unique identifier for the
+ physical host as displayed by <code>xe host-list</code>.</dd>
</dl>
</column>
</group>
capability categories and the meaning of associated
<ref table="Capability"/> records.
</column>
+
+ <column name="statistics">
+ <p>
+ Key-value pairs that report statistics about a system running an Open
+ vSwitch. These are updated periodically (currently, every 5
+ seconds). Key-value pairs that cannot be determined or that do not
+ apply to a platform are omitted.
+ </p>
+
+ <dl>
+ <dt><code>cpu</code></dt>
+ <dd>
+ <p>
+ Number of CPU processors, threads, or cores currently online and
+ available to the operating system on which Open vSwitch is
+ running, as an integer. This may be less than the number
+ installed, if some are not online or if they are not available to
+ the operating system.
+ </p>
+ <p>
+ Open vSwitch userspace processes are not multithreaded, but the
+ Linux kernel-based datapath is.
+ </p>
+ </dd>
+
+ <dt><code>load_average</code></dt>
+ <dd>
+ <p>
+ A comma-separated list of three floating-point numbers,
+ representing the system load average over the last 1, 5, and 15
+ minutes, respectively.
+ </p>
+ </dd>
+
+ <dt><code>memory</code></dt>
+ <dd>
+ <p>
+ A comma-separated list of integers, each of which represents a
+ quantity of memory in kilobytes that describes the operating
+ system on which Open vSwitch is running. In respective order,
+ these values are:
+ </p>
+
+ <ol>
+ <li>Total amount of RAM allocated to the OS.</li>
+ <li>RAM allocated to the OS that is in use.</li>
+ <li>RAM that can be flushed out to disk or otherwise discarded
+ if that space is needed for another purpose. This number is
+ necessarily less than or equal to the previous value.</li>
+ <li>Total disk space allocated for swap.</li>
+ <li>Swap space currently in use.</li>
+ </ol>
+
+ <p>
+ On Linux, all five values can be determined and are included. On
+ other operating systems, only the first two values can be
+ determined, so the list will only have two values.
+ </p>
+ </dd>
+
+ <dt><code>process_</code><var>name</var></dt>
+ <dd>
+ <p>
+ One such key-value pair will exist for each running Open vSwitch
+ daemon process, with <var>name</var> replaced by the daemon's
+ name (e.g. <code>process_ovs-vswitchd</code>). The value is a
+ comma-separated list of integers. The integers represent the
+ following, with memory measured in kilobytes and durations in
+ milliseconds:
+ </p>
+
+ <ol>
+ <li>The process's virtual memory size.</li>
+ <li>The process's resident set size.</li>
+ <li>The amount of user and system CPU time consumed by the
+ process.</li>
+ <li>The number of times that the process has crashed and been
+ automatically restarted by the monitor.</li>
+ <li>The duration since the process was started.</li>
+ <li>The duration for which the process has been running.</li>
+ </ol>
+
+ <p>
+ The interpretation of some of these values depends on whether the
+ process was started with the <option>--monitor</option>. If it
+ was not, then the crash count will always be 0 and the two
+ durations will always be the same. If <option>--monitor</option>
+ was given, then the crash count may be positive; if it is, the
+ latter duration is the amount of time since the most recent crash
+ and restart.
+ </p>
+
+ <p>
+ There will be one key-value pair for each file in Open vSwitch's
+ ``run directory'' (usually <code>/var/run/openvswitch</code>)
+ whose name ends in <code>.pid</code>, whose contents are a
+ process ID, and which is locked by a running process. The
+ <var>name</var> is taken from the pidfile's name.
+ </p>
+
+ <p>
+ Currently Open vSwitch is only able to obtain all of the above
+ detail on Linux systems. On other systems, the same key-value
+ pairs will be present but the values will always be the empty
+ string.
+ </p>
+ </dd>
+
+ <dt><code>file_systems</code></dt>
+ <dd>
+ <p>
+ A space-separated list of information on local, writable file
+ systems. Each item in the list describes one file system and
+ consists in turn of a comma-separated list of the following:
+ </p>
+
+ <ol>
+ <li>Mount point, e.g. <code>/</code> or <code>/var/log</code>.
+ Any spaces or commas in the mount point are replaced by
+ underscores.</li>
+ <li>Total size, in kilobytes, as an integer.</li>
+ <li>Amount of storage in use, in kilobytes, as an integer.</li>
+ </ol>
+
+ <p>
+ This key-value pair is omitted if there are no local, writable
+ file systems or if Open vSwitch cannot obtain the needed
+ information.
+ </p>
+ </dd>
+ </dl>
+ </column>
</group>
</table>
<group title="OpenFlow Configuration">
<column name="controller">
- OpenFlow controller set. If unset, defaults to the set of
- controllers specified by <ref column="controller"
- table="Open_vSwitch"/> in the <ref table="Open_vSwitch"/>
- table. If the default is also unset, then no OpenFlow
- controllers will be used.
+ OpenFlow controller set. If unset, then no OpenFlow controllers
+ will be used.
+ </column>
+
+ <column name="fail_mode">
+ <p>When a controller is configured, it is, ordinarily, responsible
+ for setting up all flows on the switch. Thus, if the connection to
+ the controller fails, no new network connections can be set up.
+ If the connection to the controller stays down long enough,
+ no packets can pass through the switch at all. This setting
+ determines the switch's response to such a situation. It may be set
+ to one of the following:
+ <dl>
+ <dt><code>standalone</code></dt>
+ <dd>If no message is received from the controller for three
+ times the inactivity probe interval
+ (see <ref column="inactivity_probe"/>), then Open vSwitch
+ will take over responsibility for setting up flows. In
+ this mode, Open vSwitch causes the bridge to act like an
+ ordinary MAC-learning switch. Open vSwitch will continue
+ to retry connecting to the controller in the background
+ and, when the connection succeeds, it will discontinue its
+ standalone behavior.</dd>
+ <dt><code>secure</code></dt>
+ <dd>Open vSwitch will not set up flows on its own when the
+ controller connection fails or when no controllers are
+ defined. The bridge will continue to retry connecting to
+ any defined controllers forever.</dd>
+ </dl>
+ </p>
+ <p>If this value is unset, the default is implementation-specific.</p>
+ <p>When more than one controller is configured,
+ <ref column="fail_mode"/> is considered only when none of the
+ configured controllers can be contacted.</p>
</column>
<column name="datapath_id">
</column>
<column name="external_ids">
- Key-value pairs that identify this bridge's role in external systems.
- The currently defined key-value pairs are:
+ Key-value pairs for use by external frameworks that integrate
+ with Open vSwitch, rather than by Open vSwitch itself. System
+ integrators should either use the Open vSwitch development
+ mailing list to coordinate on common key-value definitions, or
+ choose key names that are likely to be unique. The currently
+ defined key-value pairs are:
<dl>
- <dt><code>network-uuids</code></dt>
+ <dt><code>bridge-id</code></dt>
+ <dd>A unique identifier of the bridge. On Citrix XenServer this
+ will commonly be the same as <code>xs-network-uuids</code>.</dd>
+ <dt><code>xs-network-uuids</code></dt>
<dd>Semicolon-delimited set of universally unique identifier(s) for
- the network with which this bridge is associated. The form of the
- identifier(s) depends on the type of the host. On a Citrix
- XenServer host, the network identifiers are RFC 4122 UUIDs as
+ the network with which this bridge is associated on a Citrix
+ XenServer host. The network identifiers are RFC 4122 UUIDs as
displayed by, e.g., <code>xe network-list</code>.</dd>
</dl>
</column>
<p>A bridge port must be configured for VLANs in one of two
mutually exclusive ways:
<ul>
- <li>A ``trunk port'' has an empty value for
- <ref column="tag"/> and a possibly non-empty
- <ref column="trunks"/> value.</li>
+ <li>A ``trunk port'' has an empty value for <ref
+ column="tag"/>. Its <ref column="trunks"/> value may be
+ empty or non-empty.</li>
<li>An ``implicitly tagged VLAN port'' or ``access port''
- has an nonempty value for <ref column="tag"/> and an empty
- <ref column="trunks"/> value.</li>
+ has an nonempty value for <ref column="tag"/>. Its
+ <ref column="trunks"/> value must be empty.</li>
</ul>
If <ref column="trunks"/> and <ref column="tag"/> are both
nonempty, the configuration is ill-formed.
</p>
<column name="tag">
- <p>If nonempty, this port's implicitly tagged VLAN. Frames
- arriving on trunk ports will be forwarded to this port only
- if they are tagged with the given VLAN. Frames arriving on
- other VLAN ports will be forwarded to this port only if they
- have the same <ref column="tag"/> value. Frames forwarded
- to this port will not have an 802.1Q header.</p>
- <p>When a frame with a 802.1Q header that indicates a nonzero VLAN is
- received on an implicit VLAN port, it is discarded.</p>
- <p>Must be empty if this is a trunk port.</p>
+ <p>
+ If this is an access port (see above), the port's implicitly
+ tagged VLAN. Must be empty if this is a trunk port.
+ </p>
+ <p>
+ Frames arriving on trunk ports will be forwarded to this
+ port only if they are tagged with the given VLAN (or, if
+ <ref column="tag"/> is 0, then if they lack a VLAN header).
+ Frames arriving on other access ports will be forwarded to
+ this port only if they have the same <ref column="tag"/>
+ value. Frames forwarded to this port will not have an
+ 802.1Q header.
+ </p>
+ <p>
+ When a frame with a 802.1Q header that indicates a nonzero
+ VLAN is received on an access port, it is discarded.
+ </p>
</column>
<column name="trunks">
- <p>The 802.1Q VLAN(s) that this port trunks. If the column is
- empty, then the port trunks all VLANs as well as packets that
- have no VLAN header. Otherwise, only frames that have an
- 802.1Q header with one of the specified VLANs are accepted.
- If <code>0</code> is included, then frames without an 802.1Q
- header are also accepted.</p>
- <p>Must be empty unless this is a trunk port.</p>
+ <p>
+ If this is a trunk port (see above), the 802.1Q VLAN(s) that
+ this port trunks; if it is empty, then the port trunks all
+ VLANs. Must be empty if this is an access port.
+ </p>
+ <p>
+ Frames arriving on trunk ports are dropped if they are not
+ in one of the specified VLANs. For this purpose, packets
+ that have no VLAN header are treated as part of VLAN 0.
+ </p>
</column>
</group>
</column>
<column name="external_ids">
- Key-value pairs that identify this port's role in external systems. No
- key-value pairs native to <ref table="Port"/> are currently defined.
- For fake bridges (see the <ref column="fake_bridge"/> column), external
- IDs for the fake bridge are defined here by prefixing a
- <ref table="Bridge"/> <ref table="Bridge" column="external_ids"/> key
- with <code>fake-bridge-</code>,
- e.g. <code>fake-bridge-network-uuids</code>.
+ <p>
+ Key-value pairs for use by external frameworks that integrate with
+ Open vSwitch, rather than by Open vSwitch itself. System integrators
+ should either use the Open vSwitch development mailing list to
+ coordinate on common key-value definitions, or choose key names that
+ are likely to be unique.
+ </p>
+ <p>
+ No key-value pairs native to <ref table="Port"/> are currently
+ defined. For fake bridges (see the <ref column="fake_bridge"/>
+ column), external IDs for the fake bridge are defined here by
+ prefixing a <ref table="Bridge"/> <ref table="Bridge"
+ column="external_ids"/> key with <code>fake-bridge-</code>,
+ e.g. <code>fake-bridge-xs-network-uuids</code>.
+ </p>
</column>
<column name="other_config">
<dt><code>tap</code></dt>
<dd>A TUN/TAP device managed by Open vSwitch.</dd>
<dt><code>gre</code></dt>
- <dd>An Ethernet over RFC 1702 Generic Routing Encapsulation over IPv4
+ <dd>An Ethernet over RFC 2890 Generic Routing Encapsulation over IPv4
tunnel. Each tunnel must be uniquely identified by the
combination of <code>remote_ip</code>, <code>local_ip</code>, and
<code>in_key</code>. Note that if two ports are defined that are
the same except one has an optional identifier and the other does
not, the more specific one is matched first. <code>in_key</code>
is considered more specific than <code>local_ip</code> if a port
- defines one and another port defines the other. The arguments
- are:
+ defines one and another port defines the other. The following
+ options may be specified in the <ref column="options"/> column:
<dl>
<dt><code>remote_ip</code></dt>
<dd>Required. The tunnel endpoint.</dd>
either be a 32-bit number or the word <code>flow</code>. If
<code>flow</code> is specified then the key may be set using
the <code>set_tunnel</code> Nicira OpenFlow vendor extension (0
- is used in the absense of an action). The ovs-ofctl manual
+ is used in the absence of an action). The ovs-ofctl manual
page contains additional information about the Nicira OpenFlow
vendor extensions. Default is no key.</dd>
</dl>
</dl>
<dl>
<dt><code>csum</code></dt>
- <dd>Optional. Compute GRE checksums for outgoing packets and
- require checksums for incoming packets. Default is enabled,
- set to <code>false</code> to disable.</dd>
+ <dd>Optional. Compute GRE checksums on outgoing packets.
+ Checksums present on incoming packets will be validated
+ regardless of this setting. Note that GRE checksums
+ impose a significant performance penalty as they cover the
+ entire packet. As the contents of the packet is typically
+ covered by L3 and L4 checksums, this additional checksum only
+ adds value for the GRE and encapsulated Ethernet headers.
+ Default is disabled, set to <code>true</code> to enable.</dd>
</dl>
<dl>
<dt><code>pmtud</code></dt>
compliance with the IEEE 802.1D specification for bridges.
Default is enabled, set to <code>false</code> to disable.</dd>
</dl>
+ <dl>
+ <dt><code>header_cache</code></dt>
+ <dd>Optional. 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 IP tables)
+ 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. If IPsec is enabled through the
+ <ref column="other_config"/> parameters, header caching will be
+ automatically disabled.</dd>
+ </dl>
+ </dd>
+ <dt><code>capwap</code></dt>
+ <dd>Ethernet tunneling over the UDP transport portion of CAPWAP
+ (RFC 5415). This allows interoperability with certain switches
+ where GRE is not available. Note that only the tunneling component
+ of the protocol is implemented. Due to the non-standard use of
+ CAPWAP, UDP ports 58881 and 58882 are used as the source and
+ destinations ports respectivedly. Each tunnel must be uniquely
+ identified by the combination of <code>remote_ip</code> and
+ <code>local_ip</code>. If two ports are defined that are the same
+ except one includes <code>local_ip</code> and the other does not,
+ the more specific one is matched first. CAPWAP support is not
+ available on all platforms. Currently it is only supported in the
+ Linux kernel module with kernel versions >= 2.6.25. The following
+ options may be specified in the <ref column="options"/> column:
+ <dl>
+ <dt><code>remote_ip</code></dt>
+ <dd>Required. The tunnel endpoint.</dd>
+ </dl>
+ <dl>
+ <dt><code>local_ip</code></dt>
+ <dd>Optional. The destination IP that received packets must
+ match. Default is to match all addresses.</dd>
+ </dl>
+ <dl>
+ <dt><code>tos</code></dt>
+ <dd>Optional. The value of the ToS bits to be set on the
+ encapsulating packet. It may also be the word
+ <code>inherit</code>, in which case the ToS will be copied from
+ the inner packet if it is IPv4 or IPv6 (otherwise it will be
+ 0). Note that the ECN fields are always inherited. Default is
+ 0.</dd>
+ </dl>
+ <dl>
+ <dt><code>ttl</code></dt>
+ <dd>Optional. The TTL to be set on the encapsulating packet.
+ It may also be the word <code>inherit</code>, in which case the
+ TTL will be copied from the inner packet if it is IPv4 or IPv6
+ (otherwise it will be the system default, typically 64).
+ Default is the system default TTL.</dd>
+ </dl>
+ <dl>
+ <dt><code>pmtud</code></dt>
+ <dd>Optional. Enable tunnel path MTU discovery. If enabled
+ ``ICMP destination unreachable - fragmentation'' needed
+ messages will be generated for IPv4 packets with the DF bit set
+ and IPv6 packets above the minimum MTU if the packet size
+ exceeds the path MTU minus the size of the tunnel headers. It
+ also forces the encapsulating packet DF bit to be set (it is
+ always set if the inner packet implies path MTU discovery).
+ Note that this option causes behavior that is typically
+ reserved for routers and therefore is not entirely in
+ compliance with the IEEE 802.1D specification for bridges.
+ Default is enabled, set to <code>false</code> to disable.</dd>
+ </dl>
+ <dl>
+ <dt><code>header_cache</code></dt>
+ <dd>Optional. 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 IP tables)
+ 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.</dd>
+ </dl>
</dd>
<dt><code>patch</code></dt>
- <dd>A pair of virtual devices that act as a patch cable. A
- <code>peer</code> argument is required that indicates the name
- of the other side of the patch. Since a patch must work in
- pairs, a second patch interface must be declared with the
- <code>name</code> and <code>peer</code> arguments reversed.</dd>
+ <dd>
+ <p>
+ A pair of virtual devices that act as a patch cable. The <ref
+ column="options"/> column must have the following key-value pair:
+ </p>
+ <dl>
+ <dt><code>peer</code></dt>
+ <dd>
+ 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.
+ </dd>
+ </dl>
+ </dd>
</dl>
</column>
Configuration options whose interpretation varies based on
<ref column="type"/>.
</column>
+
+ <column name="status">
+ <p>
+ Key-value pairs that report port status. Supported status
+ values are <code>type</code>-dependent.
+ </p>
+ <p>The only currently defined key-value pair is:</p>
+ <dl>
+ <dt><code>source_ip</code></dt>
+ <dd>The source IP address used for an IPv4 tunnel end-point,
+ such as <code>gre</code> or <code>capwap</code>. Not
+ supported by all implementations.</dd>
+ </dl>
+ </column>
</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>The burst size should be at least the size of the interface's
- MTU.</p>
- </column>
-
- <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> to
- disable policing.</p>
- <p>The meaning of ``ingress'' is from Open vSwitch's perspective. If
- configured on a physical interface, then it limits the rate at which
- traffic is allowed into the system from the outside. If configured
- on a virtual interface that is connected to a virtual machine, then
- it limits the rate at which the guest is able to transmit.</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="Other Features">
<column name="external_ids">
- <p>Key-value pairs that identify this interface's role in external
- systems. All of the currently defined key-value pairs specifically
+ Key-value pairs for use by external frameworks that integrate
+ with Open vSwitch, rather than by Open vSwitch itself. System
+ integrators should either use the Open vSwitch development
+ mailing list to coordinate on common key-value definitions, or
+ choose key names that are likely to be unique. The currently
+ defined common key-value pairs are:
+ <dl>
+ <dt><code>attached-mac</code></dt>
+ <dd>
+ 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.</dd>
+ <dt><code>iface-id</code></dt>
+ <dd>A system-unique identifier for the interface. On XenServer,
+ this will commonly be the same as <code>xs-vif-uuid</code>.</dd>
+ </dl>
+ <p>
+ Additionally the following 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>
- <p>The currently defined key-value pairs are:</p>
+ formats.
+ </p>
+ <p>The currently defined key-value pairs for XenServer are:</p>
<dl>
- <dt><code>vif-uuid</code></dt>
+ <dt><code>xs-vif-uuid</code></dt>
<dd>The virtual interface associated with this interface.</dd>
- <dt><code>network-uuid</code></dt>
+ <dt><code>xs-network-uuid</code></dt>
<dd>The virtual network to which this interface is attached.</dd>
- <dt><code>vm-uuid</code></dt>
+ <dt><code>xs-vm-uuid</code></dt>
<dd>The VM to which this interface belongs.</dd>
- <dt><code>vif-mac</code></dt>
- <dd>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.</dd>
</dl>
</column>
+
+ <column name="other_config">
+ Key-value pairs for rarely used interface features. Currently,
+ the only keys are for configuring GRE-over-IPsec, which is only
+ available through the <code>openvswitch-ipsec</code> package for
+ Debian. The currently defined key-value pairs are:
+ <dl>
+ <dt><code>ipsec_local_ip</code></dt>
+ <dd>Required key for GRE-over-IPsec interfaces. Additionally,
+ the <ref column="type"/> must be <code>gre</code> and the
+ <code>ipsec_psk</code> <ref column="other_config"/> key must
+ be set. The <code>in_key</code>, <code>out_key</code>, and
+ <code>key</code> <ref column="options"/> must not be
+ set.</dd>
+ <dt><code>ipsec_psk</code></dt>
+ <dd>Required key for GRE-over-IPsec interfaces. Specifies a
+ pre-shared key for authentication that must be identical on
+ both sides of the tunnel. Additionally, the
+ <code>ipsec_local_ip</code> key must also be set.</dd>
+ </dl>
+ </column>
+
+ <column name="statistics">
+ <p>
+ Key-value pairs that report interface statistics. The current
+ implementation updates these counters periodically. In the future,
+ we plan to, instead, 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>
+ The currently defined key-value pairs are listed below. 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>
+ <ul>
+ <li>
+ Successful transmit and receive counters:
+ <dl>
+ <dt><code>rx_packets</code></dt>
+ <dd>Number of received packets.</dd>
+ <dt><code>rx_bytes</code></dt>
+ <dd>Number of received bytes.</dd>
+ <dt><code>tx_packets</code></dt>
+ <dd>Number of transmitted packets.</dd>
+ <dt><code>tx_bytes</code></dt>
+ <dd>Number of transmitted bytes.</dd>
+ </dl>
+ </li>
+ <li>
+ Receive errors:
+ <dl>
+ <dt><code>rx_dropped</code></dt>
+ <dd>Number of packets dropped by RX.</dd>
+ <dt><code>rx_frame_err</code></dt>
+ <dd>Number of frame alignment errors.</dd>
+ <dt><code>rx_over_err</code></dt>
+ <dd>Number of packets with RX overrun.</dd>
+ <dt><code>rx_crc_err</code></dt>
+ <dd>Number of CRC errors.</dd>
+ <dt><code>rx_errors</code></dt>
+ <dd>
+ Total number of receive errors, greater than or equal
+ to the sum of the above.
+ </dd>
+ </dl>
+ </li>
+ <li>
+ Transmit errors:
+ <dl>
+ <dt><code>tx_dropped</code></dt>
+ <dd>Number of packets dropped by TX.</dd>
+ <dt><code>collisions</code></dt>
+ <dd>Number of collisions.</dd>
+ <dt><code>tx_errors</code></dt>
+ <dd>
+ Total number of transmit errors, greater
+ than or equal to the sum of the above.
+ </dd>
+ </dl>
+ </li>
+ </ul>
+ </column>
</group>
</table>
defined types are listed below:</p>
<dl>
<dt><code>linux-htb</code></dt>
- <dd>Linux ``hierarchy token bucket'' classifier.</dd>
+ <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>
</column>
Mbps.</dd>
</dl>
</column>
+
+ <column name="external_ids">
+ Key-value pairs for use by external frameworks that integrate with Open
+ vSwitch, rather than by Open vSwitch itself. System integrators should
+ either use the Open vSwitch development mailing list to coordinate on
+ common key-value definitions, or choose key names that are likely to be
+ unique. No common key-value pairs are currently defined.
+ </column>
</table>
<table name="Queue" title="QoS output queue.">
values are unimportant; only relative ordering matters.</dd>
</dl>
</column>
+
+ <column name="external_ids">
+ Key-value pairs for use by external frameworks that integrate with Open
+ vSwitch, rather than by Open vSwitch itself. System integrators should
+ either use the Open vSwitch development mailing list to coordinate on
+ common key-value definitions, or choose key names that are likely to be
+ unique. No common key-value pairs are currently defined.
+ </column>
</table>
<table name="Mirror" title="Port mirroring (SPAN/RSPAN).">
in the appropriate <ref table="Bridge"/> table or tables.</p>
</column>
</group>
+
+ <group title="Other Features">
+ <column name="external_ids">
+ Key-value pairs for use by external frameworks that integrate with Open
+ vSwitch, rather than by Open vSwitch itself. System integrators should
+ either use the Open vSwitch development mailing list to coordinate on
+ common key-value definitions, or choose key names that are likely to be
+ unique. No common key-value pairs are currently defined.
+ </column>
+ </group>
</table>
<table name="Controller" title="OpenFlow controller configuration.">
<p>An OpenFlow controller.</p>
- <p>Open vSwitch permits a bridge to have any number of OpenFlow
- controllers. When multiple controllers are configured, Open vSwitch
- connects to all of them simultaneously. OpenFlow 1.0 does not specify
- how multiple controllers coordinate in interacting with a single switch,
- so more than one controller should be specified only if the controllers
- are themselves designed to coordinate with each other.</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.
- The following connection methods are currently
- supported:</p>
+ <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"/> must point to a valid
- SSL configuration when this form is used.</p>
+ 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>
<p>SSL support is an optional feature that is not always built as
part of Open vSwitch.</p>
</dd>
used only for bootstrapping the OpenFlow PKI at initial switch
setup; <code>ovs-vswitchd</code> does not use it at all.</p>
</dd>
- <dt><code>none</code></dt>
- <dd>Disables the controller.</dd>
</dl>
- <p>When multiple controllers are configured for a single bridge, the
- <ref column="target"/> values must be unique. Duplicate
- <ref column="target"/> values yield unspecified results.</p>
+ <p>
+ The following connection methods are currently supported for service
+ controllers:
+ </p>
+ <dl>
+ <dt><code>pssl:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
+ <dd>
+ <p>
+ Listens for SSL connections on the specified TCP <var>port</var>
+ (default: 6633). If <var>ip</var>, which must be expressed as an
+ IP address (not a DNS name), is specified, then connections are
+ restricted to the specified local IP address.
+ </p>
+ <p>
+ 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>
+ <p>SSL support is an optional feature that is not always built as
+ part of Open vSwitch.</p>
+ </dd>
+ <dt><code>ptcp:</code>[<var>port</var>][<code>:<var>ip</var></code>]</dt>
+ <dd>
+ Listens for connections on the specified TCP <var>port</var>
+ (default: 6633). If <var>ip</var>, which must be expressed as an
+ IP address (not a DNS name), is specified, then connections are
+ restricted to the specified local IP address.
+ </dd>
+ </dl>
+ <p>When multiple controllers are configured for a single bridge, the
+ <ref column="target"/> values must be unique. Duplicate
+ <ref column="target"/> values yield unspecified results.</p>
</column>
<column name="connection_mode">
- <p>If it is specified, this setting must be one of the following
- strings that describes how Open vSwitch contacts this OpenFlow
- controller over the network:</p>
-
- <dl>
- <dt><code>in-band</code></dt>
- <dd>In this mode, this controller's OpenFlow traffic travels over the
- bridge associated with the controller. With this setting, Open
- vSwitch allows traffic to and from the controller regardless of the
- contents of the OpenFlow flow table. (Otherwise, Open vSwitch
- would never be able to connect to the controller, because it did
- not have a flow to enable it.) This is the most common connection
- mode because it is not necessary to maintain two independent
- networks.</dd>
- <dt><code>out-of-band</code></dt>
- <dd>In this mode, OpenFlow traffic uses a control network separate
- from the bridge associated with this controller, that is, the
- bridge does not use any of its own network devices to communicate
- with the controller. The control network must be configured
- separately, before or after <code>ovs-vswitchd</code> is started.
- </dd>
- </dl>
+ <p>If it is specified, this setting must be one of the following
+ strings that describes how Open vSwitch contacts this OpenFlow
+ controller over the network:</p>
+
+ <dl>
+ <dt><code>in-band</code></dt>
+ <dd>In this mode, this controller's OpenFlow traffic travels over the
+ bridge associated with the controller. With this setting, Open
+ vSwitch allows traffic to and from the controller regardless of the
+ contents of the OpenFlow flow table. (Otherwise, Open vSwitch
+ would never be able to connect to the controller, because it did
+ not have a flow to enable it.) This is the most common connection
+ mode because it is not necessary to maintain two independent
+ networks.</dd>
+ <dt><code>out-of-band</code></dt>
+ <dd>In this mode, OpenFlow traffic uses a control network separate
+ from the bridge associated with this controller, that is, the
+ bridge does not use any of its own network devices to communicate
+ with the controller. The control network must be configured
+ separately, before or after <code>ovs-vswitchd</code> is started.
+ </dd>
+ </dl>
<p>If not specified, the default is implementation-specific. If
<ref column="target"/> is <code>discover</code>, the connection mode
assumes the connection has been broken and attempts to reconnect.
Default is implementation-specific.
</column>
-
- <column name="fail_mode">
- <p>When a controller is configured, it is, ordinarily, responsible
- for setting up all flows on the switch. Thus, if the connection to
- the controller fails, no new network connections can be set up.
- If the connection to the controller stays down long enough,
- no packets can pass through the switch at all. This setting
- determines the switch's response to such a situation. It may be set
- to one of the following:
- <dl>
- <dt><code>standalone</code></dt>
- <dd>If no message is received from the controller for three
- times the inactivity probe interval
- (see <ref column="inactivity_probe"/>), then Open vSwitch
- will take over responsibility for setting up flows. In
- this mode, Open vSwitch causes the bridge to act like an
- ordinary MAC-learning switch. Open vSwitch will continue
- to retry connecting to the controller in the background
- and, when the connection succeeds, it will discontinue its
- standalone behavior.</dd>
- <dt><code>secure</code></dt>
- <dd>Open vSwitch will not set up flows on its own when the
- controller connection fails. It will continue retry
- connecting to the controller forever.</dd>
- </dl>
- </p>
- <p>If this value is unset, the default is implementation-specific.</p>
- <p>When more than one controller is configured,
- <ref column="fail_mode"/> is considered only when none of the
- configured controllers can be contacted. At that point, the bridge
- enters secure mode if any of the controllers'
- <ref column="fail_mode"/> is set to <code>secure</code>. Otherwise,
- it enters standalone mode if at least one <ref column="fail_mode"/>
- is set to <code>standalone</code>. If none of the
- <ref column="fail_mode"/> values are set, the default is
- implementation-defined.</p>
- </column>
</group>
<group title="OpenFlow Rate Limiting">
<group title="Additional Discovery Configuration">
<p>These values are considered only when <ref column="target"/>
- is <code>discover</code>.</p>
+ is <code>discover</code>.</p>
<column name="discover_accept_regex">
A POSIX
<group title="Additional In-Band Configuration">
<p>These values are considered only in in-band control mode (see
- <ref column="connection_mode"/>) and only when <ref column="target"/>
- is not <code>discover</code>. (For controller discovery, the network
- configuration obtained via DHCP is used instead.)</p>
+ <ref column="connection_mode"/>) and only when <ref column="target"/>
+ is not <code>discover</code>. (For controller discovery, the network
+ configuration obtained via DHCP is used instead.)</p>
<p>When multiple controllers are configured on a single bridge, there
- should be only one set of unique values in these columns. If different
- values are set for these columns in different controllers, the effect
- is unspecified.</p>
+ should be only one set of unique values in these columns. If different
+ values are set for these columns in different controllers, the effect
+ is unspecified.</p>
<column name="local_ip">
The IP address to configure on the local port,
this network has no gateway.
</column>
</group>
+
+ <group title="Other Features">
+ <column name="external_ids">
+ Key-value pairs for use by external frameworks that integrate with Open
+ vSwitch, rather than by Open vSwitch itself. System integrators should
+ either use the Open vSwitch development mailing list to coordinate on
+ common key-value definitions, or choose key names that are likely to be
+ unique. No common key-value pairs are currently defined.
+ </column>
+ </group>
</table>
<table name="NetFlow">
disambiguate the traffic.</p>
<p>When this option is enabled, a maximum of 508 ports are supported.</p>
</column>
+
+ <column name="external_ids">
+ Key-value pairs for use by external frameworks that integrate with Open
+ vSwitch, rather than by Open vSwitch itself. System integrators should
+ either use the Open vSwitch development mailing list to coordinate on
+ common key-value definitions, or choose key names that are likely to be
+ unique. No common key-value pairs are currently defined.
+ </column>
</table>
<table name="SSL">
SSL connection to a man-in-the-middle attack obtaining the initial
CA certificate.</em> It may still be useful for bootstrapping.
</column>
+
+ <column name="external_ids">
+ Key-value pairs for use by external frameworks that integrate with Open
+ vSwitch, rather than by Open vSwitch itself. System integrators should
+ either use the Open vSwitch development mailing list to coordinate on
+ common key-value definitions, or choose key names that are likely to be
+ unique. No common key-value pairs are currently defined.
+ </column>
</table>
<table name="sFlow">
sFlow targets in the form
<code><var>ip</var>:<var>port</var></code>.
</column>
+
+ <column name="external_ids">
+ Key-value pairs for use by external frameworks that integrate with Open
+ vSwitch, rather than by Open vSwitch itself. System integrators should
+ either use the Open vSwitch development mailing list to coordinate on
+ common key-value definitions, or choose key names that are likely to be
+ unique. No common key-value pairs are currently defined.
+ </column>
</table>
<table name="Capability">