A database with this schema holds the configuration for one Open
vSwitch daemon. The root of the configuration for the daemon is
@@ -25,14 +26,27 @@
- 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:
-
system-uuid
-
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., xe host-list.
+
system-type
+
An identifier for the switch type, such as
+ XenServer or KVM.
+
system-version
+
The version of the switch software, such as
+ 5.6.0 on XenServer.
+
system-id
+
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
+ xs-system-uuid.
+
xs-system-uuid
+
The Citrix XenServer universally unique identifier for the
+ physical host as displayed by xe host-list.
@@ -61,21 +75,133 @@
- Key-value pairs that report statistics about a running Open_vSwitch
- daemon. The current implementation updates these counters
- periodically. In the future, we plan to, instead, update them only
- when they are queried (e.g. using an OVSDB select
- operation) and perhaps at other times, but not on any regular
- periodic basis.
-
- The currently defined key-value pairs are listed below. Some Open
- vSwitch implementations may not support some statistics, in which
- case those key-value pairs are omitted.
+ 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.
+
+
-
load-average
+
cpu
+
+
+ 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.
+
+
+ Open vSwitch userspace processes are not multithreaded, but the
+ Linux kernel-based datapath is.
+
+
+
+
load_average
+
+
+ A comma-separated list of three floating-point numbers,
+ representing the system load average over the last 1, 5, and 15
+ minutes, respectively.
+
+
+
+
memory
+
+
+ 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:
+
+
+
+
Total amount of RAM allocated to the OS.
+
RAM allocated to the OS that is in use.
+
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.
+
Total disk space allocated for swap.
+
Swap space currently in use.
+
+
+
+ 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.
+
+
+
+
process_name
+
+
+ One such key-value pair will exist for each running Open vSwitch
+ daemon process, with name replaced by the daemon's
+ name (e.g. process_ovs-vswitchd). The value is a
+ comma-separated list of integers. The integers represent the
+ following, with memory measured in kilobytes and durations in
+ milliseconds:
+
+
+
+
The process's virtual memory size.
+
The process's resident set size.
+
The amount of user and system CPU time consumed by the
+ process.
+
The number of times that the process has crashed and been
+ automatically restarted by the monitor.
+
The duration since the process was started.
+
The duration for which the process has been running.
+
+
+
+ The interpretation of some of these values depends on whether the
+ process was started with the . If it
+ was not, then the crash count will always be 0 and the two
+ durations will always be the same. If
+ 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.
+
+
+
+ There will be one key-value pair for each file in Open vSwitch's
+ ``run directory'' (usually /var/run/openvswitch)
+ whose name ends in .pid, whose contents are a
+ process ID, and which is locked by a running process. The
+ name is taken from the pidfile's name.
+
+
+
+ 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.
+
+
+
+
file_systems
- System load average multiplied by 100 and rounded to the nearest
- integer.
+
+ 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:
+
+
+
+
Mount point, e.g. / or /var/log.
+ Any spaces or commas in the mount point are replaced by
+ underscores.
+
Total size, in kilobytes, as an integer.
+
Amount of storage in use, in kilobytes, as an integer.
+
+
+
+ This key-value pair is omitted if there are no local, writable
+ file systems or if Open vSwitch cannot obtain the needed
+ information.
+
+
@@ -151,8 +277,9 @@
standalone behavior.
secure
Open vSwitch will not set up flows on its own when the
- controller connection fails. It will continue retry
- connecting to the controller forever.
+ controller connection fails or when no controllers are
+ defined. The bridge will continue to retry connecting to
+ any defined controllers forever.
If this value is unset, the default is implementation-specific.
@@ -177,14 +304,20 @@
- 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:
-
network-uuids
+
bridge-id
+
A unique identifier of the bridge. On Citrix XenServer this
+ will commonly be the same as xs-network-uuids.
+
xs-network-uuids
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., xe network-list.
@@ -331,13 +464,21 @@
- Key-value pairs that identify this port's role in external systems. No
- key-value pairs native to are currently defined.
- For fake bridges (see the column), external
- IDs for the fake bridge are defined here by prefixing a
- key
- with fake-bridge-,
- e.g. fake-bridge-network-uuids.
+
+ 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 key-value pairs native to are currently
+ defined. For fake bridges (see the
+ column), external IDs for the fake bridge are defined here by
+ prefixing a key with fake-bridge-,
+ e.g. fake-bridge-xs-network-uuids.
+
@@ -425,15 +566,15 @@
tap
A TUN/TAP device managed by Open vSwitch.
gre
-
An Ethernet over RFC 1702 Generic Routing Encapsulation over IPv4
+
An Ethernet over RFC 2890 Generic Routing Encapsulation over IPv4
tunnel. Each tunnel must be uniquely identified by the
combination of remote_ip, local_ip, and
in_key. 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. in_key
is considered more specific than local_ip 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 column:
remote_ip
Required. The tunnel endpoint.
@@ -460,7 +601,7 @@
either be a 32-bit number or the word flow. If
flow is specified then the key may be set using
the set_tunnel 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.
@@ -488,9 +629,80 @@
csum
-
Optional. Compute GRE checksums for outgoing packets and
- require checksums for incoming packets. Default is enabled,
- set to false to disable.
+
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 true to enable.
+
+
+
pmtud
+
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 false to disable.
+
+
+
header_cache
+
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
+ false to disable.
+
+
+
capwap
+
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 remote_ip and
+ local_ip. If two ports are defined that are the same
+ except one includes local_ip 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 column:
+
+
remote_ip
+
Required. The tunnel endpoint.
+
+
+
local_ip
+
Optional. The destination IP that received packets must
+ match. Default is to match all addresses.
+
+
+
tos
+
Optional. The value of the ToS bits to be set on the
+ encapsulating packet. It may also be the word
+ inherit, 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.
+
+
+
ttl
+
Optional. The TTL to be set on the encapsulating packet.
+ It may also be the word inherit, 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.
pmtud
@@ -506,13 +718,36 @@
compliance with the IEEE 802.1D specification for bridges.
Default is enabled, set to false to disable.
+
+
header_cache
+
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
+ false to disable.
+
patch
-
A pair of virtual devices that act as a patch cable. A
- peer 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
- name and peer arguments reversed.
+
+
+ A pair of virtual devices that act as a patch cable. The column must have the following key-value pair:
+
+
+
peer
+
+ The of the for
+ the other side of the patch. The named 's own peer option must specify
+ this 's name. That is, the two patch
+ interfaces must have reversed and
+ peer values.
+
+
+
@@ -520,55 +755,157 @@
Configuration options whose interpretation varies based on
.
+
+
+
+ Key-value pairs that report port status. Supported status
+ values are type-dependent.
+
+
The only currently defined key-value pair is:
+
+
source_ip
+
The source IP address used for an IPv4 tunnel end-point,
+ such as gre or capwap. Not
+ supported by all implementations.
+
+
+
+ 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.
+
+
+ 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 and tables).
+
+
+ Policing is currently implemented only on Linux. The Linux
+ implementation uses a simple ``token bucket'' approach:
+
+
+
+ The size of the bucket corresponds to . Initially the bucket is full.
+
+
+ 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.
+
+
+ Whenever it is not full, the bucket is refilled with tokens at the
+ rate specified by .
+
+
+
+ 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.
+
+
+
+ Maximum rate for data received on this interface, in kbps. Data
+ received faster than this rate is dropped. Set to 0
+ (the default) to disable policing.
+
+
+
Maximum burst size for data received on this interface, in kb. The
default burst size if set to 0 is 1000 kb. This value
has no effect if
is 0.
-
The burst size should be at least the size of the interface's
- MTU.
-
-
-
-
Maximum rate for data received on this interface, in kbps. Data
- received faster than this rate is dropped. Set to 0 to
- disable policing.
-
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.
+
+ 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 helps TCP come
+ closer to achieving the full rate.
+
-
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:
+
+
attached-mac
+
+ The MAC address programmed into the ``virtual hardware'' for this
+ interface, in the form
+ xx:xx:xx:xx:xx:xx.
+ For Citrix XenServer, this is the value of the MAC
+ field in the VIF record for this interface.
+
iface-id
+
A system-unique identifier for the interface. On XenServer,
+ this will commonly be the same as xs-vif-uuid.
+
+
+ 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 -uuid 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.
-
The currently defined key-value pairs are:
+ formats.
+
+
The currently defined key-value pairs for XenServer are:
-
vif-uuid
+
xs-vif-uuid
The virtual interface associated with this interface.
-
network-uuid
+
xs-network-uuid
The virtual network to which this interface is attached.
-
vm-uuid
+
xs-vm-uuid
The VM to which this interface belongs.
-
vif-mac
-
The MAC address programmed into the "virtual hardware" for this
- interface, in the
- form xx:xx:xx:xx:xx:xx.
- For Citrix XenServer, this is the value of the MAC
- field in the VIF record for this interface.
+
+
+
+
+ Key-value pairs for rarely used interface features. Currently,
+ the only keys are for configuring GRE-over-IPsec, which is only
+ available through the openvswitch-ipsec package for
+ Debian. The currently defined key-value pairs are:
+
+
ipsec_local_ip
+
Required key for GRE-over-IPsec interfaces. Additionally,
+ the must be gre and the
+ ipsec_psk key must
+ be set. The in_key, out_key, and
+ key must not be
+ set.
+
ipsec_psk
+
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
+ ipsec_local_ip key must also be set.
@@ -648,7 +985,12 @@
defined types are listed below:
linux-htb
-
Linux ``hierarchy token bucket'' classifier.
+
+ Linux ``hierarchy token bucket'' classifier. See tc-htb(8) (also at
+ http://linux.die.net/man/8/tc-htb) and the HTB manual
+ (http://luxik.cdi.cz/~devik/qos/htb/manual/userg.htm)
+ for information on how this classifier works and how to configure it.
+
@@ -675,6 +1017,14 @@
Mbps.
+
+
+ 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.
+
@@ -716,6 +1066,14 @@
values are unimportant; only relative ordering matters.
+
+
+ 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.
+
@@ -797,31 +1155,95 @@
in the appropriate table or tables.
+
+
+
+ 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.
+
+
An OpenFlow controller.
-
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.
+
+ Open vSwitch supports two kinds of OpenFlow controllers:
+
+
+
+
Primary controllers
+
+
+ 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.
+
+
+
+ Open vSwitch initiates and maintains persistent connections to
+ primary controllers, retrying the connection each time it fails or
+ drops. The column in the
+ table applies to primary controllers.
+
+
+
+ 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 NXT_ROLE OpenFlow
+ vendor extension may be useful for this.)
+
+
+
Service controllers
+
+
+ These kinds of OpenFlow controller connections are intended for
+ occasional support and maintenance use, e.g. with
+ ovs-ofctl. Usually a service controller connects only
+ briefly to inspect or modify some of a switch's state.
+
+
+
+ Open vSwitch listens for incoming connections from service
+ controllers. The service controllers initiate and, if necessary,
+ maintain the connections from their end. The column in the table does
+ not apply to service controllers.
+
+
+
+ Open vSwitch supports configuring any number of service controllers.
+
+
+
+
+
+ The determines the type of controller.
+
-
Connection method for controller.
- The following connection methods are currently
- supported:
+
Connection method for controller.
+
+ The following connection methods are currently supported for primary
+ controllers:
+
ssl:ip[:port]
The specified SSL port (default: 6633) on the host at
- the given ip, which must be expressed as an IP address
- (not a DNS name). The
- column in the must point to a valid
- SSL configuration when this form is used.
+ the given ip, which must be expressed as an IP address
+ (not a DNS name). The
+ column in the table must point to a
+ valid SSL configuration when this form is used.
SSL support is an optional feature that is not always built as
part of Open vSwitch.
@@ -846,8 +1268,35 @@
used only for bootstrapping the OpenFlow PKI at initial switch
setup; ovs-vswitchd does not use it at all.
-
none
-
Disables the controller.
+
+
+ The following connection methods are currently supported for service
+ controllers:
+
+
+
pssl:[port][:ip]
+
+
+ Listens for SSL connections on the specified TCP port
+ (default: 6633). If ip, which must be expressed as an
+ IP address (not a DNS name), is specified, then connections are
+ restricted to the specified local IP address.
+
+
+ The column in the table must point to a valid SSL
+ configuration when this form is used.
+
+
SSL support is an optional feature that is not always built as
+ part of Open vSwitch.
+
+
ptcp:[port][:ip]
+
+ Listens for connections on the specified TCP port
+ (default: 6633). If ip, which must be expressed as an
+ IP address (not a DNS name), is specified, then connections are
+ restricted to the specified local IP address.
+
When multiple controllers are configured for a single bridge, the
values must be unique. Duplicate
@@ -984,6 +1433,16 @@
this network has no gateway.
+
+
+
+ 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.
+
+
@@ -1025,6 +1484,14 @@
disambiguate the traffic.
When this option is enabled, a maximum of 508 ports are supported.
+
+
+ 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.
+
@@ -1057,6 +1524,14 @@
SSL connection to a man-in-the-middle attack obtaining the initial
CA certificate. It may still be useful for bootstrapping.
+
+
+ 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.
+
@@ -1091,6 +1566,14 @@
sFlow targets in the form
ip:port.
+
+
+ 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.
+