+<?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="managers">
- Remote database clients to which the Open vSwitch's database server
- should connect or to which it should listen.
- </column>
-
<column name="ssl">
SSL used globally by the daemon.
</column>
<column name="statistics">
<p>
- 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 <code>select</code>
- operation) and perhaps at other times, but not on any regular
- periodic basis.</p>
- <p>
- 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.</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>load-average</code></dt>
+ <dt><code>cpu</code></dt>
<dd>
- System load average multiplied by 100 and rounded to the nearest
- integer.</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>
+
+ <group title="Database Configuration">
+ <p>
+ These columns primarily configure the Open vSwitch database
+ (<code>ovsdb-server</code>), not the Open vSwitch switch
+ (<code>ovs-vswitchd</code>). The OVSDB database also uses the <ref
+ column="ssl"/> settings.
+ </p>
+
+ <p>
+ The Open vSwitch switch does read the database configuration to
+ determine remote IP addresses to which in-band control should apply.
+ </p>
+
+ <column name="manager_options">
+ Database clients to which the Open vSwitch database server should
+ connect or to which it should listen, along with options for how these
+ connection should be configured. See the <ref table="Manager"/> table
+ for more information.
+ </column>
+
+ <column name="managers">
+ <p>
+ Remote database clients to which the Open vSwitch's database server
+ should connect or to which it should listen. Adding an OVSDB target
+ to this set is equivalent to adding it to <ref
+ column="manager_options"/> with all of the default options.
+ </p>
+
+ <p>
+ Use of this column is deprecated and may be removed sometime in the
+ future. New applications should use and set <ref
+ column="manager_options"/> instead.
+ </p>
+ </column>
+ </group>
</table>
<table name="Bridge">
<dt><code>datapath-id</code></dt>
<dd>Exactly 16 hex
digits to set the OpenFlow datapath ID to a specific
- value.</dd>
+ value. May not be all-zero.</dd>
+ <dt><code>disable-in-band</code></dt>
+ <dd>If set to <code>true</code>, disable in-band control on
+ the bridge regardless of controller and manager settings.</dd>
<dt><code>hwaddr</code></dt>
<dd>An Ethernet address in the form
<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>:<var>xx</var>
to set the hardware address of the local port and influence the
datapath ID.</dd>
+ <dt><code>in-band-queue</code></dt>
+ <dd>
+ A queue ID as a nonnegative integer. This sets the OpenFlow queue
+ ID that will be used by flows set up by in-band control on this
+ bridge. If unset, or if the port used by an in-band control flow
+ does not have QoS configured, or if the port does not have a queue
+ with the specified ID, the default queue is used instead.
+ </dd>
</dl>
</column>
</group>
<p>Open vSwitch populates this column when the port number becomes
known. If the interface is successfully added,
<ref column="ofport"/> will be set to a number between 1 and 65535
- (generally either in the range 1 to 65280, exclusive, or 65534, the
+ (generally either in the range 1 to 65279, inclusive, or 65534, the
port number for the OpenFlow ``local port''). If the interface
cannot be added then Open vSwitch sets this column
to -1.</p>
<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>
+ 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>
<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>
+ 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>
</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
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">
<column name="other_config">
<p>Key-value pairs for configuring QoS features that depend on
<ref column="type"/>.</p>
- <p>The <code>linux-htb</code> class supports the following key-value
- pairs:</p>
+ <p>The <code>linux-htb</code> and <code>linux-hfsc</code> classes support
+ the following key-value pairs:</p>
<dl>
<dt><code>max-rate</code></dt>
<dd>Maximum rate shared by all queued traffic, in bit/s.
column="type"/> of <code>min-rate</code> are:</p>
<dl>
<dt><code>min-rate</code></dt>
- <dd>Minimum guaranteed bandwidth, in bit/s. Required.</dd>
+ <dd>Minimum guaranteed bandwidth, in bit/s. Required. The
+ floor value is 1500 bytes/s (12,000 bit/s).</dd>
</dl>
<p>The key-value pairs defined for <ref table="QoS"/> <ref table="QoS"
column="type"/> of <code>linux-htb</code> are:</p>
a queue with a larger value receives any. Specific priority
values are unimportant; only relative ordering matters.</dd>
</dl>
+ <p>The key-value pairs defined for <ref table="QoS"/> <ref table="QoS"
+ column="type"/> of <code>linux-hfsc</code> are:</p>
+ <dl>
+ <dt><code>min-rate</code></dt>
+ <dd>Minimum guaranteed bandwidth, in bit/s. Required.</dd>
+ <dt><code>max-rate</code></dt>
+ <dd>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.</dd>
+ </dl>
</column>
<column name="external_ids">
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>
+
<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>
+
+ <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
<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,
</group>
</table>
+ <table name="Manager" title="OVSDB management connection.">
+ <p>
+ Configuration for a database connection to an Open vSwitch database
+ (OVSDB) client.
+ </p>
+
+ <p>
+ This table primarily configures the Open vSwitch database
+ (<code>ovsdb-server</code>), not the Open vSwitch switch
+ (<code>ovs-vswitchd</code>). The switch does read the table to determine
+ what connections should be treated as in-band.
+ </p>
+
+ <p>
+ The Open vSwitch database server can initiate and maintain active
+ connections to remote clients. It can also listen for database
+ connections.
+ </p>
+
+ <group title="Core Features">
+ <column name="target">
+ <p>Connection method for managers.</p>
+ <p>
+ The following connection methods are currently supported:
+ </p>
+ <dl>
+ <dt><code>ssl:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
+ <dd>
+ <p>
+ The specified SSL <var>port</var> (default: 6632) 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>
+ <p>
+ SSL support is an optional feature that is not always built as
+ part of Open vSwitch.
+ </p>
+ </dd>
+
+ <dt><code>tcp:<var>ip</var></code>[<code>:<var>port</var></code>]</dt>
+ <dd>
+ The specified TCP <var>port</var> (default: 6632) on the host at
+ the given <var>ip</var>, which must be expressed as an IP address
+ (not a DNS name).
+ </dd>
+ <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: 6632). 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: 6632). 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 managers are configured, 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 OVSDB client over the
+ network:
+ </p>
+
+ <dl>
+ <dt><code>in-band</code></dt>
+ <dd>
+ In this mode, this connection's traffic travels over a bridge
+ managed by Open vSwitch. With this setting, Open vSwitch allows
+ traffic to and from the client regardless of the contents of the
+ OpenFlow flow table. (Otherwise, Open vSwitch would never be able
+ to connect to the client, 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, the client's traffic uses a control network separate
+ from that managed by Open vSwitch, that is, Open vSwitch does not
+ use any of its own network devices to communicate with the client.
+ 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.
+ </p>
+ </column>
+ </group>
+
+ <group title="Client Failure Detection and Handling">
+ <column name="max_backoff">
+ Maximum number of milliseconds to wait between connection attempts.
+ Default is implementation-specific.
+ </column>
+
+ <column name="inactivity_probe">
+ Maximum number of milliseconds of idle time on connection to the client
+ before sending an inactivity probe message. If Open vSwitch does not
+ communicate with the client for the specified number of seconds, it
+ will send a probe. If a response is not received for the same
+ additional amount of time, Open vSwitch assumes the connection has been
+ broken and attempts to reconnect. Default is implementation-specific.
+ </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">
A NetFlow target. NetFlow is a protocol that exports a number of
details about terminating IP flows, such as the principals involved
projects / openvswitch / blobdiff